summaryrefslogtreecommitdiff
path: root/Build
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-05-01 16:21:16 +0000
committerKarl Berry <karl@freefriends.org>2014-05-01 16:21:16 +0000
commitd70f477753c9fe3b147dcc8ec32676a2206aa277 (patch)
tree000c8cef7cc4f52426b2889d442daec45940924d /Build
parenta0f2f92d8061cd9861314b924f8caebe6d43f133 (diff)
split building chapter into sections
git-svn-id: svn://tug.org/texlive/trunk@33779 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build')
-rw-r--r--Build/source/README.2building129
-rw-r--r--Build/source/README.5configure19
-rw-r--r--Build/source/README.6cross7
-rw-r--r--Build/source/doc/ChangeLog6
-rw-r--r--Build/source/doc/tlbuild.info352
-rw-r--r--Build/source/doc/tlbuild.texi169
6 files changed, 506 insertions, 176 deletions
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 (<http://tug.org/texlive/svn>)
+ 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 (<http://pdftex.org>), which
+are indeed a cut-down TL source tree.
diff --git a/Build/source/README.5configure b/Build/source/README.5configure
index f94b0ae674d..605a1db1201 100644
--- a/Build/source/README.5configure
+++ b/Build/source/README.5configure
@@ -163,8 +163,17 @@ Do or do not build and install the program(s) of the module 'PROG'.
--------------------------
Do not build any program modules by default--only those explicitly
-enabled. Without this option, all modules are built except those that
-are explicitly disabled or specify 'disable' in their 'ac/withenable.ac'
+enabled. This is useful when one wants to work on only a single
+program, which is specified with an additional '--enable' option, e.g.,
+'--enable-dvipdfm-x'. It's still simplest to check out and configure
+the whole source tree, but at least only the program you are interested
+in, and its dependencies, are built. The 'configure' will generally
+take less than a minute with everything disabled. (It is a good idea to
+run 'make check' after doing this, and after making any changes, to
+ensure that whatever tests have been written still pass.)
+
+ Without this option, all modules are built except those that are
+explicitly disabled or specify 'disable' in their 'ac/withenable.ac'
fragment.
7.2.3 Configure options for 'texk/web2c'
@@ -251,10 +260,12 @@ libraries).
The former modules 'dvipdfmx' (extended DVI to PDF converter) and
'xdvipdfmx' (the same, as used by XeTeX) have been merged into
-'dvipdfm-x'.
+'dvipdfm-x' at the source level. Two separate binaries are still
+created by default. In addition, 'dvipdfm' is created as a symlink to
+'dvipdfmx', with backward-compatible (very slightly different) behavior.
'--disable-dvipdfmx'
-Do not build the 'dvipdfmx' program.
+Do not build the 'dvipdfmx' program or create the 'dvipdfm' symlink.
'--disable-xdvipdfmx'
Do not build the 'xdvipdfmx' program (building 'xdvipdfmx' requires the
diff --git a/Build/source/README.6cross b/Build/source/README.6cross
index 8527564f7f2..71894cde31d 100644
--- a/Build/source/README.6cross
+++ b/Build/source/README.6cross
@@ -84,9 +84,14 @@ avoided if possible and otherwise must supply a pessimistic test result.
(auxiliary or installable) programs. Auxiliary programs can be placed
into a subdirectory that is configured natively as is done for
'texk/web2c/web2c', 'texk/dvipsk/squeeze', and 'texk/xdvik/squeeze'.
-The module 'libs/freetype' uses the value of 'CC_BUILD', 'BUILD-gcc',
+The module 'libs/freetype2' uses the value of 'CC_BUILD', 'BUILD-gcc',
'gcc', or 'cc' as compiler for the auxiliary program.
+ Building LuaTeX (or LuaJITTeX) uses the auxiliary program 'txt2zlib'
+to create 'pdflua.c' and, if necessary, update the distributed version
+of that file. In a cross compilation we simply use that distributed
+file.
+
The situation for installable programs needed by the build process is
somewhat different. A quite expensive possibility, chosen for the ICU
libraries in module 'libs/icu', is to first compile natively for the
diff --git a/Build/source/doc/ChangeLog b/Build/source/doc/ChangeLog
index 7948264da4f..b7a80a43bb5 100644
--- a/Build/source/doc/ChangeLog
+++ b/Build/source/doc/ChangeLog
@@ -1,3 +1,8 @@
+2014-05-01 Karl Berry <karl@tug.org>
+
+ * tlbuild.texi (Building): split into sections.
+ Give full example of working on a single program.
+
2014-04-09 Karl Berry <karl@tug.org>
Peter Breitenlohner <peb@mppmu.mpg.de>
@@ -11,3 +16,4 @@
* doc/build.texi: Fixed some typos.
+(This ChangeLog file is in the public domain.)
diff --git a/Build/source/doc/tlbuild.info b/Build/source/doc/tlbuild.info
index 0622c28997f..12c5277a9ba 100644
--- a/Build/source/doc/tlbuild.info
+++ b/Build/source/doc/tlbuild.info
@@ -20,7 +20,7 @@ versions, except that this permission notice may be stated in a
translation approved by the TeX Users Group.
INFO-DIR-SECTION TeX
START-INFO-DIR-ENTRY
-* TeX Live building: (tlbuild). TL configuration and development.
+* TL-build: (tlbuild). TeX Live configuration and development.
END-INFO-DIR-ENTRY

@@ -62,6 +62,9 @@ found in other TL documentation resources, such as:
* The TeX Live web pages: <http://tug.org/texlive>.
+ * The web page with an overview of how to build the binaries which
+ Are distributed with TeX Live: <http://tug.org/texlive/build.html>.
+
* The TeX Live user manual: <http://tug.org/texlive/doc.html>, or run
'texdoc texlive'.
@@ -200,7 +203,21 @@ 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
+* Menu:
+
+* Build iteration:: What 'configure' and 'make' do.
+* Build problems:: If the build fails.
+* Build in parallel:: Simultaneous 'make' processes.
+* Build distribution:: Making a distribution tarball.
+* Build one package:: Example of working on just one program.
+
+
+File: tlbuild.info, Node: Build iteration, Next: Build problems, Up: Building
+
+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
@@ -219,37 +236,113 @@ 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
+
+File: tlbuild.info, Node: Build problems, Next: Build in parallel, Prev: Build iteration, Up: Building
+
+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).
+
+
+File: tlbuild.info, Node: Build in parallel, Next: Build distribution, Prev: Build problems, Up: Building
+
+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).
+
+
+File: tlbuild.info, Node: Build distribution, Next: Build one package, Prev: Build in parallel, Up: Building
+
+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::.
+
+
+File: tlbuild.info, Node: Build one package, Prev: Build distribution, Up: Building
+
+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 (<http://tug.org/texlive/svn>)
+ 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 (<http://pdftex.org>), which
+are indeed a cut-down TL source tree.

File: tlbuild.info, Node: Installing, Next: Layout and infrastructure, Prev: Building, Up: Top
@@ -1289,8 +1382,17 @@ File: tlbuild.info, Node: '--disable-all-pkgs', Next: Configure options for 't
--------------------------
Do not build any program modules by default--only those explicitly
-enabled. Without this option, all modules are built except those that
-are explicitly disabled or specify 'disable' in their 'ac/withenable.ac'
+enabled. This is useful when one wants to work on only a single
+program, which is specified with an additional '--enable' option, e.g.,
+'--enable-dvipdfm-x'. It's still simplest to check out and configure
+the whole source tree, but at least only the program you are interested
+in, and its dependencies, are built. The 'configure' will generally
+take less than a minute with everything disabled. (It is a good idea to
+run 'make check' after doing this, and after making any changes, to
+ensure that whatever tests have been written still pass.)
+
+ Without this option, all modules are built except those that are
+explicitly disabled or specify 'disable' in their 'ac/withenable.ac'
fragment.

@@ -1386,10 +1488,12 @@ File: tlbuild.info, Node: Configure options for 'texk/dvipdfm-x', Next: Config
The former modules 'dvipdfmx' (extended DVI to PDF converter) and
'xdvipdfmx' (the same, as used by XeTeX) have been merged into
-'dvipdfm-x'.
+'dvipdfm-x' at the source level. Two separate binaries are still
+created by default. In addition, 'dvipdfm' is created as a symlink to
+'dvipdfmx', with backward-compatible (very slightly different) behavior.
'--disable-dvipdfmx'
-Do not build the 'dvipdfmx' program.
+Do not build the 'dvipdfmx' program or create the 'dvipdfm' symlink.
'--disable-xdvipdfmx'
Do not build the 'xdvipdfmx' program (building 'xdvipdfmx' requires the
@@ -1858,14 +1962,14 @@ Index
* --bindir configure option: '--prefix' '--bindir' ....
(line 6)
* --build=HOST: Cross configuring. (line 6)
-* --disable-all-packages configure option: Building. (line 46)
+* --disable-all-packages configure option: Build one package. (line 6)
* --disable-all-pkgs: '--disable-all-pkgs'. (line 6)
* --disable-bibtex8: Configure options for 'texk/bibtex-x'.
(line 9)
* --disable-dump-share: Configure options for 'texk/web2c'.
(line 27)
* --disable-dvipdfmx: Configure options for 'texk/dvipdfm-x'.
- (line 10)
+ (line 12)
* --disable-etex-synctex: Configure options for 'texk/web2c'.
(line 64)
* --disable-ipc: Configure options for 'texk/web2c'.
@@ -1888,7 +1992,7 @@ Index
* --disable-web-progs: Configure options for 'texk/web2c'.
(line 46)
* --disable-xdvipdfmx: Configure options for 'texk/dvipdfm-x'.
- (line 13)
+ (line 15)
* --enable-*win for Metafont window support: Configure options for 'texk/web2c'.
(line 60)
* --enable-auto-core: Configure options for 'texk/web2c'.
@@ -1924,7 +2028,7 @@ Index
* --host=HOST: Cross configuring. (line 6)
* --libdir: '--enable-multiplatform'.
(line 6)
-* --no-clean Build option: Building. (line 40)
+* --no-clean Build option: Build problems. (line 6)
* --prefix configure option: '--prefix' '--bindir' ....
(line 6)
* --with-banner-add=STR: Configure options for 'texk/web2c'.
@@ -1963,6 +2067,8 @@ Index
(line 12)
* --without-ln-s: '--without-ln-s'. (line 6)
* --without-x: '--without-x'. (line 6)
+* -C configure option: Build in parallel. (line 11)
+* -j make option: Build in parallel. (line 6)
* adapting TeX Live for distros: Distro builds. (line 54)
* adding a new generic library: Adding a new generic library module.
(line 6)
@@ -1991,17 +2097,23 @@ Index
(line 6)
* BSD distro: Distro builds. (line 6)
* build directory, required: Building. (line 17)
-* build on demand: Building. (line 46)
+* build iteration: Build iteration. (line 6)
+* build on demand: Build one package. (line 6)
+* build one package: Build one package. (line 6)
+* build problems: Build problems. (line 6)
* Build script: Building. (line 6)
* build system, design of: Overview of build system.
(line 6)
* BUILDCC, BUILDCFLAGS, ...: Cross configuring. (line 42)
* building: Building. (line 6)
+* building a distribution: Build distribution. (line 6)
+* building in parallel: Build in parallel. (line 6)
* C, ANSI, required: Declarations and definitions.
(line 6)
* C99, avoided: Declarations and definitions.
(line 6)
-* cache for 'configure': Building. (line 58)
+* cache file, for 'configure': Build in parallel. (line 11)
+* cache for 'configure': Build in parallel. (line 6)
* callexe.c: Macros for Windows. (line 32)
* CC: Variables for configure.
(line 10)
@@ -2062,6 +2174,7 @@ Index
(line 11)
* declarations and definitions, in source code: Declarations and definitions.
(line 6)
+* dependencies, with several output files: Build in parallel. (line 6)
* DESTDIR: '--prefix' '--bindir' ....
(line 9)
* directories, for installation: Installation directories.
@@ -2069,7 +2182,9 @@ Index
* directories, top-level: Top-level directories.
(line 6)
* discards qualifiers warning: Const. (line 30)
-* distribution tarball, making: Building. (line 65)
+* 'dist' and 'distcheck' targets for 'make': Build distribution.
+ (line 6)
+* distribution tarball, making: Build distribution. (line 6)
* distro, building for: Distro builds. (line 6)
* dvipdfmx: Configure options for 'texk/dvipdfm-x'.
(line 6)
@@ -2083,6 +2198,7 @@ Index
(line 43)
* 'extra/' top-level directory: Top-level directories.
(line 39)
+* failure to build: Build problems. (line 6)
* 'ffcall', required by 'xindy': Prerequisites. (line 30)
* flags, macros for library and header: Macros for library and header flags.
(line 6)
@@ -2123,8 +2239,8 @@ Index
* interprocess communication: Configure options for 'texk/web2c'.
(line 31)
* introduction: Introduction. (line 6)
-* iteration through sources, by 'configure' and 'make': Building.
- (line 21)
+* iteration through sources, by 'configure' and 'make': Build iteration.
+ (line 6)
* kpathsea library: 'kpathsea' library. (line 6)
* kpathsea.ac: 'kpathsea' library. (line 20)
* kpse-libpng-flags.m4: 'png' library. (line 43)
@@ -2245,6 +2361,7 @@ Index
* motif: Configure options for 'texk/xdvik'.
(line 9)
* native cross compilation: Cross compilation. (line 10)
+* one package, building: Build one package. (line 6)
* OpenGL, required for Asymptote: 'asymptote'. (line 6)
* operating system distribution, building for: Distro builds. (line 6)
* opl2ofm, et al.: Configure options for 'texk/web2c'.
@@ -2253,7 +2370,7 @@ Index
* overall build process: Building. (line 6)
* Par::Packer: Variables for configure.
(line 46)
-* parallel build: Building. (line 58)
+* parallel build: Build in parallel. (line 6)
* paths, for installation: Installation directories.
(line 6)
* PDF files, size of: '--disable-largefile'.
@@ -2277,6 +2394,7 @@ Index
* preloaded binaries: Configure options for 'texk/web2c'.
(line 50)
* prerequisites for building: Prerequisites. (line 6)
+* problems with build: Build problems. (line 6)
* program module, adding: Adding a new program module.
(line 6)
* program modules: Program modules. (line 6)
@@ -2294,6 +2412,7 @@ Index
* shared libraries, using vs. avoiding: Distro builds. (line 11)
* size of PDF and PS files: '--disable-largefile'.
(line 10)
+* size of source tree: Build one package. (line 57)
* source code declarations: Declarations and definitions.
(line 6)
* source directory building, not supported: Building. (line 17)
@@ -2375,73 +2494,78 @@ Index

Tag Table:
-Node: Top987
-Node: Introduction1780
-Node: Overview of build system2815
-Node: Prerequisites4879
-Node: Building6981
-Node: Installing10631
-Node: Installation directories11659
-Node: Linked scripts13479
-Node: Distro builds14627
-Node: Layout and infrastructure17007
-Node: Build system tools17796
-Node: Top-level directories19808
-Node: Autoconf macros21875
-Node: General setup macros22576
-Node: Macros for programs23443
-Node: Macros for compilers24255
-Node: Macros for libraries25689
-Node: Macros for library and header flags26115
-Node: Macros for Windows27984
-Node: Library modules29561
-Node: 'png' library30058
-Node: 'zlib' library32351
-Node: 'freetype' library32872
-Node: 'kpathsea' library33406
-Node: Program modules34830
-Node: 't1utils' package35266
-Node: 'xindy' package35833
-Node: 'xdvik' package37012
-Node: 'asymptote'38091
-Node: Extending TeX Live38546
-Node: Adding a new program module38914
-Node: Adding a new generic library module40433
-Node: Adding a new TeX-specific library module42646
-Node: Configure options43333
-Node: Global configure options44724
-Node: '--disable-native-texlive-build'45292
-Node: '--prefix' '--bindir' ...46288
-Node: '--disable-largefile'46836
-Node: '--disable-missing'47603
-Node: '--enable-compiler-warnings='LEVEL48010
-Node: '--enable-cxx-runtime-hack'48755
-Node: '--enable-maintainer-mode'49188
-Node: '--enable-multiplatform'49723
-Node: '--enable-shared'50284
-Node: '--enable-silent-rules'50661
-Node: '--without-ln-s'51123
-Node: '--without-x'51480
-Node: Program-specific configure options51672
-Node: '--enable-PROG' '--disable-PROG'52335
-Node: '--disable-all-pkgs'52618
-Node: Configure options for 'texk/web2c'53071
-Node: Configure options for 'texk/bibtex-x'55738
-Node: Configure options for 'texk/dvipdfm-x'56314
-Node: Configure options for 'texk/dvisvgm'56924
-Node: Configure options for 'texk/texlive'57814
-Node: Configure options for 'texk/xdvik'58241
-Node: Configure options for 'utils/xindy'58730
-Node: Library-specific configure options59792
-Node: Configure options for 'kpathsea'60806
-Node: Configure options for system 'poppler'61519
-Node: Variables for configure62286
-Node: Cross compilation64792
-Node: Cross configuring66057
-Node: Cross problems67730
-Node: Coding conventions69591
-Node: Declarations and definitions70255
-Node: Const72438
-Node: Index74301
+Node: Top993
+Node: Introduction1786
+Node: Overview of build system2965
+Node: Prerequisites5029
+Node: Building7131
+Node: Build iteration8350
+Node: Build problems9422
+Node: Build in parallel9815
+Node: Build distribution10407
+Node: Build one package10978
+Node: Installing13751
+Node: Installation directories14779
+Node: Linked scripts16599
+Node: Distro builds17747
+Node: Layout and infrastructure20127
+Node: Build system tools20916
+Node: Top-level directories22928
+Node: Autoconf macros24995
+Node: General setup macros25696
+Node: Macros for programs26563
+Node: Macros for compilers27375
+Node: Macros for libraries28809
+Node: Macros for library and header flags29235
+Node: Macros for Windows31104
+Node: Library modules32681
+Node: 'png' library33178
+Node: 'zlib' library35471
+Node: 'freetype' library35992
+Node: 'kpathsea' library36526
+Node: Program modules37950
+Node: 't1utils' package38386
+Node: 'xindy' package38953
+Node: 'xdvik' package40132
+Node: 'asymptote'41211
+Node: Extending TeX Live41666
+Node: Adding a new program module42034
+Node: Adding a new generic library module43553
+Node: Adding a new TeX-specific library module45766
+Node: Configure options46453
+Node: Global configure options47844
+Node: '--disable-native-texlive-build'48412
+Node: '--prefix' '--bindir' ...49408
+Node: '--disable-largefile'49956
+Node: '--disable-missing'50723
+Node: '--enable-compiler-warnings='LEVEL51130
+Node: '--enable-cxx-runtime-hack'51875
+Node: '--enable-maintainer-mode'52308
+Node: '--enable-multiplatform'52843
+Node: '--enable-shared'53404
+Node: '--enable-silent-rules'53781
+Node: '--without-ln-s'54243
+Node: '--without-x'54600
+Node: Program-specific configure options54792
+Node: '--enable-PROG' '--disable-PROG'55455
+Node: '--disable-all-pkgs'55738
+Node: Configure options for 'texk/web2c'56732
+Node: Configure options for 'texk/bibtex-x'59399
+Node: Configure options for 'texk/dvipdfm-x'59975
+Node: Configure options for 'texk/dvisvgm'60814
+Node: Configure options for 'texk/texlive'61704
+Node: Configure options for 'texk/xdvik'62131
+Node: Configure options for 'utils/xindy'62620
+Node: Library-specific configure options63682
+Node: Configure options for 'kpathsea'64696
+Node: Configure options for system 'poppler'65409
+Node: Variables for configure66176
+Node: Cross compilation68682
+Node: Cross configuring69947
+Node: Cross problems71620
+Node: Coding conventions73481
+Node: Declarations and definitions74145
+Node: Const76328
+Node: Index78191

End Tag Table
diff --git a/Build/source/doc/tlbuild.texi b/Build/source/doc/tlbuild.texi
index f434795ed44..9fd0f5d915a 100644
--- a/Build/source/doc/tlbuild.texi
+++ b/Build/source/doc/tlbuild.texi
@@ -47,7 +47,7 @@ approved by the @TeX{} Users Group.
@dircategory TeX
@direntry
-* TeX Live building: (tlbuild). TL configuration and development.
+* TL-build: (tlbuild). TeX Live configuration and development.
@end direntry
@titlepage
@@ -106,6 +106,9 @@ found in other TL documentation resources, such as:
@itemize
@item The @TL{} web pages: @url{http://tug.org/texlive}.
+@item The web page with an overview of how to build the binaries which
+Are distributed with @TL{}: @url{http://tug.org/texlive/build.html}.
+
@item The @TL{} user manual: @url{http://tug.org/texlive/doc.html}, or
run @code{texdoc texlive}.
@@ -294,7 +297,21 @@ An alternative, and the one we will mainly discuss here, is to run
subdirectory. Building in the source directory itself is not
supported (sorry).
+@menu
+* Build iteration:: What @code{configure} and @code{make} do.
+* Build problems:: If the build fails.
+* Build in parallel:: Simultaneous @code{make} processes.
+* Build distribution:: Making a distribution tarball.
+* Build one package:: Example of working on just one program.
+@end menu
+
+
+@node Build iteration
+@section Build iteration
+
+@cindex build iteration
@cindex iteration through sources, by @code{configure} and @code{make}
+
Running the top-level @file{configure} script configures the top level
and the subdirectories @file{libs}, @file{utils}, and @file{texk}.
Running @code{make} at the top-level first iterates over all
@@ -321,6 +338,13 @@ Running the top-level @code{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.
+
+@node Build problems
+@section Build problems
+
+@cindex build problems
+@cindex problems with build
+@cindex failure to build
@vindex --no-clean Build @r{option}
If configuring or building a module fails, you could either
(a)@tie{}find and fix the problem, or (b)@tie{}remove the subdirectory
@@ -328,39 +352,118 @@ for that module from the build tree, and rerun the top-level
@code{make} (or @file{Build} with @code{--no-clean} as its first
argument).
-@vindex --disable-all-packages configure @r{option}
-@cindex build on demand
-With the configure option @code{--disable-all-pkgs}, all program and
-library modules are configured but none of them is built. The
-@file{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 @code{luatex}
-repository to build Lua@TeX{}, essentially from a subset of the
-complete @TL{} tree. Similarly, when, e.g., building the original
-e-@TeX{} has been disabled (as it is by default), one can run
-@code{make etex} (or @code{make etex.exe}) in @file{texk/web2c/} to
-build e-@TeX{} (although there is no comparably simple way to install
-e-@TeX{}).
+@node Build in parallel
+@section Build in parallel
+
+@cindex building in parallel
@cindex parallel build
@cindex cache for @code{configure}
+
+@cindex dependencies, with several output files
+@vindex -j make @r{option}
The TL build system carefully formulates dependencies as well as
@code{make} rules when a tool (such as @code{tangle}, @code{ctangle},
or @code{convert}) creates several output files. This allows for
parallel builds (@code{make -j @var{n}} with @math{@var{n}>1} or even
@code{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 @code{-C} (recommended).
+@cindex cache file, for @code{configure}
+@vindex -C configure @r{option}
+Incidentally, a noticeable speed-up can also be (independently) gained
+by using a configure cache file, i.e., with the option @code{-C}
+(recommended).
+
+
+@node Build distribution
+@section Build distribution
+
+@cindex building a distribution
@cindex distribution tarball, making
+
+@cindex @code{dist} and @code{distcheck} targets for @code{make}
Running @code{make dist} at the top-level creates a tarball
@file{tex-live-@var{yyyy}-@var{mm}-@var{dd}.tar.xz} from the TL source
-tree. Running @code{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.)
+tree. Running @code{make 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; @pxref{Installing}.
+
+@node Build one package
+@section Build one package
+
+@cindex build one package
+@cindex one package, building
+
+@vindex --disable-all-packages configure @r{option}
+@cindex build on demand
+To build one package, the basic idea is to use the @code{configure}
+option @code{--disable-all-pkgs} (@pxref{@code{--disable-all-pkgs}}).
+Then all program and library modules are configured but none are made.
+However, the @file{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 @code{luatex}
+repository to build Lua@TeX{}, essentially from a subset of the
+complete @TL{} tree. Similarly, when, e.g., building the original
+e-@TeX{} has been disabled (as it is by default), one can run
+@code{make etex} (or @code{make etex.exe}) in @file{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 @code{dvipdfmx}.
+
+@example
+mkdir mydir && cd mydir # new working directory
+
+# Get sources (@url{http://tug.org/texlive/svn})
+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
+@end example
+
+Then you modify source files in @file{mydir/texk/dvipdfm-x} and rerun
+@code{make} in @file{mydir/Work/texk/dvipdfm-x} to rebuild.
+
+The second line the @code{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 @code{-C} speeds up
+@code{configure}, and the @code{CFLAGS} and @code{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 @code{configure} options you can
+tweak as desired; check the output from @code{configure --help}.
+
+@cindex size of source tree
+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
+@code{configure} flags to individually disable using system versions
+of libraries, or the intricacies of the dependencies (such as
+@code{teckit} requiring @code{zlib}) will have undesired side effects.
+For an example, see the @code{build-pdftex.sh} script in the
+@code{pdftex} development sources (@url{http://pdftex.org}), which are
+indeed a cut-down TL source tree.
@node Installing
@@ -1593,8 +1696,18 @@ Do or do not build and install the program(s) of the module @code{@var{prog}}.
@vindex --disable-all-pkgs
Do not build any program modules by default---only those explicitly
-enabled. Without this option, all modules are built except those that
-are explicitly disabled or specify @code{disable} in their
+enabled. This is useful when one wants to work on only a single
+program, which is specified with an additional @code{--enable} option,
+e.g., @code{--enable-dvipdfm-x}. It's still simplest to check out and
+configure the whole source tree, but at least only the program you are
+interested in, and its dependencies, are built. The @code{configure}
+will generally take less than a minute with everything disabled. (It
+is a good idea to run @code{make check} after doing this, and after
+making any changes, to ensure that whatever tests have been written
+still pass.)
+
+Without this option, all modules are built except those that are
+explicitly disabled or specify @code{disable} in their
@file{ac/withenable.ac} fragment.
@@ -1721,10 +1834,14 @@ into the module @code{bibtex-x} (extended Bib@TeX{}).
The former modules @code{dvipdfmx} (extended DVI to PDF converter) and
@code{xdvipdfmx} (the same, as used by Xe@TeX{}) have been merged into
-@code{dvipdfm-x}.
+@code{dvipdfm-x} at the source level. Two separate binaries are still
+created by default. In addition, @file{dvipdfm} is created as a
+symlink to @file{dvipdfmx}, with backward-compatible (very slightly
+different) behavior.
@vindex --disable-dvipdfmx
-@noindent @code{--disable-dvipdfmx}@*Do not build the @file{dvipdfmx} program.
+@noindent @code{--disable-dvipdfmx}@*Do not build the @file{dvipdfmx}
+program or create the @file{dvipdfm} symlink.
@vindex --disable-xdvipdfmx
@noindent @code{--disable-xdvipdfmx}@*Do not build the @file{xdvipdfmx}