From d70f477753c9fe3b147dcc8ec32676a2206aa277 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 1 May 2014 16:21:16 +0000 Subject: split building chapter into sections git-svn-id: svn://tug.org/texlive/trunk@33779 c570f23f-e606-0410-a88d-b1316a301751 --- Build/source/README.2building | 129 ++++++++++++++++++++++++++++++++---------- 1 file changed, 98 insertions(+), 31 deletions(-) (limited to 'Build/source/README.2building') diff --git a/Build/source/README.2building b/Build/source/README.2building index 6111516eead..cc4795229f0 100644 --- a/Build/source/README.2building +++ b/Build/source/README.2building @@ -20,7 +20,10 @@ complicated. '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 +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 @@ -39,35 +42,99 @@ iterations consist of two steps: 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 +4.2 Build problems +================== + +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). + +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 -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.) +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 'dvipdfmx'. + + mkdir mydir && cd mydir # new working directory + + # Get sources () + 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/dvipdfmx + 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 the 'configure' are 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' are to 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 500mb). +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 (), which +are indeed a cut-down TL source tree. -- cgit v1.2.3