summaryrefslogtreecommitdiff
path: root/Build/source/doc/tlbuild.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/doc/tlbuild.texi')
-rw-r--r--Build/source/doc/tlbuild.texi2137
1 files changed, 2137 insertions, 0 deletions
diff --git a/Build/source/doc/tlbuild.texi b/Build/source/doc/tlbuild.texi
new file mode 100644
index 00000000000..8b26d72b10e
--- /dev/null
+++ b/Build/source/doc/tlbuild.texi
@@ -0,0 +1,2137 @@
+@c This is part of the TeX Live manual.
+@c Copyright 2013, 2014 Karl Berry & Peter Breitenlohner.
+@c See file texlive.texi for copying conditions.
+
+@c The first word of the chapter/section title here is used to
+@c construct the README.* filenames, so choose well. (Or hack the script.)
+
+@node Build system
+@chapter Build system
+
+@cindex build system, design of
+
+@cindex Autoconf
+@cindex Automake
+@cindex Libtool
+@cindex tests, running
+The @TL{} build system was redesigned in 2009, consistently using
+Autoconf, Automake, and Libtool. Thus@*@ @ @ @code{configure &&
+make && make check && make install}@*or the basically-equivalent
+top-level @code{Build} script suffice to build and install the TL
+programs. The @code{make check} clause performs various tests of the
+generated programs---not strictly required but strongly recommended.
+Running @code{configure --help} will display a comprehensive list of
+all @code{configure} options.
+
+The main components of the TL build system are:
+
+@table @file
+@item texk/@var{lib}
+@TeX{}-specific libraries in subdirectories, notably
+@var{lib}=@code{kpathsea}. (The other one is @file{texk/ptexenc}.)
+
+@item texk/@var{prog}
+@TeX{}-specific programs (that use Kpathsea).
+
+@item utils/@var{prog}
+Other programs (that don't use Kpathsea).
+
+@item libs/@var{lib}
+Generic libraries.
+@end table
+
+@pindex kpse-pkgs.m4
+The primary design goal of the build system is modularity. Each
+program and library module (or package) specifies its own requirements
+and properties, such as required libraries, whether an installed
+(system) version of a library can be used, @code{configure} options to
+be seen at the top-level, and more. An explicit list of all available
+modules is kept in only one, central, place (@file{m4/kpse-pkgs.m4}).
+
+A second, related goal is to configure and build each library before
+configuring any other (program or library) module which uses that
+library. This allows checking for properties and features of a
+library built as part of the TL tree in much the same way as for a
+system version of that library.
+
+All generic libraries and several programs are maintained
+independently. The corresponding modules use (most of) the
+distributed source tree and document any modifications of that source
+tree.
+
+All this is for the sake of simplifying both upgrading of modules
+maintained independently and integrating new modules into the
+TL build system. (Not to say that either task has become trivial.)
+
+@menu
+* Prerequisites:: Requirements for building @TL{}.
+* Building:: The overall build process.
+* Installing:: How and where installation happens (or not).
+* Infrastructure and layout:: Autoconf macros, etc., in detail.
+* Configure options:: List of all configure options.
+* Cross compilation::
+* Coding conventions::
+@end menu
+
+
+@node Prerequisites
+@section Prerequisites for building @TL{}
+
+@cindex prerequisites for building
+@cindex requirements for building
+
+@cindex compilers, C and C++
+Overall, building the @TL{} programs, when using all libraries from
+the TL source tree, requires only C and C++ compilers and GNU
+@code{make}. (If @code{make} from your @code{PATH} is not GNU make,
+you can set @code{MAKE} in the environment to whatever is necessary.)
+
+@cindex GNU @code{make}, required
+@cindex @code{gmake}, required
+@cindex FreeType
+Indeed, GNU @code{make} is required only because of some
+third-party libraries, notably FreeType; all the TL-maintained
+directories (and Automake/Autoconf output in general) should work with
+any reasonable @code{make}.
+
+However, a few programs in the tree have additional requirements:
+
+@table @file
+@item biber
+@cindex @code{perl}, required by @code{biber}, etc.
+requires @code{perl} for autodetection of the TL platform name.
+
+@item xdvik
+@itemx xpdfopen
+@cindex X11, required by X clients
+require X11 headers and libraries, often a ``development'' package
+that is not installed by default.
+
+@item xetex
+@cindex @code{fontconfig} library, required by @code{xetex}
+requires @file{fontconfig} (again both headers and library).
+
+@item xindy
+@cindex @code{clisp}, required by @code{xindy}
+requires GNU @code{clisp} and in addition @code{perl},
+@code{latex}, and @code{pdflatex} to build the rules and/or
+documentation.
+
+@end table
+
+@noindent Lacking the required tools, building these
+programs must avoided, e.g., @code{configure --disable-biber
+--without-x --disable-xetex --disable-xindy}.
+
+Modifying source files also induces more requirements:
+
+@itemize
+@item
+Modification of any @code{.y} or @code{.l} source files requires
+@file{bison} or @file{flex} to updatete the corresponding C sources.
+
+@item
+Modification of the sources for @code{.info} files requires
+@code{makeinfo}.
+
+@item
+Modification of any part of the build system (M4 macros,
+@file{configure.ac}, @file{Makefile.am}, or their fragments) requires
+GNU M4, GNU Autoconf, GNU Automake, and GNU Libtool to update the
+generated files. @xref{Build system tools}.
+
+@end itemize
+
+
+@node Building
+@section Building
+
+@cindex building
+@cindex overall build process
+
+@pindex Build @r{script}
+The top-level @file{Build} script is intended to simplify building the
+binaries distributed with @TL{} itself---we call this the ``native''
+TL build. It configures and makes everything in a subdirectory of the
+main build tree (default @file{Work/}), installs everything in an
+other subdirectory (default @file{inst/}), and finally runs @code{make
+check}. The exact directory and command names can be specified via
+environment variables and a few leading options. All remaining
+arguments (assignments or options) are passed to the @file{configure}
+script. Please take a look at the script itself for more information;
+it is not complicated.
+
+@cindex source directory building, not supported
+@cindex build directory, required
+An alternative, and the one we will mainly discuss here, is to run
+@code{configure} and @code{make} oneself in a suitable empty
+subdirectory. Building in the source directory itself is not
+supported (sorry).
+
+@cindex iteration through sources, by @code{configure} and @code{make}
+Running the top-level @file{configure} script configures the top level
+and the subdirectories @file{libs}, @file{utils}, and @file{texk}.
+Running @code{make} at the top-level first iterates over all
+@TeX{}-specific libraries, and then runs @code{make} in
+@file{libs}, @file{utils}, and @file{texk} to iterate over all generic
+libraries, utility programs, and @TeX{}-specific programs. These
+iterations consist of two steps:
+
+@enumerate
+@item
+For each library or program module not yet configured, run
+@code{configure}, adding the configure option @code{--disable-build}
+if the module need not be built, otherwise running @code{make all}.
+
+@item
+For each library or program module that must be built, run
+@code{make} for the selected target(s): @code{default} or
+@code{all} to (re-)build, @code{check} to run tests, @code{install},
+etc.
+
+@end enumerate
+
+Running the top-level @code{make} a second time iterates again over
+all the library and program modules, but finds (should find) nothing
+to be done unless some source files have been modified.
+
+@vindex --no-clean Build @r{option}
+If configuring or building a module fails, you could either
+(a)@tie{}find and fix the problem, or (b)@tie{}remove the subdirectory
+for that module from the build tree, and rerun the top-level
+@code{make} (or @file{Build} with @code{--no-clean} as its first
+argument).
+
+@vindex --disable-all-packages configure @r{option}
+@cindex build on demand
+With the configure option @code{--disable-all-pkgs}, all program and
+library modules are configured but none of them is built. The
+@file{Makefile} for each such module contains all build rules and
+dependencies and can be invoked to build an individual program or
+library and causes to first build any required libraries. This
+``build-on-demand'' procedure is used, e.g., in the @code{luatex}
+repository to build Lua@TeX{}, essentially from a subset of the
+complete @TL{} tree. Similarly, when, e.g., building the original
+e-@TeX{} has been disabled (as it is by default), one can run
+@code{make etex} (or @code{make etex.exe}) in @file{texk/web2c/} to
+build e-@TeX{} (although there is no comparably simple way to install
+e-@TeX{}).
+
+@cindex parallel build
+@cindex cache for @code{configure}
+The TL build system carefully formulates dependencies as well as
+@code{make} rules when a tool (such as @code{tangle}, @code{ctangle},
+or @code{convert}) creates several output files. This allows for
+parallel builds (@code{make -j @var{n}} with @math{@var{n}>1} or even
+@code{make -j}) that can considerably speed up the TL build.
+Independently, speed-up can also be achieved by using a configure
+cache file, i.e., with the option @code{-C} (recommended).
+
+@cindex distribution tarball, making
+Running @code{make dist} at the top-level creates a tarball
+@file{tex-live-@var{yyyy}-@var{mm}-@var{dd}.tar.xz} from the TL source
+tree. Running @code{make dist-check} also verifies that this tarball
+suffices to build and install all of TL. (This is useful for checking
+consistency of the source tree and Makefiles, but the result is not a
+complete or even usable @TeX{} system, since all the support files are
+lacking; see the next section.)
+
+
+@node Installing
+@section Installing
+
+@cindex installing
+This section discusses the results of @code{make install} in the
+source tree.
+
+@cindex support files, separate from build
+@pindex texlive.tlpdb@r{, @TL{} database}
+@pindex install-tl@r{, @TL{} installer}
+@pindex plain.tex@r{, not in source tree}
+The main consideration is that this is not enough to make a usable
+@TeX{} installation. Beyond the binaries that are built from the
+sources, (thousands of) support files are needed; just as a first
+example @file{plain.tex} is not in the source tree.
+
+These support files are maintained completely independently and are
+not present in the source tree. The best basis for dealing with them
+is the @TL{} (plain text) database in
+@file{Master/tlpkg/texlive.tlpdb}, and/or the @TL{} installer,
+@code{install-tl}. More information is under @file{Master/tlpkg} and
+at @url{http://tug.org/texlive/distro.html}.
+
+@menu
+* Installation directories:: The prefix, @code{bindir}, etc., directories.
+* Linked scripts:: Scripts not maintained in the sources.
+* Distro builds:: Configuring and building for OS distributions.
+@end menu
+
+
+@node Installation directories
+@subsection Installation directories
+
+@cindex installation directories
+@cindex directories, for installation
+@cindex paths, for installation
+
+Running @code{make install} (or @code{make install-strip}) installs
+executables in @code{@var{bindir}}, libraries in @code{@var{libdir}},
+headers in @code{@var{includedir}}, general data (including ``linked
+scripts'', @pxref{Linked scripts}) in
+@code{@var{datarootdir}/texmf-dist}, man pages in @code{@var{mandir}},
+and Info files in @code{@var{infodir}}.
+
+The values of these directories are determined by @code{configure}
+and can be specified explictly as options such as
+@code{--prefix=@var{prefix}} or @code{--bindir=@var{bindir}};
+otherwise, they are given by their usual Autoconf defaults:
+
+@example
+@var{prefix} /usr/local
+@var{exec_prefix} @var{prefix}
+@var{bindir} @var{exec_prefix}/bin
+@var{libdir} @var{exec_prefix}/lib
+@var{includedir} @var{prefix}/include
+@var{datarootdir} @var{prefix}/share
+@var{mandir} @var{datarootdir}/man
+@var{infodir} @var{datarootdir}/info
+@end example
+
+@noindent @dots{} except possibly modified as follows:
+
+@itemize @bullet
+@item
+If the option @code{--enable-multiplatform} is given,
+@code{/@var{platform}} (i.e., the canonical platform name) is appended
+to @code{@var{bindir}} and @code{@var{libdir}}. This is implied for a
+native TL build.
+
+@item
+@raggedright
+In a native TL build, @code{@var{datarootdir}} is set to
+@code{@var{prefix}}, @code{@var{infodir}} is set to
+@code{@var{prefix}/texmf-dist/doc/info}, and @code{@var{mandir}} to
+@code{@var{prefix}/texmf-dist/doc/man}, corresponding to the
+directories used in the TL distribution.
+@end raggedright
+
+@end itemize
+
+@noindent The top-level @file{configure} script displays all these installation
+paths.
+
+For the native TL build, the @code{Build} script leaves the binaries
+in @file{./inst/bin/@var{std-platform-name}}. The new binaries are
+not directly usable from that location; they need to be copied to
+@file{Master/bin/@var{tl-platform}}. The other files and directories
+that end up in @file{./inst/} are ignored.
+
+
+@node Linked scripts
+@subsection Linked scripts
+
+@cindex linked scripts
+@cindex scripts, linked and not maintained
+
+@cindex symlinks, used for scripts
+@cindex wrapper binary for scripts on Windows
+@cindex Windows, invoking scripts on
+Quite a few executables are architecture-independent shell, Perl, or
+other scripts, rather than compiled binaries. A few are maintained as
+part of the TL source tree, but most are maintained elsewhere with
+copies under @file{texk/texlive/linked_scripts}. These are installed
+under @code{@var{datarootdir}/texmf-dist/scripts}; for Unix-like
+systems a symbolic link is made in @code{@var{bindir}}. For example,
+a symlink points from @code{@var{bindir}/ps2eps} to
+@code{@var{datarootdir}/texmf-dist/scripts/ps2eps/ps2eps.pl}.
+
+For Windows, a standard wrapper binary (e.g.,
+@code{@var{bindir}/ps2eps.exe}) serves the same purpose. (The source
+for it is in @file{texk/texlive/w32_wrapper}.)
+
+One reason for all this is to avoid having many copies for the same
+script, but most importantly this allows invoking the same script on
+all operating systems. Furthermore, we want the @code{@var{bindir}}
+resulting from the build to be exactly what is in the TL distribution;
+any deviations cause considerable extra work.
+
+
+@node Distro builds
+@subsection Distro builds
+
+@cindex distro, building for
+@cindex operating system distribution, building for
+@cindex system distribution, building for
+
+@cindex GNU/Linux distro
+@cindex BSD distro
+Although they use the same code base, building for the native TL
+distribution as shipped by the TL user groups is typically quite
+different from a ``distro'' build needed by, e.g., a full GNU/Linux
+or BSD operating system distribution.
+
+@cindex shared libraries, using vs.@: avoiding
+The native TL distribution uses shared libraries only when absolutely
+necessary (@file{libc}, @file{libm}, X11 libraries, and
+@file{libfontconfig}). However, a distro typically wants to use as
+many shared libraries as possible from elsewhere on the system,
+including @TeX{}-specific libraries such as @file{libkpathsea} (even
+though Kpathsea has never officially been released as a shared
+library, but we digress). In addition, the installation paths will,
+in general, be completely different.
+
+Here are the @code{configure} options that distro builds are likely to
+find most relevant:
+
+@table @code
+@item --disable-native-texlive-build
+This must be specified to avoid interference from the many tweaks we
+do for the native TL build.
+
+@item --with-banner-add=/@var{SomeDistro}
+This isn't technically required, but is strongly recommended, so your
+build and your distro can be distinguished from others.
+
+@item --enable-shared
+Build shared versions of the @TeX{}-specific libraries (uses
+@code{libtool}).
+
+@item --disable-static
+Do not build the static versions of the @TeX{}-specific libraries.
+
+@item --with-system-@var{lib}
+Use system versions for as many libraries @var{lib} as possible.
+@code{configure --help} will give you the list of possibilities.
+
+@item --with-@var{lib}-includes=@var{dir}
+@itemx --with-@var{lib}-libdir=@var{dir}
+If needed, allows you to specify where the headers/code are for the
+given library @var{lib}.
+
+@item --prefix=/usr
+@itemx --prefix=/opt/TeXLive
+Or whatever your convention is. The default is @file{/usr/local} and
+you shouldn't install there for a distro.
+
+@item --libdir=\$@{exec_prefix@}/lib64
+May be needed for 64-bit bi-architecture (GNU/Linux) systems.
+
+@end table
+
+@cindex Preining, Norbert
+@cindex adapting @TL{} for distros
+You will need to take care of the support files mentioned above
+(@pxref{Installing}), and many other issues, such as font maps,
+languages, and formats, independently of the build. Norbert Preining
+has written a detailed article on adapting TL for distros:
+@url{http://tug.org/TUGboat/tb34-3/tb108preining-distro.pdf}. (If it
+needs updating at some point, perhaps we will merge it into this
+document.)
+
+
+@node Infrastructure and layout
+@section Infrastructure and layout
+
+@cindex layout of sources
+@cindex source tree
+
+The @TL{} source tree is the subtree rooted at @file{Build/source} of
+the complete TL distribution and contains the sources for all executables
+distributed by TL, as well as @code{configure} scripts and @code{make}
+rules to build and install them together with some of their support
+files.
+
+@menu
+* Build system tools:: If modifying infrastructure files.
+* Top-level directories::
+* Autoconf macros:: TL-specific Autoconf macros.
+* Library modules:: Details on some specific libraries,
+* Program modules:: and on some programs.
+* Extending @TL{}:: Adding a new module.
+@end menu
+
+
+@node Build system tools
+@subsection Build system tools
+
+@cindex tools, for building
+@cindex GNU tools, needed for building
+@cindex infrastructure, tools needed for
+
+As mentioned above (@pxref{Prerequisites}), a normal build requires
+very little. On the other hand, if you want to modify the @TL{}
+infrastructure sources, such as @file{configure.ac} or
+@file{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 @code{configure --prefix=/usr/local/gnu}
+and having @env{PATH} start with @file{/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:
+
+@display
+@include build-tools.txt
+@end display
+
+@pindex reautoconf
+@vindex --enable-maintainer-mode configure @r{option}
+These versions should be used to update the generated files (e.g.,
+@file{configure} or @file{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 @code{reautoconf} script or implicitly
+by using the configure option @code{--enable-maintainer-mode}.
+
+@cindex Subversion repository
+@cindex timestamps, in repository
+@vindex use-commit-times@r{, Subversion}
+The files in the Subversion repository (see
+@url{http://tug.org/texlive/svn}) are all up to date, but
+unfortunately this may not be reflected by their timestamps. (For
+starters, be sure to set @file{use-commit-times=yes} in
+@file{~/.subversion/config} or the equivalent.)
+
+@cindex touching files to avoid rerunning
+@pindex make -t
+To avoid unnecessary runs of @code{bison}, @code{flex}, or
+@code{makeinfo} it may be necessary to @code{touch} the generated
+(@file{.c}, @file{.h}, or @file{.info}) files. With
+@code{--enable-maintainer-mode} it may also be necessary to
+@code{touch} first @file{aclocal.m4}, then @file{configure} and
+@file{config.h.in} (or @file{c-auto.in}), and finally all
+@file{Makefile.in} files. Perhaps @code{make -t} will help.
+
+
+@node Top-level directories
+@subsection Top-level directories
+
+@cindex directories, top-level
+@cindex top-level directories
+
+Here is a brief description of the top-level directories in the @TL{}
+source tree.
+
+As mentioned at the beginning of the chapter (@pxref{Build system}),
+the main source directories are @file{texk/} (@TeX{}-specific programs
+and libraries), @file{utils/} (additional programs), and @file{libs}
+(generic libraries).
+
+@cindex @file{am/} top-level directory
+@cindex @file{m4/} top-level directory
+The top-level directories @file{am/} and @file{m4/} contain
+@file{Makefile.am} fragments and Autoconf macros, respectively, used
+in many places. Specifically, the file @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 @file{configure.ac} scripts at
+the top-level and in the subdirectories @file{libs}, @file{utils}, and
+@file{texk}. The fragments from program modules supply
+@code{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
+@file{make} targets such as @code{dist} or @code{distcheck}.
+
+@pindex config.guess@r{,} config.sub
+@cindex Gnulib, used for common files
+The top-level @file{build-aux/} directory contains the common files
+@file{compile}, @file{config.guess}, @file{config.sub},
+@file{depcomp}, etc.@ for most packages, pulled from the GNU Gnulib
+sources (@url{http://www.gnu.org/software/gnulib}), which in turn
+synchronizes with the appropriate ultimate upstream repository. There
+are, however, independent copies in, e.g.,
+@file{libs/freetype2/freetype-*/builds/unix/}, and similar places.
+The @code{reautoconf} script does not touch those, but a TL cron job
+keeps them in sync (nightly).
+
+@cindex @file{extra/} top-level directory
+The directory @file{extra/} contains things which are not part of the
+TL build, but are present for convenience, e.g., @file{epstopdf}
+developed here and @file{xz/} required by the TL installer.
+
+
+@node Autoconf macros
+@subsection Autoconf macros
+
+@cindex autoconf macros
+
+@c Texinfo macro: @ovar(ARG)
+@c ARG is the name of an optional argument; this is used for
+@c documentation of macro arguments (@defmac lines). Plain
+@c brackets are treated specially and appear more distinct.
+@macro ovar{varname}
+[@var{\varname\}]
+@end macro
+
+@c @dvar(ARG, DEFAULT)
+@c -------------------
+@c The ARG is an optional argument, defaulting to DEFAULT. To be used
+@c for macro arguments in their documentation (@defmac).
+@c @macro xxdvar{varname, default}
+@c @r{[}@var{\varname\} = @samp{\default\}@r{]}
+@c @end macro
+
+Here we describe some of the Autoconf macros used in several
+modules--not a complete list, by any means. These general macros are
+supplemented by module-specific macros in directories such as
+@file{texk/dvipng/m4/}; some of those are described in @ref{Library
+modules} and @pxref{Program modules}.
+
+@menu
+* Setup: General setup macros.
+* Programs: Macros for programs.
+* Compilers: Macros for compilers.
+* Libraries: Macros for libraries.
+* Flags: Macros for library and header flags.
+* Windows: Macros for Windows.
+@end menu
+
+@node General setup macros
+@subsubsection General setup macros
+
+@cindex general setup macros
+@cindex setup macros, general
+@cindex macros, general setup
+The TL sources use two general setup macros:
+
+@defmac KPSE_BASIC (@var{name}, @ovar{more-options})
+Initialize the basic TL infrastructure for module @var{name}:@*@ @ @
+@code{AM_INIT_AUTOMAKE([foreign @var{more-options}])}@*@ @ @
+@code{AM_MAINTAINER_MODE}@*@ @ @ @code{KPSE_COMPILER_WARNINGS}@*
+and make sure the C compiler understands function prototypes. This is
+used for all generic library and program modules.
+@end defmac
+
+@defmac KPSE_COMMON (@var{name}, @ovar{more-options})
+Like @code{KPSE_BASIC} but add:@*@ @ @ @code{LT_PREREQ([2.2.6])}@*@ @
+@ @code{LT_INIT([win32-dll])}@*@ @ @ @code{AC_SYS_LARGEFILE}@*@ @ @
+@code{AC_FUNC_FSEEKO}@*and check for frequently used functions,
+headers, types, and structures. This is used for @TeX{}-specific
+modules.
+@end defmac
+
+
+@node Macros for programs
+@subsubsection Macros for programs
+
+@cindex macros, for programs
+Macros for program checks:
+
+@defmac KPSE_CHECK_LATEX
+Set @code{LATEX} to the name of the first of @code{latex},
+@code{elatex}, or @code{lambda} which exists in @code{PATH}, or to
+@code{no} if none of them exists. Call @code{AC_SUBST} for
+@code{LATEX}. The result of this test can be overridden by setting
+the @code{LATEX} environment variable or the cache variable
+@code{ac_cv_prog_LATEX}.
+@end defmac
+
+@defmac KPSE_CHECK_PDFLATEX
+Check for @code{pdflatex} in @code{PATH} and set @code{PDFLATEX}.
+@end defmac
+
+@defmac KPSE_CHECK_PERL
+Check for @code{perl} or @code{perl5} in @code{PATH} and set
+@code{PERL}.
+@end defmac
+
+@defmac KPSE_PROG_LEX
+Call @code{AC_PROG_LEX} and add the flag @code{-l} for @code{flex}.
+@end defmac
+
+
+@node Macros for compilers
+@subsubsection Macros for compilers
+
+@cindex macros, for compilers
+
+Macros for compiler-related checks:
+
+@defmac KPSE_COMPILER_WARNINGS
+@vindex WARNING_C[XX]FLAGS
+When using the (Objective) C/C++ compiler, set
+@code{WARNING_[OBJ]C[XX}]FLAGS to suitable warning flags (depending on
+the value given to or implied for @code{--enable-compiler-warnings}).
+Call @code{AC_SUBST} for them. At the moment this only works for GNU
+compilers, but could be extended to others if necessary.
+
+@vindex kpse_cv_warning_cflags
+This macro caches its results in the @code{kpse_cv_warning_cflags},
+@dots{} variables.
+@end defmac
+
+@defmac KPSE_COMPILER_VISIBILITY
+When using the C or C++ compiler, try to set
+@code{VISIBILITY_C[XX]FLAGS} to flags to hide external symbols. Call
+@code{AC_SUBST} for this variable. At the moment this only tests for
+the compiler option @code{-fvisibility=hidden}, but that could be
+extended with more checks if necessary.
+
+@vindex kpse_cv_visibility_c[xx]flags
+This macro caches its results in the @code{kpse_cv_visibility_cflags}
+or @code{kpse_cv_visibility_cxxflags} variable.
+@end defmac
+
+@defmac KPSE_CXX_HACK
+@cindex static linking for C++
+@cindex linking C++ libraries statically
+@vindex --enable-cxx-runtime-hack configure @r{option}
+@pindex libstc++@r{, statically linking}
+Provide the configure option @code{--enable-cxx-runtime-hack}. If
+enabled and when using @code{g++}, try to statically link with
+@file{libstdc++}, somewhat improving portability of the resulting
+binary.
+
+@vindex kpse_cv_cxx_hack
+This macro caches its result in the @code{kpse_cv_cxx_hack} variable.
+@end defmac
+
+
+@node Macros for libraries
+@subsubsection Macros for libraries
+
+@cindex macros, for libraries
+One macro for a library check:
+
+@defmac KPSE_LARGEFILE (@var{variable}, @ovar{extra-define})
+Call @code{AC_SYS_LARGEFILE} and @code{AC_FUNC_FSEEKO} and append
+suitable @code{-D} flags (optionally including
+@code{-D@var{extra-define}}) to @var{variable}.
+@end defmac
+
+
+@node Macros for library and header flags
+@subsubsection Macros for library and header flags
+
+@cindex macros, for library and header flags
+@cindex flags, macros for library and header
+@vindex KPSE_@var{LIB}_FLAGS
+Each library module @file{libs/@var{lib}} or @file{texk/@var{lib}} is
+supplemented by a macro @code{KPSE_@var{LIB}_FLAGS} (all uppercase)
+that provides make variables for that library. E.g., for
+@file{libs/libpng}:
+
+@defmac KPSE_LIBPNG_FLAGS
+Provide the configure option @code{--with-system-libpng}. Set and
+@code{AC_SUBST} @code{make} variables for modules using this library
+(either an installed version or from the @TL{} tree): @code{LIBPNG_INCLUDES}
+for use in CPPFLAGS, LIBPNG_LIBS for use in LDADD, LIBPNG_DEPEND for
+use as dependency, and LIBPNG_RULE defining @code{make} rules to
+rebuild the library.
+@end defmac
+
+@defmac KPSE_ADD_FLAGS (@var{libname})
+Temporarily extend CPPFLAGS and LIBS with the values required for the
+library module @code{@var{name}}.
+@end defmac
+
+@defmac KPSE_RESTORE_FLAGS
+Restore @code{CPPFLAGS} and @code{LIBS} to their original values.
+@end defmac
+
+As an example, the @file{configure.ac} file for a hypothetical program
+@file{utils/foo} using @file{libpng}, and hence @file{zlib}, would
+contain
+@example
+KPSE_ZLIB_FLAGS
+KPSE_LIBPNG_FLAGS
+@end example
+
+@noindent and its @file{Makefile.am} would be along these lines:
+@example
+bin_PROGRAMS = foo
+AM_CPPFLAGS = $@{ZLIB_INCLUDES@} $@{LIBPNG_INCLUDES@}
+foo_LDADD = $@{ZLIB_LIBS@} $@{LIBPNG_LIBS@}
+foo_DEPENDENCIES = $@{ZLIB_DEPEND@} $@{LIBPNG_DEPEND@}
+## Rebuild libz
+@@ZLIB_RULE@@
+## Rebuild libpng
+@@LIBPNG_RULE@@
+@end example
+
+If it was necessary to examine whether certain @file{zlib} or
+@file{libpng} features were available, @file{configure.ac} should be
+continued this way:
+@example
+KPSE_ADD_FLAGS([zlib])
+@dots{} # @r{tests for @file{zlib} features, if any}
+KPSE_ADD_FLAGS([libpng])
+@dots{} # @r{tests for @file{libpng} features}
+KPSE_RESTORE_FLAGS # @r{restore @code{CPPFLAGS} and @code{LIBS}}
+@end example
+
+
+@node Macros for Windows
+@subsubsection Macros for Windows
+
+@cindex macros, for Windows
+@cindex Windows, macros for
+Windows differs in several aspects from Unix-like systems, many of
+them due to the lack of symbolic links.
+
+@defmac KPSE_CHECK_WIN32
+@vindex kpse_cv_have_win32
+Check if compiling for a Windows system. The result is @code{no} for
+Unix-like systems (including Cygwin), @code{mingw32} for Windows with
+GCC, or @code{native} for Windows with MSVC. The result is cached in
+the @code{kpse_cv_have_win32} variable.
+@end defmac
+
+@defmac KPSE_COND_WIN32
+@vindex WIN32@r{, Automake conditional}
+Call @code{KPSE_CHECK_WIN32} and define the Automake conditional
+@code{WIN32} (@code{true} if the value of @code{kpse_cv_have_win32} is
+not @code{no}).
+@end defmac
+
+@defmac KPSE_COND_MINGW32
+@vindex MINGW32@r{, Automake conditional}
+Call @code{KPSE_COND_WIN32} and define the Automake conditional
+@code{MINGW32} (@code{true} if the value of @code{kpse_cv_have_win32} is
+@code{mingw32}).
+@end defmac
+
+@defmac KPSE_COND_WIN32_WRAP
+@vindex WIN32_WRAP@r{, Automake conditional}
+@pindex runscript.exe
+Call @code{KPSE_COND_WIN32} and define the Automake conditional
+@code{WIN32_WRAP} (@code{true} if the standard Windows wrapper
+(@file{texk/texlive/w32_wrapper/runscript.exe}) exists. This wrapper
+is used on Windows instead of symlinks for the ``linked scripts''
+(@pxref{Linked scripts}).
+@end defmac
+
+@defmac KPSE_WIN32_CALL
+@pindex callexe.c
+Call @code{KPSE_COND_WIN32}, check if the file
+@file{texk/texlive/w32_wrapper/callexe.c} exists; if it does, create a
+symlink in the build tree. Compiling @file{callexe.c} with
+@code{-DEXEPROG='"@var{foo}.exe"'} and installing @file{callexe.exe}
+as @code{@var{bar}.exe} is used on Windows instead of a symlink
+@code{@var{bar}->@var{foo}} for Unix-like systems.
+@end defmac
+
+
+@node Library modules
+@subsection Library modules
+
+@cindex library modules
+@cindex modules, for libraries
+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.
+
+@menu
+* @code{png} library:: @file{libs/libpng}
+* @code{zlib} library:: @file{libs/zlib}
+* @code{freetype} library:: @file{libs/freetype2}
+* @code{kpathsea} library:: @file{texk/kpathsea}
+@end menu
+
+@node @code{png} library
+@subsubsection The @code{png} library in @file{libs/libpng}
+
+@pindex png @r{library}
+@pindex libpng @r{library}
+This generic library uses the source tree in, e.g., the subdirectory
+@file{libpng-1.5.17} with all modifications for TL recorded in
+@file{libpng-1.5.17-PATCHES/*}. The @file{configure.ac} fragment
+@file{ac/withenable.ac} contains
+
+@example
+KPSE_WITH_LIB([libpng], [zlib])
+@end example
+
+@noindent specifying the module name, and indicating the dependency on
+@code{zlib}. A third literal argument @code{tree} would specify that
+the library from the @TL{} tree cannot be replaced by a system
+version. That not being the case here, a second fragment
+@file{ac/libpng.ac} contains
+
+@findex KPSE_TRY_LIB
+@example
+KPSE_TRY_LIB([libpng],
+ [#include <png.h>],
+ [png_structp png; png_voidp io; png_rw_ptr fn;
+png_set_read_fn(png, io, fn);])
+@end example
+
+@noindent thus providing the simple C code
+
+@example
+#include <png.h>
+int main ()
+@{ png_structp png; png_voidp io; png_rw_ptr fn;
+ png_set_read_fn(png, io, fn);
+ return 0; @}
+@end example
+
+@findex KPSE_TRY_LIBXX
+@noindent which Autoconf uses to verify the usability of a system
+version with C code. The analogous macro @code{KPSE_TRY_LIBXX} would
+check using C++ code. These fragments are included by
+@file{configure.ac} at the top level.
+
+For this library, among many other modules, a proxy build system for
+TL is used (@file{configure.ac}, @file{Makefile.am}, and
+@file{include/Makefile.am}), ignoring the distributed one.
+Consequently, a few generated files and auxiliary scripts are removed
+from the distributed source tree. The public headers @file{png.h},
+@file{pngconf.h}, and @file{pnglibconf.h} are ``installed'' (as
+symlinks) under @file{include/} in the build tree exactly as they are
+for a system version under, e.g., @file{/usr/include/}.
+
+@pindex kpse-libpng-flags.m4
+@vindex KPSE_LIBPNG_FLAGS
+The module is supplemented by the file @file{m4/kpse-libpng-flags.m4}
+that defines the M4 macro @code{KPSE_LIBPNG_FLAGS} used by all modules
+depending on this library in their @file{configure.ac} to generate the
+@code{make} variables @code{LIBPNG_INCLUDES} for use in
+@code{CPPFLAGS}, @code{LIBPNG_LIBS} for use in @code{LDADD},
+@code{LIBPNG_DEPEND} for use as dependencies, and @code{LIBPNG_RULE}
+defining @code{make} rules to rebuild the library.
+
+@file{m4/kpse-libpng-flags.m4} also supplies the configure option
+@code{--with-system-libpng} and uses @code{pkg-config} to determine
+the flags required for the system library.
+
+
+@node @code{zlib} library
+@subsubsection The @code{zlib} library in @file{libs/zlib}
+
+@pindex zlib @r{library}
+
+@pindex kpse-zlib-flags.m4
+This generic library is very much analogous to @code{libpng}, but
+without the dependency on any other library. The file
+@file{m4/kpse-zlib-flags.m4} supplies the configure option
+@code{--with-system-zlib}, as well as @code{--with-zlib-includes} and
+@code{--with-zlib-libdir} to specify non-standard locations of the
+@code{zlib} headers and/or library.
+
+
+@node @code{freetype} library
+@subsubsection The @code{freetype} library in @file{libs/freetype2}
+
+@pindex freetype @r{library}
+
+@pindex freetype-config
+This module uses a wrapper build system with an almost trivial
+@file{configure.ac} and with a @file{Makefile.am} that invokes
+@code{configure} and @code{make} for the distributed source, followed
+by @code{make install} with the build tree as destination. The flags
+required for the system library are obtained through
+@code{freetype-config}.
+
+
+@node @code{kpathsea} library
+@subsubsection The @code{kpathsea} library in @file{texk/kpathsea}
+
+@pindex kpathsea @r{library}
+
+This is one of the @TeX{}-specific libraries that are maintained as
+part of @TL{} (@pxref{,,, kpathsea, Kpathsea}). Despite being a core
+part of the @TeX{} system, it is not a terribly special case in the
+infrastructure. The @TeX{} libraries are Libtool libraries (static
+and/or shared) and are installed by @code{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.
+
+@pindex --with-system-kpathsea
+It is possible, and possibly even useful for distro builds
+(@pxref{Distro builds}, to specify the configure option
+@code{--with-system-kpathsea} in order to use a system version of the
+library and it may then be necessary to specify
+@code{--with-kpathsea-includes} and/or @code{--with-kpathsea-libdir}.
+
+@pindex kpathsea.ac
+@pindex mktex.ac
+@vindex --enable-mktextfm-default
+@pindex mktextfm
+In addition to @file{ac/withenable.ac} and @file{ac/kpathsea.ac} there
+is a third fragment @file{ac/mktex.ac} included by both
+@file{ac/withenable.ac} and @file{configure.ac} that supplies
+configure options such as @code{--enable-mktextfm-default}, which
+determine the compile time default of whether or not to run
+@code{mktextfm} to generate a missing @file{.tfm} file. In any case,
+however, the command line options @code{-mktex=tfm} or
+@code{-no-mktex=tfm} for the @TeX{}-like engines override this default.
+
+
+@node Program modules
+@subsection Program modules
+
+@cindex program modules
+@cindex modules, for programs
+As with libraries (@pxref{Library modules}), here we discuss the
+details for a few of the programs in TL.
+
+@menu
+* @code{t1utils} package:: @file{utils/t1utils}
+* @code{xindy} package:: @file{utils/xindy}
+* @code{xdvik} package:: @file{texk/xdvik}
+* @code{asymptote}:: @file{utils/asymptote}
+@end menu
+
+
+@node @code{t1utils} package
+@subsubsection The @code{t1utils} package in @file{utils/t1utils}
+
+@pindex t1utils @r{package}
+
+Once again we use the distributed source tree @file{t1utils-1.38} with
+modifications documented in @file{t1utils-1.38-PATCHES/*} and a proxy
+build system consisting of @file{configure.ac} and @file{Makefile.am}.
+The fragment @file{ac/withenable.ac} contains
+
+@example
+KPSE_ENABLE_PROG([t1utils])
+@end example
+
+@noindent specifying the module name without any dependencies, and
+supplies the configure option @code{--disable-t1utils}.
+
+
+@node @code{xindy} package
+@subsubsection The @code{xindy} package in @file{utils/xindy}
+
+@pindex xindy
+
+This module uses the distributed source tree @file{xindy-2.4} with
+modifications documented in @file{xindy-2.4-PATCHES/*}, a proxy
+@file{configure.ac}, and a wrapper @file{Makefile.am} that descends
+into @file{xindy-2.4}. The @code{xindy} build requires that the
+distributed @file{Makefile}s allow a @code{VPATH} build, can handle
+all targets, and do not refer to @code{$@{top_srcdir@}} or
+@code{$@{top_builddir@}}. The fragment @code{ac/withenable.ac}
+contains
+
+@example
+KPSE_ENABLE_PROG([xindy], , [disable native])
+m4_include(kpse_TL[utils/xindy/ac/xindy.ac])
+m4_include(kpse_TL[utils/xindy/ac/clisp.ac])
+@end example
+
+@noindent where @code{disable} in the third argument indicates that
+@code{xindy} is only built if explicitly enabled by the user with
+@code{configure --enable-xindy} (the need for @code{clisp} is too
+painful to require by default), and @code{native} disallows cross
+compilation. The additional fragments @file{ac/xindy.ac} and
+@file{ac/clisp.ac} specify more @code{configure} options to be seen at
+the top level with @file{ac/xindy.ac} also included by
+@file{configure.ac}.
+
+
+@node @code{xdvik} package
+@subsubsection The @code{xdvik} package in @file{texk/xdvik}
+
+@pindex xdvik
+
+This package is maintained as part of the @TL{} tree with sources in
+its top level directory and the subdirectory @file{gui}. The fragment
+@code{ac/withenable.ac} contains
+
+@example
+dnl extra_dirs = texk/xdvik/squeeze
+KPSE_ENABLE_PROG([xdvik], [kpathsea freetype2], [x])
+m4_include(kpse_TL[texk/xdvik/ac/xdvik.ac])
+@end example
+
+@pindex squeeze/configure.ac
+@cindex cross compilation, with host binary
+@noindent thus specifying the dependency on the @code{kpathsea},
+@code{freetype}, and X11 libraries. The M4 comment (following
+@code{dnl}) signals the subsidiary @file{squeeze/configure.ac}. This
+is needed because the main executable @file{xdvi-bin} (to be installed
+as, e.g., @file{xdvi-xaw}) is for the @code{host} system whereas the
+auxiliary program @file{squeeze/squeeze} has to run on the
+@code{build} system and in a cross compilation they differ.
+
+@vindex --with-xdvi-x-toolkit
+The additional fragment @code{ac/xdvik.ac} is also included by
+@file{configure.ac} and supplies the configure option
+@code{--with-xdvi-x-toolkit} also seen at the top-level.
+
+
+@node @code{asymptote}
+@subsubsection The subdirectory @file{utils/asymptote}
+
+@pindex asymptote
+@pindex xasy
+
+@cindex OpenGL, required for Asymptote
+This subdirectory contains the sources for @file{asy} and @file{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.
+
+
+@node Extending @TeX{} Live
+@subsection Extending @TeX{} Live
+
+@cindex extending @TL{}
+@cindex adding to @TL{}
+
+This section outlines the basic process for adding new packages to the
+TL build system.
+
+@menu
+* Adding a new program module::
+* Adding a new generic library module::
+* Adding a new @TeX{}-specific library module::
+@end menu
+
+
+@node Adding a new program module
+@subsubsection Adding a new program module
+
+@cindex adding a new program
+@cindex program module, adding
+
+@vindex kpse_texk_pkgs
+A @TeX{}-specific program module in a subdirectory
+@file{texk/@var{prog}} may use the @TeX{}-specific libraries and is
+included by adding its name @file{@var{prog}} to the M4 list
+@code{kpse_texk_pkgs} defined in @file{m4/kpse-pkgs.m4}.
+
+@vindex kpse_utils_pkgs
+A generic program module in a subdirectory @file{utils/@var{prog}}
+must not use the @TeX{}-specific libraries and is included by adding
+its name @file{@var{prog}} to the M4 list @code{kpse_utils_pkgs} in
+@file{m4/kpse-pkgs.m4}.
+
+@pindex withenable.ac@r{, for new modules}
+@findex KPSE_ENABLE_PROG
+In either case, apart from the program sources and build system
+(@file{configure.ac} and @file{Makefile.am}), the subdirectory
+@file{texk/@var{prog}} or @file{utils/@var{prog}} must provide a
+fragment @file{ac/withenable.ac} that contains the M4 macro
+@code{KPSE_ENABLE_PROG} defined in @file{m4/kpse-setup.m4} with
+@code{@var{prog}} as the mandatory first argument and three optional
+arguments:
+
+@enumerate
+@item a list of required libraries from the TL tree;
+
+@item a list of options (@code{disable} if this module is not to be
+built without the configure option @code{--enable-@var{prog}},
+@code{native} if cross compilation is not possible, @code{x} if the
+program requires X11 libraries);
+
+@item and a comment added to the help text for the @code{configure}
+option @code{--enable-@var{prog}} or @code{--disable-@var{prog}}.
+@end enumerate
+
+If the module requires specific configure options to be seen at the
+top-level, they should be defined in an additional fragment
+@file{ac/@var{prog}.ac} included from @file{ac/withenable.ac} and
+@file{configure.ac}.
+
+
+@node Adding a new generic library module
+@subsubsection Adding a new generic library module
+
+@cindex adding a new generic library
+@cindex generic library module, adding
+@cindex library module, generic, adding
+
+@vindex kpse_libs_pkgs
+A generic library module in a subdirectory @file{libs/@var{lib}} must
+not depend on @TeX{}-specific libraries, by definition. It is
+included by adding its name @file{@var{lib}} to the M4 list
+@code{kpse_libs_pkgs} in @file{m4/kpse-pkgs.m4}---before any other
+libraries from the @TL{} tree on which it depends.
+
+@findex KPSE_WITH_LIB
+As with program modules, the subdirectory @file{libs/@var{lib}} must
+contain the sources and build system for the library (and any
+installable support programs) and a fragment @file{ac/withenable.ac}
+that contains the M4 macro @code{KPSE_WITH_LIB} defined in
+@file{m4/kpse-setup.m4} with @code{@var{lib}} as the mandatory first
+argument and two optional arguments: a list of required libraries from
+the TL tree, and a list of options (currently there is only one:
+specify @code{tree} if this library cannot be replaced by a system
+version).
+
+@findex KPSE_TRY_LIB
+@findex KPSE_TRY_LIBXX
+If a system version can be used, a second fragment
+@file{ac/@var{lib}.ac} is needed, containing the M4 macro
+@code{KPSE_TRY_LIB} (or @code{KPSE_TRY_LIBXX}) with @code{@var{lib}}
+as the mandatory first argument and two additional arguments for the
+Autoconf macro @code{AC_LANG_PROGRAM} used to compile and link a small
+C (or C++) program as sanity check for using the system library.
+
+@vindex KPSE_@var{LIB}_FLAGS
+In addition a file @file{m4/kpse-@var{lib}-flags} (at the top level)
+must define the M4 macro @code{KPSE_@var{LIB}_FLAGS} (all uppercase)
+setting up the @code{make} variables @code{@var{LIB}_INCLUDES},
+@code{@var{LIB}_LIBS}, @code{@var{LIB}_DEPEND}, and
+@code{@var{LIB}_RULE} with the values required for @code{CPPFLAGS},
+@code{LDADD}, dependencies, and a (multi-line) @code{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.
+
+@vindex --with-system-@var{lib}
+@vindex KPSE_@var{LIB}_SYSTEM_FLAGS
+@vindex KPSE_ALL_SYSTEM_FLAGS
+If a system library is allowed, @code{KPSE_@var{LIB}_FLAGS} also
+provides the configure option @code{--with-system-@var{lib}} and uses
+the additional M4 macro @code{KPSE_@var{LIB}_SYSTEM_FLAGS} to generate
+the @code{make} variables for a system library. Furthermore the
+definition of the M4 macro @code{KPSE_ALL_SYSTEM_FLAGS} in
+@file{m4/kpse-pkgs.m4} must be extended by the line:@*@ @ @
+@code{AC_REQUIRE([KPSE_@var{LIB}_SYSTEM_FLAGS])}
+
+
+@node Adding a new @TeX{}-specific library module
+@subsubsection Adding a new @TeX{}-specific library module
+
+@cindex adding a new @TeX{}-specific library
+@cindex @TeX{}-specific library module, adding
+@cindex library module, @TeX{}-specific, adding
+
+A @TeX{}-specific library module in a subdirectory
+@file{texk/@var{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:
+
+@itemize @bullet
+@item
+@vindex kpse_texlibs_pkgs
+The library name @code{@var{lib}} is added to the M4 list
+@code{kpse_texlibs_pkgs} also in @file{m4/kpse-pkgs.m4}.
+
+@item
+@findex KPSE_WITH_TEXLIB
+The fragment @code{ac/withenable.ac} must use @code{KPSE_WITH_TEXLIB}.
+@end itemize
+
+
+@node Configure options
+@section Configure options
+
+@cindex @code{configure} options
+
+Corresponding to the large number of program and library modules there
+are a large number @code{configure} options, most of which are
+described here. The command@*@ @ @ @code{configure --help}@*at the
+top level gives an exhaustive list of all global options and a few
+important module-specific ones, whereas, e.g.,@*@ @ @
+@code{texk/lcdf-typetools/configure --help}@* also displays the
+@code{lcdf-typetools} specific options, which are not shown by the
+top-level @code{--help}.
+
+@cindex environment variables, for @code{configure}
+The help text also mentions several influential environment variables,
+but for @TL{} it is better to specify them as assigments on the
+command line.
+
+The @file{./Build} script used to make the binaries shipped with @TL{}
+invokes the top-level @code{configure} with a few additional options
+(@pxref{Building}). The defaults discussed below are those for the
+actual @code{configure} script; invoking @code{configure} via
+@file{./Build} may yield different results.
+
+Defaults for most options are set at the top level and propagated
+explicitly to all subdirectories. Options specified on the command
+line are checked for consistency but never modified.
+
+@menu
+* Global configure options::
+* Program-specific configure options::
+* Library-specific configure options::
+* Variables for configure::
+@end menu
+
+
+@node Global configure options
+@subsection Global configure options
+
+@cindex global @code{configure} options
+@cindex @code{configure} options, global
+Here are the global configure options.
+
+@menu
+* @code{--disable-native-texlive-build}::
+* @code{--prefix} @code{--bindir} @dots{}::
+* @code{--disable-largefile}::
+* @code{--disable-missing}::
+* @code{--enable-compiler-warnings=}@var{level}::
+* @code{--enable-cxx-runtime-hack}::
+* @code{--enable-maintainer-mode}::
+* @code{--enable-multiplatform}::
+* @code{--enable-shared}::
+* @code{--enable-silent-rules}::
+* @code{--without-ln-s}::
+* @code{--without-x}::
+@end menu
+
+
+@node @code{--disable-native-texlive-build}
+@subsubsection @code{--disable-native-texlive-build}
+
+@vindex --disable-native-texlive-build
+If enabled (the default), build for a TL binary distribution as
+shipped by the @TeX{} user groups. This requires GNU @code{make} and
+implies @code{--enable-multiplatform} and
+@code{--enable-cxx-runtime-hack} (unless they are explicitly disabled),
+and enforces @code{--disable-shared}.
+
+If building TL for a GNU/Linux or other distribution, this should be
+disabled and system versions of most libraries would be used
+(@pxref{Distro builds}). This may fail without GNU @code{make}, but
+will be tried regardless.
+
+@vindex --enable-texlive-build
+A related option, @code{--enable-texlive-build}, is automatically
+passed to all subdirectories (and cannot be disabled). Subdirectories
+that can also be built independently from the TL tree (such as
+@file{utils/xindy} and @file{texk/dvipng}) can use this option, e.g.,
+to choose TL-specific installation paths.
+
+
+@node @code{--prefix} @code{--bindir} @dots{}
+@subsubsection @code{--prefix}, @code{--bindir}, @dots{}
+
+@vindex --prefix configure @r{option}
+@vindex --bindir configure @r{option}
+These standard Autoconf options specify various installation
+directories as usual. For the complete list, @pxref{Installation
+directories}.
+
+@vindex DESTDIR
+Also as usual, all values are prefixed by the value of @code{DESTDIR},
+if set, on the @code{make} command line (@pxref{Staged Installs, ,
+Installation in a temporary location, automake, GNU Automake}).
+
+
+@node @code{--disable-largefile}
+@subsubsection @code{--disable-largefile}
+
+@vindex --disable-largefile
+@cindex large file support
+@cindex LFS (large file support)
+Omit large file support (LFS), needed on most 32-bit Unix systems for
+files with 2GB or more. Regardless of this, the size of @code{DVI}
+and @code{GF} files must always be @math{<2}GB, due to the file format
+specifications.
+
+@cindex size of PDF and PS files
+@cindex PDF files, size of
+@cindex PostScript files, size of
+With LFS, there is no fixed limit on the size of PDF files created by
+@file{pdftex} or PostScript files created by @file{dvips}. The size
+of PDF images included by @file{pdftex} must, however, be @math{<4}GB
+when using @file{xpdf} and @math{<2}GB when using older versions of
+@file{poppler} (even on 64-bit systems with LFS), whereas
+@file{poppler} versions@tie{}0.23 and later impose no such limit.
+
+
+@node @code{--disable-missing}
+@subsubsection @code{--disable-missing}
+
+@vindex --disable-missing
+Immediately terminate the build process if a requested program or feature
+must be disabled, e.g., due to missing libraries. This can help when
+figuring out a specific (sub)set of modules to enable.
+
+
+@node @code{--enable-compiler-warnings=}@var{level}
+@subsubsection @code{--enable-compiler-warnings=}@var{level}
+
+@vindex --enable-compiler-warnings=@var{level}
+Enable various levels of compiler warnings for (Objective) C and C++:
+the @var{level} value can be one of: @code{no min yes max all}.
+The default is @code{yes} in @code{maintainer-mode} (see below) and
+@code{min} otherwise. This option defines
+@code{WARNING_[OBJ]C[XX]FLAGS} but these flags are not used in all
+library and program modules. Using them should help to resolve
+portability problems.
+
+At present, these warning flags are only defined for the GNU compilers
+but flags for other compilers could be added when needed.
+
+
+@node @code{--enable-cxx-runtime-hack}
+@subsubsection @code{--enable-cxx-runtime-hack}
+
+If enabled (as it is for the native TL build) and when using
+@code{g++}, try to statically link with @code{libstdc++}, somewhat
+improving portability of the resulting binary. @xref{Macros for
+compilers}.
+
+
+@node @code{--enable-maintainer-mode}
+@subsubsection @code{--enable-maintainer-mode}
+
+@vindex --enable-maintainer-mode
+Enable @file{make} rules and dependencies not useful (and sometimes
+confusing) to the casual user. This requires current versions of the
+GNU build tools (@pxref{Build system tools}), as it automatically
+rebuilds infrastructure files as needed. @xref{maintainer-mode,,
+@code{missing} and @code{AM_MAINTAINER_MODE}, automake, GNU Automake}.
+
+
+@node @code{--enable-multiplatform}
+@subsubsection @code{--enable-multiplatform}
+
+@vindex --enable-multiplatform
+@vindex exec_prefix
+@vindex --libdir
+If enabled, install executables and libraries in per-platform
+subdirectories of @file{@var{eprefix}/bin} and
+@file{@var{eprefix}/lib} where @var{eprefix} is the value given or
+implied for @code{exec_prefix}. This can be overridden by explicitly
+@code{--bindir=@var{dir}} or @code{--libdir=@var{dir}}. In any case,
+the values for @code{bindir} and @code{libdir} are automatically
+propagated to all subdirectories.
+
+
+@node @code{--enable-shared}
+@subsubsection @code{--enable-shared}
+
+@vindex --enable-shared
+Build shared versions of the @TeX{}-specific libraries such as
+@file{libkpathsea}. This is not allowed for a native TL build (i.e.,
+@code{--disable-native-texlive-build} must also be specified).
+
+
+@node @code{--enable-silent-rules}
+@subsubsection @code{--enable-silent-rules}
+
+@vindex --enable-silent-rules
+Enable the use of less verbose build rules. When using GNU
+@code{make} (or another @code{make} implementation supporting nested
+variable expansions), you can specify @code{V=1} on the @code{make} command
+line to get more verbosity, or @code{V=0} to get less, regardless of
+this option.
+
+
+@node @code{--without-ln-s}
+@subsubsection @code{--without-ln-s}
+
+@vindex --without-ln-s
+Required when using a system without a working @code{ln -s} to build
+binaries for a Unix-like system. However, @code{make install} will
+not create anything useful and might even fail.
+
+
+@node @code{--without-x}
+@subsubsection @code{--without-x}
+
+@vindex --without-x
+Disable all programs using the X Window System.
+
+
+@node Program-specific configure options
+@subsection Program-specific configure options
+
+@cindex program-specific @code{configure} options
+@cindex @code{configure} options, program-specific
+Here are (some of) the program-specific @code{configure} options.
+
+@menu
+* @code{--enable-@var{prog}} @code{--disable-@var{prog}}::
+* @code{--disable-all-pkgs}::
+* Configure options for @file{texk/web2c}::
+* Configure options for @file{texk/bibtex-x}::
+* Configure options for @file{texk/dvipdfm-x}::
+* Configure options for @file{texk/dvisvgm}::
+* Configure options for @file{texk/texlive}::
+* Configure options for @file{texk/xdvik}::
+* Configure options for @file{utils/xindy}::
+@end menu
+
+
+@node @code{--enable-@var{prog}} @code{--disable-@var{prog}}
+@subsubsection @code{--enable-@var{prog}}, @code{--disable-@var{prog}}
+
+@vindex --enable-@var{prog}
+@vindex --disable-@var{prog}
+Do or do not build and install the program(s) of the module @code{@var{prog}}.
+
+
+@node @code{--disable-all-pkgs}
+@subsubsection @code{--disable-all-pkgs}
+
+@vindex --disable-all-pkgs
+Do not build any program modules by default---only those explicitly
+enabled. Without this option, all modules are built except those that
+are explicitly disabled or specify @code{disable} in their
+@file{ac/withenable.ac} fragment.
+
+
+@node Configure options for @file{texk/web2c}
+@subsubsection Configure options for @file{texk/web2c}
+
+@cindex @code{configure} options, for @code{web2c}
+
+@vindex --with-banner-add=@var{str}
+@noindent @code{--with-banner-add=@var{str}}@*Add @code{@var{str}} to the
+default version string (@code{TeX Live @var{year}} or @code{Web2C
+@var{year}}) appended to banner lines. This is ignored for a native
+TL build, but distro builds should specify, e.g.,
+@code{/@var{SomeDistro}}.
+
+@vindex --with-editor=@var{cmd}
+@noindent @code{--with-editor=@var{cmd}}@*Specify the command
+@code{@var{cmd}} to invoke from the @code{e} option of @TeX{}-like engines,
+replacing the default @code{vi +%d '%s'} for Unix or @code{texworks
+--position=%d "%s"} for Windows.
+
+@vindex --with-fontconfig-includes=@var{dir}
+@vindex --with-fontconfig-libdir=@var{dir}
+@noindent @code{--with-fontconfig-includes=@var{dir}},
+@code{--with-fontconfig-libdir=@var{dir}}@*Building Xe@TeX{} on
+non-Mac systems requires the @code{fontconfig} library headers and
+code. If one or both of these options are given, the required flags
+are derived from them; otherwise, they are determined via
+@file{pkg-config} (if present).
+
+@cindex X toolkit
+@pindex libXt
+@pindex Xlib
+@noindent @code{--with-mf-x-toolkit}@*Use the X toolkit (@file{libXt}) for
+Metafont (the default is to use the lowest-level @file{Xlib} support;
+it seems this has the best chance of working across X installations
+nowadays).
+
+@vindex --disable-dump-share
+@cindex LittleEndian architectures
+@noindent @code{--disable-dump-share}@*Make the @code{fmt}/@code{base}
+dump files architecture dependent (somewhat faster on LittleEndian
+architectures).
+
+@vindex --disable-ipc
+@cindex interprocess communication
+@noindent @code{--disable-ipc}@*Disable @TeX{}'s @code{--ipc} option.
+
+@vindex --disable-mf-nowin
+@pindex mf-nowin
+@noindent @code{--disable-mf-nowin}@*Do not build a separate
+non-graphically-capable Metafont (@file{mf-nowin}).
+
+@vindex --disable-omfonts
+@pindex opl2ofm@r{, et al.}
+@noindent @code{--disable-omfonts}@*Build the WEB versions of the
+Omega font utilities @file{ofm2opl}, @file{opl2ofm}, @file{ovf2ovp},
+and @code{ovp2ovf} instead of the C version @file{omfonts}. The WEB
+and C versions should be roughly equivalent.
+
+@vindex --disable-tex
+@vindex --enable-etex
+@pindex web2c.ac
+@noindent @code{--disable-tex}, @code{--enable-etex}, @dots{}@*Do not or
+do build the various @TeX{}, Metafont, and MetaPost engines (defaults are
+defined in the fragment @file{texk/web2c/ac/web2c.ac}).
+
+@vindex --disable-web-progs
+@noindent @code{--disable-web-progs}@*Do not build the core WEB programs
+@file{bibtex}, @dots{}, @file{weave}. Useful if, e.g., you only want
+to (re)build some engines.
+
+@vindex --enable-auto-core
+@cindex preloaded binaries
+@noindent @code{--enable-auto-core}@*This option causes @TeX{} and Metafont
+to produce a core dump when a particular hacky filename is
+encountered, for use in creating preloaded binaries. This is rarely
+done nowadays.
+
+@vindex --enable-libtool-hack
+@pindex libtool@r{, hack for avoiding excessive linking}
+@noindent @code{--enable-libtool-hack}@*
+If enabled (which is the default for all platforms), prevents
+@code{libtool} from linking explicitly with dependencies of
+@file{libfontconfig} such as @file{libexpat}.
+
+@vindex --enable-*win @r{for Metafont window support}
+@noindent @code{--enable-*win}@*Include various types of other window
+support for Metafont (EPSF output, @code{mftalk}, old terminals, @dots{}).
+
+@vindex --enable-tex-synctex
+@vindex --disable-etex-synctex
+@cindex synctex
+@noindent @code{--enable-tex-synctex}, @code{--disable-etex-synctex},
+@dots{}@*Build the @TeX{} engines with or without @code{SyncTeX}
+support; ignored for a native @TL{} build, defaults are again defined
+in @file{texk/web2c/ac/web2c.ac}.
+
+
+@node Configure options for @file{texk/bibtex-x}
+@subsubsection Configure options for @file{texk/bibtex-x}
+
+@cindex @code{configure} options, for @code{bibtex-x}
+@pindex bibtex8
+@pindex bibtexu
+@pindex bibtex-x
+The former programs @code{bibtex8} and @code{bibtexu} have been merged
+into the module @code{bibtex-x} (extended Bib@TeX{}).
+
+@vindex --disable-bibtex8
+@noindent @code{--disable-bibtex8}@*Do not build the @file{bibtex8} program.
+
+--disable-bibtexu
+@noindent @code{--disable-bibtexu}@*Do not build the @file{bibtexu} program
+(building @file{bibtexu} requires @code{ICU} libraries).
+
+
+@node Configure options for @file{texk/dvipdfm-x}
+@subsubsection Configure options for @file{texk/dvipdfm-x}
+
+@cindex @code{configure} options, for @code{dvipdfm-x}
+@pindex dvipdfmx
+@pindex xdvipdfmx
+
+The former modules @code{dvipdfmx} (extended DVI to PDF converter) and
+@code{xdvipdfmx} (the same, as used by Xe@TeX{}) have been merged into
+@code{dvipdfm-x}.
+
+@vindex --disable-dvipdfmx
+@noindent @code{--disable-dvipdfmx}@*Do not build the @file{dvipdfmx} program.
+
+@vindex --disable-xdvipdfmx
+@noindent @code{--disable-xdvipdfmx}@*Do not build the @file{xdvipdfmx}
+program (building @file{xdvipdfmx} requires the @code{freetype} library).
+
+
+@node Configure options for @file{texk/dvisvgm}
+@subsubsection Configure options for @file{texk/dvisvgm}
+
+@cindex @code{configure} options, for @file{dvisvgm}
+@pindex dvisvgm
+
+@vindex --with-system-libgs
+@noindent @code{--with-system-libgs}@*Build @file{dvisvgm} using installed
+Ghostscript (@code{gs}) headers and library (not allowed for a native
+TL build). The default is to load the @code{gs} library at runtime if
+possible, or otherwise disable support for PostScript specials.
+
+@vindex --without-libgs
+@noindent @code{--without-libgs}@*Build @file{dvisvgm} without PostScript
+support at all. Because the dynamic loading just mention defeats all
+attempts at static linking, the result can crash due to library
+incompatibilities, e.g., on CentOS 5.
+
+@vindex --with-libgs-includes@r{,} -libdir
+@noindent @code{--with-libgs-includes=@var{dir}},
+@code{--with-libgs-libdir=@var{dir}}@*Specify non-standard locations
+of the Ghostscript headers and library.
+
+
+@node Configure options for @file{texk/texlive}
+@subsubsection Configure options for @file{texk/texlive}
+
+@cindex @code{configure} options, for @file{texk/texlive}
+@vindex --disable-linked-scripts
+@noindent @code{--disable-linked-scripts}@*Do not install the ``linked
+scripts'' (@pxref{Linked scripts}), except for the TL scripts required
+to run @code{texlinks}.
+
+
+@node Configure options for @file{texk/xdvik}
+@subsubsection Configure options for @file{texk/xdvik}
+
+@cindex @code{configure} options, for @file{xdvik}
+@pindex xdvik
+
+@vindex --with-gs=@var{filename}
+@noindent @code{--with-gs=@var{filename}}@*Hardwire the location of Ghostscript
+(@file{gs}).
+
+@vindex --with-xdvi-x-toolkit=@var{kit}
+@pindex motif
+@pindex xaw
+@noindent @code{--with-xdvi-x-toolkit=@var{kit}}@*Use toolkit
+@code{@var{kit}} for @file{xdvik}, one of: @code{motif xaw xaw3d
+neXtaw}. The default is @code{motif} if available, else @code{xaw}.
+
+
+@node Configure options for @file{utils/xindy}
+@subsubsection Configure options for @file{utils/xindy}
+
+@cindex @code{configure} options, for @file{xindy}
+@pindex xindy
+
+@vindex --enable-xindy-rules
+@noindent @code{--enable-xindy-rules}@*Build and install @code{xindy} rules
+(default: yes, except for a native TL build).
+
+@vindex --enable-xindy-docs
+@noindent @code{--enable-xindy-docs}@*Build and install @code{xindy}
+documentation (default: yes, except for a native TL build).
+
+@vindex --with-clisp-runtime=@var{filename}
+@pindex lisp.run@r{,} lisp.exe
+@cindex CLISP
+@noindent @code{--with-clisp-runtime=@var{filename}}@*Specifies the
+Full path for the CLISP runtime file (@file{lisp.run} or
+@file{lisp.exe}) to be installed. When specified as @code{default}
+(the default for a native TL build) the path is determined by the
+CLISP executable; the value @code{system} (not allowed for a native TL
+build, but the default for a non-native one) indicates that
+@file{xindy} will use the installed version of @file{clisp} (which
+must be identical to the one used to build @file{xindy}).
+
+@vindex --with-recode
+@pindex recode
+@pindex iconv
+@noindent @code{--with-recode}@*Use @file{recode} instead of @file{iconv}
+to build the @code{xindy} rules and documentation, required for some
+systems where @file{iconv} is missing or broken.
+
+
+@node Library-specific configure options
+@subsection Library-specific configure options
+
+@cindex library-specific @code{configure} options
+@cindex @code{configure} options, library-specific
+Here are (some of) the library-specific @code{configure} options,
+starting with this generic one:
+
+@vindex --with-system-@var{lib}
+@noindent @code{--with-system-@var{lib}}
+
+Use an installed (system) version of the library @code{@var{lib}};
+this option exists for most libraries, but is not allowed for a native
+TL build. Using a system version implies also using the system
+versions of all libraries (if any) that @var{lib} depends on.
+
+@vindex --with-@var{lib}-includes=@var{dir}@r{,} -libdir
+For many libraries @code{--with-@var{lib}-includes=@var{dir}} and
+@code{--with-@var{lib}-libdir=@var{dir}} to specify non-standard
+search locations; others use @file{pkg-config} or similar to determine
+the required flags.
+
+The top-level @file{configure} script performs a consistency check for all
+required system libraries and bails out if tests fail.
+
+@menu
+* Configure options for @code{kpathsea}::
+* Configure options for system @code{poppler}::
+@end menu
+
+
+@node Configure options for @code{kpathsea}
+@subsubsection Configure options for @code{kpathsea}
+
+@cindex @code{configure} options, for @code{kpathsea}
+
+@noindent @code{--enable-@var{cmd}-default},
+@code{--disable-@var{cmd}-default}@*Determine the compile time default
+whether or not to run @var{cmd}, one of:
+@table @code
+@item mkocp
+(Omega compiled translation process file)
+@item mkofm
+(Omega font metrics file)
+@item mktexfmt
+(format/base dump file)
+@item mktexmf
+(Metafont source)
+@item mktexpk
+(PK bitmap font)
+@item mktextex
+(@TeX{} source)
+@item mktextfm
+(TFM file)
+@end table
+
+@noindent to generate the specified type of file dynamically.
+The default can be overridden by the user in any case.
+
+
+@node Configure options for system @code{poppler}
+@subsubsection Configure options for system @code{poppler}
+
+@cindex @code{configure} options, for system @code{poppler}
+
+@pindex poppler
+@pindex xpdf @r{as library}
+Building Lua@TeX{} and Xe@TeX{} requires @code{poppler}, either from
+the TL tree or system headers and library. Building pdf@TeX{}
+requires either @code{xpdf} from the @TL{} tree or system
+@code{poppler} headers and library.
+
+@vindex --with-system-poppler
+@noindent @code{--with-system-poppler}@*Use a system version (0.18 or
+newer) of @code{poppler} for Lua@TeX{} and Xe@TeX{}, and use
+@file{pkg-config} to obtain the required flags.
+
+@vindex --with-system-xpdf
+@noindent @code{--with-system-xpdf}@*Use a system version (0.12 or better)
+of @code{poppler} (and @file{pkg-config}) for pdf@TeX{} instead of
+@code{xpdf} from the TL tree. @xref{@code{--disable-largefile}}.
+
+@node Variables for configure
+@subsection Variables for configure
+
+@cindex variables for @code{configure}
+@cindex @code{configure} variables
+
+The values for these variables can be specified as @code{configure}
+arguments of the form @code{@var{VAR}=@var{value}}. They can also be
+defined in the environment, but that might not work for cross
+compilations.
+
+@vtable @code
+@item CC
+@itemx CXX
+@itemx CPPFLAGS
+And plenty more. As usual with Autoconf, these variables specify the
+name (or full path) of compilers, preprocessor flags, and similar.
+@xref{Preset Output Variables,, autoconf, GNU Autoconf}.
+
+@item CLISP
+@pindex clisp
+Name (or full path) of the @file{clisp} executable, used to build
+@code{xindy}.
+
+@item FT2_CONFIG
+@itemx ICU_CONFIG
+@itemx PKG_CONFIG
+@pindex freetype-config
+@pindex icu-config
+@pindex libfreetype
+@cindex ICU libraries
+These specify the name (or path) for the @file{freetype-config},
+@file{icu-config}, and @file{pkg-config} commands used to determine the
+flags required for system versions of @file{libfreetype}, the ICU
+libraries, or many other libraries.
+
+@item KPSEWHICH
+@pindex kpsewhich
+Name (or path) of an installed @file{kpsewhich} binary, used by
+@code{make check} to determine the location of, e.g.,
+@file{cmbx10.tfm}.
+
+@item MAKE
+@itemx SED
+And more. Name (or path) of the @code{make}, @code{sed}, and similar
+programs; used at the top level and propagated to all subdirectories.
+
+@item PERL
+@itemx LATEX
+@itemx PDFLATEX
+Name (or full path) for the @file{perl}, @file{latex}, and @file{pdflatex}
+commands used, e.g., to build the @code{xindy} documentation.
+
+@item TL_PLATFORM
+@pindex biber
+@pindex Par::Packer
+The utility program @code{biber} consists of many Perl modules bundled
+into an executable by the @code{Par::Packer} mechanism. Therefore
+it is not feasible to build @code{biber} as part of TL.
+
+However, in order for @code{make install} to create all executables in
+@file{bindir}, the @code{biber} module in TL contains pre-made
+binaries (by @code{biber} contributors, released on the original
+@code{biber} site) for the platforms for which they are available. TL
+merely checks if an executable is present for the current platform,
+and if so, installs it.
+
+@cindex platform, current
+@pindex config.guess@r{,} config.sub
+@pindex TLUtils.pm
+@pindex TLConfig.pm
+The complication is hidden in the phrase ``current platform''. TL has
+its own ideas about platform names, and the mapping from the canonical
+system name determined by @file{config.guess} or @file{config.sub} to
+the TL platform name is not trivial. So, a value given for
+@code{TL_PLATFORM} is used as the TL platform name. Otherwise, the
+build uses copies of the Perl modules @code{TeXLive/TLUtils.pm} and
+@code{TeXLive/TLConfig.pm}, to avoid duplicating the
+platform-detection logic.
+
+@end vtable
+
+
+@node Cross compilation
+@section Cross compilation
+
+@cindex cross compilation
+In a cross compilation a @dfn{build} system is used to create
+binaries to be executed on a @dfn{host} system with different
+hardware and/or operating system.
+
+@cindex native cross compilation
+In simple cases, the build system can execute binaries for the host
+system. This typically occurs for bi-arch systems where, e.g.,
+@code{i386-linux} binaries can run on @code{x86_64-linux} systems and
+@code{win32} binaries can run on @code{win64} systems. Although
+sometimes called ``native cross'', technically this is not cross
+compilation at all. In most such cases it suffices to specify
+suitable compiler flags. It might be useful to add the configure
+option @code{--build=@var{host}} to get the correct canonical host
+name, but note that this should @emph{not} be @code{--host=@var{host}}
+(@pxref{Hosts and Cross-Compilation,,, autoconf, GNU Autoconf}).
+
+In order to build, e.g., 32-bit binaries with @command{clang} on a 64-bit
+OSX system one could use @* @ @ @ @code{./Build --build=i386-apple-darwin
+CC='clang -arch i386'} @backslashchar{} @* @ @ @ @ @ @ @ @ @
+@code{CXX='clang++ -arch i386' OBJCXX='clang++ -arch i386'}
+
+@menu
+* Cross configuring:: Configuring for cross compilation.
+* Cross problems:: Cross compilation problems.
+@end menu
+
+
+@node Cross configuring
+@subsection Cross configuring
+
+@cindex cross compilation configuring
+@cindex configuring, for cross compilation
+
+@vindex --host=@var{host}
+@vindex --build=@var{host}
+In a standard cross compilation, binaries for the host system cannot
+execute on the build system and it is necessary to specify the
+configure options @code{--host=@var{host}} and
+@code{--build=@var{build}} with two different values.
+
+Building binaries requires suitable ``cross'' tools, e.g., compiler,
+linker, and archiver, and perhaps a ``cross'' version of
+@code{pkg-config} and similar to locate host system libraries.
+Autoconf expects that these cross tools are given by their usual
+variables or found under their usual name prefixed with
+@code{@var{host}-}. Here a list of such tools and corresponding
+variables:
+
+@example
+@code{ar} AR
+@code{freetype-config} FT2_CONFIG
+@code{g++} CXX
+@code{gcc} CC
+@code{icu-config} ICU_CONFIG
+@code{objdump} OBJDUMP
+@code{pkg-config} PKG_CONFIG
+@code{ranlib} RANLIB
+@code{strip} STRIP
+@end example
+
+@cindex @code{mingw32}
+@noindent In order to, e.g., build @code{mingw32} binaries on
+@code{x86_64-linux} with a cross compiler found as
+@file{i386-pc-mingw32-gcc} one would specify
+
+@example
+--host=i386-pc-mingw32 --build=x86_64-linux-gnu
+@end example
+
+@noindent or perhaps
+
+@example
+--host=mingw32 --build=x86_64-linux CC=i386-pc-mingw32-gcc
+@end example
+
+@noindent but this latter, especially, might require adding @code{CXX} and others.
+
+Configure arguments such as @code{CFLAGS=@dots{}} refer to the cross
+compiler. If necessary, you can specify compilers and flags for the
+few auxiliary C and C++ programs required for the build process as
+configure arguments
+
+@vindex BUILDCC@r{,} BUILDCFLAGS@r{, @dots{}}
+@example
+BUILDCC=@dots{}
+BUILDCPPFLAGS=@dots{}
+BUILDCFLAGS=@dots{}
+BUILDCXX=@dots{}
+BUILDCXXFLAGS=@dots{}
+BUILDLDFLAGS=@dots{}
+@end example
+
+
+@node Cross problems
+@subsection Cross problems
+
+@cindex cross compilation problems
+
+The fact that binaries for the host system cannot be executed on the
+build system causes some problems.
+
+One problem is that configure tests using @code{AC_RUN_IFELSE} can
+compile and link the test program but cannot execute it. Such tests
+should be avoided if possible and otherwise must supply a pessimistic
+test result.
+
+@pindex squeeze
+@pindex web2c @r{program}
+@cindex @code{freetype} cross compiling
+@vindex CC_BUILD
+Another problem arises if the build process must execute some
+(auxiliary or installable) programs. Auxiliary programs can be placed
+into a subdirectory that is configured natively as is done for
+@file{texk/web2c/web2c}, @file{texk/dvipsk/squeeze}, and
+@file{texk/xdvik/squeeze}. The module @file{libs/freetype} uses the
+value of @code{CC_BUILD}, @file{@var{build}-gcc}, @file{gcc}, or
+@file{cc} as compiler for the auxiliary program.
+
+@cindex ICU cross compiling
+The situation for installable programs needed by the build process is
+somewhat different. A quite expensive possibility, chosen for the ICU
+libraries in module @file{libs/icu}, is to first compile natively for
+the build system and in a second step to use these (uninstalled)
+programs during the cross compilation.
+
+@pindex tangle
+@pindex ctangle
+@pindex otangle
+@pindex tie
+This approach would also be possible for the tools such as
+@file{tangle} used in the module @file{texk/web2c} to build the WEB
+programs, but that would require first building a native
+@code{kpathsea} library. To avoid this complication, cross
+compilation of the WEB or CWEB programs requires sufficiently recent
+installed versions of @file{tangle}, @file{ctangle}, @file{otangle},
+and @file{tie}.
+
+@cindex @code{xindy} cross compiling impossible
+Building @code{xindy} requires running the host system @file{clisp}
+binary, thus cross compilation is not possible.
+
+
+@node Coding conventions
+@section Coding conventions
+
+@cindex coding conventions
+@cindex conventions, coding
+
+Ideally, building all of @TL{} with @code{--enable-compiler-warnings=max}
+should produce no (GCC) compiler warnings at all. In spite of
+considerable efforts into that direction we are still far from that goal and
+there are reasons that we may never fully reach it. Below are some rules
+about declarations of functions or variables and the use of @code{const}.
+These rules should be applied to all parts of the @TL{} tree, except some of
+those maintained independently.
+
+@menu
+* Declarations and definitions::
+* Const::
+@end menu
+
+
+@node Declarations and definitions
+@subsection Declarations and definitions
+
+@cindex declarations and definitions, in source code
+@cindex source code declarations
+@cindex ANSI C
+@cindex C, ANSI, required
+@cindex C99, avoided
+
+@subsubheading C standards
+
+The @TL{} build system no longer supports pre-ANSI C compilers. Thus
+all function prototypes and definitions must conform to the ANSI C
+standard (including @code{void} in the declaration of C functions with
+no parameters). On the other hand, TL is built for a wide variety of
+systems, not all of which support the C99 standard. Therefore using
+C99 features should be avoided if that can easily be done. In
+particular C code must not contain declarations after statements or
+C++-style comments.
+
+@pindex chktex
+@findex stpcpy
+If some C99 (or later) constructs must be used, the module should
+verify that they are available and otherwise provide an alternative.
+For example, the module @file{texk/chktex} uses the C99 function
+@code{stpcpy()} that may or may not be available on a particular
+system. It uses @code{AC_CHECK_DECLS([stpcpy])} in
+@file{configure.ac} to test this, and provides the perhaps slightly
+less efficient alternative
+
+@example
+#if !(defined HAVE_DECL_STPCPY && HAVE_DECL_STPCPY)
+#static inline char *stpcpy(char *dest, const char *src)
+@{
+ return strcpy(dest, src) + strlen(src);
+@}
+#endif
+@end example
+
+@noindent in the file @file{Utility.h}.
+
+
+@subsubheading Static functions
+
+@cindex @code{static} functions
+Functions used in only one file should be declared @code{static}; they
+require no prototype except as forward declaration.
+
+@subsubheading Extern functions
+
+@cindex @code{extern} functions
+Functions not declared @code{static}, usually because they are used in
+several files, require an (@code{extern}) prototype in exactly one
+header file, which is included in the file defining the function and
+in all files using that function---this is the only way to guarantee
+consistency between definition and use. There should be no
+@code{extern} declarations sprinkled throughout the C code (with or
+without comments as to where that function is defined).
+
+@subsubheading Variable declarations
+
+@cindex variable declarations, in source code
+The declaration of global variables follows analogous rules: they are
+either declared @code{static} if used in only one file or declared
+@code{extern} in exactly one header and instantiated in exactly one
+file.
+
+@node Const
+@subsection Const
+
+@cindex @code{const}
+
+The @code{const} feature of C is valuable, but easy to mis-use.
+
+@subsubheading Function parameters
+
+Ideally, a function parameter not modified by the function should be
+declared as @code{const}. This is important in particular for strings
+(@code{char*}) because the actual arguments are often string literals.
+It is perfectly legitimate and safe to use a type @code{char*} value
+for a type @code{const char*} variable (in an assignment, as
+initializer, as function argument, or as return value). It is equally
+safe to use a type @code{char**} value for a type @code{const
+char*const*} variable, but not for a type @code{const char**} variable
+since that might cause modification of a quantity supposed to be
+constant.
+
+@cindex X11 headers, and @code{const}
+@cindex @code{libfreetype}, and @code{const}
+Getting all @code{const} qualifiers right can get quite involved but
+can almost always be done. There are only a couple notable
+exceptions: the X11 headers are full of declarations that ought to use
+@code{const} but do not, and the same is true to some extent for
+@file{libfreetype} (but, thankfully, not for @code{zlib} nowadays).
+
+@subsubheading What must be avoided with @code{const}
+
+@cindex warning, discards qualifiers
+@cindex discards qualifiers warning
+The GCC compiler warnings ``assignment discards qualifiers@dots{}''
+and analogous warnings for ``initialization'', ``passing arg'', or
+``return'' must be strenously avoided in our own code. The only
+exception is when they are caused by X11 headers or macros or other
+third party code.
+
+@subsubheading What should be avoided with @code{const}
+
+@cindex type cast, avoiding
+A type cast, e.g., from @code{const char*} to @code{char*} does not
+solve any problems; depending on warning options, it may only hide
+them. Therefore such casts should be avoided whenever possible and
+otherwise must be carefully analyzed to make sure that they cannot
+cause the modification of quantities supposed to be constant.
+