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