source/README.2building

   1 (This file was generated by makeinfo and splitinfo.gawk.)
   2 (Released under the old-style GNU documentation license;
   3  see sources or other output files for full text.)
   4
   5 4 Building
   6 **********
   7
   8 The top-level 'Build' script is intended to simplify building the
   9 binaries distributed with TeX Live itself--we call this the "native" TL
  10 build.  It configures and makes everything in a subdirectory of the main
  11 build tree (default 'Work/'), installs everything in another
  12 subdirectory (default 'inst/'), and finally runs 'make check'.  The
  13 exact directory and command names can be specified via environment
  14 variables and a few leading options.  All remaining arguments
  15 (assignments or options) are passed to the 'configure' script.  Please
  16 take a look at the './Build' source file itself for more information; it
  17 is a straightforward shell script.
  18
  19    An alternative, and the one we will mainly discuss here, is to run
  20 'configure' and 'make' oneself in a suitable empty subdirectory.
  21 Building in the source directory itself is not supported (sorry).
  22
  23 4.1 Build iteration
  24 ===================
  25
  26 Running the top-level 'configure' script configures the top level and
  27 the subdirectories 'libs', 'utils', and 'texk'.  Running 'make' at the
  28 top-level first iterates over all TeX-specific libraries, and then runs
  29 'make' in 'libs', 'utils', and 'texk' to iterate over all generic
  30 libraries, utility programs, and TeX-specific programs.  These
  31 iterations consist of two steps:
  32
  33   1. For each library or program module not yet configured, run
  34      'configure', adding the configure option '--disable-build' if the
  35      module need not be built, otherwise running 'make all'.
  36
  37   2. For each library or program module that must be built, run 'make'
  38      for the selected target(s): 'default' or 'all' to (re-)build,
  39      'check' to run tests, 'install', etc.
  40
  41    Running the top-level 'make' a second time iterates again over all
  42 the library and program modules, but finds (should find) nothing to be
  43 done unless some source files have been modified.
  44
  45 4.2 Build problems
  46 ==================
  47
  48 If configuring or building a module fails, you should first find and fix
  49 the problem, then perhaps remove the subdirectory for that module from
  50 the build tree, and finally rerun the top-level 'make' (or 'Build' with
  51 '--no-clean' as its first argument).
  52
  53 4.3 Build in parallel
  54 =====================
  55
  56 The TL build system carefully formulates dependencies as well as 'make'
  57 rules when a tool (such as 'tangle', 'ctangle', or 'convert') creates
  58 several output files.  This allows for parallel builds ('make -j N' with
  59 N>1 or even 'make -j') that can considerably speed up the TL build.
  60
  61    Incidentally, a noticeable speed-up can also be (independently)
  62 gained by using a configure cache file, i.e., with the option '-C'
  63 (recommended).
  64
  65 4.4 Build distribution
  66 ======================
  67
  68 Running 'make dist' at the top-level creates a tarball
  69 'tex-live-YYYY-MM-DD.tar.xz' from the TL source tree.  Running 'make
  70 distcheck' also verifies that this tarball suffices to build and install
  71 all of TL.
  72
  73    This is useful for checking consistency of the source tree and
  74 Makefiles, but the result is not a complete or even usable TeX system,
  75 since all the support files are lacking; *note Installing::.
  76
  77 4.5 Build one package
  78 =====================
  79
  80 To build one package, the basic idea is to use the 'configure' option
  81 '--disable-all-pkgs' (*note --disable-all-pkgs::).  Then all program and
  82 library modules are configured but none are made.  However, the
  83 'Makefile's still contain all build rules and dependencies and can be
  84 invoked to build an individual program or library and causes to first
  85 build any required libraries.
  86
  87    This "build-on-demand" procedure is used, e.g., in the upstream
  88 LuaTeX repository to build LuaTeX, essentially from a subset of the
  89 complete TeX Live tree.  Similarly, when, e.g., building the original
  90 e-TeX has been disabled (as it is by default), one can run 'make etex'
  91 (or 'make etex.exe') in 'texk/web2c/' to build e-TeX (although there is
  92 no comparably simple way to install e-TeX).
  93
  94    If you want to work on a single program within the TL sources, this
  95 is the recommended way to do it.  Here is an example from start to
  96 finish for working on 'dvipdfm-x'.
  97
  98      mkdir mydir && cd mydir  # new working directory
  99
 100      # Get sources (<http://tug.org/texlive/svn>)
 101      rsync -a --delete --exclude=.svn --exclude=Work \
 102            tug.org::tldevsrc/Build/source/ .
 103
 104      # Create build directory:
 105      mkdir Work && cd Work
 106
 107      # Do the configure:
 108      ../configure --disable-all-pkgs --enable-dvipdfm-x \
 109        -C CFLAGS=-g CXXFLAGS=-g >&outc
 110
 111      # Do the make:
 112      make >&outm
 113
 114      # Test:
 115      cd texk/dvipdfm-x
 116      make check
 117
 118    Then you modify source files in 'mydir/texk/dvipdfm-x' and rerun
 119 'make' in 'mydir/Work/texk/dvipdfm-x' to rebuild.
 120
 121    The second line of the 'configure' invocation shows examples of extra
 122 things you likely want to specify if you intend to hack the sources (and
 123 not just build binaries): the '-C' speeds up 'configure', and the
 124 'CFLAGS' and 'CXXFLAGS' settings eliminate compiler optimization for
 125 debugging purposes.
 126
 127    Of course, one should actually look at the output and check that
 128 things are working.  There are many 'configure' options you can tweak as
 129 desired; check the output from 'configure --help'.
 130
 131    Finally, the above retrieves the entire TL source tree (some 300mb).
 132 It is natural to ask if this is really necessary.  Strictly speaking,
 133 the answer is no, but it is vastly more convenient to do so.  If you cut
 134 down the source tree, you must also give additional 'configure' flags to
 135 individually disable using system versions of libraries, or the
 136 intricacies of the dependencies (such as 'teckit' requiring 'zlib') will
 137 have undesired side effects.  For an example, see the 'build-pdftex.sh'
 138 script in the 'pdftex' development sources (<http://pdftex.org>), which
 139 are indeed a cut-down TL source tree.
 140
 141    Caveat 1: even with '--disable-all-pkgs', dependencies will be
 142 checked.  For instance, if a non-MacOSX system does not have
 143 'fontconfig', XeTeX cannot be built (*note Prerequisites::) and
 144 'configure' will terminate.  To proceed without such dependencies,
 145 specify '--enable-missing' also.  (Arguably this should happen
 146 automatically.)
 147
 148    Caveat 2: unless 'CC' and 'CXX' and 'OBJCXX' are explicitly
 149 specified, each package will configure its own compiler(s).  In
 150 practice, this results in a conflict in only one instance: the ICU
 151 ('libs/icu') library will prefer 'clang' and 'clang++' over all others
 152 if they are installed, whereas everything else prefers 'gcc' and 'g++'.
 153 Usually the results will be interoperable, but it can cause extra
 154 confusion and problems when debugging a program that uses ICU.
 155