Copyright (C) 2009-2013 Peter Breitenlohner You may freely use, modify and/or distribute this file. Modifying the TeX Live (TL) build system ======================================== 1. Currently used versions of tools =================================== In general, we use the latest released versions of GNU build tools. We install these directly from the original GNU releases (e.g., by building them with configure --prefix=/usr/local/gnu and having /usr/local/gnu/bin first in our PATH). autoconf (GNU Autoconf) 2.69 automake (GNU automake) 1.14 ltmain.sh (GNU libtool) 2.4.2 bison (GNU Bison) 3.0 flex 2.5.37 m4 (GNU M4) 1.4.16 2. Updating the TL build system =============================== When anything in the TL build system (configure.ac and Makefile.am files with their fragments or M4 macros in m4/) has been modified you have to rebuild the coresponding configure, Makefile.in, config.h or c-auto.h, or other generated files. You should use the versions mentioned above. This is most easily done automatically using maintainer-mode. The files in the SVN repository are all up to date, but some of them may be rebuilt in maintainer-mode due to their timestamps (this is somewhat tedious to avoid due to SVN's handling of timestamps). Alternatively, you can run the 'reautoconf' script from the top-level. The 'config.guess', 'config.sub', etc. files for most packages are kept centrally in build-aux/, sourced from GNU Gnulib (http://www.gnu.org/software/gnulib), which in turn pulls them from their ultimate upstream source repository. There are, however, independent copies in, e.g., libs/freetype2/freetype-*/builds/unix/, and similar places. The 'reautoconf' script does not take care of those, but a TL cron job does keep them in sync (nightly). 3. Extending the TL build system ================================ 3.1 Adding a new program directory ---------------------------------- To add a new program directory utils/Util/ (not using Kpathsea) or texk/Prog/ (possibly using Kpathsea and Ptexenc) you must add the directory Util to the M4 list kpse_utils_pkgs or Prog to the M4 list kpse_texk_pkgs defined in m4/kpse-pkgs.m4. In addition you must create a configure.ac fragment utils/Util/ac/withenable.ac or texk/Prog/ac/withenable.ac defining any required libraries from the TL tree and whether this new program is to be built by default (in the absence of the corresponding '--enable-Util/Prog' or '--disable-Util/Prog' configure options). If a program in texk/Prog/ or utils/Util/ requires specific configure options to be seen at the top-level, they should be defined in an additional configure.ac fragment texk/Prog/ac/Prog.ac or utils/Util/ac/Util.ac (included from texk/Prog/ac/withenable.ac and texk/Prog/configure.ac or utils/Util/ac/withenable.ac and utils/Util/configure.ac) as, e.g., for texk/web2c/, texk/xdvik/, and utils/xindy/. As an example, the file texk/dvipdfmx/ac/withenable.ac contains KPSE_ENABLE_PROG([dvipdfmx], [kpathsea libpng]) where KPSE_ENABLE_PROG, defined in m4/kpse-setup.m4, has one required argument -- the name of the subdirectory -- and three optional arguments: a list of required TL libraries (zlib is implied by libpng and need not be mentioned), a list of options ('disable' if this program is not to be built by default, 'native' if cross compilation is not possible, 'x' if this program requires X11), and a comment added to the help text for the disable or enable configure option for this program. 3.2 Adding a new generic library directory ------------------------------------------ To add a new generic library directory libs/Lib/ you must add the directory Lib to the M4 list kpse_libs_pkgs defined in m4/kpse-pkgs.m4. In addition you must create a configure.ac fragment libs/Lib/ac/withenable.ac defining any required libraries from the TL tree and whether an installed (system) version of this library can be used. If that is the case, another configure.ac fragment libs/Lib/ac/Lib.ac should specify a small program as test for a system version to be acceptable. Finally you must create a file m4/kpse-Lib-flags.m4 defining the M4 macro KPSE_LIB_FLAGS (where 'LIB' is a sanitized uppercase version of 'Lib') setting up the Make variables LIB_INCLUDES, LIB_LIBS, and LIB_DEPEND with the required values for CPPFLAGS, LDADD, and dependencies, as well as LIB_RULE with a (multiline) Make rule to rebuild that library when necessary. If a system version of the library can be used, another M4 macro KPSE_LIB_SYSTEM_FLAGS in m4/kpse-Lib-flags.m4 must define values for LIB_INCLUDES and LIB_LIBS, and you must add the line 'AC_REQUIRE([KPSE_LIB_SYSTEM_FLAGS])' to the definition of the M4 macro KPSE_ALL_SYSTEM_FLAGS in m4/kpse-pkgs.m4. In many cases LIB_INCLUDES and LIB_LIBS are constructed from values for the configure options '--with-Lib-includes' and/or '--with-Lib-libdir'; alternatively they may result from running pkg-config, freetype-config, or similar. As an example, the file libs/libpng/ac/withenable.ac contains KPSE_WITH_LIB([libpng], [zlib]) where KPSE_WITH_LIB, defined in m4/kpse-setup.m4, has one required argument -- the name of the subdirectory -- and two optional arguments: a list of required TL libraries, and a list of options ('tree' if only the library from the TL tree can be used). The file libs/libpng/ac/libpng.ac contains KPSE_TRY_LIB([libpng], [#include ], [png_structp png; png_voidp io; png_rw_ptr fn; png_set_read_fn(png, io, fn);]) where KPSE_TRY_LIB, defined in m4/kpse-setup.m4, has three required arguments -- the name of the subdirectory and two AC_LANG_PROGRAM arguments. This causes the configure script to compile and link the C program #include int main () { png_structp png; png_voidp io; png_rw_ptr fn; png_set_read_fn(png, io, fn); return 0; } as sanity check for using an installed PNG library. The analogous macro KPSE_TRY_LIBXX uses the C++ compiler. 3.3 Adding a new TeX specific library directory ----------------------------------------------- To add a new TeX specific library directory texk/Lib/ proceed as for a generic library (described above) with these exceptions: (*) Add the directory Lib to the M4 list kpse_texlibs_pkgs (also defined in m4/kpse-pkgs.m4) instead of kpse_libs_pkgs. (*) The configure.ac fragment libs/Lib/ac/withenable.ac must use KPSE_WITH_TEXLIB instead of KPSE_WITH_LIB. (*) The new library must not depend on any generic libraries. 4. Using libraries from the TL tree =================================== The TL build system provides Autoconf macros for all libraries in the TL tree. A program requiring additional libraries must use standard Autoconf and Automake features (such as AC_ARG_WITH to specify their installation directories, AC_CHECK_LIB and AC_CHECK_FUNCS for library functions, AC_CHECK_HEADERS for header files). 4.1 configure.ac ---------------- In order to use, e.g., libpng (either an installed version or from the TL tree) configure.ac must use KPSE_ZLIB_FLAGS and KPSE_LIBPNG_FLAGS. As a consequence the Make variables LIBPNG_DEPEND, LIBPNG_INCLUDES, LIBPNG_LIBS, and LIBPNG_RULE (and analogous ZLIB_* variables) will be defined. A program may wish to examine features of the PNG library. To do so configure.ac must use KPSE_ADD_FLAGS([zlib]) followed by test for zlib features (if any) and KPSE_ADD_FLAGS([libpng]) followed by tests for libpng features. These macros temporarily add appropriate values to CPPFLAGS and LIBS. The tests must be terminated by KPSE_RESTORE_FLAGS in order to restore CPPFLAGS and LIBS to their former values. 4.2 Makefile.am --------------- In order to use, e.g., libpng (and zlib) the Make variables mentioned above must be used in Makefile.am as follows $(LIBPNG_INCLUDES) $(ZLIB_INCLUDES) must be added to AM_CPPFLAGS (or target specific target_CPPFLAGS). $(LIBPNG_LIBS) $(ZLIB_LIBS) must be added to LDADD or target_LDADD. $(LIBPNG_DEPEND) $(ZLIB_DEPEND) should be added to target_DEPENDENCIES such that rebuilding zlib and/or libpng causes the target to be rebuilt. Two lines containing @ZLIB_RULE@ and @LIBPNG_RULE@ create the rules required to (re-)build zlib and libpng when necessary.