summaryrefslogtreecommitdiff
path: root/Build/source/README.2building
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/source/README.2building
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/source/README.2building')
-rw-r--r--Build/source/README.2building129
1 files changed, 98 insertions, 31 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.