Copyright (C) 2009 Peter Breitenlohner You may freely use, modify and/or distribute this file. Layout of the TeX Live (TL) build system ======================================== The TL 2009 build system has been completely restructured, using Autoconf, Automake, and Libtool. The main purpose was to configure and build each library before configuring any module (program or other library) depending on that library. This allows to check for properties and features of a library built as part of the TL tree in much the same way as for an installed (system) version of that library. This should simplify upgrading of modules maintained independently and/or integrating new modules into the TL build system. 1. Layout of directories ======================== 1.1. Overall layout ------------------- texk/kpathsea/* the Kpathsea library libs/*/* various other libraries texk/*/* programs (mostly using Kpathsea) utils/*/* utility programs (not using Kpathsea) texk/am/* Makefile.am fragments texk/web2c/am/* for the Kpathsea library texk/web2c/*/am/* and the Web2C programs libs/Lib/* library Lib (zlib, libpng, t1lib, etc.) texk/Prog/* program package Prog (web2c, afm2pl, bibtex8, etc.) utils/Util/* utility program package Util (dialog, pdfopen, ps2eps, etc.) libs/dummy/* dummy modules texk/dummy/* used to configure utils/dummy/* the real modules ac/* various configure.ac fragments (configure options) */ac/* for the whole TL tree */*/ac/* or for a particular component build-aux/* auxiliary build scripts (config.guess etc.) m4/kpse-pkgs.m4 Autoconf macros defining the lists of Lib, Prog, and Util modules and handling loops over these lists m4/* other Autoconf macros 1.2. A library `Lib' -------------------- libs/Lib/ac/withenable.ac defines libraries required by Lib libs/Lib/ac/Lib.ac defines basic tests for a system version of Lib m4/kpse-Lib-flags.m4 defines Autoconf macros for configure options as well as KPSE_LIB_FLAGS, to be used in configure.ac files and defining Make variables Several libraries use an (almost) unmodified source tree supplemented by a proxy build system (bypassing that of the source tree), e.g., libs/zlib/zlib-1.2.3/* (almost) unmodified source tree libs/zlib/Makefile.am proxy Makefile.am libs/zlib/configure.ac and configure.ac 1.3. A program `Prog' --------------------- texk/Prog/ac/withenable.ac defines libraries required by Prog, provides the configure option --disable-Prog texk/Prog/ac/Prog.ac optionally defines Prog specific configure option that should be seen at the top-level 1.4. A utility program `Util' ----------------------------- utils/Util/ac/withenable.ac defines libraries required by Util, provides the configure option --disable-Util 2. Running `configure' ====================== Running 'configure' for the top-level directory will in addition configure the directories texk/kpathsea/, libs/, libs/dummy/, utils/, utils/dummy/, texk/, and texk/dummy/. This will determine the programs (utils/Util/ and texk/Prog) to be built and libraries from the TL tree (texk/kpathsea/ and libs/Lib) required by these programs. 3. Running `make' ================= Running 'make' in the top-level directory will recurse into the directories texk/kpathsea/, libs/, utils/, and texk/. 3.1. Running `make' in libs/ ---------------------------- First, for each subdirectory libs/Lib/ not yet configured, this runs `configure' and if required `make all' in that directory. Then this recurses into all required subdirectories for the selected Make target: `default' or `all' to (re-)build, `check' to run tests, `install' etc. 3.2. Running `make' in utils/ and texk/ --------------------------------------- Quite similarly, for each subdirectory utils/Util/ and texk/Prog/ not yet configured, this first runs `configure' and if required `make all' in that directory. Subsequently, this recurses into all required subdirectories to (re-)build, run tests, install, etc. 3.3 Parallel builds ------------------- The TL build system allows for parallel builds ('make -j n' with n>1), carefully formulating Make rules when a tool (such as 'tangle' or 'convert') creates several output files. This can considerably speed up a TL build on multi core systems. I usually use 'make -j 4 -l 8.0'; please report any failures. 3.4 Using a Configure Cache File -------------------------------- Further speed up of a TL build can be achieved by using a configure cache file, e.g., running 'configure -C' at the top-level. This should work after some initial problem have been fixed; please report any failures. 3.5 Comments ------------ 3.5.1 Comment 1 --------------- After successfully running 'make' from the top-level, as second 'make' should not have to rebuild anything. When configure scripts have been modified, it may take several iterations of 'make' (only in in tekx/web2c/) until everything has stabilized. This is a problem that still needs investigation, but I believe that after the first iteration everything is up to date, except for some bad timestamps. 3.5.2 Comment 2 --------------- If running 'make' from the top-level fails in a subdirectory libs/*/, utils/*/, or /texk/*/ you can remove that directory from the build tree, fix the problem, and once again run 'make' from the top-level. 3.5.3 Comment 3 --------------- The build system allows to successfully run 'make dist' and 'make distcheck' (at least on my {i686,x86_64}-linux-gnu systems), producing tarballs tex-live-2009-MM-DD.tar.{bz2,gz} from which everything can be (re-)built; please keep it that way! 3.5.4 Comment 4 --------------- The process described above configures all directories, even for libraries and programs not to be built. This is necessary for Make targets such as `dist' or `distcheck' that have to recurse into all subdirectories, whereas normal targets such as `all', `check', or `install' only recurse into the required subdirectories. As a side effect, if building in utils/Util/ or texk/Prog/ has been disabled, the Makefile in that directory still contains all the rules to build everything. Thus running 'make' and 'make install' in that subdirectory will build and install everything, unless some configure tests have failed because required libraries from the TL tree where missing when that subdirectory has been configured. Similarly, when, e.g., building e-TeX has been disabled (as by default), you can run 'make etex' (or 'make etex.exe') in the subdirectory texk/web2c/ to build e-TeX (although there is no simple way to have e-TeX installed).