(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).

   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.

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

   With the configure option '--disable-all-pkgs', all program and
library modules are configured but none of them is built.  The
'Makefile' for each such module contains 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).

   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.  Independently, speed-up can also be achieved by using a
configure cache file, i.e., with the option '-C' (recommended).

   Running 'make dist' at the top-level creates a tarball
'tex-live-YYYY-MM-DD.tar.xz' from the TL source tree.  Running 'make
dist-check' 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; see the next
section.)