Sync with TL 38274
[luatex.git] / source / README.4layout
blobefb1a5670980d3702382cb7368c65f0f9472b7be
1 (This file was generated by makeinfo and splitinfo.gawk.)
2 (Released under the old-style GNU documentation license;
3  see sources or other output files for full text.)
5 6 Layout and infrastructure
6 ***************************
8 The TeX Live source tree is the subtree rooted at 'Build/source' of the
9 complete TL distribution and contains the sources for all executables
10 distributed by TL, as well as 'configure' scripts and 'make' rules to
11 build and install them together with some of their support files.
13 6.1 Build system tools
14 ======================
16 As mentioned above (*note Prerequisites::), a normal build requires very
17 little.  On the other hand, if you want to modify the TeX Live
18 infrastructure sources, such as 'configure.ac' or 'Makefile.am' files,
19 you will need to have several additional tools installed.
21    In general, the TL build system uses the latest released versions of
22 the GNU build tools, installed directly from the original GNU releases
23 (e.g., by building them with 'configure --prefix=/usr/local/gnu' and
24 having 'PATH' start with '/usr/local/gnu/bin').  We have found that
25 trying to use the versions of these tools packaged for distros causes
26 many extra hassles, so don't do that, tempting as it may be.
28    Currently the versions we use are:
30      autoconf (GNU Autoconf) 2.69
31      automake (GNU automake) 1.15
32      bison (GNU Bison) 3.0.4
33      flex 2.5.39
34      ltmain.sh (GNU libtool) 2.4.6
35      m4 (GNU M4) 1.4.17
36      makeinfo (GNU texinfo) 5.2
38    These versions should be used to update the generated files (e.g.,
39 'configure' or 'Makefile.in') in all or parts of the TL tree after their
40 dependencies have been changed.  This can be done explicitly with the
41 top-level 'reautoconf' script or implicitly by using the configure
42 option '--enable-maintainer-mode'.
44    The files in the Subversion repository (see
45 <http://tug.org/texlive/svn>) are all up to date, but unfortunately this
46 may not be reflected by their timestamps.  (For starters, be sure to set
47 'use-commit-times=yes' in '~/.subversion/config' or the equivalent.)
49    To avoid unnecessary runs of 'bison', 'flex', or 'makeinfo' it may be
50 necessary to 'touch' the generated ('.c', '.h', or '.info') files.  With
51 '--enable-maintainer-mode' it may also be necessary to 'touch' first
52 'aclocal.m4', then 'configure' and 'config.h.in' (or 'c-auto.in'), and
53 finally all 'Makefile.in' files.  Perhaps 'make -t' will help.
55 6.2 Top-level directories
56 =========================
58 Here is a brief description of the top-level directories in the TeX Live
59 source tree.
61    As mentioned at the beginning of *note Overview of build system::,
62 the main source directories are 'texk/' (TeX-specific programs and
63 libraries), 'utils/' (additional programs), and 'libs/' (generic
64 libraries).
66    The top-level directories 'am/' and 'm4/' contain 'Makefile.am'
67 fragments and Autoconf macros, respectively, used in many places.
68 Specifically, the file 'm4/kpse-pkgs.m4' contains lists of all program
69 and library modules; missing modules are silently ignored.  (This helps
70 in creating cut-down source trees.)
72    Each module contributes fragments (in separate files) defining its
73 capabilities and requirements to the 'configure.ac' scripts at the
74 top-level and in the subdirectories 'libs', 'utils', and 'texk'.  The
75 fragments from program modules supply 'configure' options to disable or
76 enable building them; those from library modules specify if an installed
77 (system) version of that library can be used.  This ultimately
78 determines which modules need to be built--although all modules must be
79 configured for the benefit of 'make' targets such as 'dist' or
80 'distcheck'.
82    The top-level 'build-aux/' directory contains the common files
83 'compile', 'config.guess', 'config.sub', 'depcomp', etc. for most
84 packages, pulled from the GNU Gnulib sources
85 (<http://www.gnu.org/software/gnulib>), which in turn synchronizes with
86 the appropriate ultimate upstream repository.  There are, however,
87 independent copies in, e.g., 'libs/freetype2/freetype-*/builds/unix/',
88 and similar places.  The 'reautoconf' script does not touch those, but a
89 TL cron job keeps them in sync (nightly).
91    The directory 'extra/' contains things which are not part of the TL
92 build, but are present just for (someone's) convenience, e.g.,
93 'epstopdf' which is developed here.
95 6.3 Autoconf macros
96 ===================
98 Here we describe some of the Autoconf macros used in several modules-not
99 a complete list, by any means.  These general macros are supplemented by
100 module-specific macros in directories such as 'texk/dvipng/m4/'; some of
101 those are described in *note Library modules:: and *note Program
102 modules::.
104 6.3.1 General setup macros
105 --------------------------
107 The TL sources use two general setup macros:
109  -- Macro: KPSE_BASIC (NAME, [MORE-OPTIONS])
110      Initialize the basic TL infrastructure for module NAME:
111         'AM_INIT_AUTOMAKE([foreign MORE-OPTIONS])'
112         'AM_MAINTAINER_MODE'
113         'KPSE_COMPILER_WARNINGS'
114      and make sure the C compiler understands function prototypes.  This
115      is used for all generic library and program modules.
117  -- Macro: KPSE_COMMON (NAME, [MORE-OPTIONS])
118      Like 'KPSE_BASIC' but add:
119         'LT_PREREQ([2.2.6])'
120         'LT_INIT([win32-dll])'
121         'AC_SYS_LARGEFILE'
122         'AC_FUNC_FSEEKO'
123      and check for frequently used functions, headers, types, and
124      structures.  This is used for TeX-specific modules.
126 6.3.2 Macros for programs
127 -------------------------
129 Macros for program checks:
131  -- Macro: KPSE_CHECK_LATEX
132      Set 'LATEX' to the name of the first of 'latex', 'elatex', or
133      'lambda' which exists in 'PATH', or to 'no' if none of them exists.
134      Call 'AC_SUBST' for 'LATEX'.  The result of this test can be
135      overridden by setting the 'LATEX' environment variable or the cache
136      variable 'ac_cv_prog_LATEX'.
138  -- Macro: KPSE_CHECK_PDFLATEX
139      Check for 'pdflatex' in 'PATH' and set 'PDFLATEX'.
141  -- Macro: KPSE_CHECK_PERL
142      Check for 'perl' or 'perl5' in 'PATH' and set 'PERL'.
144  -- Macro: KPSE_PROG_LEX
145      Call 'AC_PROG_LEX' and add the flag '-l' for 'flex'.
147 6.3.3 Macros for compilers
148 --------------------------
150 Macros for compiler-related checks:
152  -- Macro: KPSE_COMPILER_WARNINGS
153      When using the (Objective) C/C++ compiler, set
154      'WARNING_[OBJ]C[XX]FLAGS' to suitable warning flags (depending on
155      the value given to or implied for '--enable-compiler-warnings').
156      Call 'AC_SUBST' for them.  At the moment this only works for GNU
157      compilers, but could be extended to others if necessary.
159      This macro caches its results in the 'kpse_cv_warning_cflags', ...
160      variables.
162  -- Macro: KPSE_COMPILER_VISIBILITY
163      When using the C or C++ compiler, try to set
164      'VISIBILITY_C[XX]FLAGS' to flags to hide external symbols.  Call
165      'AC_SUBST' for this variable.  At the moment this only tests for
166      the compiler option '-fvisibility=hidden', but that could be
167      extended with more checks if necessary.
169      This macro caches its results in the 'kpse_cv_visibility_cflags' or
170      'kpse_cv_visibility_cxxflags' variable.
172  -- Macro: KPSE_CXX_HACK
173      Provide the configure option '--enable-cxx-runtime-hack'.  If
174      enabled and when using 'g++', try to statically link with
175      'libstdc++', somewhat improving portability of the resulting
176      binary.
178      This macro caches its result in the 'kpse_cv_cxx_hack' variable.
180 6.3.4 Macros for libraries
181 --------------------------
183 One macro for a library check:
185  -- Macro: KPSE_LARGEFILE (VARIABLE, [EXTRA-DEFINE])
186      Call 'AC_SYS_LARGEFILE' and 'AC_FUNC_FSEEKO' and append suitable
187      '-D' flags (optionally including '-DEXTRA-DEFINE') to VARIABLE.
189 6.3.5 Macros for library and header flags
190 -----------------------------------------
192 Each library module 'libs/LIB' or 'texk/LIB' is supplemented by a macro
193 'KPSE_LIB_FLAGS' (all uppercase) that provides make variables for that
194 library.  E.g., for 'libs/libpng':
196  -- Macro: KPSE_LIBPNG_FLAGS
197      Provide the configure option '--with-system-libpng'.  Set and
198      'AC_SUBST' 'make' variables for modules using this library (either
199      an installed version or from the TeX Live tree): 'LIBPNG_INCLUDES'
200      for use in 'CPPFLAGS', 'LIBPNG_LIBS' for use in 'LDADD',
201      'LIBPNG_DEPEND' for use as dependency, and 'LIBPNG_RULE' defining
202      'make' rules to rebuild the library.
204  -- Macro: KPSE_ADD_FLAGS (NAME)
205      Temporarily extend 'CPPFLAGS' and 'LIBS' with the values required
206      for the library module 'NAME'.
208  -- Macro: KPSE_RESTORE_FLAGS
209      Restore 'CPPFLAGS' and 'LIBS' to their original values.
211    As an example, the 'configure.ac' file for a hypothetical program
212 'utils/foo' using 'libpng', and hence 'zlib', would contain
213      KPSE_ZLIB_FLAGS
214      KPSE_LIBPNG_FLAGS
216 and its 'Makefile.am' would be along these lines:
217      bin_PROGRAMS = foo
218      AM_CPPFLAGS = ${LIBPNG_INCLUDES} ${ZLIB_INCLUDES}
219      foo_LDADD = ${LIBPNG_LIBS} ${ZLIB_LIBS}
220      foo_DEPENDENCIES = ${ZLIB_DEPEND} ${LIBPNG_DEPEND}
221      ## Rebuild libz
222      @ZLIB_RULE@
223      ## Rebuild libpng
224      @LIBPNG_RULE@
226    If it was necessary to examine whether certain 'zlib' or 'libpng'
227 features were available, 'configure.ac' should be continued this way:
228      KPSE_ADD_FLAGS([zlib])
229      ... # tests for 'zlib' features, if any
230      KPSE_ADD_FLAGS([libpng])
231      ... # tests for 'libpng' features
232      KPSE_RESTORE_FLAGS # restore 'CPPFLAGS' and 'LIBS'
234 6.3.6 Macros for Windows
235 ------------------------
237 Windows differs in several aspects from Unix-like systems, many of them
238 due to the lack of symbolic links.
240  -- Macro: KPSE_CHECK_WIN32
241      Check if compiling for a Windows system.  The result is 'no' for
242      Unix-like systems (including Cygwin), 'mingw32' for Windows with
243      GCC, or 'native' for Windows with MSVC. The result is cached in the
244      'kpse_cv_have_win32' variable.
246  -- Macro: KPSE_COND_WIN32
247      Call 'KPSE_CHECK_WIN32' and define the Automake conditional 'WIN32'
248      ('true' if the value of 'kpse_cv_have_win32' is not 'no').
250  -- Macro: KPSE_COND_MINGW32
251      Call 'KPSE_COND_WIN32' and define the Automake conditional
252      'MINGW32' ('true' if the value of 'kpse_cv_have_win32' is
253      'mingw32').
255  -- Macro: KPSE_COND_WIN32_WRAP
256      Call 'KPSE_COND_WIN32' and define the Automake conditional
257      'WIN32_WRAP' ('true' if the standard Windows wrapper
258      ('texk/texlive/w32_wrapper/runscript.exe') exists.  This wrapper is
259      used on Windows instead of symlinks for the "linked scripts" (*note
260      Linked scripts::).
262  -- Macro: KPSE_WIN32_CALL
263      Call 'KPSE_COND_WIN32', check if the file
264      'texk/texlive/w32_wrapper/callexe.c' exists; if it does, create a
265      symlink in the build tree.  Compiling 'callexe.c' with
266      '-DEXEPROG='"FOO.exe"'' and installing 'callexe.exe' as 'BAR.exe'
267      is used on Windows instead of a symlink 'BAR->FOO' for Unix-like
268      systems.
270 6.4 Library modules
271 ===================
273 Here we discuss some specifics for a few of the libraries in TL, both
274 for the details themselves, and as a way of illuminating the general
275 structure and variation.
277 6.4.1 The 'png' library in 'libs/libpng'
278 ----------------------------------------
280 This generic library uses the source tree in, e.g., the subdirectory
281 'libpng-1.6.16' with all modifications for TL recorded in
282 'libpng-1.6.16-PATCHES/*'.  The 'configure.ac' fragment
283 'ac/withenable.ac' contains
285      KPSE_WITH_LIB([libpng], [zlib])
287 specifying the module name, and indicating the dependency on 'zlib'.  A
288 third literal argument 'tree' would specify that the library from the
289 TeX Live tree cannot be replaced by a system version.  That not being
290 the case here, a second fragment 'ac/libpng.ac' contains
292      KPSE_TRY_LIB([libpng],
293                   [#include <png.h>],
294                   [png_structp png; png_voidp io; png_rw_ptr fn;
295      png_set_read_fn(png, io, fn);])
297 thus providing the simple C code
299      #include <png.h>
300      int main ()
301      { png_structp png; png_voidp io; png_rw_ptr fn;
302        png_set_read_fn(png, io, fn);
303        return 0; }
305 which Autoconf uses to verify the usability of a system version with C
306 code.  The analogous macro 'KPSE_TRY_LIBXX' would check using C++ code.
307 These fragments are included by 'configure.ac' at the top level.
309    For this library, among many other modules, a proxy build system for
310 TL is used ('configure.ac', 'Makefile.am', and 'include/Makefile.am'),
311 ignoring the distributed one.  Consequently, a few generated files and
312 auxiliary scripts are removed from the distributed source tree.  The
313 public headers 'png.h', 'pngconf.h', and 'pnglibconf.h' are "installed"
314 (as symlinks) under 'include/' in the build tree exactly as they are for
315 a system version under, e.g., '/usr/include/'.
317    The module is supplemented by the file 'm4/kpse-libpng-flags.m4' that
318 defines the M4 macro 'KPSE_LIBPNG_FLAGS' used by all modules depending
319 on this library in their 'configure.ac' to generate the 'make' variables
320 'LIBPNG_INCLUDES' for use in 'CPPFLAGS', 'LIBPNG_LIBS' for use in
321 'LDADD', 'LIBPNG_DEPEND' for use as dependencies, and 'LIBPNG_RULE'
322 defining 'make' rules to rebuild the library.
324    'm4/kpse-libpng-flags.m4' also supplies the configure option
325 '--with-system-libpng' and uses 'pkg-config' to determine the flags
326 required for the system library.
328 6.4.2 The 'zlib' library in 'libs/zlib'
329 ---------------------------------------
331 This generic library is very much analogous to 'libpng', but without the
332 dependency on any other library.  The file 'm4/kpse-zlib-flags.m4'
333 supplies the configure option '--with-system-zlib', as well as
334 '--with-zlib-includes' and '--with-zlib-libdir' to specify non-standard
335 locations of the 'zlib' headers and/or library.
337 6.4.3 The 'freetype' library in 'libs/freetype2'
338 ------------------------------------------------
340 This module uses a wrapper build system with an almost trivial
341 'configure.ac' and with a 'Makefile.am' that invokes 'configure' and
342 'make' for the distributed source, followed by 'make install' with the
343 build tree as destination.  The flags required for the system library
344 are obtained through 'freetype-config'.
346 6.4.4 The 'kpathsea' library in 'texk/kpathsea'
347 -----------------------------------------------
349 This is one of the TeX-specific libraries that are maintained as part of
350 TeX Live (*note (kpathsea)::).  Despite being a core part of the TeX
351 system, it is not a terribly special case in the infrastructure.  The
352 TeX libraries are Libtool libraries (static and/or shared) and are
353 installed by 'make install' together with the programs.  They are,
354 however, not part of the TL DVD as distributed by TeX user groups, and
355 have never been officially released for standalone use.
357    It is possible, and perhaps even useful for distro builds (*note
358 Distro builds::), to specify the configure option
359 '--with-system-kpathsea' in order to use a system version of the
360 library.  Programs outside the TL tree should use 'pkg-config' for the
361 required flags.
363    In addition to 'ac/withenable.ac' and 'ac/kpathsea.ac' there is a
364 third fragment 'ac/mktex.ac' included by both 'ac/withenable.ac' and
365 'configure.ac' that supplies configure options such as
366 '--enable-mktextfm-default', which determine the compile time default of
367 whether or not to run 'mktextfm' to generate a missing '.tfm' file.  In
368 any case, however, the command line options '-mktex=tfm' or
369 '-no-mktex=tfm' for the TeX-like engines override this default.
371 6.5 Program modules
372 ===================
374 As with libraries (*note Library modules::), here we discuss the details
375 for a few of the programs in TL.
377 6.5.1 The 't1utils' package in 'utils/t1utils'
378 ----------------------------------------------
380 Once again we use the distributed source tree 't1utils-1.39' with
381 modifications documented in 't1utils-1.39-PATCHES/*' and a proxy build
382 system consisting of 'configure.ac' and 'Makefile.am'.  The fragment
383 'ac/withenable.ac' contains
385      KPSE_ENABLE_PROG([t1utils])
387 specifying the module name without any dependencies, and supplies the
388 configure option '--disable-t1utils'.
390 6.5.2 The 'xindy' package in 'utils/xindy'
391 ------------------------------------------
393 This module uses the distributed source tree 'xindy-2.5.1' with
394 modifications documented in 'xindy-2.5.1-PATCHES/*', a proxy
395 'configure.ac', and a wrapper 'Makefile.am' that descends into
396 'xindy-2.5.1'.  The 'xindy' build requires that the distributed
397 'Makefile's allow a 'VPATH' build, can handle all targets, and do not
398 refer to '${top_srcdir}' or '${top_builddir}'.  The fragment
399 'ac/withenable.ac' contains
401      KPSE_ENABLE_PROG([xindy], , [disable native])
402      m4_include(kpse_TL[utils/xindy/ac/xindy.ac])
403      m4_include(kpse_TL[utils/xindy/ac/clisp.ac])
405 where 'disable' in the third argument indicates that 'xindy' is only
406 built if explicitly enabled by the user with 'configure --enable-xindy'
407 (the need for 'clisp' is too painful to require by default), and
408 'native' disallows cross compilation.  The additional fragments
409 'ac/xindy.ac' and 'ac/clisp.ac' specify more 'configure' options to be
410 seen at the top level with 'ac/xindy.ac' also included by
411 'configure.ac'.
413 6.5.3 The 'xdvik' package in 'texk/xdvik'
414 -----------------------------------------
416 This package is maintained as part of the TeX Live tree with sources in
417 its top level directory and the subdirectory 'gui'.  The fragment
418 'ac/withenable.ac' contains
420      dnl extra_dirs = texk/xdvik/squeeze
421      KPSE_ENABLE_PROG([xdvik], [kpathsea freetype2], [x])
422      m4_include(kpse_TL[texk/xdvik/ac/xdvik.ac])
424 thus specifying the dependency on the 'kpathsea', 'freetype', and X11
425 libraries.  The M4 comment (following 'dnl') signals the subsidiary
426 'squeeze/configure.ac'.  This is needed because the main executable
427 'xdvi-bin' (to be installed as, e.g., 'xdvi-xaw') is for the 'host'
428 system whereas the auxiliary program 'squeeze/squeeze' has to run on the
429 'build' system and in a cross compilation they differ.
431    The additional fragment 'ac/xdvik.ac' is also included by
432 'configure.ac' and supplies the configure option '--with-xdvi-x-toolkit'
433 also seen at the top-level.
435 6.5.4 The subdirectory 'utils/asymptote'
436 ----------------------------------------
438 This subdirectory contains the sources for 'asy' and 'xasy' but due to
439 its complexity and prerequisites (e.g., OpenGL) it is not part of the TL
440 build system.  These programs must be built and installed independently,
441 but are included on the TL DVD together with their support files.
443 6.6 Extending TeX Live
444 ======================
446 This section outlines the basic process for adding new packages to the
447 TL build system.
449 6.6.1 Adding a new program module
450 ---------------------------------
452 A TeX-specific program module in a subdirectory 'texk/PROG' may use the
453 TeX-specific libraries and is included by adding its name 'PROG' to the
454 M4 list 'kpse_texk_pkgs' defined in 'm4/kpse-pkgs.m4'.
456    A generic program module in a subdirectory 'utils/PROG' must not use
457 the TeX-specific libraries and is included by adding its name 'PROG' to
458 the M4 list 'kpse_utils_pkgs' in 'm4/kpse-pkgs.m4'.
460    In either case, apart from the program sources and build system
461 ('configure.ac' and 'Makefile.am'), the subdirectory 'texk/PROG' or
462 'utils/PROG' must provide a fragment 'ac/withenable.ac' that contains
463 the M4 macro 'KPSE_ENABLE_PROG' defined in 'm4/kpse-setup.m4' with
464 'PROG' as the mandatory first argument and three optional arguments:
466   1. a list of required libraries from the TL tree;
468   2. a list of options ('disable' if this module is not to be built
469      without the configure option '--enable-PROG', 'native' if cross
470      compilation is not possible, 'x' if the program requires X11
471      libraries);
473   3. and a comment added to the help text for the 'configure' option
474      '--enable-PROG' or '--disable-PROG'.
476    If the module requires specific configure options to be seen at the
477 top-level, they should be defined in an additional fragment 'ac/PROG.ac'
478 included from 'ac/withenable.ac' and 'configure.ac'.
480 6.6.2 Adding a new generic library module
481 -----------------------------------------
483 A generic library module in a subdirectory 'libs/LIB' must not depend on
484 TeX-specific libraries, by definition.  It is included by adding its
485 name 'LIB' to the M4 list 'kpse_libs_pkgs' in 'm4/kpse-pkgs.m4'--before
486 any other libraries from the TeX Live tree on which it depends.
488    As with program modules, the subdirectory 'libs/LIB' must contain the
489 sources and build system for the library (and any installable support
490 programs) and a fragment 'ac/withenable.ac' that contains the M4 macro
491 'KPSE_WITH_LIB' defined in 'm4/kpse-setup.m4' with 'LIB' as the
492 mandatory first argument and two optional arguments: a list of required
493 libraries from the TL tree, and a list of options (currently there is
494 only one: specify 'tree' if this library cannot be replaced by a system
495 version).
497    If a system version can be used, a second fragment 'ac/LIB.ac' is
498 needed, containing the M4 macro 'KPSE_TRY_LIB' (or 'KPSE_TRY_LIBXX')
499 with 'LIB' as the mandatory first argument and two additional arguments
500 for the Autoconf macro 'AC_LANG_PROGRAM' used to compile and link a
501 small C (or C++) program as sanity check for using the system library.
503    In addition a file 'm4/kpse-LIB-flags' (at the top level) must define
504 the M4 macro 'KPSE_LIB_FLAGS' (all uppercase) setting up the 'make'
505 variables 'LIB_INCLUDES', 'LIB_LIBS', 'LIB_DEPEND', and 'LIB_RULE' with
506 the values required for 'CPPFLAGS', 'LDADD', dependencies, and a
507 (multi-line) 'make' rule to rebuild the library when necessary.  All of
508 that is needed for the library from the TL tree and, if supported, for a
509 system version.
511    If a system library is allowed, 'KPSE_LIB_FLAGS' also provides the
512 configure option '--with-system-LIB' and uses the additional M4 macro
513 'KPSE_LIB_SYSTEM_FLAGS' to generate the 'make' variables for a system
514 library.  Furthermore the definition of the M4 macro
515 'KPSE_ALL_SYSTEM_FLAGS' in 'm4/kpse-pkgs.m4' must be extended by the
516 line:
517    'AC_REQUIRE([KPSE_LIB_SYSTEM_FLAGS])'
519 6.6.3 Adding a new TeX-specific library module
520 ----------------------------------------------
522 A TeX-specific library module in a subdirectory 'texk/LIB' may depend on
523 other TeX-specific libraries but must not depend on any generic library
524 from the TL tree.  It is included in the same general ways as a generic
525 library (see the previous section), with these modifications:
527    * The library name 'LIB' is added to the M4 list 'kpse_texlibs_pkgs'
528      also in 'm4/kpse-pkgs.m4'.
530    * The fragment 'ac/withenable.ac' must use 'KPSE_WITH_TEXLIB'.