README.4layout

(This file was generated by makeinfo and splitinfo.gawk.)
(Released under the old-style GNU documentation license;
 see sources or other output files for full text.)

6 Layout and infrastructure
***************************

The TeX Live source tree is the subtree rooted at 'Build/source' of the
complete TL distribution and contains the sources for all executables
distributed by TL, as well as 'configure' scripts and 'make' rules to
build and install them together with some of their support files.

6.1 Build system tools
======================

As mentioned above (see Prerequisites), a normal build has few
requirements.  On the other hand, if you want to modify the TeX Live
infrastructure sources, such as 'configure.ac' or 'Makefile.am' files,
you will need to have several additional tools installed.

   In general, the TL build system uses the latest released versions of
the GNU build tools, installed directly from the original GNU releases
(e.g., by building them with 'configure --prefix=/usr/local/gnu' and
having 'PATH' start with '/usr/local/gnu/bin').  We have found that
trying to use the versions of these tools packaged for distros causes
many extra hassles, so don't do that, tempting as it may be.

   Currently the versions we use are:

     autoconf (GNU Autoconf) 2.72
     automake (GNU automake) 1.17
     bison (GNU Bison) 3.8.2
     flex 2.6.0
     ltmain.sh (GNU libtool) 2.5.4
     m4 (GNU M4) 1.4.19
     makeinfo (GNU texinfo) 7.2

   These versions should be used to update the generated files (e.g.,
'configure' or 'Makefile.in') in all or parts of the TL tree after their
dependencies have been changed.  This can be done explicitly with the
top-level 'reautoconf' script or implicitly by using the configure
option '--enable-maintainer-mode'.

   It has often turned out that the bison and flex versions are not
