diff options
author | Karl Berry <karl@freefriends.org> | 2014-05-01 16:21:16 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2014-05-01 16:21:16 +0000 |
commit | d70f477753c9fe3b147dcc8ec32676a2206aa277 (patch) | |
tree | 000c8cef7cc4f52426b2889d442daec45940924d /Build/source/doc/tlbuild.texi | |
parent | a0f2f92d8061cd9861314b924f8caebe6d43f133 (diff) |
split building chapter into sections
git-svn-id: svn://tug.org/texlive/trunk@33779 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/doc/tlbuild.texi')
-rw-r--r-- | Build/source/doc/tlbuild.texi | 169 |
1 files changed, 143 insertions, 26 deletions
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} |