Support for multiple TEX distributions in i-Installer and MacTEX

Richard Koch 2740 Washington St. Eugene, Oregon, USA koch (at) math dot uoregon dot edu http://uoregon.edu/~koch/ Abstract We discuss a data structure by Gerben Wierda and J´erˆome Laurens which makes it easy to use multiple TEX distributions on Mac OS X.

1 A confession Meanwhile, TUG’s Mac OS X Working Group The wonderful data structure described below was produced three one-button install packages for TEX, designed by Gerben Wierda and J´erˆomeLaurens all based on TEX Live and differing mainly in size. and implemented first in Gerben’s i-Installer pack- These packages are available at http://tug.org/ mactex. The first of these, BasicT X, is a 39.7 MB age for gwTEX and then later in the various MacTEX E install packages I maintain. When I learned the de- package for users with slow download connections; tails of the design, I was repulsed by its complex- it installs a surprisingly useful subset of TEX Live ity, and opposed it with increasingly vitriolic emails. 2007. The second, gwTEX, is a 321 MB package Then one day, an email from J´erˆomeled to a reli- which installs gwTEX; users can use i-Installer to gious conversion on my part. The data structure maintain this distribution. The third, TEX Live now seems natural, and the Gods have condemned 2007, is a 619 MB package which installs the com- me to write this article as punishment for opposi- plete 2007 version of TEX Live. tion. There are also independent distributions based on teTEX in Fink and in MacPorts. 2 The problem All of these distributions install in different lo- cations, so installing one does not overwrite the oth- TEX GUI applications on the Macintosh, like (my ers. For example, BasicT X is a subset of T X Live program) TeXShop, LATEXiT, iTEXMac, BibDesk, E E and others, call command line programs to typeset. 2007, but installing TEX Live 2007 creates a com- pletely separate installation rather than upgrading A year ago, the standard Mac TEX distribution was the BasicT X installation. teTEX, as packaged by Gerben Wierda. Therefore E these GUI applications were configured to use that This proliferation of distributions confuses new distribution, and so the applications worked right users. In early June, a physics graduate student at out of the box without any configuration. the University of Oregon called me after switching But in May of 2006, Thomas Esser announced from Windows to a Mac. He set aside a Saturday to install software. From the web he learned about the end of his support for teTEX. This led to a mad the MacT X full T X Live distribution and installed scramble in the TEX world — some users switched to E E it. Then his lab partners told him to get scientific the full unmodified TEX Live and others continued applications with Fink, so he installed Fink. Fink to rely on teTEX. At the international TUG meet- ing in Marrakesh held in November 2006, Gerben asked him which programs to install, so he said “give me everything” and unknowingly got a second T X introduced a new distribution named gwTEX based E distribution. After that, friends suggested learning on TEX Live. But alarmingly, he also announced the end of email support for his distribution, and TEX by starting with LyX, so he installed that. The modified i-Installer so the first dialog which appears LyX installer told him that it needed to put style says Unsupported Software in bold letters, fol- files in /usr/local/gwTeX, so he searched the inter- lowed by a paragraph of text which begins “I regret net and found gwTEX. In the course of a single af- having to inform you that i-Installer is unsupported ternoon, he had managed to install three complete software as of Jan 1, 2007.” Gerben continues to TEX distributions on his portable. Everything went smoothly until a Fink web page explained how to re- maintain gwTEX, with a substantial following, and “unsupported” seems to mean merely that he has configure TeXShop for teTEX, and he couldn’t figure adopted Donald Knuth’s policy of not reading email. out what teTEX was. But his message puts new users into panic mode.

TUGboat, Volume 28 (2007), No. 3 — Proceedings of the 2007 Annual Meeting 329 Richard Koch

