Info Catalog tlbuild: Build distribution tlbuild: Building tlbuild: Build one engine

tlbuild: Build one package

 
 4.4 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
 
      # Run the tests:
      cd texk/dvipdfm-x
      make check
 
      # Run the new binary in the build tree, finding support files
      # in a separate tree for a TeX Live release YYYY
      # (Bourne shell syntax):
      TEXMFROOT=/usr/local/texlive/YYYY \
      TEXMFCNF=$TEXMFROOT/texmf-dist/web2c \
      ./xdvipdfmx ...
 
    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.
 
 Reducing source download size
 .............................
 
 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.
 
 GCC used by default
 ...................
 
 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'.
 
 Removing C+11 dependency
 ........................
 
 Some libraries and programs require C++11; one such is XeTeX. If you
 want to build with an older compiler lacking such support, you need to
 (re)move those source directories; unfortunately, specifying '--disable'
 for them does not suffice.  It's also necessary to specify
 '--disable-xetex' explicitly.  Specifically, before running 'configure
 --disable-xetex ...':
 
      rm -rf libs/icu libs/graphite2 texk/dvisvgm texk/web2c/xetexdir
 
    Also, even with '--disable-all-pkgs', dependencies are (currently)
 checked.  One notable case: if a (non-MacOS) 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.
 
    As of 2022, HarfBuzz also requires C++11.  Therefore even more would
 have to be disabled and removed, notably including 'luahbtex', the
 standard engine used for LuaLaTeX.  Removing that would not be
 acceptable for builds intended for distribution; but perhaps for testing
 the above information could still be useful.
 
    In general, the TL 'configure' will run in all directories.
 Therefore a general workaround for build problems is to remove failing
 directories from the tree, and also specify the relevant '--disable-...'
 option(s).
 
    Patches to improve all this would be most welcome.
 

Info Catalog tlbuild: Build distribution tlbuild: Building tlbuild: Build one engine