TeX Live build procedure

To build the executable programs included in TeX Live, there are usual steps of downloading the sources, configuring, compiling, and installing. But there are some peculiarities, briefly described here.

TeX Live, unlike many other projects, ships precompiled binaries to TeX users. This web page is especially for the volunteers who contribute those binaries, but anyone who wants to build TeX Live from source may find it useful.

We have a mailing list specifically for discussion of build issues: tlbuild@tug.org. Feel free to join or peruse the archives if you are interested.

On this page: downloading - building - deployment/testing - xz & wget - xindy - asymptote - volunteers.

Downloading the sources

A separate page describes the ways to get the development sources. If all you want to do is compile the sources (as opposed to having a complete runnable TeX system), you can use rsync -a --delete --exclude=.svn tug.org::tldevsrc/Build/source/ /your/dir/

All the components of the TeX Live release, including the program sources, are also available as a tarball.

Building

The simplest way is to configure, compile, and install in one step using the top-level Build script. Use Build --debug to compile without optimization. (The unstripped binaries will be left in the build directory, namely ./Work, where you can remake normally after source changes, if needed.) Other options are passed to configure.

The prerequisites for a default build are fairly minimal, but you may want to check through them.

If you want to exclude certain programs from the build, use --disable-progname. Run configure --help to see the list.

Most everything that Build does can be overridden with environment variables; take a look. Alternatively, what Build boils down to is configure && make world, where make world is the same as make install strip. Adapt as desired. Run make check for a few minimal tests of what was built.

When making the TL-distributed executables, please use Build or otherwise arrange for the binaries to be stripped. (The targets world and strip in the top-level Makefile will do this.)

When making executables for an independent distro, we request/encourage adding a suffix to the banner, via adding something like this to the configure arguments: --with-banner-add='/MyDistro'. When using the Build script, that would be TL_CONFIGURE_ARGS=--with-banner-add=....

Deployment and testing

The result of the TL make install is a directory such as Build/source/inst/bin/i686-pc-linux-gnu full of executables, but they can't be directly run from there. (The data files created by make install under inst/ aren't directly useful for anything. Ignore them.)

The easiest way to test the newly-built binaries is to copy/move that bindir to the existing Master/bin/archname in a full TL checkout, where archname is the TL platform name, such as i386-linux. (This name is different than the directory name resulting from Build.)

Then run, e.g., latex small2e; the latex.fmt file should be automatically built and you should end up with a small2e.dvi file that you can, for example, view with xdvi or convert with dvips.

For the TL-distributed executables, when you are happy with the results, either post a tarball of the bindir (preferably with no top level directory) on the web somewhere and email karl@tug.org, or commit them to the TL repository yourself. If you like to do it youself, you may find the tl-update-bindir script useful. (It takes care of Subversion housekeeping chores mostly related to symbolic links.)

For deploying and testing your own builds, you may find the TeX Live tarballs convenient. For instance, if you have run configure with --disable-multiplatform --prefix=/somewhere/texlive, then unpack at least the texmf and texmf-dist tarballs under /somewhere.

You can also use the TeX Live installer with the -custom-bin option to test installation.

Special considerations for xz & wget

xz is a compression format (essentially zip with improved parameters), which compresses both better and faster than bzip2. We are using it for packages as of TeX Live 2009. (We used xz's predecessor, lzma, in 2008.)

Please download and compile xz from the original distribution. What we want to end up with are the stripped xz and xzdec binaries (only) in Master/tlpkg/installer/xz, with the platform name as a suffix, e.g., xz.i386-linux.

So, for the TL-distributed executables, something like this:

  1. cd /some/directory/xz-*
  2. ./configure --disable-shared && make
  3. strip src/xz/xz src/xzdec/xzdec
  4. cp src/xz/xz xz.`tlmgr -print-arch`
  5. cp src/xzdec/xzdec xzdec.`tlmgr -print-arch`
  6. either email a url to those binaries to karl@tug.org or commit them yourself in the location tlpkg/installer/xz.

The `tlmgr -print-arch` is just a generic short cut to get the platform name as known to TeX Live—the names of the directories under Master/bin/ in the source repository. You can also just type in the string.

wget: on systems which do not provide GNU wget as part of the normal installation, it is good to download, compile, and install it under tlpkg/installer/wget, as with xz (mutatis mutandi).

Special considerations for xindy

We include Joachim Schrod's xindy indexing program in TeX Live. However, xindy requires GNU CLISP; therefore, it is disabled by default in the Build script.

For the TL-distributed executables, to enable xindy, first compile clisp, as explained in the instructions for setting up clisp. (The relevant info is at the end of the linked-to file; you can ignore the notes about the other programs.) There is no need to install clisp anywhere. Then, specify the path to the clisp binary built in your clisp source tree to Build or configure, as in --enable-xindy CLISP=/path/to/clisp/binary.

The reason for building our own clisp to use for the TL compilation is to minimize shared library dependencies. Although some systems come with clisp, using the system version will almost certainly result in pulling in many other libraries, resulting in an xindy executable that's unlikely to work for many TL users.

Special considerations for asymptote

We include the asymptote 3d graphics program in TeX Live. However, due to the complexity of its build process, it is not enabled in the Build script by default. Instead, you have to do it by hand:

  1. cd /your/texlive/checkout/source/utils/asymptote
  2. svn update
  3. mv .svn dot.svn
  4. ./configure --prefix=/tmp/asyinst --enable-texlive-build \
    --disable-gsl --disable-fftw # --disable-gl
  5. make # CFLAGS="-g -DBROKEN_COMPILER"
  6. mv dot.svn .svn
  7. strip asy

(If you use rsync to update your sources, then of course just ignore the .svn-related items above.)

You can test the various libraries with the asytestlibs.asy file available in the source tree. Running make check will run many more tests.

Then, send karl@tug.org a url to the resulting asy executable. If you want to commit it yourself, also commit a symlink named xasy, pointing to ../../texmf-dist/asymptote/GUI/xasy.py.

Explanations:

Implementation

This web page isn't the place to write in depth about how TeX and friends are compiled in TeX Live. In brief, Knuth's original sources are implemented as literate programs using Pascal, and TL's web2c process converts them to C for compilation.

Volunteer builders

Here is a list of platforms and their respective builders, to the best of our knowledge. Volunteers for other systems are most welcome.

Please send corrections to the tlbuild list.


$Date: 2014/04/24 20:26:01 $; TeX Live;
TUG home page; contact webmaster; (via Google)