tlbuild: Build one package
4.5 Build one package
=====================
To build one package, the basic idea is to use the 'configure' option
'--disable-all-pkgs' (⇒--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, first building any
required libraries.
Here is an example from start to finish for working on 'dvipdfm-x'.
(Unfortunately, this does not suffice for building the TeX engines; see
the next section.)
mkdir mydir && cd mydir # new working directory
# Get sources (<https://tug.org/texlive/svn>), e.g.:
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 || echo fail
# Do the make:
make >&outm || echo fail
# Test:
cd texk/dvipdfm-x
make check
Then you can modify source files in 'mydir/texk/dvipdfm-x' and rerun
'make' in 'mydir/Work/texk/dvipdfm-x' to rebuild; that build directory
is where the binary ends up and where you can run a debugger, etc.
The second line of the 'configure' 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 'configure' by enabling a
cache file, and the 'CFLAGS' and 'CXXFLAGS' settings eliminate compiler
optimization for debugging purposes.
Of course, you need to 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'. It is also a good
idea to run 'make check' after making any changes, to ensure that
whatever tests have been written still pass.
Finally, the above retrieves the entire TL source tree (several
hundred megabytes). 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 of
this approach, see the 'build-pdftex.sh' script in the 'pdftex'
development source (details at <http://pdftex.org>), which is indeed
such a cut-down TL source tree.
Some libraries and programs require C++11. If you want to build with
an older compiler lacking such support, you need to (re)move those
source directories; specifying '--disable' for them does not suffice,
unfortunately. Specifically, before running 'configure':
rm -rf libs/icu libs/graphite2 texk/dvisvgm
Also, even with '--disable-all-pkgs', dependencies are (currently)
checked. For instance, if a (non-MacOSX) system does not have
'fontconfig', XeTeX cannot be built (⇒Prerequisites), and
'configure' will terminate even with '--disable-xetex'. To proceed
without such dependencies, specify '--enable-missing' also. (Patches to
improve this would be most welcome.)
By default, the 'gcc' compilers will be used if present; otherwise,
individual packages may use something different. You can explicitly
specify the compilers to be used with the environment variables 'CC',
'CXX', and 'OBJCXX'.