Multiple Distribution Support

The MacTeX packages --- teTeX.pkg, gwTeX.pkg, TeXLive-2007.pkg, and TeXLiveMTS-2007.pkg --- support multiple TeX distributions on a single machine using a design by Gerben Wierda and Jerome Laurens. This design was introduced in the i-Installer gwTeX package.

Why multiple distributions are useful

We are entering a period of uncertainly for TeX on Mac OS X. It is not clear which distribution will predominate ultimately. Users may wish to experiment with various possibilities while maintaining their current distribution for production work.

In addition, TeXLive is updated in an interesting way. The 2005 version was installed in /usr/local/texlive/2005; the 2007 version will be installed in /usr/local/texlive/2007. Thus users can test the new version while retaining the earlier version for production work. When they are certain that the 2007 version introduces no problems, they can switch to it permanently.

Why multiple distributions are dangerous

Unfortunately, switching from one distribution to another is tricky. It is necessary to switch the PATH variable for Terminal use, it is necessary to switch the MAN configuration so Terminal can find appropriate man files, and it is necessary to switch Preference items in many different GUI applications (TeXShop, LaTeXiT, BibDesk, etc.) Some of these changes are difficult; for instance, switching PATHs can require editing a hidden .profile file which many users never use. Improperly making these changes can lead to a situation where the Terminal uses one distribution and selected GUI programs use another. The possibilities for error are so numerous that users working on a project are usually unwilling to experiment.

How Gerben Wierda and Jerome Lauren solve these problems

After installing new distributions with i-Installer or MacTeX, you will find a new control panel in System Preferences. When opened, this "TeX Distribution" control panel by Jerome Laurens lists all installed TeX distributions, and shows the currently active distribution. To switch to another, click on its name and type a password in the resulting Authentication Panel. Done. Automatically, the PATH variable will be changed to the appropriate value in all shells, the MAN variable will point to the correct location, and all appropriate preferences in all GUI applications will simultaneously switch to the new distribution.

It may seem scary that the control panel roams over the system making all of these changes. But it doesn't. Actually, the control panel changes only one symbolic link in a data structure stored in /Library/TeX, but this data structure has been cleverly designed to implicitely make all of these changes.

This data structure does not change the individual TeX distributions in any way. For example, TeXLive-2007 is installed in /usr/local/texlive/2007. Not a single file in this location has been alterated or added to make these changes possible. If a user installs only one distribution as in the past, their TeX will work exactly as it always did and the new data structure will never be used.

There is one detail users may notice. All GUI applications contain preference settings giving the location of the TeX binary programs. For instance, TeXShop has a setting with default value

and LaTeXiT has several settings giving the locations of pdfLaTeX, xeLaTeX, and other programs
etc. The new data structure introduces a link /usr/texbin pointing to the binary directory of the currently active distribution. The location this link points to changes when the Preference Panel is used. Thus GUI applications need to be reconfigured to use this link, but this reconfiguration needs to be made just once and then the GUI applications should work automatically with all TeX distributions in the future. For instance, the three listed preferences should be changed to
It is likely that these values will soon be the default values of most GUI applications.

More Details

The data structure in /Library/TeX has already been configured for Gerben's old distribution, for his new gwTeX, and for TeXLive-2004, TeXLive-2005, and TeXLive-2007. This means that if you are currently using Gerben's old distribution and install gwTeX, the system will also see your old distribution. Similarly, if you install TeXLive-2004 in the default location /usr/local/texlive/2004 using the TUG install script from two years ago, your system will automatically recognize this distribution even though that install script was written two years before Gerben and Jerome began working. The data structure is simple, so users can easily add support for the TeX distributions by fink, macports, and others. We hope these distributors provide automatic support in the future.

There is more to this data structure than mentioned so far. It provides a way for GUI programs of the future to peek into the active distribution. For instance, a program might offer to open selected documentation files from the active distribution --- there is a lot of documentation, but it is currently hidden away.

The data structure comes with a command line tool called texdist which may be useful in case the Preference Pane fails. Open Terminal and type

texdist --usage
The tool will then list all commands it can perform. Type
texdist --current
to see the currently active distribution, and
texdist --list
to see all available distributions. Each item of the resulting list will end with ".texdist". For instance, one element of the list may be gwTeX.texdist. To make a distribution active, type something like
sudo texdist --setcurrent=gwTeX
Notice that the distribution is named without the ".texdist" and notice the sudo, which will force you to give a password before making the change.

Technical Design

The location /Library/TeX/Distributions contains a technical design document describing the data structure in detail. Roughly speaking, each distribution is represented by a small folder in /Library/TeX/Distributions. One such folder is TeXLive-2007.texdist. Inside this folder is a symbolic link named Contents. This link points to hidden data in /Library/TeX/Distributions/.FactoryDefaults. Specifically, it points to

This Contents folder contains the actual links describing the TeXLive-2007 data structure.

In addition, there is a hidden link /Library/TeX/Distributions/.DefaultTeX/Contents. This link points to the active distribution; for instance, it might point to

Changing just this one link changes the active distribution.

The location /usr/texbin mentioned earlier is a symbolic link to

on an Intel machine (the last entry is powerpc on a PowerPC machine). Thus this always points to the active binary directory. The PATH variable is set in /etc/.profile and /etc/csh.login to /usr/texdist, and thus this path automatically points to the active binary directory without rewriting this shell startup script.

With these hints and a little experimentation, it will be clear how the data structure works, and what information is provided to GUI programs about the active distribution.