(This file was generated by makeinfo and splitinfo.gawk.)
(Released under the old-style GNU documentation license;
 see sources or other output files for full text.)

4 Building
**********

The top-level 'Build' script is intended to simplify building the
binaries distributed with TeX Live itself--we call this the "native" TL
build.  It configures and makes everything in a subdirectory of the main
build tree (default 'Work/'), installs everything in an other
subdirectory (default 'inst/'), and finally runs 'make check'.  The
exact directory and command names can be specified via environment
variables and a few leading options.  All remaining arguments
(assignments or options) are passed to the 'configure' script.  Please
take a look at the script itself for more information; it is not
complicated.

   An alternative, and the one we will mainly discuss here, is to run
'configure' and 'make' oneself in a suitable empty subdirectory.
Building in the source directory itself is not supported (sorry).

4.1 Build iteration
===================

Running the top-level 'configure' script configures the top level and
the subdirectories 'libs', 'utils', and 'texk'.  Running 'make' at the
top-level first iterates over all TeX-specific libraries, and then runs
'make' in 'libs', 'utils', and 'texk' to iterate over all generic
libraries, utility programs, and TeX-specific programs.  These
iterations consist of two steps:

  1. For each library or program module not yet configured, run
     'configure', adding the configure option '--disable-build' if the
     module need not be built, otherwise running 'make all'.

  2. For each library or program module that must be built, run 'make'
     for the selected target(s): 'default' or 'all' to (re-)build,
     'check' to run tests, 'install', etc.

   Running the top-level 'make' a second time iterates again over all
the library and program modules, but finds (should find) nothing to be
done unless some source files have been modified.

4.2 Build problems
==================

If configuring or building a module fails, you should first find and fix
the problem, then perhaps remove the subdirectory for that module from
the build tree, and finally rerun the top-level 'make' (or 'Build' with
'--no-clean' as its first argument).

4.3 Build in parallel
=====================

The TL build system carefully formulates dependencies as well as 'make'
rules when a tool (such as 'tangle', 'ctangle', or 'convert') creates
several output files.  This allows for parallel builds ('make -j N' with
N>1 or even 'make -j') that can considerably speed up the TL build.

   Incidentally, a noticeable speed-up can also be (independently)
gained by using a configure cache file, i.e., with the option '-C'
(recommended).

4.4 Build distribution
======================

Running 'make dist' at the top-level creates a tarball
'tex-live-YYYY-MM-DD.tar.xz' from the TL source tree.  Running 'make
distcheck' also verifies that this tarball suffices to build and install
all of TL.

   This is useful for checking consistency of the source tree and
Makefiles, but the result is not a complete or even usable TeX system,
since all the support files are lacking; *note Installing::.

4.5 Build one package
=====================

To build one package, the basic idea is to use the 'configure' option
'--disable-all-pkgs' (*note '--disable-all-pkgs'::).  Then all program
and library modules are configured but none are made.  However, the
'Makefile's still contain all build rules and dependencies and can be
invoked to build an individual program or library and causes to first
build any required libraries.

   This "build-on-demand" procedure is used, e.g., in the 'luatex'
repository to build LuaTeX, essentially from a subset of the complete
TeX Live tree.  Similarly, when, e.g., building the original e-TeX has
been disabled (as it is by default), one can run 'make etex' (or 'make
etex.exe') in 'texk/web2c/' to build e-TeX (although there is no
comparably simple way to install e-TeX).

   If you want to work on a single program within the TL sources, this
is the recommended way to do it.  Here is an example from start to
finish for working on 'dvipdfm-x'.

     mkdir mydir && cd mydir  # new working directory

     # Get sources (<http://tug.org/texlive/svn>)
     rsync -a --delete --exclude=.svn --exclude=Work \
           tug.org::tldevsrc/Build/source/ .

     # Create build directory:
     mkdir Work && cd Work

     # Do the configure:
     ../configure --disable-all-pkgs --enable-dvipdfm-x \
       -C CFLAGS=-g CXXFLAGS=-g >&outc

     # Do the make:
     make >&outm

     # Test:
     cd texk/dvipdfm-x
     make check

   Then you modify source files in 'mydir/texk/dvipdfm-x' and rerun
'make' in 'mydir/Work/texk/dvipdfm-x' to rebuild.

   The second line of the 'configure' invocation shows examples of extra
things you likely want to specify if you intend to hack the sources (and
not just build binaries): the '-C' speeds up 'configure', and the
'CFLAGS' and 'CXXFLAGS' settings eliminate compiler optimization for
debugging purposes.

   Of course, one should actually look at the output and check that
things are working.  There are many 'configure' options you can tweak as
desired; check the output from 'configure --help'.

   Finally, the above retrieves the entire TL source tree (some 300mb).
It is natural to ask if this is really necessary.  Strictly speaking,
the answer is no, but it is vastly more convenient to do so.  If you cut
down the source tree, you must also give additional 'configure' flags to
individually disable using system versions of libraries, or the
intricacies of the dependencies (such as 'teckit' requiring 'zlib') will
have undesired side effects.  For an example, see the 'build-pdftex.sh'
script in the 'pdftex' development sources (<http://pdftex.org>), which
are indeed a cut-down TL source tree.