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.) 4 56 Layout and infrastructure 6*************************** 7 8The TeX Live source tree is the subtree rooted at 'Build/source' of the 9complete TL distribution and contains the sources for all executables 10distributed by TL, as well as 'configure' scripts and 'make' rules to 11build and install them together with some of their support files. 12 136.1 Build system tools 14====================== 15 16As mentioned above (*note Prerequisites::), a normal build requires very 17little. On the other hand, if you want to modify the TeX Live 18infrastructure sources, such as 'configure.ac' or 'Makefile.am' files, 19you will need to have several additional tools installed. 20 21 In general, the TL build system uses the latest released versions of 22the GNU build tools, installed directly from the original GNU releases 23(e.g., by building them with 'configure --prefix=/usr/local/gnu' and 24having 'PATH' start with '/usr/local/gnu/bin'). We have found that 25trying to use the versions of these tools packaged for distros causes 26many extra hassles, so don't do that, tempting as it may be. 27 28 Currently the versions we use are: 29 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 37 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 40dependencies have been changed. This can be done explicitly with the 41top-level 'reautoconf' script or implicitly by using the configure 42option '--enable-maintainer-mode'. 43 44 The files in the Subversion repository (see 45<http://tug.org/texlive/svn>) are all up to date, but unfortunately this 46may not be reflected by their timestamps. (For starters, be sure to set 47'use-commit-times=yes' in '~/.subversion/config' or the equivalent.) 48 49 To avoid unnecessary runs of 'bison', 'flex', or 'makeinfo' it may be 50necessary 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 53finally all 'Makefile.in' files. Perhaps 'make -t' will help. 54 556.2 Top-level directories 56========================= 57 58Here is a brief description of the top-level directories in the TeX Live 59source tree. 60 61 As mentioned at the beginning of *note Overview of build system::, 62the main source directories are 'texk/' (TeX-specific programs and 63libraries), 'utils/' (additional programs), and 'libs/' (generic 64libraries). 65 66 The top-level directories 'am/' and 'm4/' contain 'Makefile.am' 67fragments and Autoconf macros, respectively, used in many places. 68Specifically, the file 'm4/kpse-pkgs.m4' contains lists of all program 69and library modules; missing modules are silently ignored. (This helps 70in creating cut-down source trees.) 71 72 Each module contributes fragments (in separate files) defining its 73capabilities and requirements to the 'configure.ac' scripts at the 74top-level and in the subdirectories 'libs', 'utils', and 'texk'. The 75fragments from program modules supply 'configure' options to disable or 76enable building them; those from library modules specify if an installed 77(system) version of that library can be used. This ultimately 78determines which modules need to be built--although all modules must be 79configured for the benefit of 'make' targets such as 'dist' or 80'distcheck'. 81 82 The top-level 'build-aux/' directory contains the common files 83'compile', 'config.guess', 'config.sub', 'depcomp', etc. for most 84packages, pulled from the GNU Gnulib sources 85(<http://www.gnu.org/software/gnulib>), which in turn synchronizes with 86the appropriate ultimate upstream repository. There are, however, 87independent copies in, e.g., 'libs/freetype2/freetype-*/builds/unix/', 88and similar places. The 'reautoconf' script does not touch those, but a 89TL cron job keeps them in sync (nightly). 90 91 The directory 'extra/' contains things which are not part of the TL 92build, but are present just for (someone's) convenience, e.g., 93'epstopdf' which is developed here. 94 956.3 Autoconf macros 96=================== 97 98Here we describe some of the Autoconf macros used in several modules-not 99a complete list, by any means. These general macros are supplemented by 100module-specific macros in directories such as 'texk/dvipng/m4/'; some of 101those are described in *note Library modules:: and *note Program 102modules::. 103 1046.3.1 General setup macros 105-------------------------- 106 107The TL sources use two general setup macros: 108 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. 116 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. 125 1266.3.2 Macros for programs 127------------------------- 128 129Macros for program checks: 130 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'. 137 138 -- Macro: KPSE_CHECK_PDFLATEX 139 Check for 'pdflatex' in 'PATH' and set 'PDFLATEX'. 140 141 -- Macro: KPSE_CHECK_PERL 142 Check for 'perl' or 'perl5' in 'PATH' and set 'PERL'. 143 144 -- Macro: KPSE_PROG_LEX 145 Call 'AC_PROG_LEX' and add the flag '-l' for 'flex'. 146 1476.3.3 Macros for compilers 148-------------------------- 149 150Macros for compiler-related checks: 151 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. 158 159 This macro caches its results in the 'kpse_cv_warning_cflags', ... 160 variables. 161 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. 168 169 This macro caches its results in the 'kpse_cv_visibility_cflags' or 170 'kpse_cv_visibility_cxxflags' variable. 171 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. 177 178 This macro caches its result in the 'kpse_cv_cxx_hack' variable. 179 1806.3.4 Macros for libraries 181-------------------------- 182 183One macro for a library check: 184 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. 188 1896.3.5 Macros for library and header flags 190----------------------------------------- 191 192Each library module 'libs/LIB' or 'texk/LIB' is supplemented by a macro 193'KPSE_LIB_FLAGS' (all uppercase) that provides make variables for that 194library. E.g., for 'libs/libpng': 195 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. 203 204 -- Macro: KPSE_ADD_FLAGS (NAME) 205 Temporarily extend 'CPPFLAGS' and 'LIBS' with the values required 206 for the library module 'NAME'. 207 208 -- Macro: KPSE_RESTORE_FLAGS 209 Restore 'CPPFLAGS' and 'LIBS' to their original values. 210 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 215 216and 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@ 225 226 If it was necessary to examine whether certain 'zlib' or 'libpng' 227features 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' 233 2346.3.6 Macros for Windows 235------------------------ 236 237Windows differs in several aspects from Unix-like systems, many of them 238due to the lack of symbolic links. 239 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. 245 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'). 249 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'). 254 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::). 261 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. 269 2706.4 Library modules 271=================== 272 273Here we discuss some specifics for a few of the libraries in TL, both 274for the details themselves, and as a way of illuminating the general 275structure and variation. 276 2776.4.1 The 'png' library in 'libs/libpng' 278---------------------------------------- 279 280This 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 284 285 KPSE_WITH_LIB([libpng], [zlib]) 286 287specifying the module name, and indicating the dependency on 'zlib'. A 288third literal argument 'tree' would specify that the library from the 289TeX Live tree cannot be replaced by a system version. That not being 290the case here, a second fragment 'ac/libpng.ac' contains 291 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);]) 296 297thus providing the simple C code 298 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; } 304 305which Autoconf uses to verify the usability of a system version with C 306code. The analogous macro 'KPSE_TRY_LIBXX' would check using C++ code. 307These fragments are included by 'configure.ac' at the top level. 308 309 For this library, among many other modules, a proxy build system for 310TL is used ('configure.ac', 'Makefile.am', and 'include/Makefile.am'), 311ignoring the distributed one. Consequently, a few generated files and 312auxiliary scripts are removed from the distributed source tree. The 313public headers 'png.h', 'pngconf.h', and 'pnglibconf.h' are "installed" 314(as symlinks) under 'include/' in the build tree exactly as they are for 315a system version under, e.g., '/usr/include/'. 316 317 The module is supplemented by the file 'm4/kpse-libpng-flags.m4' that 318defines the M4 macro 'KPSE_LIBPNG_FLAGS' used by all modules depending 319on 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' 322defining 'make' rules to rebuild the library. 323 324 'm4/kpse-libpng-flags.m4' also supplies the configure option 325'--with-system-libpng' and uses 'pkg-config' to determine the flags 326required for the system library. 327 3286.4.2 The 'zlib' library in 'libs/zlib' 329--------------------------------------- 330 331This generic library is very much analogous to 'libpng', but without the 332dependency on any other library. The file 'm4/kpse-zlib-flags.m4' 333supplies the configure option '--with-system-zlib', as well as 334'--with-zlib-includes' and '--with-zlib-libdir' to specify non-standard 335locations of the 'zlib' headers and/or library. 336 3376.4.3 The 'freetype' library in 'libs/freetype2' 338------------------------------------------------ 339 340This 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 343build tree as destination. The flags required for the system library 344are obtained through 'freetype-config'. 345 3466.4.4 The 'kpathsea' library in 'texk/kpathsea' 347----------------------------------------------- 348 349This is one of the TeX-specific libraries that are maintained as part of 350TeX Live (*note (kpathsea)::). Despite being a core part of the TeX 351system, it is not a terribly special case in the infrastructure. The 352TeX libraries are Libtool libraries (static and/or shared) and are 353installed by 'make install' together with the programs. They are, 354however, not part of the TL DVD as distributed by TeX user groups, and 355have never been officially released for standalone use. 356 357 It is possible, and perhaps even useful for distro builds (*note 358Distro builds::), to specify the configure option 359'--with-system-kpathsea' in order to use a system version of the 360library. Programs outside the TL tree should use 'pkg-config' for the 361required flags. 362 363 In addition to 'ac/withenable.ac' and 'ac/kpathsea.ac' there is a 364third 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 367whether or not to run 'mktextfm' to generate a missing '.tfm' file. In 368any case, however, the command line options '-mktex=tfm' or 369'-no-mktex=tfm' for the TeX-like engines override this default. 370 3716.5 Program modules 372=================== 373 374As with libraries (*note Library modules::), here we discuss the details 375for a few of the programs in TL. 376 3776.5.1 The 't1utils' package in 'utils/t1utils' 378---------------------------------------------- 379 380Once again we use the distributed source tree 't1utils-1.39' with 381modifications documented in 't1utils-1.39-PATCHES/*' and a proxy build 382system consisting of 'configure.ac' and 'Makefile.am'. The fragment 383'ac/withenable.ac' contains 384 385 KPSE_ENABLE_PROG([t1utils]) 386 387specifying the module name without any dependencies, and supplies the 388configure option '--disable-t1utils'. 389 3906.5.2 The 'xindy' package in 'utils/xindy' 391------------------------------------------ 392 393This module uses the distributed source tree 'xindy-2.5.1' with 394modifications 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 398refer to '${top_srcdir}' or '${top_builddir}'. The fragment 399'ac/withenable.ac' contains 400 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]) 404 405where 'disable' in the third argument indicates that 'xindy' is only 406built 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 410seen at the top level with 'ac/xindy.ac' also included by 411'configure.ac'. 412 4136.5.3 The 'xdvik' package in 'texk/xdvik' 414----------------------------------------- 415 416This package is maintained as part of the TeX Live tree with sources in 417its top level directory and the subdirectory 'gui'. The fragment 418'ac/withenable.ac' contains 419 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]) 423 424thus specifying the dependency on the 'kpathsea', 'freetype', and X11 425libraries. 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' 428system whereas the auxiliary program 'squeeze/squeeze' has to run on the 429'build' system and in a cross compilation they differ. 430 431 The additional fragment 'ac/xdvik.ac' is also included by 432'configure.ac' and supplies the configure option '--with-xdvi-x-toolkit' 433also seen at the top-level. 434 4356.5.4 The subdirectory 'utils/asymptote' 436---------------------------------------- 437 438This subdirectory contains the sources for 'asy' and 'xasy' but due to 439its complexity and prerequisites (e.g., OpenGL) it is not part of the TL 440build system. These programs must be built and installed independently, 441but are included on the TL DVD together with their support files. 442 4436.6 Extending TeX Live 444====================== 445 446This section outlines the basic process for adding new packages to the 447TL build system. 448 4496.6.1 Adding a new program module 450--------------------------------- 451 452A TeX-specific program module in a subdirectory 'texk/PROG' may use the 453TeX-specific libraries and is included by adding its name 'PROG' to the 454M4 list 'kpse_texk_pkgs' defined in 'm4/kpse-pkgs.m4'. 455 456 A generic program module in a subdirectory 'utils/PROG' must not use 457the TeX-specific libraries and is included by adding its name 'PROG' to 458the M4 list 'kpse_utils_pkgs' in 'm4/kpse-pkgs.m4'. 459 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 463the M4 macro 'KPSE_ENABLE_PROG' defined in 'm4/kpse-setup.m4' with 464'PROG' as the mandatory first argument and three optional arguments: 465 466 1. a list of required libraries from the TL tree; 467 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); 472 473 3. and a comment added to the help text for the 'configure' option 474 '--enable-PROG' or '--disable-PROG'. 475 476 If the module requires specific configure options to be seen at the 477top-level, they should be defined in an additional fragment 'ac/PROG.ac' 478included from 'ac/withenable.ac' and 'configure.ac'. 479 4806.6.2 Adding a new generic library module 481----------------------------------------- 482 483A generic library module in a subdirectory 'libs/LIB' must not depend on 484TeX-specific libraries, by definition. It is included by adding its 485name 'LIB' to the M4 list 'kpse_libs_pkgs' in 'm4/kpse-pkgs.m4'--before 486any other libraries from the TeX Live tree on which it depends. 487 488 As with program modules, the subdirectory 'libs/LIB' must contain the 489sources and build system for the library (and any installable support 490programs) 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 492mandatory first argument and two optional arguments: a list of required 493libraries from the TL tree, and a list of options (currently there is 494only one: specify 'tree' if this library cannot be replaced by a system 495version). 496 497 If a system version can be used, a second fragment 'ac/LIB.ac' is 498needed, containing the M4 macro 'KPSE_TRY_LIB' (or 'KPSE_TRY_LIBXX') 499with 'LIB' as the mandatory first argument and two additional arguments 500for the Autoconf macro 'AC_LANG_PROGRAM' used to compile and link a 501small C (or C++) program as sanity check for using the system library. 502 503 In addition a file 'm4/kpse-LIB-flags' (at the top level) must define 504the M4 macro 'KPSE_LIB_FLAGS' (all uppercase) setting up the 'make' 505variables 'LIB_INCLUDES', 'LIB_LIBS', 'LIB_DEPEND', and 'LIB_RULE' with 506the values required for 'CPPFLAGS', 'LDADD', dependencies, and a 507(multi-line) 'make' rule to rebuild the library when necessary. All of 508that is needed for the library from the TL tree and, if supported, for a 509system version. 510 511 If a system library is allowed, 'KPSE_LIB_FLAGS' also provides the 512configure option '--with-system-LIB' and uses the additional M4 macro 513'KPSE_LIB_SYSTEM_FLAGS' to generate the 'make' variables for a system 514library. Furthermore the definition of the M4 macro 515'KPSE_ALL_SYSTEM_FLAGS' in 'm4/kpse-pkgs.m4' must be extended by the 516line: 517 'AC_REQUIRE([KPSE_LIB_SYSTEM_FLAGS])' 518 5196.6.3 Adding a new TeX-specific library module 520---------------------------------------------- 521 522A TeX-specific library module in a subdirectory 'texk/LIB' may depend on 523other TeX-specific libraries but must not depend on any generic library 524from the TL tree. It is included in the same general ways as a generic 525library (see the previous section), with these modifications: 526 527 * The library name 'LIB' is added to the M4 list 'kpse_texlibs_pkgs' 528 also in 'm4/kpse-pkgs.m4'. 529 530 * The fragment 'ac/withenable.ac' must use 'KPSE_WITH_TEXLIB'. 531 532