1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
Copyright (C) 2009-2011 Peter Breitenlohner <tex-live@tug.org>
You may freely use, modify and/or distribute this file.
Design of the TeX Live (TL) build system
========================================
The TL build system has been completely redesigned, using Autoconf,
Automake, and Libtool. The main components are TeX specific or utility
program modules (directories texk/*/ and utils/*/), and TeX specific or
generic library modules (directories texk/kpathsea/, texk/ptexenc/, and
libs/*/) providing libraries required by the program modules.
The primary design goal was modularity. Each module specifies its own
requirements and properties, such as required libraries, whether an
installed (system) version of a library can be used, configure options to be
seen at the top-level, and more. Consequently an explicit list of all
available modules is kept only in one central place.
A second, related goal was to configure and build each library before
configuring any (program or other library) module depending on that library.
This allows to check 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.
Most generic libraries and several programs that are maintained independently
use the distributed source tree, with any patches to that source tree
also kept separately as precise documentation of our changes.
All this should simplify upgrading of modules maintained independently
and/or integrating new modules into the TL build system.
Layout of the TL build system
=============================
1. Layout of directories
========================
1.1. Overall layout
-------------------
texk/kpathsea/ the two TeX specific libraries, Kpathsea
texk/ptexenc/ and Ptexenc
libs/Lib/ generic library Lib (zlib, libpng, t1lib, etc.)
texk/Prog/ TeX specific program package Prog (web2c, afm2pl, etc.)
utils/Util/ utility program package Util (chktex, ps2eps, etc.)
auxdir/auxsub/ dummy module used to configure the real modules
*/*/ac/*.ac various configure.ac fragments (configure options)
build-aux/ auxiliary build scripts (config.guess etc.)
m4/kpse-pkgs.m4 Autoconf macros defining lists of library and program
modules and handling loops over these lists
m4/*.m4 other Autoconf macros
texk/am/*.am Makefile.am fragments
texk/web2c/am/*.am for the Kpathsea library
texk/web2c/*/am/*.am and the Web2C programs
1.2. A generic library `Lib'
----------------------------
libs/Lib/ac/withenable.ac defines libraries required by Lib
libs/Lib/ac/Lib.ac defines basic tests for a system version of Lib
m4/kpse-Lib-flags.m4 defines Autoconf macros for configure options
as well as KPSE_LIB_FLAGS, to be used
in configure.ac files and defining
Make variables
Several libraries use an (almost) unmodified source tree supplemented by a
proxy build system (bypassing that of the source tree), e.g.,
libs/zlib/zlib-1.2.5/ (almost) unmodified source tree
libs/zlib/zlib-1.2.5-PATCHES/ modifications applied to that source tree
libs/zlib/Makefile.am proxy Makefile.am
libs/zlib/configure.ac and configure.ac
The header files for many libraries are `installed' (as symlinks) under
libs/Lib/include/ in the build tree exactly as they are for a system version
under, e.g., /usr/include/.
The same structure is used for the TeX specific libraries.
1.3. A TeX specific program `Prog'
----------------------------------
texk/Prog/ac/withenable.ac defines libraries required by Prog,
provides the configure option --disable-Prog
texk/Prog/ac/Prog.ac optionally defines Prog specific configure
option that should be seen at the top-level
1.4. A utility program `Util'
-----------------------------
utils/Util/ac/withenable.ac defines libraries required by Util, provides
the configure option --disable-Util
2. Running `configure'
======================
Running 'configure' for the top-level directory will in addition configure
the directories auxdir/auxsub/, libs/, utils/, and texk/. This will
determine the programs (utils/Util/ and texk/Prog/) to be built and
libraries from the TL tree (texk/kpathsea/, texk/ptexenc/, and libs/Lib/)
required by these programs.
3. Running `make' at the top-level
==================================
First, if texk/kpathsea/ or texk/ptexenc/ is not yet configured, this runs
`configure' and if required `make all' in that directory. Then this
recurses into all required subdirectories texk/kpathsea/, texk/ptexenc/,
libs/, utils/, and texk/ for the selected Make target: `default' or `all' to
(re-)build, `check' to run tests, `install' etc.
3.1. Running `make' in libs/
----------------------------
First, for each subdirectory libs/Lib/ not yet configured, this runs
`configure' and if required `make all' in that directory. Then this
recurses into all required subdirectories for the selected Make target:
`default' or `all' to (re-)build, `check' to run tests, `install' etc.
3.2. Running `make' in utils/ and texk/
---------------------------------------
Quite similarly, for each subdirectory utils/Util/ and texk/Prog/ not yet
configured, this first runs `configure' and if required `make all' in that
directory. Subsequently, this recurses into all required subdirectories to
(re-)build, run tests, install, etc.
3.3 Parallel builds
-------------------
The TL build system allows for parallel builds ('make -j n' with n>1),
carefully formulating Make rules when a tool (such as 'tangle' or 'convert')
creates several output files. This can considerably speed up a TL build on
multi core systems. I usually use 'make -j 4 -l 8.0' or even 'make -j' with
up to 50 compilations in parallel.
3.4 Using a Configure Cache File
--------------------------------
Further speed up of a TL build can be achieved by using a configure cache
file, e.g., running 'configure -C' at the top level.
3.5 Comments
------------
3.5.1 Comment 1
---------------
After successfully running 'make' from the top-level, as second 'make'
has nothing to rebuild.
When configure scripts or source files have been modified, a second 'make'
will rebuild only as required.
3.5.2 Comment 2
---------------
If running 'make' from the top-level fails in a subdirectory libs/*/,
utils/*/, or /texk/*/ you can remove that directory from the build tree,
fix the problem, and once again run 'make' from the top-level.
3.5.3 Comment 3
---------------
The TL build system successfully runs 'make dist' and 'make distcheck'
(at least on my {i686,x86_64}-linux-gnu systems), producing tarballs
tex-live-20YY-MM-DD.tar.{gz,xz} from which everything can be (re-)built;
please keep it that way!
3.5.4 Comment 4
---------------
The process described above configures all directories, even for libraries
and programs not to be built. This is necessary for Make targets such as
`dist' or `distcheck' that have to recurse into all subdirectories, whereas
the normal targets `all', `check', or `install' only recurse into the
required subdirectories.
As a side effect, this allows building all programs `on demand'. If, e.g.,
building in utils/Util/ or texk/Prog/ has been disabled, the Makefile in
that directory still contains all build rules. Thus running 'make' and
'make install' in that directory will build and install everything.
Similarly, when, e.g., building e-TeX has been disabled (as by default), you
can run 'make etex' (or 'make etex.exe') in the subdirectory texk/web2c/ to
build e-TeX (although there is no simple way to have e-TeX installed).
Consider the extreme case of running configure with '--disable-all-pkgs',
i.e., no programs and consequently no libraries are to be built. Running
'make' will then configure all library and program directories but build
nothing; similarly 'make install' will install nothing. Nevertheless next
running, e.g., 'make tex' in the subdirectory texk/web2c/ will build first
the Kpathsea library, then tangle, and finally tex.
|