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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
Copyright (C) 2009 Peter Breitenlohner <tex-live@tug.org>
You may freely use, modify and/or distribute this file.
Layout of the TeX Live (TL) build system
========================================
The TL 2009 build system has been completely restructured, using Autoconf,
Automake, and Libtool. The main purpose was to configure and build each
library before configuring any module (program or other library) 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 an
installed (system) version of that library.
This should simplify upgrading of modules maintained independently and/or
integrating new modules into the TL build system.
1. Layout of directories
========================
1.1. Overall layout
-------------------
texk/kpathsea/* the Kpathsea library
libs/*/* various other libraries
texk/*/* programs (mostly using Kpathsea)
utils/*/* utility programs (not using Kpathsea)
texk/am/* Makefile.am fragments
texk/web2c/am/* for the Kpathsea library
texk/web2c/*/am/* and the Web2C programs
libs/Lib/* library Lib (zlib, libpng, t1lib, etc.)
texk/Prog/* program package Prog (web2c, afm2pl, bibtex8, etc.)
utils/Util/* utility program package Util (dialog, pdfopen, ps2eps, etc.)
libs/dummy/* dummy modules
texk/dummy/* used to configure
utils/dummy/* the real modules
ac/* various configure.ac fragments (configure options)
*/ac/* for the whole TL tree
*/*/ac/* or for a particular component
build-aux/* auxiliary build scripts (config.guess etc.)
m4/kpse-pkgs.m4 Autoconf macros defining the lists of Lib, Prog, and Util
modules and handling loops over these lists
m4/* other Autoconf macros
1.2. A 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.3/* (almost) unmodified source tree
libs/zlib/Makefile.am proxy Makefile.am
libs/zlib/configure.ac and configure.ac
1.3. A 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 texk/kpathsea/, libs/, libs/dummy/, utils/, utils/dummy/,
texk/, and texk/dummy/. This will determine the programs (utils/Util/ and
texk/Prog) to be built and libraries from the TL tree (texk/kpathsea/ and
libs/Lib) required by these programs.
3. Running `make'
=================
Running 'make' in the top-level directory will recurse into the directories
texk/kpathsea/, libs/, utils/, and texk/.
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'; please report any
failures.
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. This should work after
some initial problem have been fixed; please report any failures.
3.5 Comments
------------
3.5.1 Comment 1
---------------
After successfully running 'make' from the top-level, as second 'make'
should not have to rebuild anything.
When configure scripts have been modified, it may take several iterations of
'make' (only in in tekx/web2c/) until everything has stabilized. This is a
problem that still needs investigation, but I believe that after the first
iteration everything is up to date, except for some bad timestamps.
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 build system allows to successfully run 'make dist' and 'make distcheck'
(at least on my {i686,x86_64}-linux-gnu systems), producing tarballs
tex-live-2009-MM-DD.tar.{bz2,gz} 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
normal targets such as `all', `check', or `install' only recurse into the
required subdirectories.
As a side effect, if building in utils/Util/ or texk/Prog/ has been
disabled, the Makefile in that directory still contains all the rules to
build everything. Thus running 'make' and 'make install' in that
subdirectory will build and install everything, unless some configure tests
have failed because required libraries from the TL tree where missing when
that subdirectory has been configured.
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).
4. Extending the TL build system
================================
4.1 Adding a new program directory
----------------------------------
To add a new program directory utils/Util/ (not using Kpathsea) or
texk/Prog/ (possibly using Kpathsea) you must add the directory Util to the
M4 list kpse_utils_pkgs or Prog to the M4 list kpse_texk_pkgs defined in
m4/kpse-pkgs.m4. In addition you must create a configure.ac fragment
utils/Util/ac/witheanble.ac or texk/Prog/ac/witheanble.ac defining any
required libraries from the TL tree and whether this new program is to be
built by default (in the absence of the corresponding '--enable-Util/Prog'
or '--disable-Util/Prog' configure options). If a program in texk/Prog/ or
utils/Util/ requires specific configure options to be seen at the top-level,
they should be defined in an additional configure.ac fragment
texk/Prog/ac/Prog.ac or utils/Util/ac/Util.ac (included from
texk/Prog/ac/withenable.ac or utils/Util/ac/withenable.ac and
texk/Prog/configure.ac (as, e.g., for texk/web2c/, texk/xdvik/, and
utils/xindy/).
4.2 Adding a new library directory
----------------------------------
To add a new library directory libs/Lib/ you must add the directory Lib to
the M4 list kpse_libs_pkgs defined in m4/kpse-pkgs.m4. In addition you must
create a configure.ac fragment libs/Lib/ac/witheanble.ac defining any
required libraries from the TL tree and whether an installed (system)
version of this library can be used. If that is the case, another
configure.ac fragment libs/Lib/ac/Lib.ac must define (AC_CHECK_FUNCS and
AC_CHECK_HEADERS) tests for a system version to be acceptable. Finally you
must create a file m4/kpse-Lib-flags.m4 defining the M4 macro KPSE_LIB_FLAGS
(where 'LIB' is a sanitized uppercase version of 'Lib') setting up the Make
variables LIB_INCLUDES, LIB_LIBS, and LIB_DEPEND with the required values
for CPPFLAGS, LDADD, and dependencies, as well as LIB_RULE with a
(multiline) Make rule to rebuild that library when necessary.
If a system version of the library can be used, another M4 macro
KPSE_LIB_SYSTEM_FLAGS in m4/kpse-Lib-flags.m4 must define values for
LIB_INCLUDES and LIB_LIBS, usually depending on values for the configure
options '--with-Lib-includes' and/or '--with-Lib-libdir', and you must add
the line 'AC_REQUIRE([KPSE_LIB_SYSTEM_FLAGS])' to the definition of the M4
macro KPSE_ALL_SYSTEM_FLAGS in m4/kpse-pkgs.m4.
5. Updating the TL build system
===============================
When anything in the TL build system (configure.ac and Makefile.am files
with their fragments or M4 macros in m4/) has been modified you have to
rebuild the coresponding configure, Makefile.in, and config.h or c-auto,h
files.
This is most easily done automatically using maintainer-mode. The files in
the SVN repository are all up to date, but some of them may be rebuilt in
maintainer-mode due to their relative timestamps. This will eventually be
fixed, once everything has stabilized.
Alternatively, you can run the 'reautoconf' script from the top-level.
The 'config.guess', 'config.sub', etc. files for most packages are kept
centrally in build-aux/. There are, however, independent copies in, e.g.,
libs/freetype/freetype-1.5/, libs/freetype2/freetype-2.3.8/builds/unix/, and
similar places that might need updating (not done automatically by the
'reautoconf' script).
|
