Formatting Information: — Configuring TEX search paths

Your support for our advertisers helps cover the cost of hosting, research, and maintenance of this document

Formatting Information — An introduction to typesetting with LATEX

Appendix A: Installation

TEX systems run on a huge variety of platforms, and are typically made up of a very large number of very small files in several separate ‘trees’ of directories (folders). This allows users to update parts of the system without having to update all of it, and to maintain their own tree of preferred files without having to have administrative rights on the computer.

To make sure TEX finds the right file, it uses a technique borrowed from the Unix world, based on a simple ‘hash index’ for each directory tree they need to look in. This is known as the ls-R database, from the Unix command (ls -R) which creates it. The program which does this for TEX is actually called after this command: mktexlsr, although it may be aliased as texhash or something else on your system. This is the program referred to in step 4 above.

However, to know where to make these indexes, and thus where to search, TEX needs to be told about them. You don’t normally need to change the configuration, but sometimes you might want to move directories between disks to free up space or use faster equipment, which would mean changing the configuration.

In a standard TEX installation this information is in the main (not the local) installation directory, in texmf/web2c/texmf.cnf. The file is similar to a Unix shell script, but the only lines of significance for the search paths are the following (this is how they appear in the default Unix installation, omitting the comments):

TEXMFMAIN = /usr/share/texmf
TEXMFLOCAL = /usr/local/share/texmf
HOMETEXMF = $HOME/texmf
TEXMF = {$HOMETEXMF,!!$TEXMFLOCAL,!!$TEXMFMAIN}
SYSTEXMF = $TEXMF
VARTEXFONTS = /var/lib/texmf
TEXMFDBS = $TEXMF;$VARTEXFONTS

This defines where the main TEX/METAFONT (texmf) directory is, where the local one is, and where the user’s personal (home) one is. It then defines the order in which they are searched, and makes this the system-wide list. A temporary directory for bitmap fonts is set up, and added to the list, defining the places in which texhash or mktexlsr creates its databases.

Finding out where LATEX looks for stuff

There is a program distributed in all LATEX installations called kpsewhich, a TEX-specific variant of the standard Unix which command. If you type the command followed by a filename, it will tell you whereabouts in your TEX installation it is.

$ kpsewhich article.cls
/usr/share/texmf-texlive/tex/latex/base/article.cls

Better, there is an option to tell you where your main, local, system, and personal trees (directories) are installed, and even where LATEX puts its map files and format files (internal setups), and where shared BIBTEX files can be stored:

$ kpsewhich -var-value TEXMFMAIN
$ kpsewhich -var-value TEXMFLOCAL
$ kpsewhich -var-value TEXMFSYSVAR
$ kpsewhich -var-value TEXMFHOME
$ kpsewhich -var-value BIBINPUTS

So if you forget where to put something you are installing, $TEXMFHOME is where it should go on a single-user system, and $TEXMFLOCAL on a multi-user system.

In some installations, the local directory may be set up in a slightly different directory to the one given in the example. Under Microsoft Windows, the names will be full paths such as C:\Program Files\TeXLive\texmf (for TEX Live) or C:\Program Files\MikTeX 2.9\tex (for MiKTEX). On an Apple Mac, it is ~/Library/texmf for each user.

Previous section

Next appendix