3 The solution ognizes legacy distributions written before the pane I’ll get to the new data structure in a minute, but existed: Fink’s teTEX, MacPort’s teTEX, Gerben’s first let me tell you what J´erˆomeLaurens wrote in old teTEX, TEX Live 2004, TEX Live 2005, and — email which led to my religious conversion. J´erˆome well, there wasn’t any TEX Live 2006. told me he had a preference pane for Apple’s System 4 Another problem solved Preferences which would list available TEX distribu- tions and allow users to switch from one to another. Developers want the newest versions of computer J´erˆome’spane lists distributions installed on a software. But many TEX users don’t think that way. machine. The active distribution is marked in this I’ve often heard variants of “I’m in the middle of list. Click on another distribution to make it active. two book projects and five papers with coauthors; This action automatically switches the PATH and don’t talk to me about upgrading TEX.” To some MANPATH variables so Terminal and other shells extent, interest in upgrading depends on the com- use the correct binaries and man pages. It auto- ponent of TEX being used; ConTEXt and X TE EX are matically reconfigures all GUI programs to use the undergoing rapid development and users of these A appropriate distribution. For example, TeXShop, programs upgrade regularly, while users of LTEX and pdfT X are more likely to desire stability over LATEXiT, iTEXMac, and BibDesk switch instantly E to the new distribution. You can open a source change. file, typeset, switch distributions with the pane, and The TEX Live distribution is upgraded once a typeset again with the new distribution, all without year and each upgrade is installed in a different loca- restarting the GUI program or even reloading the tion. So TEX Live users can safely upgrade, knowing source file. that it is easy to return to their older distribution. All of the GUI programs I’ve listed are config- Nevertheless, I’m willing to bet that a very large ured by default to use the new data structure, so percentage of TUG members put the TEX Collec- they all work right out of the box without any con- tion DVD aside when it arrives because they are in figuration. the middle of a project. I also bet that most of these Here is the preference pane: folks never retrieve the disk and upgrade.

Do you remember our physics student? I told him “TeXShop is already configured; don’t do any- The problem is that retreating to the old dis- thing. Go to System Preferences, open the TeX Dis- tribution is not foolproof. It is all too easy to recon- tribution pane, and you’ll see a list of your three figure the GUI front end and leave the PATH in Ter- distributions. Switch to the one you want to use.” minal unchanged. Months later such a user might Magical, huh? reconfigure TEX with a Terminal command, only to J´erˆome’spanel is automatically installed by i- discover that the change didn’t “take” in the GUI Installer when it installs gwTEX, and by all three program. This is a difficult bug to diagnose. MacTEXdistributions. So of course the preference But J´erˆome’spanel completely solves the prob- pane recognizes these distributions. But it also rec- lem. Users can retreat to the old distribution with a

330 TUGboat, Volume 28 (2007), No. 3 — Proceedings of the 2007 Annual Meeting Support for multiple TEX distributions in i-Installer and MacTEX

