Copyright (C) 2009, 2010 Peter Breitenlohner <tex-live@tug.org>
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.h>],
	             [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 <png.h>
	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.