kpathsea: ls-R
5.5.1 'ls-R'
------------
As mentioned above, you must name the main filename database 'ls-R'.
You can put one at the root of each TeX installation hierarchy you wish
to search ('$TEXMF' by default, which expands to a braced list of
several hierarchies in TeX Live).
Kpathsea looks for 'ls-R' files along the 'TEXMFDBS' path. It is
best for this to contain all and only those hierarchies from '$TEXMF'
which are specified with '!!'--and also to specify them with '!!' in
'TEXMFDBS'. (See the end of this section for more on '!!'.)
The recommended way to create and maintain 'ls-R' is to run the
'mktexlsr' script, which is installed in '$(bindir)' ('/usr/local/bin'
by default). That script goes to some trouble to follow symbolic links
as necessary, etc. It's also invoked by the distributed 'mktex...'
scripts.
At its simplest, though, you can build 'ls-R' with the command
cd /YOUR/TEXMF/ROOT && ls -LAR ./ >ls-R
presuming your 'ls' produces the right output format (see the section
below). GNU 'ls', for example, outputs in this format. Also presuming
your 'ls' hasn't been aliased in a system file (e.g., '/etc/profile') to
something problematic, e.g., 'ls --color=tty'. In that case, you will
have to disable the alias before generating 'ls-R'. For the precise
definition of the file format, see ⇒Database format.
Regardless of whether you use the supplied script or your own, you
will almost certainly want to invoke it via 'cron', so when you make
changes in the installed files (say if you install a new LaTeX package),
'ls-R' will be automatically updated. However, for those using TeX Live
or system distributions, the package managers should run 'mktexlsr' as
needed.
The '-A' option to 'ls' includes files beginning with '.' (except for
'.' and '..'), such as the file '.tex' included with the LaTeX tools
package. (On the other hand, _directories_ whose names begin with '.'
are always ignored.)
If your system does not support symbolic links, omit the '-L'.
'ls -LAR /YOUR/TEXMF/ROOT' will also work. But using './' avoids
embedding absolute pathnames, so the hierarchy can be easily
transported. It also avoids possible trouble with automounters or other
network filesystem conventions.
Kpathsea warns you if it finds an 'ls-R' file, but the file does not
contain any usable entries. The usual culprit is running plain 'ls -R'
instead of 'ls -LR ./' or 'ls -R /YOUR/TEXMF/ROOT'. Another possibility
is some system directory name starting with a '.' (perhaps if you are
using AFS); Kpathsea ignores everything under such directories.
If a particular path element begins with '!!', _only_ the database
will be searched for that element, never the disk; and if the database
does not exist, nothing at all will be searched. In TeX Live, most of
the trees are specified with '!!'.
For path elements that do not begin with '!!', if the database
exists, it will be used, and the disk will not be searched. However, in
this case, if the database does not exist, the disk will be searched.
In TeX Live, the most notable case of this is the 'TEXMFHOME' tree, to
allow users to add and remove files from their own tree without having
to worry about 'ls-R'.
(Aside: there are uncommon cases where a '!!' tree will be searched
on disk even if the 'ls-R' file exists; they are too obscure to try to
explain here. See 'pathsearch.c' in the source if you need to know.)
To sum up: do not create an 'ls-R' file unless you also take care to
keep it up to date. Otherwise newly-installed files will not be found.
Info Catalog
kpathsea: Filename database
kpathsea: Filename aliases