Internals of TeX Live 1: stacked versus non-stacked files, texmf.cnf adaptions

I thought about writing a series of entries about internals of the TeX Live ecosystem. Background is that there is a big need for packaging TeX Live for Distributions. I gave a talk on this topic at the FOSDEM 2013 in Brussels, but still need to write a TUGboat article. So today I start with this series and will introduce the concept of stacked versus non-stacked files, followed by an usage example in the case of texmf.cnf adaptions.

In the following we expect some knowledge about the TeX Directory Standard and TeX systems in general. It is well known in the TeX world that one can override a file by placing it into a tree that is searched earlier. Typical examples are putting newer versions of a package into TEXMFHOME tree, overriding the files shipped originally. This behaviour is called non-stacked:

non-stacked

files located in more prominent, i.e., higher up in the hierarchy of texmf trees, override files of the same name in lower priority trees.

This is the default behaviour for most of the input files in the TeX world. In particular for all the .tex, .sty, .cls files. It works as expected: if you put an updated version of foobar.sty into your TEXMFHOME, that updated version will be used instead of the system supplied one when typing in \usepackage{foobar}.

stacked

all files of the same name in all trees are read and the content is merged, multiple definitions are allowed and treated depending on the application and file

This behaviour has been common for configuration files of many Unix programs, where the system-wide configuration in /etc could be amended and overridden by configuration files in the user’s home directory.

Stacked configuration files are still very rare in the TeX eco system, for now there are only two configuration files that are treated in this way: texmf.cnf and updmap.cfg.

adaptions to texmf.cnf

texmf.cnf is the central configuration file for search path and some other program properties. At the current moment the TeX Live texmf.cnf provides the following path, in increasing order of priority:

Possible adaptions to texmf.cnf are

• adjustment of tree locations
  e.g., TEXMFSYSCONFIG = /etc/texmf
• addition of trees
  e.g., TEXMFDEBIAN = /usr/share/texmf
• inclusion of additional trees in the search path
  e.g., TEXMF = ...;$TEXMFDEBIAN;...

Anything else should in fact not be necessary.

Since the main texmf.cnf in TeX Live is located in texmf-dist/web2c/texmf.cnf, and this one is regularly replaced by newer versions by tlmgr updates (package kpathsea), making changes right there is not safe. It is better to put changed definitions (and only those!) into one of the following places:

• the root of the TeX Live installation: a texmf.cnf file in R/texmf.cnf, where R is the root of the installation, in many cases .../texlive/2013/, will be read by the kpathsea library. Setting things there will work.
• TEXMFSYSCONFIG/web2c/texmf.cnf: unless you change TEXMFSYSCONFIG itself, this is a good location for changes.

Debian example

As an example I will give the changes I made for the Debian packages of TeX Live. In Debian all the files of TeX Live are installed into /usr/share/texlive/, and we change

• TEXMFSYSCONFIG = /etc/texmf
• TEXMFLOCAL = /usr/local/share/texmf
• TEXMFSYSVAR = /var/lib/texmf
• TEXMFCONFIG = ~/.texmf-config
• TEXMFVAR = ~/.texmf-var

These changes are already made in the main texmf.cnf file since we do not provide the possibility to use tlmgr for system files. But we allow additional packages to ship snippets for the system texmf.cnf file in /etc/texmf/texmf.d from which we assemble the /etc/texmf/web2c/texmf.cnf file.