Monday, June 6, 2011

Updating LaTeX on Mac (Hard and Easy Way)

With my dissertation nearing completion, I decided to update my TeX distribution from TeX Live 2009 to 2010. This is not a horribly complicated thing if one uses the right package. However, I tend not to do things the easy way.

Before I get into some of the things I discovered, I do want to point out the simplest way to upgrade a from TeX Live 2009 to 2010 on a Mac is to download and install the MacTeX package. It'll put everything in the correct location, update the distribution information, and select the new distribution as the preferred distribution.

Now, what I did initially (the harder way) was to use the TeX Live net-installer. It's not a horribly complicated thing to use, it just took a rather long time to get all of the packages downloaded; I also had to restart the process a couple of times because of corruption issues.

With the 2010 distribution installed, I figured I'd be ready to go. However, when I'd go to render my documents, I kept using the 2009 package. So, I decided to look more closely at how TeX is setup on my Mac.

By default, the TeX Live distributions install the TeX distribution in the directory:
/usr/local/texlive/XXXX
where XXXX is the year of the distribution release. (Note that thereis also a directory called texmf-local for user-installed packages located in the /usr/local/texlive directory.)

The packages from the net-install were properly installed to the texlive directory, but for some reason the old distribution kept getting invoked. The solution was to add the new TeX Live 2010 distribution to the search path, so I edited my .bashrc file to include the line:
export PATH=/usr/local/texlive/2010/bin/universal-darwin/:$PATH. Alternatively, I could have also updated /etc/paths.

This proceedure works for getting the correct distribution to run on the command line, but the package still didn't show up in the control pannel TeX preference pane (installed from the 2009 MacTex distribution), nor did using the command "texdist --list" (a command line version of the utility) show the 2010 distribution. So, what's going on?

At any one time, multiple TeX distributions can be installed on a system. On the Mac, the texdist utility and preference pane mange which distribution is the default. The utilities don't alter any distribution directly, but do create a series of symbolic links to inform applications which TeX distribution to use. The information about the distributions is stored in the /Library/TeX/Distributions; the installer that I used to install TeX Live 2010 did not update this directory to include an entry for TeX 2010. (More information about what this directory contains can be found here.)

The texdist utilities essentially manage a collection of symbolic links that get used when TeX or its resources are invoked. The texdist utility:
  1. Switches the /Library/TeX/Distributions/.DefaultTeX directory to link to one of the directories ending in .texdist in /Library/TeX/Distributions. Each of these directories contain links to different TeX resources.
  2. The contents of /Library/TeX/Distributions/.DefaultTeX/Contents then contains links to the man, root, and other TeX package resources for the default TeX package.
  3. This switch changes what the symbolic links in /usr/texbin refer to.

Consequently, using the texdist utilities (either via the Preference Pane or using the command texdist --usage=TeXLive-2010) will set anything that uses either /usr/texbin or /Library/TeXDistributions/.DefaultTeX to the correct distribution.

As far as I could tell, I could have created my own .texdist directory for TeX 2010. There is documentation describing this in the file /Library/TeX/Distributions/TeXDist-description.rtf.

Instead, since I didn't completely know what I needed to do at the time, I chose to run the MacTeX package installer, mentioned at the top of this entry. The package installed TeX 2010 overtop of the previous install and created the appropriate symbolic links mentioned above. At this point, everything worked as it should.

Finally, to tidy up, I decided to uninstall TeX Live 2009, following these instructions.