diff options
Diffstat (limited to 'Build/source/doc/tlbuild.texi')
-rw-r--r-- | Build/source/doc/tlbuild.texi | 2689 |
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 |