single panel click and be assured that all programs style from that of Newton, who wrote at the begin- are configured correctly. Consequently, I’m hoping ning of the third book of his Principia: ‘It remains that Mac users get in the habit of upgrading as soon that, from the same principles, I now demonstrate as the new TUG DVD arrives. the frame of the System of the World.’ ” That’s my complaint about Karl. If only we 5 Some history had known earlier that TEX Live is easy to install! When Thomas Esser made his announcement, there But to get back to the story — was barely a ripple in the Mac world because “Ger- The three MacTEX install packages mentioned ben will take care of it.” But when Gerben an- earlier are based on TEX Live. In particular, the nounced end of support, there was an explosion of MacTEX package TEX Live-2007 package the full concern; several messages on the TEX on Mac OS X TEX Live exactly as it would appear if installed di- mailing list asked “is this the end of TEX on the rectly with the TEX Live script. However, there are Mac?” several reasons that Mac users should install using At that point, several people began experiment- the MacTEX packages. First, the packages modify ing with TEX Live. I was one of them. It is com- PATH and MANPATH, whereas the TEX Live install mon knowledge that TEX Live is difficult to install; script asks users to do this themselves. MacTEX its install script asks obscure questions like “does modifies these variables exactly as Gerben does from your compiler use BSD calling conventions.” Mind i-Installer and as required by the TEX distribution you, nobody ever told me about this difficulty, but data structure, so the MacTEX method is compati- I somehow knew. And as confirmation, I often talk ble with both gwTEX and this structure. to Karl Berry, who currently maintains the install In addition, the MacTEX packages automati- script, at meetings and he never once asked “why cally configure paper size, while the TEX Live scripts don’t you Mac guys use TEX Live?” ask users to run a post-installation script. But anyway, I dug up an old TUG DVD and Finally, the MacTEX packages install J´erˆome’s ran the script. Gosh. No obscure questions. Very preference pane and the associated data structures, few questions at all, and then poof, TEX Live was while the TEX Live script knows nothing about these installed and it ran like a charm. features. So I have a complaint about Karl: excessive modesty. Let me push this complaint by quoting 6 How the data structure came about: a similar complaint about the inventor of the the- A small suggestion from me . . . ory of electricity and magnetism. Freeman Dyson’s When I made MacTEX packages for TEX Live, I ran great essay Missed Opportunities, Bulletin of the into a small problem. TeXShop and the other GUI AMS, 1972, is about situations where mathemati- programs no longer worked out of the box; they cians would have made faster progress is they had had to be configured first. To make this easy, I paid attention to the physicists. The first case he stole an idea from TEX Live and created a sym- discusses is Maxwell’s theory of electricity and mag- bolic link /usr/local/texprograms pointing to the netism. Dyson begins by quoting Maxwell himself, binary directory of the installed distribution. The who said in a lecture “According to a theory of elec- idea was that GUI programs would have to be con- tricity which is making great progress in Germany, figured just once to use this link, and all installation two electrical particles act on one another directly packages on the Mac would set the link during in- at a distance, but with a force which, according to stallation. I wrote Gerben and casually asked him Weber, depends on their relative velocity, and ac- to support the link in i-Installer. cording to a theory developed by Riemann, Lorenz, and Neumann, acts not instantaneously, but after 7 . . . and Gerben runs with it a time depending on the distance. The power with Instead of making this change, Gerben began to look which this theory explains every kind of electrical at the problem from a larger perspective. There are phenomena must be studied in order to be appre- many things that a GUI application might like to ciated. Another theory of electricity which I prefer know about the active TEX distribution. Certainly . . . ” and then described his own theory. it will want to know where the binaries are. But each Dyson writes “It is difficult to read Maxwell’s TEX distribution contains a lot of documentation, address without being infuriated by his excessive and the GUI app might well like to find and display modesty, which led him to refer to his epoch-making that documentation. Perhaps the GUI app wants to discovery of nine years earlier as only ‘Another the- display man pages too. And recall the LyX installer, ory of electricity which I prefer.’ How different is his which wanted to install style files in the distribution;

TUGboat, Volume 28 (2007), No. 3 — Proceedings of the 2007 Annual Meeting 331 Richard Koch

