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); most sites have
only one hierarchy. Kpathsea looks for `ls-R' files along the
TEXMFDBS path, so that should presumably match the list of
hierarchies.
The recommended way to create and maintain `ls-R' is to run the
MakeTeXls-R 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 `MakeTeX...' 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 section 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.
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.
Because the database may be out-of-date for a particular run, if a file
is not found in the database, by default Kpathsea goes ahead and
searches the disk. If a particular path element begins with `!!',
however, only the database will be searched for that element,
never the disk. If the database does not exist, nothing will be
searched. Because this can surprise users ("I see the font
`foo.tfm' when I do an ls; why can't Dvips find it?"), it
is not in any of the default search paths.
Go to the first, previous, next, last section, table of contents.