Copyright (C) 2009, 2010 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 =================================== autoconf (GNU Autoconf) 2.68 automake (GNU automake) 1.11.1 ltmain.sh (GNU libtool) 2.4 bison (GNU Bison) 2.4.3 flex 2.5.35 m4 (GNU M4) 1.4.15 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/. There are, however, independent copies in, e.g., libs/freetype/freetype-1.5/, libs/freetype2/freetype-2.3.8/builds/unix/, and similar places that might need updating (not done automatically by the 'reautoconf' script). 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/witheanble.ac or texk/Prog/ac/witheanble.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 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/witheanble.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 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 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/witheanble.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 either INCLUDES or 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.