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
34 ltmain.sh (GNU libtool) 2.4.6
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
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
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
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.
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
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])'
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:
120 'LT_INIT([win32-dll])'
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', ...
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
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
216 and its 'Makefile.am' would be along these lines:
218 AM_CPPFLAGS = ${LIBPNG_INCLUDES} ${ZLIB_INCLUDES}
219 foo_LDADD = ${LIBPNG_LIBS} ${ZLIB_LIBS}
220 foo_DEPENDENCIES = ${ZLIB_DEPEND} ${LIBPNG_DEPEND}
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
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
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
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],
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
301 { png_structp png; png_voidp io; png_rw_ptr fn;
302 png_set_read_fn(png, io, fn);
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
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.
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
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
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
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
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
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
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'.