diff options
Diffstat (limited to 'Build/source/README.layout')
-rw-r--r-- | Build/source/README.layout | 242 |
1 files changed, 0 insertions, 242 deletions
diff --git a/Build/source/README.layout b/Build/source/README.layout deleted file mode 100644 index 5eb9c923135..00000000000 --- a/Build/source/README.layout +++ /dev/null @@ -1,242 +0,0 @@ -Copyright (C) 2009-2012 Peter Breitenlohner <tex-live@tug.org> -You may freely use, modify and/or distribute this file. - - Design of the TeX Live (TL) build system - ======================================== - -The TL build system has been completely redesigned, using Autoconf, -Automake, and Libtool. The main components are TeX specific or utility -program modules (directories texk/*/ and utils/*/), and TeX specific or -generic library modules (directories texk/kpathsea/, texk/ptexenc/, and -libs/*/) providing libraries required by the program modules. - -The primary design goal was modularity. Each module specifies its own -requirements and properties, such as required libraries, whether an -installed (system) version of a library can be used, configure options to be -seen at the top-level, and more. Consequently an explicit list of all -available modules is kept only in one central place. - -A second, related goal was to configure and build each library before -configuring any (program or other library) module 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 a system version of that library. - -Most generic libraries and several programs that are maintained independently -use the distributed source tree, with any patches to that source tree -also kept separately as precise documentation of our changes. - -All this should simplify upgrading of modules maintained independently -and/or integrating new modules into the TL build system. - - Layout of the TL build system - ============================= - -1. Layout of directories -======================== - -1.1. Overall layout -------------------- - -texk/kpathsea/ the two TeX specific libraries, Kpathsea -texk/ptexenc/ and Ptexenc -libs/Lib/ generic library Lib (zlib, libpng, t1lib, etc.) -texk/Prog/ TeX specific program package Prog (web2c, afm2pl, etc.) -utils/Util/ utility program package Util (chktex, ps2eps, etc.) - -auxdir/auxsub/ dummy module used to configure the real modules - -*/*/ac/*.ac various configure.ac fragments (configure options) - -build-aux/ auxiliary build scripts (config.guess etc.) - -m4/kpse-pkgs.m4 Autoconf macros defining lists of library and program - modules and handling loops over these lists -m4/*.m4 other Autoconf macros - -texk/am/*.am Makefile.am fragments -texk/web2c/am/*.am for the Kpathsea library -texk/web2c/*/am/*.am and the Web2C programs - -1.1.1. The TeX specific libraries - -texk/kpathsea/ac/withenable.ac defines that kpathsea requires no other libraries -texk/kpathsea/ac/kpathsea.ac defines basic tests for a system version of kpathsea -texk/kpathsea/ac/mktex.ac configure options also seen at the top-level -m4/kpse-kpathsea-flags.m4 defines Autoconf macros for configure options - as well as KPSE_KPATHSEA_FLAGS defining - Make variables and to be used in configure.ac - files for modules depending on kpathsea. - -texk/ptexenc/ac/withenable.ac defines that ptexenc requires kpathsea -texk/ptexenc/ac/ptexenc.ac defines basic tests for a system version of ptexenc -m4/kpse-ptexenc-flags.m4 defines Autoconf macros for configure options - as well as KPSE_PTEXENC_FLAGS defining - Make variables and to be used in configure.ac - files for modules depending on ptexenc. - -1.1.2 A generic library `Lib' - -libs/Lib/ac/withenable.ac defines libraries required by Lib (if any) -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 defining - Make variables and to be used in configure.ac - files for modules depending on this library. - -1.1.3. A TeX specific 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.1.4. A utility program `Util' - -utils/Util/ac/withenable.ac defines libraries required by Util, provides - the configure option --disable-Util - -1.2. The individual modules ---------------------------- - -All generic libraries and many programs are maintained independently and use -the distributed source tree, with any patches to that source tree kept as -documentation of our changes. There are several types of proxy or wrapper -build systems for these modules. - -1.2.1. A proxy build system, e.g., for libs/zlib/ - -libs/zlib/zlib-1.2.7/ (almost) unmodified source tree -libs/zlib/zlib-1.2.7-PATCHES/ modifications applied to that source tree -libs/zlib/Makefile.am proxy Makefile.am -libs/zlib/configure.ac and configure.ac - -In these cases the build system of the distributed source tree is ignored. -The header files for many libraries are `installed' (as symlinks) under -libs/Lib/include/ in the build tree exactly as they are for a system version -under, e.g., /usr/include/. - -1.2.2. A wrapper build system, e.g., for libs/freetype2/ - -libs/freetype2/freetype-2.4.9/ (almost) unmodified source tree -libs/freetype2/freetype-2.4.9-PATCHES/ modifications applied to that source tree -libs/freetype2/Makefile.am wrapper Makefile.am -libs/freetype2/configure.ac and configure.ac - -Configuring libs/freetype2/ will create the wrapper Makefile handling all -targets except 'all'. For 'make all' this will run the configure script of -the distribution and then run 'make all' and usually also 'make install' to -`install' the library and headers in the build tree - -1.2.3. A mixed build system, e.g., for utils/xindy/ - -utils/xindy/xindy-2.4/ (almost) unmodified source tree -utils/xindy/xindy-2.4-PATCHES/ modifications applied to that source tree -utils/xindy/Makefile.am wrapper Makefile.am -utils/xindy/configure.ac proxy configure.ac - -Configuring utils/xindy/ (or texk/lcdf-typetools/) will create the wrapper -Makefile and the Makefiles of the distribution. The wrapper Makefile will -essentially just invoke the top-level Makefile of the distribution. This -requires that the Makefiles of the distribution allow a VPATH build, can -handle all targets, and do not refer to $(top_srcdir) or $(top_builddir). - -2. Running `configure' -====================== - -Running 'configure' for the top-level directory will in addition configure -the directories auxdir/auxsub/, libs/, utils/, and texk/. This will -determine the programs (utils/Util/ and texk/Prog/) to be built and -libraries from the TL tree (texk/kpathsea/, texk/ptexenc/, and libs/Lib/) -required by these programs. - -3. Running `make' at the top-level -================================== - -First, if texk/kpathsea/ or texk/ptexenc/ is not yet configured, this runs -`configure' and if required `make all' in that directory. Then this -recurses into all required subdirectories texk/kpathsea/, texk/ptexenc/, -libs/, utils/, and texk/ for the selected Make target: `default' or `all' to -(re-)build, `check' to run tests, `install' etc. - -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 dependencies as well as 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' or even 'make -j' with up to 50 compilations in parallel. - -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. - -3.5 Comments ------------- - -3.5.1 Comment 1 ---------------- - -After successfully running 'make' from the top-level, as second 'make' -has nothing to rebuild. - -When configure scripts or source files have been modified, a second 'make' -will rebuild only as required. - -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 TL build system successfully runs 'make dist' and 'make distcheck' -(at least on my {i686,x86_64}-linux-gnu systems), producing tarballs -tex-live-20YY-MM-DD.tar.{gz,xz} 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 -the normal targets `all', `check', or `install' only recurse into the -required subdirectories. - -As a side effect, this allows building all programs `on demand'. If, e.g., -building in utils/Util/ or texk/Prog/ has been disabled, the Makefile in -that directory still contains all build rules. Thus running 'make' and -'make install' in that directory will build and install everything. - -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). - -Consider the extreme case of running configure with '--disable-all-pkgs', -i.e., no programs and consequently no libraries are to be built. Running -'make' will then configure all library and program directories but build -nothing; similarly 'make install' will install nothing. Nevertheless next -running, e.g., 'make tex' in the subdirectory texk/web2c/ will build first -the Kpathsea library, then tangle, and finally tex. |