critical; however, the autotools versions are.  If you don't have the
given versions, get them before modifying the build infrastructure.

   The files in the Subversion repository (see
<https://tug.org/texlive/svn>) are all up to date (barring bugs).  For
this to be reflected by their timestamps in your checkout, be sure to
set 'use-commit-times=yes' in '~/.subversion/config' or the equivalent.

   If timestamps are wrong, you may also be able to avoid unnecessary
runs of 'bison', 'flex', or 'makeinfo' with 'touch' of the generated
('.c', '.h', or '.info') files.  With '--enable-maintainer-mode' it may
also be necessary to 'touch' first 'aclocal.m4', then 'configure' and
'config.h.in' (or 'c-auto.in'), and finally all 'Makefile.in' files.

6.2 Top-level directories
=========================

Here is a brief description of the top-level directories in the TeX Live
source tree.

   As mentioned at the beginning of see Overview of build system, the
main source directories are 'texk/' (TeX-specific programs and
libraries), 'utils/' (additional programs), and 'libs/' (generic
libraries).

   In addition, the top-level directories 'am/' and 'm4/' contain
'Makefile.am' fragments and Autoconf macros, respectively, used in many
places.  Specifically, the file 'm4/kpse-pkgs.m4' contains lists of all
program and library modules; missing modules are silently ignored.
(This helps in creating cut-down source trees.)

   Each module contributes fragments (in separate files) defining its
capabilities and requirements to the 'configure.ac' scripts at the
top-level and in the subdirectories 'libs', 'utils', and 'texk'.  The
fragments from program modules supply 'configure' options to disable or
enable building them; those from library modules specify if an installed
(system) version of that library can be used.  This ultimately
determines which modules need to be built--although all modules must be
configured for the benefit of 'make' targets such as 'dist' or
'distcheck'.

   The top-level 'build-aux/' directory contains the common files
'compile', 'config.guess', 'config.sub', 'depcomp', etc. used by most
packages.  These are taken from the GNU Gnulib sources
(<https://www.gnu.org/software/gnulib>), which in turn synchronizes with
any ultimate upstream repository.  There are independent copies of some
of these in a few other places, e.g.,
'libs/freetype2/freetype-*/builds/unix/'.  The 'reautoconf' script does
not touch those, but a TL cron job keeps them in sync (nightly).

   When the top-level './Build' script is used to build TL, two more two
more top-level directories appear: 'Work/' for the build tree, and
'inst/' for the install tree (from 'make install').  These names (and
everything else about 'Build''s operation) can be changed by setting
environment variables before running it; see the script source.

6.3 Autoconf macros
===================

Here we describe a few of the Autoconf macros used in several
modules--many more are defined in the sources; see the top-level 'm4/'
directory.  These general macros are supplemented by module-specific
macros in directories such as 'texk/dvipng/m4/'; some of those are
described in following sections (see Library modules and Program
modules).

6.3.1 General setup macros
--------------------------

The TL sources use two general setup macros:

 -- Macro: KPSE_BASIC (NAME, [MORE-OPTIONS])
     Initialize the basic TL infrastructure for module NAME:
        'AM_INIT_AUTOMAKE([foreign MORE-OPTIONS])'
        'AM_MAINTAINER_MODE'
        'KPSE_COMPILER_WARNINGS'
     and make sure the C compiler understands function prototypes.  This
     is used for all generic library and program modules.

 -- Macro: KPSE_COMMON (NAME, [MORE-OPTIONS])
     Like 'KPSE_BASIC' but add:
        'LT_PREREQ([2.2.6])'
        'LT_INIT([win32-dll])'
        'AC_SYS_LARGEFILE'
        'AC_FUNC_FSEEKO'
     along with checks for frequently used functions, headers, types,
     and structures.  This is used for TeX-specific modules.

6.3.2 Macros for programs
-------------------------

Macros for program checks:

 -- Macro: KPSE_CHECK_LATEX
     Set 'LATEX' to the first of 'latex', 'elatex', or 'lambda' which
     exists in 'PATH', or to 'no' if none of them exists.  Call
     'AC_SUBST' for 'LATEX'.  The result of this test can be overridden
     by setting the 'LATEX' environment variable or the cache variable
     'ac_cv_prog_LATEX'.

 -- Macro: KPSE_CHECK_PDFLATEX
     Check for 'pdflatex' in 'PATH' and set 'PDFLATEX'.

 -- Macro: KPSE_CHECK_PERL
     Check for 'perl' or 'perl5' in 'PATH' and set 'PERL'.

 -- Macro: KPSE_PROG_LEX
     Call 'AC_PROG_LEX' and add the flag '-l' for 'flex'.

6.3.3 Macros for compilers
--------------------------

Macros for compiler-related checks:

 -- Macro: KPSE_COMPILER_WARNINGS
     When using the (Objective) C/C++ compiler, set
     'WARNING_[OBJ]C[XX]FLAGS' to suitable warning flags (depending on
     the value given to or implied for '--enable-compiler-warnings').
     Call 'AC_SUBST' for them.  At present this assumes GNU compiler
     warning options, but could be extended to others if necessary.

     This macro caches its results in the 'kpse_cv_warning_cflags', ...
     variables.

 -- Macro: KPSE_COMPILER_VISIBILITY
     When using the C or C++ compiler, try to set
     'VISIBILITY_C[XX]FLAGS' to flags to hide external symbols.  Call
     'AC_SUBST' for this variable.  This tests for the compiler option
     '-fvisibility=hidden' and, except for C,
     '-fvisibility-inlines-hidden'.  Reports or patches for additional
     tests are welcome.

     This macro caches its results in the 'kpse_cv_visibility_cflags' or
     'kpse_cv_visibility_cxxflags' variable.

 -- Macro: KPSE_CXX_HACK
     Provide the configure option '--enable-cxx-runtime-hack'.  If
     enabled and when using 'g++', try to statically link with
     'libstdc++', notably improving portability of the resulting binary.

     This macro caches its result in the 'kpse_cv_cxx_hack' variable.

6.3.4 Macros for libraries
--------------------------

One macro for a library check:

 -- Macro: KPSE_LARGEFILE (VARIABLE, [EXTRA-DEFINE])
     Call 'AC_SYS_LARGEFILE' and 'AC_FUNC_FSEEKO' and append suitable
     '-D' flags (optionally including '-DEXTRA-DEFINE') to VARIABLE.

6.3.5 Macros for library and header flags
-----------------------------------------

Each library module 'libs/LIB' or 'texk/LIB' is supplemented by a macro
'KPSE_LIB_FLAGS' (all uppercase) that provides make variables for that
library.  E.g., for 'libs/libpng':

 -- Macro: KPSE_LIBPNG_FLAGS
     Provide the configure option '--with-system-libpng'.  Set and
     'AC_SUBST' 'make' variables for modules using this library (either
     an installed version or from the TeX Live tree):

     'LIBPNG_INCLUDES'   for use in 'CPPFLAGS',
     'LIBPNG_LIBS'       for use in 'LDADD',
     'LIBPNG_DEPEND'     for use as a Makefile dependency,
     'LIBPNG_RULE'       for the 'make' rules to rebuild the library.

 -- Macro: KPSE_ADD_FLAGS (NAME)
     Temporarily extend 'CPPFLAGS' and 'LIBS' with the values required
     for the library module 'NAME'.

 -- Macro: KPSE_RESTORE_FLAGS
     Restore 'CPPFLAGS' and 'LIBS' to their original values.

   As an example, the 'configure.ac' file for a hypothetical program
'utils/foo' using 'libpng', and hence 'zlib', would contain
     KPSE_ZLIB_FLAGS
     KPSE_LIBPNG_FLAGS

and its 'Makefile.am' would be along these lines:
     bin_PROGRAMS = foo
     AM_CPPFLAGS = ${LIBPNG_INCLUDES} ${ZLIB_INCLUDES}
     foo_LDADD = ${LIBPNG_LIBS} ${ZLIB_LIBS}
     foo_DEPENDENCIES = ${ZLIB_DEPEND} ${LIBPNG_DEPEND}
     ## Rebuild libz
     @ZLIB_RULE@
     ## Rebuild libpng
     @LIBPNG_RULE@

   If it were necessary to examine whether certain 'zlib' or 'libpng'
features were available, 'configure.ac' should be continued this way:
     KPSE_ADD_FLAGS([zlib])
     ... # tests for 'zlib' features, if any
     KPSE_ADD_FLAGS([libpng])
     ... # tests for 'libpng' features
     KPSE_RESTORE_FLAGS # restore 'CPPFLAGS' and 'LIBS'

6.3.6 Macros for Windows
------------------------

Windows differs in several aspects from Unix-like systems, many of them
due to the lack of symbolic links.

 -- Macro: KPSE_CHECK_WIN32
     Check if compiling for a Windows system.  The result is either 'no'
     for Unix-like systems (including Cygwin), 'mingw32' for Windows
     with GCC, or 'native' for Windows with MSVC. The result is cached
     in the 'kpse_cv_have_win32' variable.

 -- Macro: KPSE_COND_WIN32
     Call 'KPSE_CHECK_WIN32' and define the Automake conditional 'WIN32'
     ('true' if the value of 'kpse_cv_have_win32' is not 'no').

 -- Macro: KPSE_COND_MINGW32
     Call 'KPSE_COND_WIN32' and define the Automake conditional
     'MINGW32' ('true' if the value of 'kpse_cv_have_win32' is
     'mingw32').

 -- Macro: KPSE_COND_WIN32_WRAP
     Call 'KPSE_COND_WIN32' and define the Automake conditional
     'WIN32_WRAP' ('true' if the standard Windows wrapper
     ('texk/texlive/windows_wrapper/runscript.exe') exists.  This
     wrapper is used on Windows instead of symlinks for the "linked
     scripts" (see Linked scripts).

 -- Macro: KPSE_WIN32_CALL
     Call 'KPSE_COND_WIN32' and check if the file
     'texk/texlive/windows_wrapper/callexe.c' exists; if it does, create
     a symlink in the build tree.  Compiling 'callexe.c' with
     '-DEXEPROG='"FOO.exe"'' and installing 'callexe.exe' as 'BAR.exe'
     is used on Windows instead of a symlink 'BAR->FOO' for Unix-like
     systems.

6.4 Library modules
===================

Here we discuss some specifics for a few of the libraries in TL, both
for the details themselves, and as a way of illuminating the general
structure and variation.

6.4.1 The 'png' library in 'libs/libpng'
----------------------------------------

The "generic" 'png' library uses the source tree in the subdirectory
'libpng-src/', with all modifications for TL recorded in 'TLpatches/*'.
The 'configure.ac' fragment 'ac/withenable.ac' contains

     KPSE_WITH_LIB([libpng], [zlib])

to specify the module name and indicate the dependency on 'zlib'.  A
third literal argument ''tree'' would specify that the library from the
TeX Live tree cannot be replaced by a system version.  That not being
the case here, a second fragment '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);])

thus providing the simple C code

     #include <png.h>
     int main ()
     { png_structp png; png_voidp io; png_rw_ptr fn;
       png_set_read_fn(png, io, fn);
       return 0; }

which Autoconf uses to verify the usability of a system version with C
code.  The analogous macro 'KPSE_TRY_LIBXX' would check using C++.
These fragments are included by the 'configure.ac' at the top level of
TL ('Build/source/configure.ac').

   For this library, like many other modules, a proxy build system for
TL is used, consisting of our own 'configure.ac', 'Makefile.am',
'include/Makefile.am'; the distributed build system is not used.
(Consequently, a few generated files and auxiliary scripts are removed
from the distributed source tree.)

   The public headers 'png.h', 'pngconf.h', and 'pnglibconf.h' are
"installed" (as symlinks) under 'include/' in the build tree exactly as
they are for a system version under, e.g., '/usr/include/'.

   The module is supplemented by the file 'm4/kpse-libpng-flags.m4' that
defines the M4 macro 'KPSE_LIBPNG_FLAGS' used by all modules depending
on this library in their 'configure.ac' to generate the 'make' variables
'LIBPNG_INCLUDES' for use in 'CPPFLAGS', 'LIBPNG_LIBS' for use in
'LDADD', 'LIBPNG_DEPEND' for use as dependencies, and 'LIBPNG_RULE' for
the 'make' rules to rebuild the library.

   'm4/kpse-libpng-flags.m4' also supplies the configure option
'--with-system-libpng', which then uses 'pkg-config' to determine the
flags required for the system library.

6.4.2 The 'zlib' library in 'libs/zlib'
---------------------------------------

This generic library is very much analogous to 'libpng', but without the
dependency on any other library.  The file 'm4/kpse-zlib-flags.m4'
supplies the configure option '--with-system-zlib', as well as
'--with-zlib-includes' and '--with-zlib-libdir' to specify non-standard
locations of the 'zlib' headers and/or library.

6.4.3 The 'freetype' library in 'libs/freetype2'
------------------------------------------------

This module uses a wrapper build system.  In contrast to the proxy build
described earlier, the wrapper build has an almost trivial
'configure.ac' and a 'Makefile.am' which invokes the 'configure' and
'make' in the distributed source, followed by 'make install' with the TL
build tree as destination.  In other words, this actually uses the build
system provided by upstream (possibly patched).

   The flags required for the system library are obtained through
'freetype-config'.

6.4.4 The 'kpathsea' library in 'texk/kpathsea'
-----------------------------------------------

This is one of the TeX-specific libraries that are maintained as part of
TeX Live (see (kpathsea)); the other is 'ptexenc'.  These TeX libraries
are Libtool libraries (static and/or shared) and are installed by 'make
install' together with the programs.  They are, however, not part of the
TL DVD as distributed by TeX user groups, and have never been officially
released for standalone use.

   It is possible, and probably useful for distro builds (see Distro
builds), to specify the configure option '--with-system-kpathsea' in
order to use a system version of the library.  Programs outside the TL
tree should use 'pkg-config' for the required flags.

   In addition to 'kpathsea/ac/withenable.ac' and
'kpathsea/ac/kpathsea.ac' here there is a third fragment
'kpathsea.ac/mktex.ac', included by both 'withenable.ac' and
'configure.ac', which supplies configure options such as
'--enable-mktextfm-default'.  These determine the compile time default
of whether or not to run 'mktextfm' (and similar) to generate a missing
'.tfm' (or whatever) file.  In any case, however, the command line
options '-mktex=tfm' or '-no-mktex=tfm' for the TeX-like engines
override this default.

6.5 Program modules
===================

As with libraries (see Library modules), here we discuss the details for
a few of the programs in TL.

6.5.1 The 't1utils' package in 'utils/t1utils'
----------------------------------------------

Here we use the distributed source tree 't1utils-src' with modifications
documented in 'TLpatches/*' and a proxy build system consisting of
'configure.ac' and 'Makefile.am'.  The fragment 'ac/withenable.ac'
contains

     KPSE_ENABLE_PROG([t1utils])

specifying the module name without any dependencies, and supplies the
configure option '--disable-t1utils'.

6.5.2 The 'xindy' package in 'utils/xindy'
------------------------------------------

This module uses the distributed source tree 'xindy-src/' with
modifications documented in 'TLpatches/*', and a wrapper 'configure.ac'
and 'Makefile.am' that descends into 'xindy-src'.

   The 'xindy' build requires a 'make' that supports a 'VPATH' build,
can handle all targets, and does not refer to '${top_srcdir}' or
'${top_builddir}'.  The fragment 'xindy/ac/withenable.ac' contains

     KPSE_ENABLE_PROG([xindy], , [disable])
     m4_include(kpse_TL[utils/xindy/ac/xindy.ac])
     m4_include(kpse_TL[utils/xindy/ac/clisp.ac])

where 'disable' in the third argument indicates that 'xindy' is only
built if explicitly enabled by the user with 'configure --enable-xindy'
(the need for 'clisp' makes it too painful to enable by default).

   The additional fragments 'ac/xindy.ac' and 'ac/clisp.ac' specify more
'configure' options to be seen at the top level, with 'ac/xindy.ac' also
included by 'configure.ac'.

6.5.3 The 'xdvik' package in 'texk/xdvik'
-----------------------------------------

This package is maintained as part of the TeX Live tree with sources in
its own directory ('texk/xdvik/').  The fragment
'xdvik/ac/withenable.ac' contains

     dnl extra_dirs = texk/xdvik/squeeze
     KPSE_ENABLE_PROG([xdvik], [kpathsea freetype2], [x])
     m4_include(kpse_TL[texk/xdvik/ac/xdvik.ac])

thus specifying dependencies on the 'kpathsea', 'freetype', and X11
libraries.  The M4 comment (following 'dnl') signals the subsidiary
'squeeze/configure.ac'.  This is needed because the main executable
'xdvi-bin' (to be installed as, e.g., 'xdvi-xaw') is for the 'host'
system whereas the auxiliary program 'squeeze/squeeze' has to run on the
'build' system; in a cross compilation, these differ.

   The additional fragment 'ac/xdvik.ac' is also included by
'configure.ac' and supplies the configure option '--with-xdvi-x-toolkit'
also seen at the top level.

6.5.4 The subdirectory 'utils/asymptote'
----------------------------------------

This subdirectory contains the sources for 'asy' and 'xasy' but due to
its complexity and prerequisites (e.g., OpenGL) it is not part of the TL
build system.  These programs must be built and installed independently,
but are included on the TL DVD together with their support files.  See
<https://tug.org/texlive/build.html#asymptote>.

6.6 Extending TeX Live
======================

This section outlines the basic process for adding new packages to the
TL build system.

   In any case, a new package directory 'foo' should contain the
original sources, modified only with changes necessary for TL, in
'foo/foo-src'.  The changes should be documented in 'foo/TLpatches/*',
and also be submitted upstream whenever reasonable.  In addition, 'foo/'
will need the usual Automake build-related files ('configure.ac',
'Makefile.am', etc.  Please maintain 'foo/ChangeLog' for all TL changes.

6.6.1 Adding a new program module
---------------------------------

A TeX-specific program module in a subdirectory 'texk/PROG' may use the
TeX-specific libraries and is included by adding its name 'PROG' to the
M4 list 'kpse_texk_pkgs' defined in 'm4/kpse-pkgs.m4'.

   A generic program module in a subdirectory 'utils/PROG' must not use
the TeX-specific libraries and is included by adding its name 'PROG' to
the M4 list 'kpse_utils_pkgs' in 'm4/kpse-pkgs.m4'.

   In either case, the subdirectory 'texk/PROG' or 'utils/PROG' must
provide a fragment 'ac/withenable.ac' that contains the M4 macro
'KPSE_ENABLE_PROG' defined in 'm4/kpse-setup.m4' with 'PROG' as the
mandatory first argument and three optional arguments:

  1. a list of required libraries from the TL tree;

  2. a list of options: 'disable' if this module is not to be built
     without the configure option '--enable-PROG', 'native' if cross
     compilation is not possible, 'x' if the program requires X11
     libraries;

  3. a comment added to the help text for the 'configure' option
     '--enable-PROG' or '--disable-PROG'.

   If the module requires specific 'configure' options to be seen at the
top level, they should be defined in an additional fragment 'ac/PROG.ac'
included from 'ac/withenable.ac' and 'configure.ac'.

   Usually, the new program is maintained somewhere outside of TeX Live.
In that case, as above, we put the upstream sources into a subdirectory
'PROG-src' (e.g., 'utils/newprog/newprog-src').  We do not typically run
'configure' in this original '...-src' directory, but only in our own
directory; but we do compile using the source files in '...-src'.

   So, to summarize the files that must (usually) be created inside a
new TL source directory ('texk/newprog' or 'utils/newprog'):

'ac/withenable.ac'
     The 'KPSE_ENABLE_PROG' call just explained.

'configure.ac'
'Makefile.am'
     By merging the contents of the original 'configure.ac' (if
     provided) and a comparable program already in TL. In the above
     example, one line that will be needed in 'configure.ac' (can be
     added before the 'AC_CONFIG_FILES' at the end) is:

          AC_SUBST([NEWPROG_TREE], [newprog-src])

     and then use '@NEWPROG_TREE@' in 'Makefile.am' where needed.

     In general, there is no magic recipe for this part of the job.
     It's necessary to think about what needs to be done in the original
     vs. in TeX Live.  It's useful to look at the setup for the most
     comparable programs already in TL that you can find.  It's also
     useful to grep the entire 'Build/source' tree for whatever you can
     think of to investigate how something is done.  Most of the
     TL-specific macros are defined in 'Build/source/m4/*'.

'TLpatches/TL-Changes'
     First actions taken after getting the original source tree;
     typically removal of derived or unused common files.

'TLpatches/patch-...'
     If any changes are needed to the original sources, record the
     patches here so they can be applied next time.  Also, send them
     upstream so that we don't have to maintain them forever.

'ChangeLog'
     Record all TL-specific changes, now and in the future.

   After populating the new TL source directory ('.../newprog/', in the
above), run GNU 'autoreconf' there (see Build system tools).  Once that
works, if you are the one who's eventually going to commit the new
package, 'svn add' the necessary files, including the generated
'Makefile.in aclocal.m4 configure', and 'svn:ignore' the Automake cache
'autom4te.cache'.  (This is so people checking out the TL source tree do
not have to run any autotools, but can simply run 'configure'.)

   To reiterate: do not fail to commit the generated 'configure' and
other files.  The m4 code in 'kpse-pkgs.m4' uses the existence of
'configure' to determine whether to descend into (and configure) a given
subdirectory.

   Then, run the TL tool 'reautoconf' in the top-level TL
'Build/source/' directory, to incorporate the new program into the build
tree.  It is good to then rebuild the whole tree (e.g., using TL's
'Build/Build' script) to get all the necessary files generated.

   It will probably fail.  So then you need to keep at it until the
program compiles and tests successfully.  The most efficient way is to
rerun 'autoreconf' as needed in the new source directory
('Build/source/.../newprog'), then 'make' in the corresponding build
directory ('Build/work/.../newprog'), then 'make check', etc.  In the
end, also make sure that the whole tree builds from scratch.

   After final success, don't forget to commit.  (Or email the TL
maintainers with the patch.)

6.6.2 Adding a new engine
-------------------------

Adding a new TeX engine is not completely different from adding a
program, but it's not all that similar, either.  In this case, the main
work is done by creating a new subdirectory of 'texk/web2c/' for the
engine.  The subdirectory is conventionally named ending in 'dir', like
'pdftexdir' and 'xetexdir', to avoid clashes with executable names.

   The source files for the new engine should be put in this
'NEWENGINEdir' subdirectory.  Also, a file
'NEWENGINEdir/am/NEWENGINE.am' (e.g., 'pdftexdir/am/pdftex.am' is needed
with the Makefile fragment needed to build it.

   The overall 'web2c/Makefile.am' needs to have an 'include' statement
added to insert that 'NEWENGINE.am' file.

   In 'web2c/ac/web2c.ac', a line needs to be added in the definition of
the 'kpse_tex_progs' variable to include it in the build.  That line
specifies whether the new engine is built by default, and the additional
libraries requires.

   For examples of building engines in CWEB, you can check the existing
'hitexdir' and 'mplibdir' directories; these are somewhat simpler than
LuaTeX.  Of course, every engine will have its own unique features and
requirements, so existing examples will only take you so far.

   Web2c is built as one "package", with each subdirectory's '.am'
fragment inserted with an Automake 'include'.  This means that, for
instance, '$(srcdir)' is '.../web2c', not '.../webdir/enginedir'.  It is
a difficult setup to come to terms with, but the alternative is to
recurse into each engine subdirectory, and that would be far worse (see
(automake)Directories).

6.6.3 Adding a new generic library module
-----------------------------------------

A generic library module in a subdirectory 'libs/LIB' must not depend on
TeX-specific libraries, by definition.  It is included by adding its
name 'LIB' to the M4 macro 'kpse_libs_pkgs' in 'm4/kpse-pkgs.m4'--before
any other libraries from the TeX Live tree on which it depends.

   As with program modules, the subdirectory 'libs/LIB' must contain the
sources and build system for the library (and any installable support
programs) and a fragment 'ac/withenable.ac' that contains the M4 macro
'KPSE_WITH_LIB' defined in 'm4/kpse-setup.m4' with 'LIB' as the
mandatory first argument and two optional arguments: a list of required
libraries from the TL tree, and a list of options: for libraries,
currently there is only one--specify 'tree' if this library cannot be
replaced by a system version.

   If a system version can be used, a second fragment 'ac/LIB.ac' is
needed, containing the M4 macro 'KPSE_TRY_LIB' (or 'KPSE_TRY_LIBXX')
with 'LIB' as the mandatory first argument and two additional arguments
for the Autoconf macro 'AC_LANG_PROGRAM' used to compile and link a
small C (or C++) program as sanity check for using the system library.

   In addition a file 'm4/kpse-LIB-flags' (at the top level) must define
the M4 macro 'KPSE_LIB_FLAGS' (all uppercase) setting up the 'make'
variables 'LIB_INCLUDES', 'LIB_LIBS', 'LIB_DEPEND', and 'LIB_RULE' with
the values required for 'CPPFLAGS', 'LDADD', dependencies, and a
(multi-line) 'make' rule to rebuild the library when necessary.  All of
that is needed for the library from the TL tree and, if supported, for a
system version.

   If a system library is allowed, 'KPSE_LIB_FLAGS' also provides the
configure option '--with-system-LIB' and uses the additional M4 macro
'KPSE_LIB_SYSTEM_FLAGS' to generate the 'make' variables for a system
library.  In addition, the definition of the M4 macro
'KPSE_ALL_SYSTEM_FLAGS' in 'm4/kpse-pkgs.m4' must be extended by the
line:
   'AC_REQUIRE([KPSE_LIB_SYSTEM_FLAGS])'

6.6.4 Adding a new TeX-specific library module
----------------------------------------------

A TeX-specific library module in a subdirectory 'texk/LIB' may depend on
other TeX-specific libraries but must not depend on any generic library
from the TL tree.  It is included in the same general ways as a generic
library (see the previous section), with these modifications:

   * The library name 'LIB' is added to the M4 macro
     'kpse_texlibs_pkgs', which is also in 'm4/kpse-pkgs.m4'.

   * The fragment 'ac/withenable.ac' must use 'KPSE_WITH_TEXLIB'.