it needed to know the location of the distribution’s /usr/local/texprograms.) All the standard GUI main texmf tree. apps on Mac OS X now use this as their default path. Gerben proposed a data structure which would That is why they run right out of the box. organize and locate all of this information and more. When the structure is installed by i-Installer or Let’s return to the simple issue of binary loca- MacTEX, a technical description of the structure is tion. The trouble is that each distribution handles installed in /Library/TeX/Distributions. It isn’t this in a slightly different way. In gwTEX, there necessary for me to give full details here, but let are two binary directories, one for Intel binaries and me say just a little more to indicate the range of one for PowerPC binaries. The Intel directory is possibilities opened up by the structure. The folder i386-apple-darwin-current and the PowerPC di- of links for a particular distribution contains sub- rectory is powerpc-apple-darwin-current.TEX folders named Doc, Info, Man, Root, AllTexmf, and Live works similarly, but the binary directories are others. Doc contains symbolic links to actual fold- named i386-darwin and powerpc-darwin. Fink ers in the distribution containing documentation; contains universal binaries which work with both the number of such links varies with distribution. processors, located in /sw/bin.A GUI app might For instance, for TEX Live 2007 the links are called want to find the binary directory for the processor texmf-dist-doc, texmf-doc, texmf-doc-doc, and of the machine on which it is running; this GUI app texmf-var-doc. Thus a GUI application can use shouldn’t have to know these various naming con- DefaultTeX/Doc to discover the entire documenta- ventions to do its job. tion tree for the active distribution. Once we get this far, the basic idea of Gerben Info contains links to the various GNU Info and J´erˆome’sdata structure will be clear. For each files; Man contains links to the various man pages, distribution, they create a small folder of symbolic and Root contains a link to the folder containing the links pointing to actual locations in the distribution. entire distribution. AllTexmf contains links to the The names chosen for these links are common for all various texmf trees of the distribution; for example, distributions rather than names used by a particu- the TEX Live 2007 AllTexmf contains links named lar distribution. Thus a GUI app only needs to know texmf, texmf-dist, texmf-doc, texmf-local, and the common names assigned by Gerben and J´erˆome texmf-var. rather than the actual names chosen by a distribu- The Macintosh file system has a folder named tion. In addition, there is a link named DefaultTeX /Library containing various Apple and Third Party pointing to the folder of symbolic links for the active data files which apply system wide. The TEX distri- distribution. bution data structure is installed in /Library/TeX, Here is how this works in practice. The folder where TeX is a subfolder created by i-Installer or for each distribution has a subfolder Programs and MacTEX. At the moment this folder only contains inside that folder are two symbolic links i386 and information about the TEX distribution data, but I powerpc. These point to the actual directories con- understand that some developers are eyeing it for taining the Intel and PowerPC binaries for that dis- other uses. So I don’t recommend throwing it away tribution. Putting this together, a GUI program cavalierly. The actual distribution symbolic links are running on an Intel processor will find the binaries in folders in /Library/TeX/Distributions. There for the currently active distribution in DefaultTeX/ will be one such folder for each distribution installed Programs/i386. If the active TEX happens to be on the machine, together with folders for legacy dis- TEX Live 2007, this will yield /usr/local/texlive/ tributions even if those aren’t installed. 2007/bin/i386-darwin. If the active TEX is Fink’s It is not necessary to clean up the symbolic links teTEX, it will be /sw/bin. That is the simple idea in the data structure if the corresponding distribu- in a nutshell. (In this explanation I have left out a tion is thrown away, because J´erˆomeLaurens’ pref- few details, so the paths to the links aren’t exactly erence pane is smart and only shows distributions these.) when the data structure points to something con- Tthe path to binaries for the active TEX using crete. Thus, for instance, it is perfectly ok to entirely the architecture of the current machine is of such im- remove TEX Live 2007 using the simple command portance that Gerben and J´erˆomeprovide a short- cut: a link /usr/texbin points to DefaultTeX/ sudo rm -R /usr/local/texlive/2007 Programs/i386 on Intel machines and DefaultTeX/ even though this will leave a stranded data structure Programs/powerpc on PowerPC machines. Thus behind. The data structure itself is tiny. GUI apps can use /usr/texbin as a path to TEX I have now explained all of the key ideas. The binaries. (Thus /usr/texbin replaces my earlier structure and preference pane are quite simple, but I

332 TUGboat, Volume 28 (2007), No. 3 — Proceedings of the 2007 Annual Meeting Support for multiple TEX distributions in i-Installer and MacTEX

use them virtually every day. Because of this struc- In growing frustration, I wrote a few people who ture, weren’t involved in the design and must have won- • GUI apps work right out of the box; dered what the heck I was talking about. One of those folks was Jonathan Kew, and here’s what I • TEX can safely be upgraded because it’s trivial wrote him: to revert if necessary; • GUI TEX applications may display documenta- I shouldn’t be writing you, but I need tion in the future. someone to "kvetch" to and I don’t want to pollute the mailing lists. I have just 8 But give us the dirt seen Gerben’s final "link" design. I think You may be saying “Look, I really don’t care about it is a mess. Am I supposed to support the data structure. I don’t even use a Mac. I’m here the design in MacTeX? because I want to hear about the vitriolic email.” If so, this is the section for you. Gerben will end support of his packages Let me say from the start that the disagree- in January, so we face the possibility of ments I’m going to describe are in the past — there dealing with multiple TeX distributions on was a battle, Gerben and J´erˆomewere right and I the Mac. With multiple packages, we need was wrong. But for your amusement — an easy way to configure GUI applications. When Gerben first designed the data structure, A couple of weeks ago I introduced MacTeX there was no hint of a preference pane. I didn’t packages for three distributions and had exactly know how users would switch the default each package set a symbolic link distribution, but it looked like they were expected /usr/local/texprograms. When I asked to directly open /Library/TeX/Distributions and Gerben to set /usr/local/texprograms in manipulate the folders and data inside it. This made i-Installer packages, he decided to design it urgent that this location contain straightforward a more complete solution. Fair enough. data. Initially, Gerben’s design was simple, but then KVETCH: it took an unexpected turn. Gerben and J´erˆome added an extension .texdist to the names of the But when it came time to implement folders which contain symbolic links describing ac- these changes, Gerben lost all sense tual distributions; for example, TeXLive-2007 be- of proportion. Am I expected to support came TeXLive-2007.texdist. Inside this folder his new baroque design in MacTeX? they placed a subfolder named Contents. Further Should I use Gerben’s data structure investigation revealed that most of the .texdist or just give up and make my folders were associated with mirror images in a hid- own. Am I taking this too personally? Do I den folder; for example, the folder TeXLive-2007. need to get a life? texdist had a mirror named TeXLive-2007 in a Jonathan is a very intelligent fellow. He didn’t hidden folder inside /Library/TeX/Distributions. answer this email. This mirror folder also contained a Contents folder, and the Contents in the original TeXLive-2007. 9 A Macintosh secret texdist folder proved to be a symbolic link to this Why was the new data structure so complicated? Contents folder in the mirror TeXLive-2007. That On the Macintosh, it is possible to trick the is, the actual symbolic links which described the Finder so that it displays a folder as just another distribution were inside the Contents folder in the file. The program XCode, which developers use to mirror folder living in a hidden directory. write applications, saves projects in this way; each Around this time, I realized that I could no saved project appears to be a simple file, but if you longer explain the data structure in a few sentences hold down the control key while clicking on the file and became alarmed. I have never met Gerben or name, a menu will appear offering to open up the J´erˆome(or most of my other collaborators), but file and display its contents. Gerben and I have been in email contact for years — What makes a folder magical in this way? Well, really since the start of OS X — and all of this email its name must have an extension, and it must con- has been pleasant or better. So as I realized the tain a subfolder named Contents. baroque nature of the developing data, I began com- If such a magical folder lives on a computer, plaining. it will look like any other folder until it is claimed

TUGboat, Volume 28 (2007), No. 3 — Proceedings of the 2007 Annual Meeting 333 Richard Koch by an application which understands its extension. the data structure design that he found my email When such an application is installed, the magical distracting and irritating, and J´erˆomeignored me folder will suddenly obtain an icon, and clicking on it completely. But suddenly I had an idea. I mod- will open the associated application instead of open- ified two lines of code in TeXShop, and suddenly ing the folder. Thus magical folders are like the pods TeXShop became the alien application claiming the growing in the basements of houses in Invasion of magical folders. I wrote a final email explaining the Body Snatchers. They are faceless and asleep what I had done, ending with, “Why can’t you see until a governing alien application is installed, when that no front end should do what I have done?” they suddenly obtain a face, wake up, and do the application’s bidding. 12 Paranoia doesn’t pay Gerben and J´erˆome had decided that the fold- At that point, a magical thing happened. I had ers in /Library/TeX/Distributions would be such been getting email from Gerben, but nothing from magic folders. This explained every complication in J´erˆome. Now J´erˆomemanaged to get in contact their data structure. But immediately it led to a by an indirect route; and he wrote “Did you know key question: what was the alien application they that the University of Oregon email system has been intended to claim these magical folders? I asked rejecting my mail?” Gerben this question in an email, and he replied Next J´erˆometold me that he always believed “I’m just designing the data structure; it is up to front ends shouldn’t claim .texdist. other people to use it.” After that, J´erˆomehe told me for the first time about his TeXDist Preference Pane, which in my 10 A suspicion opinion is the key ingredient which makes the data If you don’t come from the Macintosh world, there is structure usable by everyone. Finally he said that a key fact in this story that you may not know. I am he had written a small application which claimed the author of a front end for TEX named TeXShop. the magical folders, but all it did was to open the J´erˆomeLaurens is the author of a competing front TeXDist Preference Pane when the user clicked on end named iTEXMac. J´erˆome is my rival. Suddenly a magical folder. I knew what the alien application was intended to So in a single email, I learned that users could be! Gerben and J´erˆomeare both Europeans; clearly avoid learning of /Library/TeX/Distributions al- the Europeans were planning to pull the TEX rug together, that the magic folders were benign, and right out from under me! that a preference pane existed which met Apple’s high standards for simplicity and usability. It was 11 I fight an exciting day. In a series of increasingly angry emails, I argued First moral: there are fewer evil people in the that no front end should interfere with the underly- world than you may think. ing TEX distribution. Gerben was so caught up in Second moral: Your rivals also have good ideas.

334 TUGboat, Volume 28 (2007), No. 3 — Proceedings of the 2007 Annual Meeting