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.texi2689
1 files changed, 0 insertions, 2689 deletions
diff --git a/Build/source/doc/tlbuild.texi b/Build/source/doc/tlbuild.texi
deleted file mode 100644
index a6e235fb8f3..00000000000
--- a/Build/source/doc/tlbuild.texi
+++ /dev/null
@@ -1,2689 +0,0 @@
-\input texinfo
-@setfilename tlbuild.info
-
-@set version 2021
-@set month-year February 2021
-
-@set mytitle Building @TeX{} Live (@value{version})
-@settitle @value{mytitle}
-
-@macro TL
-@TeX{}@tie{}Live
-@end macro
-
-@copying
-This file documents the @TL{} build system and more.
-
-@noindent
-Copyright @copyright{} 2016--2021 Karl Berry.@*
-Copyright @copyright{} 2013--2015 Karl Berry & Peter Breitenlohner.
-
-Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries a copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-@end ignore
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation
-approved by the @TeX{} Users Group.
-@end copying
-
-@c Put everything in one index (arbitrarily chosen to be the concept index).
-@syncodeindex fn cp
-@syncodeindex ky cp
-@syncodeindex pg cp
-@syncodeindex tp cp
-@syncodeindex vr cp
-
-@dircategory TeX
-@direntry
-* TLbuild: (tlbuild). TeX Live configuration and development.
-@end direntry
-
-@dircategory Individual utilities
-@direntry
-* install-tl:: Installing TeX Live.
-* tlmgr:: Managing TeX Live.
-@end direntry
-
-@titlepage
-@title @value{mytitle}
-@subtitle @value{version} release
-@subtitle @value{month-year}
-@author Peter Breitenlohner
-@author Karl Berry
-@author @url{https://tug.org/texlive}
-
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@shortcontents
-@contents
-
-@ifnottex
-@node Top
-@top @value{mytitle}
-
-For an overview of this manual, @pxref{Introduction}.
-
-@menu
-* Introduction:: About this manual.
-* Overview of build system:: The @TL{} build system.
-* Prerequisites:: Requirements for building @TL{}.
-* Building:: The overall build process.
-* Installing:: How and where installation happens (or not).
-* Layout and infrastructure:: Autoconf macros, etc., in detail.
-* Configure options:: List of all configure options.
-* Coding conventions:: Conventions to follow.
-* Continuous integration:: Automated build testing.
-* install-tl:: The @TL{} installer.
-* tlmgr:: The native @TL{} package manager.
-* Index:: General index.
-@end menu
-@end ifnottex
-
-
-@node Introduction
-@chapter Introduction
-
-@cindex introduction
-
-This manual (dated @value{month-year}) corresponds to the @TL{}
-@value{version} release.
-
-This manual is aimed at system installers and programmers, and focuses
-on how to configure, build, and develop the @TL{} (TL) sources. It is
-also available as plain text files in the source tree:
-@file{source/README.*}.
-
-The main @file{source/README} file in the TL source tree provides
-maximally-terse information for doing a build, and portability
-information for different systems, along with
-@file{source/doc/README.solaris}.
-
-For information on acquiring the TL sources, see
-@url{https://tug.org/texlive/svn}. The canonical source repository
-uses Subversion, and we have no plans to change this.
-
-This manual does not duplicate the information found in other TL
-documentation resources, such as:
-
-@itemize
-@item The @TL{} web pages: @url{https://tug.org/texlive}.
-
-@item The web page describing how to build the binaries which
-are distributed with @TL{}: @url{https://tug.org/texlive/build.html}.
-
-@item The @TL{} user manual: @url{https://tug.org/texlive/doc.html}, or
-run @code{texdoc texlive}.
-
-@item Other @TeX{}-related Texinfo manuals (@pxref{,,,web2c, Web2c},
-@ref{,,,kpathsea, Kpathsea}, etc.):
-@url{https://tug.org/texinfohtml/}, or check the @samp{TeX} category in
-the GNU Info system.
-
-@item Package documentation:
-@url{https://tug.org/texlive/Contents/live/doc.html}, or the
-@file{doc.html} file at the top level of the installed TL.
-
-@end itemize
-
-As an exception, the full documentation for @code{install-tl} and
-@code{tlmgr} is included here as appendices, simply because it is easy
-to do so. The same text is available online (linked from
-@url{https://tug.org/texlive/doc.html}, or by invoking the program
-with @samp{--help} (or look at the end of the source).
-
-
-@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 Overview of build system
-@chapter Overview of build system
-
-@cindex build system, design of
-
-@cindex Autoconf
-@cindex Automake
-@cindex Libtool
-@cindex tests, running
-The @TL{} build system was redesigned in 2009 to consistently use
-Autoconf, Automake, and Libtool. Thus, running@*@ @ @ @code{configure
-&& make && make check && make install}@*or the essentially-equivalent
-top-level @code{Build} script suffices 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 libs/@var{lib}
-Generic libraries.
-
-@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).
-
-@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 a single 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.
-
-All this is for the sake of simplifying both upgrading of modules and
-integrating new modules into the TL build system. (Despite all
-efforts, neither task is easy.)
-
-
-@node Prerequisites
-@chapter Prerequisites
-
-@cindex prerequisites for building
-@cindex requirements for building
-
-@cindex compilers, C and C++11
-Overall, building the @TL{} programs, when using all libraries from
-the TL source tree, requires C and C++11 compilers and GNU
-@code{make}. If @code{make} from your @code{PATH} is not GNU make,
-you can set the @code{MAKE} environment variable to whatever is necessary.
-
-@cindex GNU @code{make}, required
-@cindex @code{gmake}, required
-@cindex FreeType
-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) work with any reasonable
-@code{make}.
-
-@cindex C++11, required
-A C++11 compiler is similarly required because of the third-party
-library ICU; the program @code{dvisvgm} also requires C++11. It is
-possible to build everything else with older compilers, but you have
-to remove the C++11-dependent sources. @xref{Build one package}.
-
-A few programs in the tree have additional requirements:
-
-@table @file
-@item web2c
-@cindex @code{perl}, required by @code{web2c}, etc.
-requires @code{perl} for some tests run by @code{make check}.
-
-@item xdvik
-@itemx xpdfopen
-@cindex X11 development, required by X clients
-require X11 headers and libraries, typically in ``development'' packages
-that are not installed by default.
-
-@item xetex
-@cindex @code{fontconfig} library, required by @code{xetex}
-@cindex @code{ApplicationServices} Mac framework, required by @code{xetex}
-@cindex @code{Cocoa} Mac framework, required by @code{xetex}
-requires @file{fontconfig} (again both headers and library), or, for
-MacOSX only, the @code{ApplicationServices} and @code{Cocoa}
-frameworks.
-
-@item xindy
-@cindex @code{clisp}, required by @code{xindy}
-@cindex @code{libsigsegv}, required by @code{xindy}
-requires GNU @code{clisp}, @code{libsigsegv}, and @code{libiconv};
-additionally, to build the rules and/or documentation: @code{perl},
-@code{latex}, @code{pdflatex}.
-
-@end table
-
-@noindent Lacking the required tools, building these
-programs must avoided, e.g.,@*
-@code{configure --without-x --disable-xetex --disable-xindy}
-
-Modifying source files induces more requirements, as one might expect:
-
-@itemize
-@item
-Modification of any @code{.y} or @code{.l} source files requires
-@file{bison} or @file{flex} to update 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. Furthermore, to reliably reproduce the build files,
-the original GNU releases of these tools must be used, not any distro
-packaging of them. @xref{Build system tools}, for more discussion.
-
-@end itemize
-
-If you haven't modified any source files, and infrastructure tools
-such as @code{autoconf} or @code{makeinfo} are still being run, check
-your timestamps---notably, @code{use-commit-times} must be set to
-@code{yes} in your Subversion configuration (@pxref{Build system
-tools}). Barring buggy commits, no infrastructure tools are needed to
-do a normal build.
-
-
-@node Building
-@chapter 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 runs @code{configure && make world}, which builds
-everything in a subdirectory of the main source tree (default
-@file{Work/}), installs everything in another 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 @file{./Build} source file for more information; it is a
-straightforward shell script.
-
-@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} in a suitable empty subdirectory.
-Building in the source directory itself is not supported (sorry).
-
-@menu
-* Build iteration:: What @code{configure} and @code{make} do in TL.
-* Build problems:: If the build fails.
-* Build in parallel:: Simultaneous @code{make} processes.
-* Build distribution:: Making a distribution tarball.
-* Build one package:: Example of working on just one program.
-* Build one engine:: Example of building just one @TeX{} engine.
-* Cross compilation:: Building on host X for target Y.
-@end menu
-
-
-@node Build iteration
-@section Build iteration
-
-@cindex build iteration
-@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 the
-@TeX{}-specific libraries, and then runs @code{make} in @file{libs},
-@file{utils}, and @file{texk} to iterate over the generic libraries,
-utility programs, and @TeX{}-specific programs, respectively. 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, and finds (should find) nothing
-to be done.
-
-
-@node Build problems
-@section Build problems
-
-@cindex build problems
-@cindex problems with build
-@cindex failure to build
-@vindex --no-clean Build @r{option}
-If configuring or building a module fails, you should first try to
-find and fix the problem. Failing that, a possible workaround is to
-remove the subdirectory for that module from the build tree (so
-@code{configure} won't try to run there, and finally rerun the top
-level @code{make} (or @file{./Build} @code{--no-clean}).
-
-
-@node Build in parallel
-@section Build in parallel
-
-@cindex building in parallel
-@cindex parallel build
-@cindex cache for @code{configure}
-
-@cindex dependencies, with several output files
-@vindex -j make @r{option}
-The TL build system carefully formulates dependencies as well as
-@code{make} rules when a tool (such as @code{tangle}, @code{ctangle},
-and @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.
-
-@cindex cache file, for @code{configure}
-@vindex -C configure @r{option}
-Incidentally, a noticeable speed-up can be independently gained by
-using a configure cache file, i.e., specifying the @code{configure}
-option @code{-C} (recommended).
-
-
-@node Build distribution
-@section Build distribution
-
-@cindex building a distribution
-@cindex distribution tarball, making
-
-@cindex @code{dist} and @code{distcheck} targets for @code{make}
-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 distcheck} 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; @pxref{Installing}.
-We do not actually distribute any such tarball, and have no plans to
-do so.
-
-
-@node Build one package
-@section Build one package
-
-@cindex build one package
-@cindex one package, building
-
-@vindex --disable-all-packages
-@cindex build on demand
-To build one package, the basic idea is to use the @code{configure}
-option @code{--disable-all-pkgs} (@pxref{@code{--disable-all-pkgs}}).
-Then all program and library modules are configured but none are made.
-However, the @file{Makefile}s still contain all build rules and
-dependencies and can be invoked to build an individual program or
-library, first building any required libraries.
-
-Here is an example from start to finish for working on
-@code{dvipdfm-x}. (Unfortunately, this does not suffice for building
-the @TeX{} engines; see the next section.)
-
-@example
-mkdir mydir && cd mydir # new working directory
-
-# Get sources (@url{https://tug.org/texlive/svn}), e.g.:
-rsync -a --delete --exclude=.svn --exclude=Work \
- tug.org::tldevsrc/Build/source/ .
-
-# Create build directory:
-mkdir Work && cd Work
-
-# Do the configure:
-../configure --disable-all-pkgs --enable-dvipdfm-x \
- -C CFLAGS=-g CXXFLAGS=-g >&outc || echo fail
-
-# Do the make:
-make >&outm || echo fail
-
-# Test:
-cd texk/dvipdfm-x
-make check
-@end example
-
-Then you can modify source files in @file{mydir/texk/dvipdfm-x} and
-rerun @code{make} in @file{mydir/Work/texk/dvipdfm-x} to rebuild; that
-build directory is where the binary ends up and where you can run a
-debugger, etc.
-
-The second line of the @code{configure} invocation shows examples of
-extra things you likely want to specify if you intend to hack the
-sources (and not just build binaries): the @code{-C} speeds
-@code{configure} by enabling a cache file, and the @code{CFLAGS} and
-@code{CXXFLAGS} settings eliminate compiler optimization for debugging
-purposes.
-
-Of course, you need to actually look at the output and check that
-things are working. There are many @code{configure} options you can
-tweak as desired; check the output from @code{configure --help}. It
-is also a good idea to run @code{make check} after making any changes,
-to ensure that whatever tests have been written still pass.
-
-@cindex size of source tree
-Finally, the above retrieves the entire TL source tree (several
-hundred megabytes). It is natural to ask if this is really necessary.
-Strictly speaking, the answer is no, but it is vastly more convenient
-to do so. If you cut down the source tree, you must also give
-additional @code{configure} flags to individually disable using system
-versions of libraries, or the intricacies of the dependencies (such as
-@code{teckit} requiring @code{zlib}) will have undesired side effects.
-For an example of this approach, see the @code{build-pdftex.sh} script
-in the @code{pdftex} development source (details at
-@url{http://pdftex.org}), which is indeed such a cut-down TL source
-tree.
-
-@cindex C++11, removing dependent sources
-Some libraries and programs require C++11. If you want to build with
-an older compiler lacking such support, you need to (re)move those
-source directories; specifying @code{--disable} for them does not
-suffice, unfortunately. Specifically, before running @code{configure}:
-
-@example
-rm -rf libs/icu libs/graphite2 texk/dvisvgm
-@end example
-
-@vindex --enable-missing @r{to ignore dependencies}
-Also, even with @code{--disable-all-pkgs}, dependencies are (currently)
-checked. For instance, if a (non-MacOSX) system does not have
-@code{fontconfig}, Xe@TeX{} cannot be built (@pxref{Prerequisites}),
-and @code{configure} will terminate even with @code{--disable-xetex}.
-To proceed without such dependencies, specify @code{--enable-missing}
-also. (Patches to improve this would be most welcome.)
-
-@vindex CC=@var{c-compiler}
-@vindex CXX=@var{c++-compiler}
-@vindex OBJCXX=@var{objc-compiler}
-@pindex gcc@r{, default compilers}
-By default, the @code{gcc} compilers will be used if present;
-otherwise, individual packages may use something different. You can
-explicitly specify the compilers to be used with the environment
-variables @code{CC}, @code{CXX}, and @code{OBJCXX}.
-
-
-@node Build one engine
-@section Build one engine
-
-@cindex build one engine
-@cindex one engine, building
-@cindex engine, building one
-
-Unfortunately, there is one common case where the steps in the
-preceding section to build one package (@pxref{Build one package}) do
-not suffice: wanting to build one, or a subset, of the @TeX{} engines
-(or other Web2c programs).
-
-The simplest way to do this is to disable everything and then
-explicitly specify what to make. For example, to build only the
-original @TeX{}:
-
-@example
-cd Work # top build directory
-../configure --without-x --disable-shared --disable-all-pkgs \
- --enable-tex --disable-synctex -C CFLAGS=-g CXXFLAGS=-g
-make
-cd texk/web2c # cd engine build directory
-make tex # must specify target
-@end example
-
-The first @code{make} run will configure everything, and even build
-the libraries, even though the packages are disabled.
-The source tree can be cut down to just what is needed for the given
-engine (the separate pdf@TeX{} and Lua@TeX{} source repositories do
-this, for example), but see caveats in previous section.
-
-If you want to debug an X-related program or shared library setup, or
-other variants, change the @code{configure} options
-accordingly. Either @code{../Build} or @code{../configure} can be run.
-
-Then it is necessary to again specify the target engine (@code{tex},
-in the above) in the @code{make}.
-
-All this is somewhat unfortunate. We hope to improve the situation in
-the future. Patches are welcome.
-
-@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
-MacOSX system one could use:
-
-@example
-TL_BUILD_ENV="CC='clang -arch i386' \
- CXX='clang++ -arch i386' \
- OBJCXX='clang++ -arch i386'" \
- ./Build --build=i386-apple-darwin
-@end example
-
-@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/freetype2} uses the
-value of @code{CC_BUILD}, @file{@var{build}-gcc}, @file{gcc}, or
-@file{cc} as the compiler for the auxiliary program.
-
-@cindex ICU cross compiling
-The situation for installable programs needed by the build process is
-somewhat different. A rather 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 programs written in (C)WEB requires sufficiently recent
-installed versions of @file{tangle}, @file{ctangle}, @file{otangle},
-and @file{tie}.
-
-@cindex @code{xindy} cross compiling requires @code{clisp}
-Building @code{xindy} requires running the host system @code{clisp}
-binary, thus cross compilation is painful, but possible.
-
-
-@node Installing
-@chapter 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 @code{make install} is not enough to
-make a usable @TeX{} installation. Beyond the compiled binaries,
-(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 TL 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{https://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
-@section 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 explicitly 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 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-system-triplet}}. 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
-@section 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 interpreted 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 so-called @dfn{linked scripts} 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 (copied to, e.g.,
-@code{@var{bindir}/ps2eps.exe}) serves the same purpose. The source
-for the wrapper is in @file{texk/texlive/w32_wrapper}.
-
-One reason for this is to avoid having many copies of the same
-script; a more important reason is that it guarantees the scripts will
-stay in sync across the different supported operating systems.
-
-@pindex asymptote
-@pindex biber
-@pindex xindy
-@pindex xz
-@pindex wget
-Most important of all, we want the @code{@var{bindir}} resulting from
-the build to be as close as possible to what is in the TL
-distribution. At present, there are a few exceptions---Asymptote,
-Biber, Xindy---and each one creates considerable extra work. We don't
-want to add more. (See @url{https://tug.org/texlive/build.html} for
-information about building those exceptions, as well as the @code{xz}
-and @code{wget} programs that are used in the TL infrastructure.)
-
-
-@node Distro builds
-@section 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 @TeX{} 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}). In contrast, 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). 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}
-Look for and use a system version of the library @var{lib}.
-@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{https://tug.org/TUGboat/tb34-3/tb108preining-distro.pdf}. (If the
-article needs updating in the future, perhaps we will merge it into
-this document.)
-
-
-@node Layout and infrastructure
-@chapter Layout and infrastructure
-
-@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:: Modifying infrastructure files.
-* Top-level directories:: libs texk utils; am auxdir build-aux m4; doc extra.
-* Autoconf macros:: TL-specific Autoconf macros.
-* Library modules:: Handling libraries, with examples.
-* Program modules:: Handling programs, with examples.
-* Extending @TL{}:: Adding a new module.
-@end menu
-
-
-@node Build system tools
-@section 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 has few
-requirements. 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
-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}.
-
-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.
-
-@cindex Subversion repository
-@cindex timestamps, in repository
-@vindex use-commit-times@r{, Subversion}
-The files in the Subversion repository (see
-@url{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 @file{use-commit-times=yes} in
-@file{~/.subversion/config} or the equivalent.
-
-@cindex touching files to avoid rerunning
-@pindex make -t
-If timestamps are wrong, you may also be able to avoid unnecessary
-runs of @code{bison}, @code{flex}, or @code{makeinfo} with
-@code{touch} of 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.
-
-
-@node Top-level directories
-@section 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 @pxref{Overview of 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
-In addition, 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}.
-
-@cindex @file{build-aux/} top-level directory
-@pindex config.guess@r{,} config.sub, @dots{}
-@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.@ used by most packages. These are taken from the
-GNU Gnulib sources (@url{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.,
-@file{libs/freetype2/freetype-*/builds/unix/}. The @code{reautoconf}
-script does not touch those, but a TL cron job keeps them in sync
-(nightly).
-
-@cindex @file{Work/} top-level directory
-@cindex @file{inst/} top-level directory
-When the top-level @file{./Build} script is used to build TL, two more
-two more top-level directories appear: @file{Work/} for the build tree,
-and @file{inst/} for the install tree (from @code{make install}).
-These names (and everything else about @file{Build}'s operation) can
-be changed by setting environment variables before running it; see the
-script source.
-
-
-@node Autoconf macros
-@section 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 a few of the Autoconf macros used in several
-modules---many more are defined in the sources; see the top-level
-@code{m4/} directory. These general macros are supplemented by
-module-specific macros in directories such as @file{texk/dvipng/m4/};
-some of those are described in following sections (@pxref{Library
-modules} and @ref{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
-@subsection 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}@*along with checks for frequently used functions,
-headers, types, and structures. This is used for @TeX{}-specific
-modules.
-@end defmac
-
-
-@node Macros for programs
-@subsection Macros for programs
-
-@cindex macros, for programs
-Macros for program checks:
-
-@defmac KPSE_CHECK_LATEX
-Set @code{LATEX} to 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
-@subsection 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 present this assumes GNU compiler
-warning options, 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 present this only tests for
-the compiler option @code{-fvisibility=hidden}, but could be
-extended 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
-@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++}, notably 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
-@subsection 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
-@subsection 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):
-
-@multitable {@code{LIBPNG_INCLUDES}} {for the @code{make} rules to rebuild the library.}
-@item @code{LIBPNG_INCLUDES}
-@tab for use in @code{CPPFLAGS},
-@item @code{LIBPNG_LIBS}
-@tab for use in @code{LDADD},
-@item @code{LIBPNG_DEPEND}
-@tab for use as a Makefile dependency,
-@item @code{LIBPNG_RULE}
-@tab for the @code{make} rules to rebuild the library.
-@end multitable
-@end defmac
-
-@defmac KPSE_ADD_FLAGS (@var{name})
-Temporarily extend @code{CPPFLAGS} and @code{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 = $@{LIBPNG_INCLUDES@} $@{ZLIB_INCLUDES@}
-foo_LDADD = $@{LIBPNG_LIBS@} $@{ZLIB_LIBS@}
-foo_DEPENDENCIES = $@{ZLIB_DEPEND@} $@{LIBPNG_DEPEND@}
-## Rebuild libz
-@@ZLIB_RULE@@
-## Rebuild libpng
-@@LIBPNG_RULE@@
-@end example
-
-If it were 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
-@subsection 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 either
-@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} and 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
-@section 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
-@subsection The @code{png} library in @file{libs/libpng}
-
-@pindex png @r{library}
-@pindex libpng @r{library}
-The ``generic'' @code{png} library uses the source tree in the
-subdirectory @file{libpng-src/}, with all modifications for TL
-recorded in @file{TLpatches/*}. The @file{configure.ac} fragment
-@file{ac/withenable.ac} contains
-
-@example
-KPSE_WITH_LIB([libpng], [zlib])
-@end example
-
-@noindent to specify the module name and indicate 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++. These fragments are included by the
-@file{configure.ac} at the top level of TL
-(@code{Build/source/configure.ac}).
-
-@cindex proxy build system
-For this library, like many other modules, a proxy build system for TL
-is used, consisting of our own @file{configure.ac},
-@file{Makefile.am}, @file{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 @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}
-for the @code{make} rules to rebuild the library.
-
-@file{m4/kpse-libpng-flags.m4} also supplies the configure option
-@code{--with-system-libpng}, which then uses @code{pkg-config} to
-determine the flags required for the system library.
-
-
-@node @code{zlib} library
-@subsection 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
-@subsection The @code{freetype} library in @file{libs/freetype2}
-
-@pindex freetype @r{library}
-@cindex wrapper build system
-
-This module uses a wrapper build system. In contrast to the proxy
-build described earlier, the wrapper build has an almost trivial
-@file{configure.ac} and a @file{Makefile.am} which invokes the
-@code{configure} and @code{make} in the distributed source, followed
-by @code{make install} with the TL build tree as destination. In
-other words, this actually uses the build system provided by upstream
-(possibly patched).
-
-@pindex freetype-config
-The flags required for the system library are obtained through
-@code{freetype-config}.
-
-
-@node @code{kpathsea} library
-@subsection 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
-@r{(@url{tug.org/kpathsea})}}); the other is @code{ptexenc}. These
-@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 probably 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. Programs outside the TL tree should use @code{pkg-config}
-for the required flags.
-
-@pindex kpathsea.ac
-@pindex mktex.ac
-@vindex --enable-mktextfm-default
-@pindex mktextfm
-In addition to @file{kpathsea/ac/withenable.ac} and
-@file{kpathsea/ac/kpathsea.ac} here there is a third fragment
-@file{kpathsea.ac/mktex.ac}, included by both @file{withenable.ac} and
-@file{configure.ac}, which supplies configure options such as
-@code{--enable-mktextfm-default}. These determine the compile time
-default of whether or not to run @code{mktextfm} (and similar) to
-generate a missing @file{.tfm} (or whatever) 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
-@section 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
-@subsection The @code{t1utils} package in @file{utils/t1utils}
-
-@pindex t1utils @r{package}
-
-Here we use the distributed source tree @file{t1utils-src} with
-modifications documented in @file{TLpatches/*} 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
-@subsection The @code{xindy} package in @file{utils/xindy}
-
-@pindex xindy
-
-This module uses the distributed source tree @file{xindy-src/} with
-modifications documented in @file{TLpatches/*}, and a wrapper
-@file{configure.ac} and @file{Makefile.am} that descends into
-@file{xindy-src}.
-
-The @code{xindy} build requires a @file{make} that supports a
-@code{VPATH} build, can handle all targets, and do not refer to
-@code{$@{top_srcdir@}} or @code{$@{top_builddir@}}. The fragment
-@code{xindy/ac/withenable.ac} contains
-
-@example
-KPSE_ENABLE_PROG([xindy], , [disable])
-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} makes it
-too painful to enable by default).
-
-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
-@subsection The @code{xdvik} package in @file{texk/xdvik}
-
-@pindex xdvik
-
-This package is maintained as part of the @TL{} tree with sources in
-its own directory (@file{texk/xdvik/}). The fragment
-@code{xdvik/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 dependencies 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; in a cross compilation, these 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}
-@subsection 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. See @url{https://tug.org/build.html#asymptote}.
-
-
-@node Extending @TL{}
-@section Extending @TL{}
-
-@cindex extending @TL{}
-@cindex adding to @TL{}
-
-This section outlines the basic process for adding new packages to the
-TL build system.
-
-In any case, a new package directory @file{foo} should contain the
-original sources, modified only with changes necessary for TL, in
-@file{foo/foo-src}. The changes should be documented in
-@file{foo/TLpatches/*}, and also be submitted upstream whenever
-reasonable. In addition, @file{foo/} will need the usual Automake
-build-related files (@file{configure.ac}, @file{Makefile.am}, etc.
-Please maintain @file{foo/ChangeLog} for all TL changes.
-
-@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
-@subsection 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, 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 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 @code{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}.
-
-@cindex @var{newprog-src}, original source subdirectory
-Usually, the new program is maintained somewhere outside of @TL{}. In
-that case, as above, we put the upstream sources into a subdirectory
-@file{@var{prog}-src} (e.g., @file{utils/newprog/newprog-src}). We do
-not typically run @code{configure} in this original @code{...-src}
-directory, but only in our own directory; but we do compile using the
-source files in @code{...-src}.
-
-So, to summarize the files that must (usually) be created inside a new
-TL source directory (@file{texk/newprog} or @file{utils/newprog}):
-
-@ftable @file
-@item ac/withenable.ac
-The @code{KPSE_ENABLE_PROG} call just explained.
-
-@item configure.ac
-@itemx Makefile.am
-By merging the contents of the original @file{configure.ac} (if
-provided) and a comparable program already in TL. In the above
-example, one line that will be needed in @file{configure.ac} (can be
-added before the @code{AC_CONFIG_FILES} at the end) is:
-
-@example
-AC_SUBST([NEWPROG_TREE], [newprog-src])
-@end example
-
-@noindent and then use @code{@@NEWPROG_TREE@@} in
-@code{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 @TL{}. 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 @file{Build/source} tree for whatever you can think of to
-investigate how something is done. Most of the TL-specific macros are
-defined in @file{Build/source/m4/*}.
-
-@item TLpatches/TL-Changes
-First actions taken after getting the original source tree; typically
-removal of derived or unused common files.
-
-@item 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.
-
-@item ChangeLog
-Record all TL-specific changes, now and in the future.
-
-@end ftable
-
-@pindex autoreconf@r{, for new program}
-After populating the new TL source directory (@file{.../newprog/}, in
-the above), run GNU @code{autoreconf} there (@pxref{Build system
-tools}). Once that works, if you are the one who's eventually going
-to commit the new package, @code{svn add} the necessary files,
-including the generated @file{Makefile.in aclocal.m4 configure}, and
-@code{svn:ignore} the Automake cache @file{autom4te.cache}. (This is
-so people checking out the TL source tree do not have to run any
-autotools, but can simply run @code{configure}.)
-
-To reiterate: do not fail to commit the generated @file{configure} and
-other files. The m4 code in @file{kpse-pkgs.m4} uses the existence of
-@file{configure} to determine whether to descend into (and configure)
-a given subdirectory.
-
-@pindex reautoconf@r{, for new program}
-Then, run the TL tool @code{reautoconf} in the top-level TL
-@code{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 @file{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 @code{autoreconf} as needed in the new source directory
-(@code{Build/source/.../newprog}), then @code{make} in the
-corresponding build directory (@code{Build/work/.../newprog}), then
-@code{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.)
-
-@cindex engine, adding new
-Caveat: adding a new @TeX{} engine is not completely different, but
-it's not all that similar, either. In that case, the work is done
-inside a new subdirectory of @file{texk/web2c/}. Many things are
-common to all the engines, other things need to be copied and possibly
-modified for each one, yet others are unique to each. No general
-recipe is possible.
-
-
-@node Adding a new generic library module
-@subsection 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 macro
-@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: for libraries, 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. In addition, 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
-@subsection 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 macro
-@code{kpse_texlibs_pkgs}, which is 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
-@chapter 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 at the
-top level.
-
-@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 assignments 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} yields 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
-@section 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}
-@subsection @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 should be used
-(@pxref{Distro builds}).
-
-@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}) but cooperate with TL can
-use this option to enable TL-specific adaptations, such as
-installation paths.
-
-
-@node @code{--prefix} @code{--bindir} @dots{}
-@subsection @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}
-@subsection @code{--disable-largefile}
-
-@vindex --disable-largefile
-@cindex large file support
-@cindex LFS (large file support)
-Omit large file support (LFS), which is needed on most 32-bit Unix
-systems for files with 2GB or more. Regardless of this option, 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}.
-
-
-@node @code{--disable-missing}
-@subsection @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}
-@subsection @code{--enable-compiler-warnings=}@var{level}
-
-@vindex --enable-compiler-warnings=@var{level}
-Enable various levels of compiler warnings for C, C++, and/or
-Objective@tie{}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 the
-variables @code{WARNING_[OBJ]C[XX]FLAGS}, but these variables are not
-consistently used in all library and program modules. At present,
-these warning flags assume options from the GNU compilers.
-
-
-@node @code{--enable-cxx-runtime-hack}
-@subsection @code{--enable-cxx-runtime-hack}
-
-If enabled (as it is for the native TL build), when using @code{g++},
-try to statically link with @code{libstdc++}, thus improving
-portability of the resulting binary. @xref{Macros for compilers}.
-
-
-@node @code{--enable-maintainer-mode}
-@subsection @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}
-@subsection @code{--enable-multiplatform}
-
-@vindex --enable-multiplatform
-@vindex exec_prefix
-@vindex --bindir configure @r{option}
-@vindex --libdir configure @r{option}
-If enabled (as it is for the native TL build) and
-@code{--bindir=@var{dir}} or @code{--libdir=@var{dir}} are not
-specified, 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}. In any case, the values for
-@code{bindir} and @code{libdir} are automatically propagated to all
-subdirectories.
-
-
-@node @code{--enable-shared}
-@subsection @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}
-@subsection @code{--enable-silent-rules}
-
-@vindex --enable-silent-rules
-@cindex @code{make} rules, verbose vs.@: silent
-Enable the use of less verbose build rules. When using GNU
-@code{make} (or any @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}
-@subsection @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 fail.
-
-
-@node @code{--without-x}
-@subsection @code{--without-x}
-
-@vindex --without-x
-Disable all programs using the X Window System.
-
-
-@node Program-specific configure options
-@section 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}}
-@subsection @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 module @code{@var{prog}}.
-
-
-@node @code{--disable-all-pkgs}
-@subsection @code{--disable-all-pkgs}
-
-@vindex --disable-all-pkgs
-Do not build any program modules by default---only those explicitly
-enabled. This is useful when one wants to work on only a single
-program, which is specified with an additional @code{--enable} option,
-e.g., @code{--enable-dvipdfm-x}. It's still simplest to check out and
-configure the whole source tree, but at least only the program you are
-interested in, and its dependencies, are built. @xref{Build one package}.
-
-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}
-@subsection 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 (which is `@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{} and friends,
-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-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 original 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}
-@pindex libfontconfig@r{, hack for avoiding linking dependencies}
-@pindex libexpat@r{, dependency of @code{libfontconfig}}
-@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 non-X window
-support for Metafont (EPSF output, @code{mftalk}, old graphics
-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 defined in
-@file{texk/web2c/ac/web2c.ac}.
-
-@vindex --disable-synctex
-@cindex synctex
-@noindent @code{--disable-synctex}
-@*Do not build the @code{SyncTeX} library and tool.
-
-
-@node Configure options for @file{texk/bibtex-x}
-@subsection Configure options for @file{texk/bibtex-x}
-
-@cindex @code{configure} options, for @code{bibtex-x}
-@pindex bibtex8
-@pindex bibtexu
-@pindex bibtex-x
-The 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.
-
-@vindex --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}
-@subsection Configure options for @file{texk/dvipdfm-x}
-
-@cindex @code{configure} options, for @code{dvipdfm-x}
-@pindex 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} at the source level. Two separate binaries are still
-created by default. In addition, @file{dvipdfm} is created as a
-symlink to @file{dvipdfmx}, with backward-compatible (very slightly
-different) behavior.
-
-@vindex --disable-dvipdfmx
-@noindent @code{--disable-dvipdfmx}@*Do not build the @file{dvipdfmx}
-program or make the @file{dvipdfm} symlink.
-
-@vindex --disable-xdvipdfmx
-@noindent @code{--disable-xdvipdfmx}@*Do not build the @file{xdvipdfmx}
-program.
-
-
-@node Configure options for @file{texk/dvisvgm}
-@subsection 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, else to 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 mentioned 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}
-@subsection 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}
-@subsection Configure options for @file{texk/xdvik}
-
-@cindex @code{configure} options, for @file{xdvik}
-@pindex xdvik
-
-@vindex --with-gs=@var{filename}
-@cindex Ghostscript location for Xdvik
-@noindent @code{--with-gs=@var{filename}}@*Hardwire the location of Ghostscript
-(@file{gs}) as called by Xdvik.
-
-@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}.
-
-@vindex --enable-xi2-scrolling
-@pindex XInput
-@pindex scrolling, smooth
-@noindent @code{--enable-xi2-scrolling}@*Use XInput 2.1 ``smooth scrolling''
-if available (default: yes, except for a native TL build).
-
-
-@node Configure options for @file{utils/xindy}
-@subsection 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 otherwise) indicates that @file{xindy} will use
-the installed version of @file{clisp} (which must be identical to the
-one used to build @file{xindy}).
-
-
-@node Library-specific configure options
-@section 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 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}} can 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}::
-@end menu
-
-@node Configure options for @code{kpathsea}
-@subsection 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
-for whether or not to run @var{cmd}, which is 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
-(@pxref{@code{kpathsea} library}).
-
-@node Variables for configure
-@section 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, and other libraries, respectively.
-
-@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.
-
-@end vtable
-
-
-@node Coding conventions
-@chapter 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 the code maintained in the @TL{} tree and for
-other packages whose maintainers are willing to accept patches.
-
-@menu
-* Declarations and definitions::
-* Const::
-@end menu
-
-
-@node Declarations and definitions
-@section Declarations and definitions
-
-@cindex declarations and definitions, in source code
-@cindex source code declarations
-@cindex ANSI C
-@cindex declarations before statements, avoiding
-@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 a perhaps
-less efficient alternative (in the file @file{Utility.h}):
-
-@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
-
-@subsubheading Static functions
-
-@cindex @code{static} functions
-Functions used in only one file should be declared @code{static}; they
-require no prototype except in forward declarations.
-
-@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
-@section 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; at one time, @file{libfreetype} also did not
-fully specify @code{const}, but this has not been checked recently.
-
-@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 strenuously avoided in our own code. The only
-exception is when they are caused by X11 declarations or other third
-party code.
-
-@subsubheading What should be avoided with @code{const}
-
-@cindex type cast from const, 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.
-
-
-@node Continuous integration
-@chapter Continuous integration
-
-@cindex continuous integration
-@cindex Travis-CI
-
-The @TL{} sources are subjected to continuous integration testing on
-Travis-CI (@url{https://travis-ci.org/TeX-Live/texlive-source}) via a
-git-svn mirror of the sources that is pushed to Github
-(@url{https://github.com/TeX-Live/texlive-source}). The git-svn mirror
-is updated (currently) at 30 minute intervals, and only the last
-commit pushed is tested on Travis-CI.
-
-@menu
-* Transfer from Subversion to Github::
-* Automatic update of the Git mirror::
-* CI testing on Travis-CI::
-* Releases on Github::
-@end menu
-
-
-@node Transfer from Subversion to Github
-@section Transfer from Subversion to Github
-
-@pindex git-svn
-The git-svn program (@url{https://git-scm.com/docs/git-svn}) is used
-to check out the subtree @code{Build/source} of the canonical
-Subversion repository. The author index file used is not maintained
-in either Git or Subversion but can be provided on request.
-
-@c TODO what should we do here with the author index file? It contains a
-@c mapping from subversion names to name/email as shown in git.
-
-The initial checkout was done by invoking
-@example
-git svn --authors-file usermap clone \
- svn://@var{user}@@tug.org/texlive/trunk/Build/source
-@end example
-
-@noindent where the @code{usermap} file maps Subversion user names to
-name and emails of the authors. Anonymous checkout is also possible:
-@example
-git svn --authors-file usermap clone \
- svn://tug.org/texlive/trunk/Build/source
-@end example
-
-In the following, we will use @emph{admin} to refer to a user who has
-read/write access to the @TL{} subversion repository, and is also an
-administrator of the `@code{TeX-Live}' team at Github. The above
-initial checkout has been carried out by @emph{admin} on the server
-@code{texlive.info}.
-
-On Github, a new git repository named @code{texlive-source} was
-created by @emph{admin} within the @code{TeX-Live} ``organization''
-(@url{https://github.com/TeX-Live}). The remote was added to the
-checkout with @code{git remote add origin
-git@@github.com:TeX-Live/texlive-source.git}.
-
-To automate the update on Github, a new ssh key was generated and
-added to the @code{texlive-source} repository on Github as deployment
-key. Thus, pushes using this key can only go to the
-@code{texlive-source} repository and not anywhere else.
-
-The usage of @code{git-svn} requires a strict discipline to keep a
-linear history in the master branch. Since we are aiming at a pure
-mirror facility on Github, we have decided to further restrict the
-@code{master} branch of the @code{texlive-source} repository on Github
-to changes by @emph{admin}.
-
-This setup allows other developers to branch off @code{master} and
-push their branches to the Github repository, but all updates need to
-come from the local @code{master} (not the one on Github) to
-Subversion, back to @code{master} on @code{texlive.info}, and from
-there to Github.
-
-@node Automatic update of the Git mirror
-@section Automatic update of the Git mirror
-
-@emph{admin} has installed a cron job on @code{texlive.info} running
-every 30 minute which essentially runs @code{git svn rebase} and
-@code{git push} in the @code{master} branch of the checkout. The first
-command fetches the changes from the Subversion repository and updates
-the @code{master} branch with them, and the second pushes changes (if
-any) to Github.
-
-@node CI testing on Travis-CI
-@section CI testing on Travis-CI
-
-@pindex travis.yml
-The @code{source} tree of @TL{} contains a top-level file
-@code{.travis.yml} which controls the automatic testing on
-Travis-CI. @emph{admin} has registered with Travis-CI and allowed
-access to the Github's @code{TeX-Live} organization's
-@code{texlive-source} repository. The default settings are to build
-the last commit of each push. No further action is necessary on
-Travis-CI.
-
-If changes have been pushed via the cron job above, Travis-CI will
-automatically checkout the last pushed commit and try building it.
-
-@node Releases on Github
-@section Releases on Github
-
-Given a git checkout of @code{texlive-source}:
-
-@example
-git pull
-git tag build-svnNNNN
-git push --tags
-@end example
-
-@noindent and the result will appear at
-@url{https://github.com/TeX-Live/texlive-source/releases}.
-Releases can also be made manually from that web page (see
-@code{tl-update-bindir} for hints).
-
-@c made from pod doc.
-@include tlbuild-incl/install-tl.texi
-@include tlbuild-incl/tlmgr.texi
-
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@bye