Debian Codegraph @

texmf-dist/doc/info/tlbuild.info

raw
1 This is tlbuild.info, produced by makeinfo version 7.2 from
2 tlbuild.texi.
3
4 This file documents the TeX Live build system and more.
5
6 Copyright (C) 2016-2026 Karl Berry.
7 Copyright (C) 2013-2015 Karl Berry & Peter Breitenlohner.
8
9 Permission is granted to make and distribute verbatim copies of this
10 manual provided the copyright notice and this permission notice are
11 preserved on all copies.
12
13 Permission is granted to copy and distribute modified versions of
14 this manual under the conditions for verbatim copying, provided that the
15 entire resulting derived work is distributed under the terms of a
16 permission notice identical to this one.
17
18 Permission is granted to copy and distribute translations of this
19 manual into another language, under the above conditions for modified
20 versions, except that this permission notice may be stated in a
21 translation approved by the TeX Users Group.
22 INFO-DIR-SECTION TeX
23 START-INFO-DIR-ENTRY
24 * TLbuild: (tlbuild). TeX Live configuration and development.
25 END-INFO-DIR-ENTRY
26
27 INFO-DIR-SECTION Individual utilities
28 START-INFO-DIR-ENTRY
29 * install-tl:: Installing TeX Live.
30 * tlmgr:: Managing TeX Live.
31 END-INFO-DIR-ENTRY
32
33 
34 File: tlbuild.info, Node: Top, Next: Introduction, Up: (dir)
35
36 Building TeX Live (2026)
37 ************************
38
39 For an overview of this manual, *note Introduction::.
40
41 * Menu:
42
43 * Introduction:: About this manual.
44 * Overview of build system:: The TeX Live build system.
45 * Prerequisites:: Requirements for building TeX Live.
46 * Building:: The overall build process.
47 * Installing:: How and where installation happens (or not).
48 * Layout and infrastructure:: Autoconf macros, etc., in detail.
49 * Configure options:: List of all configure options.
50 * Coding conventions:: Conventions to follow.
51 * Continuous integration:: Automated build testing.
52 * install-tl:: The TeX Live installer.
53 * tlmgr:: The native TeX Live package manager.
54 * Index:: General index.
55
56 
57 File: tlbuild.info, Node: Introduction, Next: Overview of build system, Prev: Top, Up: Top
58
59 1 Introduction
60 **************
61
62 This manual (dated January 2026) corresponds to the TeX Live 2026
63 release.
64
65 This manual is aimed at system installers and programmers, and
66 focuses on how to configure, build, and develop the TeX Live (TL)
67 sources. It is also available as plain text files in the source tree:
68 'source/README.*'.
69
70 The main 'source/README' file in the TL source tree provides
71 maximally-terse information for doing a build, and portability
72 information for different systems, along with
73 'source/doc/README.solaris'.
74
75 For information on acquiring the TL sources, see
76 <https://tug.org/texlive/svn>. The canonical source repository uses
77 Subversion, and we have no plans to change this.
78
79 This manual does not duplicate the information found in other TL
80 documentation resources, such as:
81
82 * The TeX Live web pages: <https://tug.org/texlive>.
83
84 * The web page describing how to build the binaries which are
85 distributed with TeX Live: <https://tug.org/texlive/build.html>.
86
87 * The TeX Live user manual: <https://tug.org/texlive/doc.html>, or
88 run 'texdoc texlive'.
89
90 * Other TeX-related Texinfo manuals (*note (web2c)Top::, *note
91 (kpathsea)Top::, etc.): <https://tug.org/texinfohtml/>, or check
92 the 'TeX' category in the GNU Info system.
93
94 * Package documentation:
95 <https://tug.org/texlive/Contents/live/doc.html>, or the 'doc.html'
96 file at the top level of the installed TL.
97
98 As an exception, the full documentation for 'install-tl' and 'tlmgr'
99 is included here as appendices, simply because it is easy to do so. The
100 same text is available online (linked from
101 <https://tug.org/texlive/doc.html>, or by invoking the program with
102 '--help' (or look at the end of the source).
103
104 
105 File: tlbuild.info, Node: Overview of build system, Next: Prerequisites, Prev: Introduction, Up: Top
106
107 2 Overview of build system
108 **************************
109
110 The TeX Live build system was redesigned in 2009 to consistently use
111 Autoconf, Automake, and Libtool. Thus, running
112 'configure && make && make check && make install'
113 or the essentially-equivalent top-level 'Build' script suffices to build
114 and install the TL programs. The 'make check' clause performs various
115 tests of the generated programs--not strictly required but strongly
116 recommended. Running 'configure --help' will display a comprehensive
117 list of all 'configure' options.
118
119 The main components of the TL build system are:
120
121 'libs/LIB'
122 Generic libraries.
123
124 'texk/LIB'
125 TeX-specific libraries in subdirectories, notably LIB='kpathsea'.
126 (The other one is 'texk/ptexenc'.)
127
128 'texk/PROG'
129 TeX-specific programs (that use Kpathsea).
130
131 'utils/PROG'
132 Other programs (that don't use Kpathsea).
133
134 The primary design goal of the build system is modularity. Each
135 program and library module (or package) specifies its own requirements
136 and properties, such as required libraries, whether an installed
137 (system) version of a library can be used, 'configure' options to be
138 seen at the top level, and more. An explicit list of all available
139 modules is kept in a single central place: 'm4/kpse-pkgs.m4'.
140
141 A second, related goal is to configure and build each library before
142 configuring any other (program or library) module which uses that
143 library. This allows checking for properties and features of a library
144 built as part of the TL tree in much the same way as for a system
145 version of that library.
146
147 All generic libraries and several programs are maintained
148 independently. The corresponding modules use (most of) the distributed
149 source tree and document any modifications of that source.
150
151 All this is for the sake of simplifying both upgrading of modules and
152 integrating new modules into the TL build system. (Despite all efforts,
153 neither task is easy.)
154
155 
156 File: tlbuild.info, Node: Prerequisites, Next: Building, Prev: Overview of build system, Up: Top
157
158 3 Prerequisites
159 ***************
160
161 Overall, building the TeX Live programs, when using all libraries from
162 the TL source tree, requires C and C++11 compilers, GNU 'make', and
163 Python.
164
165 * If 'make' from your 'PATH' is not GNU 'make', you can set the
166 'MAKE' environment variable to whatever is necessary.
167
168 GNU 'make' is required only because of third-party libraries,
169 notably FreeType. Automake/Autoconf output in general, and the
170 TL-maintained directories, work with any reasonable 'make'.(1)
171
172 * A C++11 compiler is similarly required because of the third-party
173 libraries ICU and HarfBuzz (at least); the program 'dvisvgm' also
174 requires C++11. It is possible to build what remains with older
175 compilers, but you have to remove the C++11-dependent sources.
176 *Note Build one package::.
177
178 * Python is required by ICU tests. (If you know how to disable these
179 tests and thus eliminate the requirement, please write.)
180
181 A few programs in the tree have additional requirements:
182
183 'web2c'
184 requires 'perl' for some tests run by 'make check'. Incidentally,
185 the TeX Live installer ('install-tl') and manager ('tlmgr') are
186 also written in Perl, but this does not matter for compiling the
187 sources.
188
189 'xdvik'
190 'xpdfopen'
191 require X11 headers and libraries, typically in devel(opment)
192 packages that are not installed by default.
193
194 'xetex'
195 requires 'fontconfig' (again both headers and library), or, for
196 MacOS only, the 'ApplicationServices' and 'Cocoa' frameworks.
197
198 'xindy'
199 requires GNU 'clisp', 'libsigsegv', and 'libiconv'; additionally,
200 to build the rules and/or documentation: 'perl', 'latex',
201 'pdflatex'.
202
203 Lacking the required tools, building these programs must avoided, e.g.,
204 'configure --without-x --disable-xetex --disable-xindy'
205
206 Modifying source files induces more requirements, as one might
207 expect:
208
209 * Modification of any '.y' or '.l' source files requires 'bison' or
210 'flex' to update the corresponding C sources.
211
212 * Modification of the sources for '.info' files requires 'makeinfo'.
213
214 * Modification of any part of the build system (M4 macros,
215 'configure.ac', 'Makefile.am', or their fragments) requires GNU M4,
216 GNU Autoconf, GNU Automake, and GNU Libtool to update the generated
217 files. Furthermore, to reliably reproduce the build files, the
218 latest original GNU releases of these tools must be used, not any
219 distro packaging of them. *Note Build system tools::, for more
220 discussion.
221
222 If you haven't modified any source files, and infrastructure tools
223 such as 'autoconf' or 'makeinfo' are still being run, check your
224 timestamps--notably, 'use-commit-times' must be set to 'yes' in your
225 Subversion configuration (*note Build system tools::). No
226 infrastructure tools are needed to do a normal build (barring bugs).
227
228 ---------- Footnotes ----------
229
230 (1) There is one exception in TL: the 'tangle-sh' and related rules
231 use '$@' to mean the target name, a feature not present in all 'make's.
232 This could be alleviated by laborious editing, but since there's no way
233 to avoid GNU 'make' for builds of the entire tree, it does not seem
234 worth the trouble.
235
236 
237 File: tlbuild.info, Node: Building, Next: Installing, Prev: Prerequisites, Up: Top
238
239 4 Building
240 **********
241
242 The top-level 'Build' script is intended to simplify building the
243 binaries distributed with TeX Live itself--we call this the "native" TL
244 build. It runs 'configure && make world', which builds everything in a
245 subdirectory of the main source tree (default 'Work/'), installs
246 everything in another subdirectory (default 'inst/'), and finally runs
247 'make check'. The exact directory and command names can be specified
248 via environment variables and a few leading options. All remaining
249 arguments (assignments or options) are passed to the 'configure' script.
250 Please take a look at the './Build' source file for more information; it
251 is a straightforward shell script.
252
253 An alternative, and the one we will mainly discuss here, is to run
254 'configure' and 'make' in a suitable empty subdirectory. Building in
255 the source directory itself is not supported (sorry).
256
257 * Menu:
258
259 * Build iteration:: What 'configure' and 'make' do in TL.
260 * Build in parallel:: Simultaneous 'make' processes.
261 * Build distribution:: (Not) making a distribution tarball.
262 * Build one package:: Example of working on just one program.
263 * Build one engine:: Example of building just one TeX engine.
264 * Cross compilation:: Building on host X for target Y.
265
266 
267 File: tlbuild.info, Node: Build iteration, Next: Build in parallel, Up: Building
268
269 4.1 Build iteration
270 ===================
271
272 Running the top-level 'configure' script configures the top level and
273 the subdirectories 'libs', 'utils', and 'texk'. Running 'make' at the
274 top level first iterates over the TeX-specific libraries, and then runs
275 'make' in 'libs', 'utils', and 'texk' to iterate over the generic
276 libraries, utility programs, and TeX-specific programs, respectively.
277 These iterations consist of two steps:
278
279 1. For each library or program module not yet configured, run
280 'configure', adding the configure option '--disable-build' if the
281 module need not be built, otherwise running 'make all'.
282
283 2. For each library or program module that must be built, run 'make'
284 for the selected target(s): 'default' or 'all' to (re-)build,
285 'check' to run tests, 'install', etc.
286
287 Running the top-level 'make' a second time iterates again over all
288 the library and program modules, and finds (should find) nothing to be
289 done.
290
291 
292 File: tlbuild.info, Node: Build in parallel, Next: Build distribution, Prev: Build iteration, Up: Building
293
294 4.2 Build in parallel
295 =====================
296
297 The TL build system carefully formulates dependencies as well as 'make'
298 rules when a tool (such as 'tangle', 'ctangle', and 'convert') creates
299 several output files. This allows for parallel builds ('make -j N' with
300 N>1 or even 'make -j') that can considerably speed up the TL build.
301
302 If you're using TL's 'Build' script, you can enable '-j' with the
303 environment variable 'TL_MAKE_FLAGS', as in: 'env
304 TL_MAKE_FLAGS=-j`nproc` ./Build'.
305
306 Independently, a noticeable speed-up can also be gained by using a
307 configure cache file, i.e., specifying the 'configure' option '-C'
308 (recommended).
309
310 
311 File: tlbuild.info, Node: Build distribution, Next: Build one package, Prev: Build in parallel, Up: Building
312
313 4.3 Build distribution
314 ======================
315
316 Running 'make dist' or related targets at the top level outputs an error
317 message and fails. We no longer try to keep 'make dist' working,
318 although it could be restored if there is some use for it.
319
320 The 'dist' target used to create a tarball
321 'tex-live-YYYY-MM-DD.tar.xz' from the TL source tree, and 'distcheck'
322 also verifies that this tarball suffices to build and install all of TL.
323
324 However, the result was not a complete or even usable TeX system,
325 since all the support files are lacking. We do not actually distribute
326 any such tarball, and have no plans to do so.
327
328 *Note Installing::, for more information on what to do with the
329 results of a build.
330
331 
332 File: tlbuild.info, Node: Build one package, Next: Build one engine, Prev: Build distribution, Up: Building
333
334 4.4 Build one package
335 =====================
336
337 To build one package, the basic idea is to use the 'configure' option
338 '--disable-all-pkgs' (*note --disable-all-pkgs::). Then all program and
339 library modules are configured but none are made. However, the
340 'Makefile's still contain all build rules and dependencies and can be
341 invoked to build an individual program or library, first building any
342 required libraries.
343
344 Here is an example from start to finish for working on 'dvipdfm-x'.
345 Unfortunately, this does not suffice for building the TeX engines; see
346 the next section.
347
348 mkdir mydir && cd mydir # new working directory
349
350 # Get sources (<https://tug.org/texlive/svn>), e.g.:
351 rsync -a --delete --exclude=.svn --exclude=Work \
352 tug.org::tldevsrc/Build/source/ .
353
354 # Create build directory:
355 mkdir Work && cd Work
356
357 # Do the configure:
358 ../configure --disable-all-pkgs --enable-dvipdfm-x \
359 -C CFLAGS=-g CXXFLAGS=-g >&outc || echo fail
360
361 # Do the make:
362 make >&outm || echo fail
363
364 # Run the tests:
365 cd texk/dvipdfm-x
366 make check
367
368 # Run the new binary in the build tree, finding support files
369 # in a separate tree for a TeX Live release YYYY
370 # (Bourne shell syntax):
371 TEXMFROOT=/usr/local/texlive/YYYY \
372 TEXMFCNF=$TEXMFROOT/texmf-dist/web2c \
373 ./xdvipdfmx ...
374
375 Then you can modify source files in 'mydir/texk/dvipdfm-x' and rerun
376 'make' in 'mydir/Work/texk/dvipdfm-x' to rebuild; that build directory
377 is where the binary ends up and where you can run a debugger, etc.
378
379 The second line of the 'configure' invocation shows examples of extra
380 things you likely want to specify if you intend to hack the sources (and
381 not just build binaries): the '-C' speeds 'configure' by enabling a
382 cache file, and the 'CFLAGS' and 'CXXFLAGS' settings eliminate compiler
383 optimization for debugging purposes.
384
385 Of course, you need to actually look at the output and check that
386 things are working. There are many 'configure' options you can tweak as
387 desired; check the output from 'configure --help'. It is also a good
388 idea to run 'make check' after making any changes, to ensure that
389 whatever tests have been written still pass.
390
391 Reducing source download size
392 .............................
393
394 The above retrieves the entire TL source tree (several hundred
395 megabytes). It is natural to ask if this is really necessary. Strictly
396 speaking, the answer is no, but it is vastly more convenient to do so.
397 If you cut down the source tree, you must also give additional
398 'configure' flags to individually disable using system versions of
399 libraries, or the intricacies of the dependencies (such as 'teckit'
400 requiring 'zlib') will have undesired side effects. For an example of
401 this approach, see the 'build-pdftex.sh' script in the 'pdftex'
402 development source (details at <http://pdftex.org>), which is indeed
403 such a cut-down TL source tree.
404
405 GCC used by default
406 ...................
407
408 By default, the 'gcc' compilers will be used if present; otherwise,
409 individual packages may use something different. You can explicitly
410 specify the compilers to be used with the environment variables 'CC',
411 'CXX', and 'OBJCXX'.
412
413 Removing C+11 dependency
414 ........................
415
416 Some libraries and programs require C++11; one such is XeTeX. If you
417 want to build with an older compiler lacking such support, you need to
418 (re)move those source directories; unfortunately, specifying '--disable'
419 for them does not suffice. It's also necessary to specify
420 '--disable-xetex' explicitly. Specifically, before running 'configure
421 --disable-xetex ...':
422
423 rm -rf libs/icu libs/graphite2 texk/dvisvgm texk/web2c/xetexdir
424
425 Also, even with '--disable-all-pkgs', dependencies are (currently)
426 checked. One notable case: if a (non-MacOS) system does not have
427 'fontconfig', XeTeX cannot be built (*note Prerequisites::), and
428 'configure' will terminate even with '--disable-xetex'. To proceed
429 without such dependencies, specify '--enable-missing' also.
430
431 As of 2022, HarfBuzz also requires C++11. Therefore even more would
432 have to be disabled and removed, notably including 'luahbtex', the
433 standard engine used for LuaLaTeX. Removing that would not be
434 acceptable for builds intended for distribution; but perhaps for testing
435 the above information could still be useful.
436
437 In general, the TL 'configure' will run in all directories.
438 Therefore a general workaround for build problems is to remove failing
439 directories from the tree, and also specify the relevant '--disable-...'
440 option(s).
441
442 Patches to improve all this would be most welcome.
443
444 
445 File: tlbuild.info, Node: Build one engine, Next: Cross compilation, Prev: Build one package, Up: Building
446
447 4.5 Build one engine
448 ====================
449
450 Unfortunately, there is one common case where the steps in the preceding
451 section to build one package (*note Build one package::) do not suffice:
452 wanting to build one, or a subset, of the TeX engines (or other Web2c
453 programs).
454
455 The simplest way to do this is to disable everything and then
456 explicitly specify what to make. For example, to build only the
457 original TeX:
458
459 cd Work # top build directory
460 ../configure --without-x --disable-shared --disable-all-pkgs \
461 --enable-tex --disable-synctex --disable-xetex \
462 --enable-missing -C CFLAGS=-g CXXFLAGS=-g
463 make
464 cd texk/web2c # cd engine build directory
465 make tex # must specify target
466
467 The first 'make' run will configure everything, and even build the
468 libraries, even though the packages are disabled.
469
470 The source tree can be cut down to just what is needed for the given
471 engine (the separate pdfTeX and LuaTeX source repositories do this, for
472 example), but see caveats in previous section. When the
473 '--disable-xetex' and '--enable-missing' options are needed is also
474 explained in the previous section.
475
476 If you want to debug an X-related program or shared library setup, or
477 other variants, change the 'configure' options accordingly. Either
478 '../Build' or '../configure' can be run.
479
480 Then it is necessary to again specify the target engine ('tex', in
481 the above) in the 'make'.
482
483 All these complications are rather unfortunate. Patches are welcome.
484
485 Testing one engine
486 ..................
487
488 To run only the tests for a given engine, say 'hitex':
489
490 make -C $ww check SUBDIRS=. TESTS='$(hitex_tests)'
491
492 where '$ww' is the web2c build directory, that is,
493 'ww=/.../Build/source/Work/texk/web2c'.
494
495 It's also possible to run individual tests the same way, using the
496 test name exactly as specified in the '.am' file:
497
498 make -C $ww check SUBDIRS=. TESTS=hitexdir/tests/hello.test
499
500 Without the 'SUBDIRS=.', errors like this will show up, since 'make'
501 will descend into every directory.
502
503 fatal: making test-suite.log: failed to create hitexdir/tests/hello.test
504
505 If you get tired of looking at the 'Entering'/'Leaving directory'
506 lines, you can add the (GNU) make option '--no-print-dir'.
507
508 You may find it useful to put lengthy incantations like this into a
509 trivial shell script with a short name (say, 'hitch'). Then you just
510 run 'hitch' and edit the file when necessary to change the options.
511
512 
513 File: tlbuild.info, Node: Cross compilation, Prev: Build one engine, Up: Building
514
515 4.6 Cross compilation
516 =====================
517
518 In a cross compilation a "build" system is used to create binaries to be
519 executed on a "host" system with different hardware and/or operating
520 system.
521
522 In simple cases, the build system can execute binaries for the host
523 system. This typically occurs for bi-arch systems where, e.g.,
524 'i386-linux' binaries can run on 'x86_64-linux' systems and 'win32'
525 binaries can run on 'win64' systems. Although sometimes called "native
526 cross", technically this is not cross compilation at all. In most such
527 cases it suffices to specify suitable compiler flags. It might be
528 useful to add the configure option '--build=HOST' to get the correct
529 canonical host name, but note that this should _not_ be '--host=HOST'
530 (*note (autoconf)Hosts and Cross-Compilation::).
531
532 In order to build, e.g., 32-bit binaries with 'clang' on a 64-bit
533 MacOS system one could use:
534
535 TL_BUILD_ENV="CC='clang -arch i386' \
536 CXX='clang++ -arch i386' \
537 OBJCXX='clang++ -arch i386'" \
538 ./Build --build=i386-apple-darwin
539
540 * Menu:
541
542 * Cross configuring:: Configuring for cross compilation.
543 * Cross problems:: Cross compilation problems.
544
545 
546 File: tlbuild.info, Node: Cross configuring, Next: Cross problems, Up: Cross compilation
547
548 4.6.1 Cross configuring
549 -----------------------
550
551 In a standard cross compilation, binaries for the host system cannot
552 execute on the build system and it is necessary to specify the configure
553 options '--host=HOST' and '--build=BUILD' with two different values.
554
555 Building binaries requires suitable "cross" tools, e.g., compiler,
556 linker, and archiver, and perhaps a "cross" version of 'pkg-config' and
557 similar to locate host system libraries. Autoconf expects that these
558 cross tools are given by their usual variables or found under their
559 usual name prefixed with 'HOST-'. Here a list of such tools and
560 corresponding variables:
561
562 ar AR
563 freetype-config FT2_CONFIG
564 g++ CXX
565 gcc CC
566 icu-config ICU_CONFIG
567 objdump OBJDUMP
568 pkg-config PKG_CONFIG
569 ranlib RANLIB
570 strip STRIP
571
572 In order to, e.g., build 'mingw32' binaries on 'x86_64-linux' with a
573 cross compiler found as 'i386-pc-mingw32-gcc' one would specify
574
575 --host=i386-pc-mingw32 --build=x86_64-linux-gnu
576
577 or perhaps
578
579 --host=mingw32 --build=x86_64-linux CC=i386-pc-mingw32-gcc
580
581 but this latter, especially, might require adding 'CXX' and others.
582
583 Configure arguments such as 'CFLAGS=...' refer to the cross compiler.
584 If necessary, you can specify compilers and flags for the few auxiliary
585 C and C++ programs required for the build process as configure arguments
586
587 BUILDCC=...
588 BUILDCPPFLAGS=...
589 BUILDCFLAGS=...
590 BUILDCXX=...
591 BUILDCXXFLAGS=...
592 BUILDLDFLAGS=...
593
594 
595 File: tlbuild.info, Node: Cross problems, Prev: Cross configuring, Up: Cross compilation
596
597 4.6.2 Cross problems
598 --------------------
599
600 The fact that binaries for the host system cannot be executed on the
601 build system causes some problems.
602
603 One problem is that configure tests using 'AC_RUN_IFELSE' can compile
604 and link the test program but cannot execute it. Such tests should be
605 avoided if possible and otherwise must supply a pessimistic test result.
606
607 Another problem arises if the build process must execute some
608 (auxiliary or installable) programs. Auxiliary programs can be placed
609 into a subdirectory that is configured natively as is done for
610 'texk/web2c/web2c', 'texk/dvipsk/squeeze', and 'texk/xdvik/squeeze'.
611 The module 'libs/freetype2' uses the value of 'CC_BUILD', 'BUILD-gcc',
612 'gcc', or 'cc' as the compiler for the auxiliary program.
613
614 The situation for installable programs needed by the build process is
615 somewhat different. A rather expensive possibility, chosen for the ICU
616 libraries in module 'libs/icu', is to first compile natively for the
617 build system and in a second step to use these (uninstalled) programs
618 during the cross compilation.
619
620 This approach would also be possible for the tools such as 'tangle'
621 used in the module 'texk/web2c' to build the WEB programs, but that
622 would require first building a native 'kpathsea' library. To avoid this
623 complication, cross compilation of programs written in (C)WEB requires
624 sufficiently recent installed versions of 'tangle', 'ctangle',
625 'otangle', and 'tie'.
626
627 Building 'xindy' requires running the host system 'clisp' binary,
628 thus cross compilation is painful, but possible.
629
630 
631 File: tlbuild.info, Node: Installing, Next: Layout and infrastructure, Prev: Building, Up: Top
632
633 5 Installing
634 ************
635
636 This section discusses the results of 'make install' in the source tree.
637
638 The main consideration is that 'make install' is nothing like enough
639 to make a usable TeX installation. It creates the compiled binaries,
640 but (thousands of) support files are also needed; just as a first
641 example, 'plain.tex' is not installed. All the support files are
642 maintained completely independently and are not present in the TL
643 'Build/source' tree of sources to be compiled.
644
645 Thus, perhaps the simplest way to get a running TeX system after
646 building new binaries from these sources is to do a normal installation
647 of TeX Live, and then use the new binaries as a so-called "custom"
648 platform (<https://tug.org/texlive/custom-bin.html>).
649
650 Alternatively, the best general basis for dealing with them, for
651 example if you're trying to figure out how to support TeX in a general
652 distro, is the TeX Live (plain text) database in
653 'Master/tlpkg/texlive.tlpdb', and/or the TeX Live installer,
654 'install-tl'.
655
656 More information is under 'Master/tlpkg' and at
657 <https://tug.org/texlive/distro.html> and
658 <https://tug.org/texlive/build.html#deploy>.
659
660 * Menu:
661
662 * Installation directories:: The prefix, 'bindir', etc., directories.
663 * Linked scripts:: Scripts not maintained in the sources.
664 * Distro builds:: Configuring and building for OS distributions.
665
666 
667 File: tlbuild.info, Node: Installation directories, Next: Linked scripts, Up: Installing
668
669 5.1 Installation directories
670 ============================
671
672 Running 'make install' (or 'make install-strip') installs executables in
673 'BINDIR', libraries in 'LIBDIR', headers in 'INCLUDEDIR', general data
674 (including "linked scripts", *note Linked scripts::) in
675 'DATAROOTDIR/texmf-dist', man pages in 'MANDIR', and Info files in
676 'INFODIR'.
677
678 The values of these directories are determined by 'configure' and can
679 be specified explicitly as options such as '--prefix=PREFIX' or
680 '--bindir=BINDIR'; otherwise, they are given by their usual Autoconf
681 defaults:
682
683 PREFIX /usr/local
684 EXEC_PREFIX PREFIX
685 BINDIR EXEC_PREFIX/bin
686 LIBDIR EXEC_PREFIX/lib
687 INCLUDEDIR PREFIX/include
688 DATAROOTDIR PREFIX/share
689 MANDIR DATAROOTDIR/man
690 INFODIR DATAROOTDIR/info
691
692 except possibly modified as follows:
693
694 * If the option '--enable-multiplatform' is given, '/PLATFORM' (i.e.,
695 the canonical platform name) is appended to 'BINDIR' and 'LIBDIR'.
696 This is implied for a native TL build.
697
698 * In a native TL build, 'DATAROOTDIR' is set to 'PREFIX', 'INFODIR'
699 is set to 'PREFIX/texmf-dist/doc/info', and 'MANDIR' to
700 'PREFIX/texmf-dist/doc/man', corresponding to the directories used
701 in the TL distribution.
702
703 The top-level 'configure' script displays all these installation paths.
704
705 For the native TL build, the 'Build' script leaves the binaries in
706 './inst/bin/STD-SYSTEM-TRIPLET'. The new binaries are not directly
707 usable from that location; they need to be copied to
708 'Master/bin/TL-PLATFORM'. The other files and directories that end up
709 in './inst/' are ignored.
710
711 
712 File: tlbuild.info, Node: Linked scripts, Next: Distro builds, Prev: Installation directories, Up: Installing
713
714 5.2 Linked scripts
715 ==================
716
717 Quite a few of the executables in TeX Live are architecture-independent
718 shell, Perl, or other interpreted scripts, rather than compiled
719 binaries. A few are maintained as part of the TL source tree, but most
720 are maintained independently in their own packages, with copies under
721 'texk/texlive/linked_scripts'.
722
723 These so-called "linked scripts" are installed under
724 'DATAROOTDIR/texmf-dist/scripts'; for Unix-like systems a symbolic link
725 is made in 'BINDIR'. For example, a symlink points from
726 'BINDIR/fmtutil' to 'DATAROOTDIR/texmf-dist/scripts/texlive/fmtutil.pl'.
727 The symlink is relative, so the installation root can be anywhere.
728
729 For Windows, we cannot portably use symlinks, so a standard wrapper
730 binary (copied to, e.g., 'BINDIR/fmtutil.exe') serves the same purpose
731 (the source for the wrapper is in 'texk/texlive/windows_wrapper').
732
733 One reason for all this is to avoid having many copies of the same
734 script; a more important reason is that it guarantees the scripts will
735 stay in sync across the different supported operating systems.
736
737 Most important of all, we want the 'BINDIR' resulting from 'make
738 install' in the TL source tree to be as close as possible to what's in
739 thej TL distribution. At present, there are a few
740 exceptions--Asymptote, Biber, Xindy--and each one creates considerable
741 extra work. We don't want to add more. (See
742 <https://tug.org/texlive/build.html> for information about building
743 those exceptions, as well as the 'xz' and 'wget' programs that are used
744 in the TL infrastructure.)
745
746 As part of the 'make install' in the 'linked_scripts' directory, a
747 file 'scripts-targets.lst' is created to record all the links that are
748 created this way, so that distros and others can reproduce them. The
749 file has one line per link. The first word is the target of the link
750 (e.g., 'texmf-dist/scripts/texlive/fmtutil.pl'), and the second word is
751 the name of the link to be placed in the bindir (e.g., 'fmtutil').
752 Determining the relative link target (how many '../'s) is left to the
753 users of this file, since it varies among distributions. It can be
754 assumed there is no whitespace in these filenames.
755
756 A few links are within bindir; in that case, the first word of the
757 line is just a base name, e.g., the file 'fmtutil mktexfmt' means that
758 doing the equivalent of 'ln -s fmtutil mktexfmt' in the bindir.
759
760 Be aware that although extensions are usually stripped (as with
761 'fmtutil'), there are exceptions, such as 'memoize-extract.pl' and
762 'listings-ext.sh'.
763
764 The 'scripts-targets.lst' file started being created as of the
765 TeX Live 2025 release. Historically, another file 'scripts.lst' has
766 been (and still is) created, containing only the link targets, and using
767 a Bourne shell syntax.
768
769 
770 File: tlbuild.info, Node: Distro builds, Prev: Linked scripts, Up: Installing
771
772 5.3 Distro builds
773 =================
774
775 Although they use the same code base, building for the native TL
776 distribution as shipped by the TeX user groups is typically quite
777 different from a "distro" build needed by, e.g., a full GNU/Linux or BSD
778 operating system distribution.
779
780 The native TL distribution uses shared libraries only when absolutely
781 necessary ('libc', 'libm', X11 libraries, and 'libfontconfig'). In
782 contrast, a distro typically wants to use as many shared libraries as
783 possible from elsewhere on the system, including TeX-specific libraries
784 such as 'libkpathsea' (even though Kpathsea has never officially been
785 released as a shared library). In addition, the installation paths
786 will, in general, be completely different.
787
788 Here are the 'configure' options that distro builds are likely to
789 find most relevant:
790
791 '--disable-native-texlive-build'
792 This must be specified to avoid interference from the many tweaks
793 we do for the native TL build.
794
795 '--with-banner-add=/SOMEDISTRO'
796 This isn't technically required, but is strongly recommended, so
797 your build and your distro can be distinguished from others.
798
799 '--enable-shared'
800 Build shared versions of the TeX-specific libraries (uses
801 'libtool').
802
803 '--disable-static'
804 Do not build the static versions of the TeX-specific libraries.
805
806 '--with-system-LIB'
807 Look for and use a system version of the library LIB. 'configure
808 --help' will give you the list of possibilities.
809
810 '--with-LIB-includes=DIR'
811 '--with-LIB-libdir=DIR'
812 If needed, allows you to specify where the headers/code are for the
813 given library LIB.
814
815 '--prefix=/usr'
816 '--prefix=/opt/TeXLive'
817 Or whatever your convention is. The default is '/usr/local' and
818 you shouldn't install there for a distro.
819
820 '--libdir=\${exec_prefix}/lib64'
821 May be needed for 64-bit bi-architecture (GNU/Linux) systems.
822
823 You will need to take care of the support files mentioned above
824 (*note Installing::), and many other issues, such as font maps,
825 languages, and formats, independently of the build. Norbert Preining
826 has written a detailed article on adapting TL for distros:
827 <https://tug.org/TUGboat/tb34-3/tb108preining-distro.pdf>. (If the
828 article needs updating in the future, perhaps we will merge it into this
829 document.)
830
831 
832 File: tlbuild.info, Node: Layout and infrastructure, Next: Configure options, Prev: Installing, Up: Top
833
834 6 Layout and infrastructure
835 ***************************
836
837 The TeX Live source tree is the subtree rooted at 'Build/source' of the
838 complete TL distribution and contains the sources for all executables
839 distributed by TL, as well as 'configure' scripts and 'make' rules to
840 build and install them together with some of their support files.
841
842 * Menu:
843
844 * Build system tools:: Modifying infrastructure files.
845 * Top-level directories:: libs texk utils; am auxdir build-aux m4; doc extra.
846 * Autoconf macros:: TL-specific Autoconf macros.
847 * Library modules:: Handling libraries, with examples.
848 * Program modules:: Handling programs, with examples.
849 * Extending TeX Live:: Adding a new module.
850
851 
852 File: tlbuild.info, Node: Build system tools, Next: Top-level directories, Up: Layout and infrastructure
853
854 6.1 Build system tools
855 ======================
856
857 As mentioned above (*note Prerequisites::), a normal build has few
858 requirements. On the other hand, if you want to modify the TeX Live
859 infrastructure sources, such as 'configure.ac' or 'Makefile.am' files,
860 you will need to have several additional tools installed.
861
862 In general, the TL build system uses the latest released versions of
863 the GNU build tools, installed directly from the original GNU releases
864 (e.g., by building them with 'configure --prefix=/usr/local/gnu' and
865 having 'PATH' start with '/usr/local/gnu/bin'). We have found that
866 trying to use the versions of these tools packaged for distros causes
867 many extra hassles, so don't do that, tempting as it may be.
868
869 Currently the versions we use are:
870
871 autoconf (GNU Autoconf) 2.72
872 automake (GNU automake) 1.18.1
873 bison (GNU Bison) 3.8.2
874 flex 2.6.0
875 ltmain.sh (GNU libtool) 2.5.4
876 m4 (GNU M4) 1.4.21
877 makeinfo (GNU texinfo) 7.2
878
879 These versions should be used to update the generated files (e.g.,
880 'configure' or 'Makefile.in') in all or parts of the TL tree after their
881 dependencies have been changed. This can be done explicitly with the
882 top-level 'reautoconf' script or implicitly by using the configure
883 option '--enable-maintainer-mode'.
884
885 It has often turned out that the bison and flex versions are not
886 critical; however, the autotools versions are. If you don't have the
887 given versions, get them before modifying the build infrastructure.
888
889 The files in the Subversion repository (see
890 <https://tug.org/texlive/svn>) are all up to date (barring bugs). For
891 this to be reflected by their timestamps in your checkout, be sure to
892 set 'use-commit-times=yes' in '~/.subversion/config' or the equivalent.
893
894 If timestamps are wrong, you may also be able to avoid unnecessary
895 runs of 'bison', 'flex', or 'makeinfo' with 'touch' of the generated
896 ('.c', '.h', or '.info') files. With '--enable-maintainer-mode' it may
897 also be necessary to 'touch' first 'aclocal.m4', then 'configure' and
898 'config.h.in' (or 'c-auto.in'), and finally all 'Makefile.in' files.
899
900 
901 File: tlbuild.info, Node: Top-level directories, Next: Autoconf macros, Prev: Build system tools, Up: Layout and infrastructure
902
903 6.2 Top-level directories
904 =========================
905
906 Here is a brief description of the top-level directories in the TeX Live
907 source tree.
908
909 As mentioned at the beginning of *note Overview of build system::,
910 the main source directories are 'texk/' (TeX-specific programs and
911 libraries), 'utils/' (additional programs), and 'libs/' (generic
912 libraries).
913
914 In addition, the top-level directories 'am/' and 'm4/' contain
915 'Makefile.am' fragments and Autoconf macros, respectively, used in many
916 places. Specifically, the file 'm4/kpse-pkgs.m4' contains lists of all
917 program and library modules; missing modules are silently ignored.
918 (This helps in creating cut-down source trees.)
919
920 Each module contributes fragments (in separate files) defining its
921 capabilities and requirements to the 'configure.ac' scripts at the
922 top-level and in the subdirectories 'libs', 'utils', and 'texk'. The
923 fragments from program modules supply 'configure' options to disable or
924 enable building them; those from library modules specify if an installed
925 (system) version of that library can be used. This ultimately
926 determines which modules need to be built--although all modules must be
927 configured for the benefit of 'make' targets such as 'dist' or
928 'distcheck'.
929
930 The top-level 'build-aux/' directory contains the common files
931 'compile', 'config.guess', 'config.sub', 'depcomp', etc. used by most
932 packages. These are taken from the GNU Gnulib sources
933 (<https://www.gnu.org/software/gnulib>), which in turn synchronizes with
934 any ultimate upstream repository. There are independent copies of some
935 of these in a few other places, e.g.,
936 'libs/freetype2/freetype-*/builds/unix/'. The 'reautoconf' script does
937 not touch those, but a TL cron job keeps them in sync (nightly).
938
939 When the top-level './Build' script is used to build TL, two more two
940 more top-level directories appear: 'Work/' for the build tree, and
941 'inst/' for the install tree (from 'make install'). These names (and
942 everything else about 'Build''s operation) can be changed by setting
943 environment variables before running it; see the script source.
944
945 
946 File: tlbuild.info, Node: Autoconf macros, Next: Library modules, Prev: Top-level directories, Up: Layout and infrastructure
947
948 6.3 Autoconf macros
949 ===================
950
951 Here we describe a few of the Autoconf macros used in several
952 modules--many more are defined in the sources; see the top-level 'm4/'
953 directory. These general macros are supplemented by module-specific
954 macros in directories such as 'texk/dvipng/m4/'; some of those are
955 described in following sections (*note Library modules:: and *note
956 Program modules::).
957
958 * Menu:
959
960 * Setup: General setup macros.
961 * Programs: Macros for programs.
962 * Compilers: Macros for compilers.
963 * Libraries: Macros for libraries.
964 * Flags: Macros for library and header flags.
965 * Windows: Macros for Windows.
966
967 
968 File: tlbuild.info, Node: General setup macros, Next: Macros for programs, Up: Autoconf macros
969
970 6.3.1 General setup macros
971 --------------------------
972
973 The TL sources use two general setup macros:
974
975 -- Macro: KPSE_BASIC (NAME, [MORE-OPTIONS])
976 Initialize the basic TL infrastructure for module NAME:
977 'AM_INIT_AUTOMAKE([foreign MORE-OPTIONS])'
978 'AM_MAINTAINER_MODE'
979 'KPSE_COMPILER_WARNINGS'
980 and make sure the C compiler understands function prototypes. This
981 is used for all generic library and program modules.
982
983 -- Macro: KPSE_COMMON (NAME, [MORE-OPTIONS])
984 Like 'KPSE_BASIC' but add:
985 'LT_PREREQ([2.2.6])'
986 'LT_INIT([win32-dll])'
987 'AC_SYS_LARGEFILE'
988 'AC_FUNC_FSEEKO'
989 along with checks for frequently used functions, headers, types,
990 and structures. This is used for TeX-specific modules.
991
992 
993 File: tlbuild.info, Node: Macros for programs, Next: Macros for compilers, Prev: General setup macros, Up: Autoconf macros
994
995 6.3.2 Macros for programs
996 -------------------------
997
998 Macros for program checks:
999
1000 -- Macro: KPSE_CHECK_LATEX
1001 Set 'LATEX' to the first of 'latex', 'elatex', or 'lambda' which
1002 exists in 'PATH', or to 'no' if none of them exists. Call
1003 'AC_SUBST' for 'LATEX'. The result of this test can be overridden
1004 by setting the 'LATEX' environment variable or the cache variable
1005 'ac_cv_prog_LATEX'.
1006
1007 -- Macro: KPSE_CHECK_PDFLATEX
1008 Check for 'pdflatex' in 'PATH' and set 'PDFLATEX'.
1009
1010 -- Macro: KPSE_CHECK_PERL
1011 Check for 'perl' or 'perl5' in 'PATH' and set 'PERL'.
1012
1013 -- Macro: KPSE_PROG_LEX
1014 Call 'AC_PROG_LEX' and add the flag '-l' for 'flex'.
1015
1016 
1017 File: tlbuild.info, Node: Macros for compilers, Next: Macros for libraries, Prev: Macros for programs, Up: Autoconf macros
1018
1019 6.3.3 Macros for compilers
1020 --------------------------
1021
1022 Macros for compiler-related checks:
1023
1024 -- Macro: KPSE_COMPILER_WARNINGS
1025 When using the (Objective) C/C++ compiler, set
1026 'WARNING_[OBJ]C[XX]FLAGS' to suitable warning flags (depending on
1027 the value given to or implied for '--enable-compiler-warnings').
1028 Call 'AC_SUBST' for them. At present this assumes GNU compiler
1029 warning options, but could be extended to others if necessary.
1030
1031 This macro caches its results in the 'kpse_cv_warning_cflags', ...
1032 variables.
1033
1034 -- Macro: KPSE_COMPILER_VISIBILITY
1035 When using the C or C++ compiler, try to set
1036 'VISIBILITY_C[XX]FLAGS' to flags to hide external symbols. Call
1037 'AC_SUBST' for this variable. This tests for the compiler option
1038 '-fvisibility=hidden' and, except for C,
1039 '-fvisibility-inlines-hidden'. Reports or patches for additional
1040 tests are welcome.
1041
1042 This macro caches its results in the 'kpse_cv_visibility_cflags' or
1043 'kpse_cv_visibility_cxxflags' variable.
1044
1045 -- Macro: KPSE_CXX_HACK
1046 Provide the configure option '--enable-cxx-runtime-hack'. If
1047 enabled and when using 'g++', try to statically link with
1048 'libstdc++', notably improving portability of the resulting binary.
1049
1050 This macro caches its result in the 'kpse_cv_cxx_hack' variable.
1051
1052 
1053 File: tlbuild.info, Node: Macros for libraries, Next: Macros for library and header flags, Prev: Macros for compilers, Up: Autoconf macros
1054
1055 6.3.4 Macros for libraries
1056 --------------------------
1057
1058 One macro for a library check:
1059
1060 -- Macro: KPSE_LARGEFILE (VARIABLE, [EXTRA-DEFINE])
1061 Call 'AC_SYS_LARGEFILE' and 'AC_FUNC_FSEEKO' and append suitable
1062 '-D' flags (optionally including '-DEXTRA-DEFINE') to VARIABLE.
1063
1064 
1065 File: tlbuild.info, Node: Macros for library and header flags, Next: Macros for Windows, Prev: Macros for libraries, Up: Autoconf macros
1066
1067 6.3.5 Macros for library and header flags
1068 -----------------------------------------
1069
1070 Each library module 'libs/LIB' or 'texk/LIB' is supplemented by a macro
1071 'KPSE_LIB_FLAGS' (all uppercase) that provides make variables for that
1072 library. E.g., for 'libs/libpng':
1073
1074 -- Macro: KPSE_LIBPNG_FLAGS
1075 Provide the configure option '--with-system-libpng'. Set and
1076 'AC_SUBST' 'make' variables for modules using this library (either
1077 an installed version or from the TeX Live tree):
1078
1079 'LIBPNG_INCLUDES' for use in 'CPPFLAGS',
1080 'LIBPNG_LIBS' for use in 'LDADD',
1081 'LIBPNG_DEPEND' for use as a Makefile dependency,
1082 'LIBPNG_RULE' for the 'make' rules to rebuild the library.
1083
1084 -- Macro: KPSE_ADD_FLAGS (NAME)
1085 Temporarily extend 'CPPFLAGS' and 'LIBS' with the values required
1086 for the library module 'NAME'.
1087
1088 -- Macro: KPSE_RESTORE_FLAGS
1089 Restore 'CPPFLAGS' and 'LIBS' to their original values.
1090
1091 As an example, the 'configure.ac' file for a hypothetical program
1092 'utils/foo' using 'libpng', and hence 'zlib', would contain
1093 KPSE_ZLIB_FLAGS
1094 KPSE_LIBPNG_FLAGS
1095
1096 and its 'Makefile.am' would be along these lines:
1097 bin_PROGRAMS = foo
1098 AM_CPPFLAGS = ${LIBPNG_INCLUDES} ${ZLIB_INCLUDES}
1099 foo_LDADD = ${LIBPNG_LIBS} ${ZLIB_LIBS}
1100 foo_DEPENDENCIES = ${ZLIB_DEPEND} ${LIBPNG_DEPEND}
1101 ## Rebuild libz
1102 @ZLIB_RULE@
1103 ## Rebuild libpng
1104 @LIBPNG_RULE@
1105
1106 If it were necessary to examine whether certain 'zlib' or 'libpng'
1107 features were available, 'configure.ac' should be continued this way:
1108 KPSE_ADD_FLAGS([zlib])
1109 ... # tests for 'zlib' features, if any
1110 KPSE_ADD_FLAGS([libpng])
1111 ... # tests for 'libpng' features
1112 KPSE_RESTORE_FLAGS # restore 'CPPFLAGS' and 'LIBS'
1113
1114 
1115 File: tlbuild.info, Node: Macros for Windows, Prev: Macros for library and header flags, Up: Autoconf macros
1116
1117 6.3.6 Macros for Windows
1118 ------------------------
1119
1120 Windows differs in several aspects from Unix-like systems, many of them
1121 due to the lack of symbolic links.
1122
1123 -- Macro: KPSE_CHECK_WIN32
1124 Check if compiling for a Windows system. The result is either 'no'
1125 for Unix-like systems (including Cygwin), 'mingw32' for Windows
1126 with GCC, or 'native' for Windows with MSVC. The result is cached
1127 in the 'kpse_cv_have_win32' variable.
1128
1129 -- Macro: KPSE_COND_WIN32
1130 Call 'KPSE_CHECK_WIN32' and define the Automake conditional 'WIN32'
1131 ('true' if the value of 'kpse_cv_have_win32' is not 'no').
1132
1133 -- Macro: KPSE_COND_MINGW32
1134 Call 'KPSE_COND_WIN32' and define the Automake conditional
1135 'MINGW32' ('true' if the value of 'kpse_cv_have_win32' is
1136 'mingw32').
1137
1138 -- Macro: KPSE_COND_WIN32_WRAP
1139 Call 'KPSE_COND_WIN32' and define the Automake conditional
1140 'WIN32_WRAP' ('true' if the standard Windows wrapper
1141 ('texk/texlive/windows_wrapper/runscript.exe') exists. This
1142 wrapper is used on Windows instead of symlinks for the "linked
1143 scripts" (*note Linked scripts::).
1144
1145 -- Macro: KPSE_WIN32_CALL
1146 Call 'KPSE_COND_WIN32' and check whether the file
1147 'texk/texlive/windows_wrapper/callexe.c' exists; if it does, create
1148 a symlink in the build tree. Compiling 'callexe.c' with
1149 '-DEXEPROG='"FOO.exe"'' and installing 'callexe.exe' as 'BAR.exe'
1150 is used on Windows instead of a symlink 'BAR->FOO' for Unix-like
1151 systems.
1152
1153 
1154 File: tlbuild.info, Node: Library modules, Next: Program modules, Prev: Autoconf macros, Up: Layout and infrastructure
1155
1156 6.4 Library modules
1157 ===================
1158
1159 Here we discuss some specifics for a few of the libraries in TL, both
1160 for the details themselves, and as a way of illuminating the general
1161 structure and variation.
1162
1163 * Menu:
1164
1165 * png library:: 'libs/libpng'
1166 * zlib library:: 'libs/zlib'
1167 * freetype library:: 'libs/freetype2'
1168 * kpathsea library:: 'texk/kpathsea'
1169
1170 
1171 File: tlbuild.info, Node: png library, Next: zlib library, Up: Library modules
1172
1173 6.4.1 The 'png' library in 'libs/libpng'
1174 ----------------------------------------
1175
1176 The "generic" 'png' library uses the source tree in the subdirectory
1177 'libpng-src/', with all modifications for TL recorded in 'TLpatches/*'.
1178 The 'configure.ac' fragment 'ac/withenable.ac' contains
1179
1180 KPSE_WITH_LIB([libpng], [zlib])
1181
1182 to specify the module name and indicate the dependency on 'zlib'. A
1183 third literal argument ''tree'' would specify that the library from the
1184 TeX Live tree cannot be replaced by a system version. That not being
1185 the case here, a second fragment 'ac/libpng.ac' contains
1186
1187 KPSE_TRY_LIB([libpng],
1188 [#include <png.h>],
1189 [png_structp png; png_voidp io; png_rw_ptr fn;
1190 png_set_read_fn(png, io, fn);])
1191
1192 thus providing the simple C code
1193
1194 #include <png.h>
1195 int main ()
1196 { png_structp png; png_voidp io; png_rw_ptr fn;
1197 png_set_read_fn(png, io, fn);
1198 return 0; }
1199
1200 which Autoconf uses to verify the usability of a system version with C
1201 code. The analogous macro 'KPSE_TRY_LIBXX' would check using C++.
1202 These fragments are included by the 'configure.ac' at the top level of
1203 TL ('Build/source/configure.ac').
1204
1205 For this library, like many other modules, a proxy build system for
1206 TL is used, consisting of our own 'configure.ac', 'Makefile.am',
1207 'include/Makefile.am'; the distributed build system is not used.
1208 (Consequently, a few generated files and auxiliary scripts are removed
1209 from the distributed source tree.)
1210
1211 The public headers 'png.h', 'pngconf.h', and 'pnglibconf.h' are
1212 "installed" (as symlinks) under 'include/' in the build tree exactly as
1213 they are for a system version under, e.g., '/usr/include/'.
1214
1215 The module is supplemented by the file 'm4/kpse-libpng-flags.m4' that
1216 defines the M4 macro 'KPSE_LIBPNG_FLAGS' used by all modules depending
1217 on this library in their 'configure.ac' to generate the 'make' variables
1218 'LIBPNG_INCLUDES' for use in 'CPPFLAGS', 'LIBPNG_LIBS' for use in
1219 'LDADD', 'LIBPNG_DEPEND' for use as dependencies, and 'LIBPNG_RULE' for
1220 the 'make' rules to rebuild the library.
1221
1222 'm4/kpse-libpng-flags.m4' also supplies the configure option
1223 '--with-system-libpng', which then uses 'pkg-config' to determine the
1224 flags required for the system library.
1225
1226 
1227 File: tlbuild.info, Node: zlib library, Next: freetype library, Prev: png library, Up: Library modules
1228
1229 6.4.2 The 'zlib' library in 'libs/zlib'
1230 ---------------------------------------
1231
1232 This generic library is very much analogous to 'libpng', but without the
1233 dependency on any other library. The file 'm4/kpse-zlib-flags.m4'
1234 supplies the configure option '--with-system-zlib', as well as
1235 '--with-zlib-includes' and '--with-zlib-libdir' to specify non-standard
1236 locations of the 'zlib' headers and/or library.
1237
1238 
1239 File: tlbuild.info, Node: freetype library, Next: kpathsea library, Prev: zlib library, Up: Library modules
1240
1241 6.4.3 The 'freetype' library in 'libs/freetype2'
1242 ------------------------------------------------
1243
1244 This module uses a wrapper build system. In contrast to the proxy build
1245 described earlier, the wrapper build has an almost trivial
1246 'configure.ac' and a 'Makefile.am' which invokes the 'configure' and
1247 'make' in the distributed source, followed by 'make install' with the TL
1248 build tree as destination. In other words, this actually uses the build
1249 system provided by upstream (possibly patched).
1250
1251 The flags required for the system library are obtained through
1252 'freetype-config'.
1253
1254 
1255 File: tlbuild.info, Node: kpathsea library, Prev: freetype library, Up: Library modules
1256
1257 6.4.4 The 'kpathsea' library in 'texk/kpathsea'
1258 -----------------------------------------------
1259
1260 This is one of the TeX-specific libraries that are maintained as part of
1261 TeX Live (*note (kpathsea)Top::); the other is 'ptexenc'. These TeX
1262 libraries are Libtool libraries (static and/or shared) and are installed
1263 by 'make install' together with the programs. They are, however, not
1264 part of the TL DVD as distributed by TeX user groups, and have never
1265 been officially released for standalone use.
1266
1267 It is possible, and probably useful for distro builds (*note Distro
1268 builds::), to specify the configure option '--with-system-kpathsea' in
1269 order to use a system version of the library. Programs outside the TL
1270 tree should use 'pkg-config' for the required flags.
1271
1272 In addition to 'kpathsea/ac/withenable.ac' and
1273 'kpathsea/ac/kpathsea.ac' here there is a third fragment
1274 'kpathsea.ac/mktex.ac', included by both 'withenable.ac' and
1275 'configure.ac', which supplies configure options such as
1276 '--enable-mktextfm-default'. These determine the compile time default
1277 of whether or not to run 'mktextfm' (and similar) to generate a missing
1278 '.tfm' (or whatever) file. In any case, however, the command line
1279 options '-mktex=tfm' or '-no-mktex=tfm' for the TeX-like engines
1280 override this default.
1281
1282 
1283 File: tlbuild.info, Node: Program modules, Next: Extending TeX Live, Prev: Library modules, Up: Layout and infrastructure
1284
1285 6.5 Program modules
1286 ===================
1287
1288 As with libraries (*note Library modules::), here we discuss the details
1289 for a few of the programs in TL.
1290
1291 * Menu:
1292
1293 * t1utils package:: 'utils/t1utils'
1294 * xindy package:: 'utils/xindy'
1295 * xdvik package:: 'texk/xdvik'
1296 * asymptote:: 'utils/asymptote'
1297
1298 
1299 File: tlbuild.info, Node: t1utils package, Next: xindy package, Up: Program modules
1300
1301 6.5.1 The 't1utils' package in 'utils/t1utils'
1302 ----------------------------------------------
1303
1304 Here we use the distributed source tree 't1utils-src' with modifications
1305 documented in 'TLpatches/*' and a proxy build system consisting of
1306 'configure.ac' and 'Makefile.am'. The fragment 'ac/withenable.ac'
1307 contains
1308
1309 KPSE_ENABLE_PROG([t1utils])
1310
1311 specifying the module name without any dependencies, and supplies the
1312 configure option '--disable-t1utils'.
1313
1314 
1315 File: tlbuild.info, Node: xindy package, Next: xdvik package, Prev: t1utils package, Up: Program modules
1316
1317 6.5.2 The 'xindy' package in 'utils/xindy'
1318 ------------------------------------------
1319
1320 This module uses the distributed source tree 'xindy-src/' with
1321 modifications documented in 'TLpatches/*', and a wrapper 'configure.ac'
1322 and 'Makefile.am' that descends into 'xindy-src'.
1323
1324 The 'xindy' build requires a 'make' that supports a 'VPATH' build,
1325 can handle all needed targets, and does not refer to '${top_srcdir}' or
1326 '${top_builddir}'. The fragment 'xindy/ac/withenable.ac' contains
1327
1328 KPSE_ENABLE_PROG([xindy], , [disable])
1329 m4_include(kpse_TL[utils/xindy/ac/xindy.ac])
1330 m4_include(kpse_TL[utils/xindy/ac/clisp.ac])
1331
1332 where 'disable' in the third argument indicates that 'xindy' is only
1333 built if explicitly enabled by the user with 'configure --enable-xindy'
1334 (the need for 'clisp' makes it too painful to enable by default).
1335
1336 The additional fragments 'ac/xindy.ac' and 'ac/clisp.ac' specify more
1337 'configure' options to be seen at the top level, with 'ac/xindy.ac' also
1338 included by 'configure.ac'.
1339
1340 
1341 File: tlbuild.info, Node: xdvik package, Next: asymptote, Prev: xindy package, Up: Program modules
1342
1343 6.5.3 The 'xdvik' package in 'texk/xdvik'
1344 -----------------------------------------
1345
1346 This package is maintained as part of the TeX Live tree with sources in
1347 its own directory ('texk/xdvik/'). The fragment
1348 'xdvik/ac/withenable.ac' contains
1349
1350 dnl extra_dirs = texk/xdvik/squeeze
1351 KPSE_ENABLE_PROG([xdvik], [kpathsea freetype2], [x])
1352 m4_include(kpse_TL[texk/xdvik/ac/xdvik.ac])
1353
1354 thus specifying dependencies on the 'kpathsea', 'freetype', and X11
1355 libraries. The M4 comment (following 'dnl') signals the subsidiary
1356 'squeeze/configure.ac'. This is needed because the main executable
1357 'xdvi-bin' (to be installed as, e.g., 'xdvi-xaw') is for the 'host'
1358 system whereas the auxiliary program 'squeeze/squeeze' has to run on the
1359 'build' system; in a cross compilation, these differ.
1360
1361 The additional fragment 'ac/xdvik.ac' is also included by
1362 'configure.ac' and supplies the configure option '--with-xdvi-x-toolkit'
1363 also seen at the top level.
1364
1365 
1366 File: tlbuild.info, Node: asymptote, Prev: xdvik package, Up: Program modules
1367
1368 6.5.4 The subdirectory 'utils/asymptote'
1369 ----------------------------------------
1370
1371 This subdirectory contains the sources for 'asy' and 'xasy' but due to
1372 its complexity and prerequisites (e.g., OpenGL) it is not part of the TL
1373 build system. These programs must be built and installed independently,
1374 but are included on the TL DVD together with their support files. See
1375 <https://tug.org/texlive/build.html#asymptote>.
1376
1377 
1378 File: tlbuild.info, Node: Extending TeX Live, Prev: Program modules, Up: Layout and infrastructure
1379
1380 6.6 Extending TeX Live
1381 ======================
1382
1383 This section outlines the basic process for adding new packages to the
1384 TL build system.
1385
1386 A new package directory 'foo' should be placed under
1387 'Build/source/texk/' if it uses Kpathsea (or another TeX-specific
1388 library), or under 'Build/source/utils' if it does not.
1389
1390 The new directory should normally have the original sources, modified
1391 only with changes necessary for TL, in a subdirectory 'foo/foo-src'.
1392 The changes should be documented in 'foo/TLpatches/*', and also be
1393 submitted upstream whenever reasonable. In addition, 'foo/' will need
1394 the usual Automake build-related files ('configure.ac', 'Makefile.am',
1395 etc. Please maintain 'foo/ChangeLog' for all TL changes.
1396
1397 It is also possible to add a package which is configured with
1398 Autoconf (or another 'make'-based system) and not Automake. The package
1399 must still support the standard 'make' variables and targets, and
1400 'VPATH' builds (*note (automake)VPATH Builds::). For Autoconf-only
1401 packages, it is probably not sensible to use a 'foo-src' subdirectory.
1402
1403 * Menu:
1404
1405 * Adding a new program module::
1406 * Adding a new engine::
1407 * Adding a new generic library module::
1408 * Adding a new TeX-specific library module::
1409
1410 
1411 File: tlbuild.info, Node: Adding a new program module, Next: Adding a new engine, Up: Extending TeX Live
1412
1413 6.6.1 Adding a new program module
1414 ---------------------------------
1415
1416 A TeX-specific program module in a subdirectory 'texk/PROG' may use the
1417 TeX-specific libraries and is included by adding its name 'PROG' to the
1418 M4 list 'kpse_texk_pkgs' defined in 'm4/kpse-pkgs.m4'.
1419
1420 A generic program module in a subdirectory 'utils/PROG' must not use
1421 the TeX-specific libraries, notably Kpathsea, and is included by adding
1422 its name 'PROG' to the M4 list 'kpse_utils_pkgs' in 'm4/kpse-pkgs.m4'.
1423
1424 In either case, the subdirectory 'texk/PROG' or 'utils/PROG' must
1425 include a file 'ac/withenable.ac' which contains a call to the M4 macro
1426 'KPSE_ENABLE_PROG' defined in 'm4/kpse-setup.m4' with 'PROG' as the
1427 mandatory first argument and three optional arguments:
1428
1429 1. a list of required libraries from the TL tree;
1430
1431 2. a list of options: 'disable' if this module is not to be built
1432 without the configure option '--enable-PROG', 'native' if cross
1433 compilation is not possible, 'x' if the program requires X11
1434 libraries;
1435
1436 3. a comment added to the help text for the 'configure' option
1437 '--enable-PROG' or '--disable-PROG'.
1438
1439 If the module requires specific 'configure' options to be seen at the
1440 top level, they should be defined in an additional fragment 'ac/PROG.ac'
1441 included from 'ac/withenable.ac' and 'configure.ac'.
1442
1443 Usually, the new program is maintained somewhere outside of TeX Live.
1444 In that case, as above, we put the upstream sources into a subdirectory
1445 'PROG-src' (e.g., 'utils/newprog/newprog-src'). We do not typically run
1446 'configure' in this original '...-src' directory, but only in our own
1447 directory; but we do compile using the source files in '...-src'.
1448
1449 So, to summarize the files that must (usually) be created inside a
1450 new TL source directory ('texk/newprog' or 'utils/newprog'):
1451
1452 'ac/withenable.ac'
1453 The 'KPSE_ENABLE_PROG' call just explained.
1454
1455 'configure.ac'
1456 'Makefile.am'
1457 By merging the contents of the original 'configure.ac' (if
1458 provided) and a comparable program already in TL. In the above
1459 example, one line that will be needed in 'configure.ac' (can be
1460 added before the 'AC_CONFIG_FILES' at the end) is:
1461
1462 AC_SUBST([NEWPROG_TREE], [newprog-src])
1463
1464 and then use '@NEWPROG_TREE@' in 'Makefile.am' where needed.
1465
1466 In general, there is no magic recipe for this part of the job.
1467 It's necessary to think about what needs to be done in the original
1468 vs. in TeX Live. It's useful to look at the setup for the most
1469 comparable programs already in TL that you can find. It's also
1470 useful to grep the entire 'Build/source' tree for whatever you can
1471 think of to investigate how something is done. Most of the
1472 TL-specific macros are defined in 'Build/source/m4/*'.
1473
1474 'TLpatches/TL-Changes'
1475 First actions taken after getting the original source tree;
1476 typically removal of derived or unused common files.
1477
1478 'TLpatches/patch-...'
1479 If any changes are needed to the original sources, record the
1480 patches here so they can be applied next time. Also, send them
1481 upstream so that we don't have to maintain them forever.
1482
1483 'ChangeLog'
1484 Record all TL-specific changes, now and in the future.
1485
1486 After populating the new TL source directory ('.../newprog/', in the
1487 above), run GNU 'autoreconf' there (*note Build system tools::). Once
1488 that works, if you are the one who's eventually going to commit the new
1489 package, 'svn add' the necessary files, including the generated
1490 'Makefile.in aclocal.m4 configure', and 'svn:ignore' the Automake cache
1491 'autom4te.cache'. (This is so people checking out the TL source tree do
1492 not have to run any autotools, but can simply run 'configure'.)
1493
1494 To reiterate: do not fail to commit the generated 'configure' and
1495 other files. The m4 code in 'kpse-pkgs.m4' uses the existence of
1496 'configure' to determine whether to descend into (and configure) a given
1497 subdirectory.
1498
1499 Then, run the TL tool 'reautoconf' in the top-level TL
1500 'Build/source/' directory, to incorporate the new program into the build
1501 tree. It is good to then rebuild the whole tree (e.g., using TL's
1502 'Build/Build' script) to get all the necessary files generated.
1503
1504 It will probably fail. So then you need to keep at it until the
1505 program compiles and tests successfully. The most efficient way is to
1506 rerun 'autoreconf' as needed in the new source directory
1507 ('Build/source/.../newprog'), then 'make' in the corresponding build
1508 directory ('Build/work/.../newprog'), then 'make check', etc. In the
1509 end, also make sure that the whole tree builds from scratch.
1510
1511 After final success, don't forget to commit. (Or email the TL
1512 maintainers with the patch.)
1513
1514 
1515 File: tlbuild.info, Node: Adding a new engine, Next: Adding a new generic library module, Prev: Adding a new program module, Up: Extending TeX Live
1516
1517 6.6.2 Adding a new engine
1518 -------------------------
1519
1520 Adding a new TeX engine is not completely different from adding a
1521 program, but it's not all that similar, either. In this case, the main
1522 work is done by creating a new subdirectory of 'texk/web2c/' for the
1523 engine. The subdirectory is conventionally named ending in 'dir', like
1524 'pdftexdir' and 'xetexdir', to avoid clashes with executable names.
1525
1526 The source files for the new engine should be put in this
1527 'NEWENGINEdir' subdirectory. Also, a file
1528 'NEWENGINEdir/am/NEWENGINE.am' (e.g., 'pdftexdir/am/pdftex.am' is needed
1529 with the Makefile fragment needed to build it.
1530
1531 The overall 'web2c/Makefile.am' needs to have an 'include' statement
1532 added to insert that 'NEWENGINE.am' file.
1533
1534 In 'web2c/ac/web2c.ac', a line needs to be added in the definition of
1535 the 'kpse_tex_progs' variable to include it in the build. That line
1536 specifies whether the new engine is built by default, and the additional
1537 libraries requires.
1538
1539 For examples of building engines in CWEB, you can check the existing
1540 'hitexdir' and 'mplibdir' directories; these are somewhat simpler than
1541 LuaTeX. Of course, every engine will have its own unique features and
1542 requirements, so existing examples will only take you so far.
1543
1544 Web2c is built as one "package", with each subdirectory's '.am'
1545 fragment inserted with an Automake 'include'. This means that, for
1546 instance, '$(srcdir)' is '.../web2c', not '.../webdir/enginedir'. It is
1547 a difficult setup to come to terms with, but the alternative is to
1548 recurse into each engine subdirectory, and that would be far worse
1549 (*note (automake)Directories::).
1550
1551 
1552 File: tlbuild.info, Node: Adding a new generic library module, Next: Adding a new TeX-specific library module, Prev: Adding a new engine, Up: Extending TeX Live
1553
1554 6.6.3 Adding a new generic library module
1555 -----------------------------------------
1556
1557 A generic library module in a subdirectory 'libs/LIB' must not depend on
1558 TeX-specific libraries, by definition. It is included by adding its
1559 name 'LIB' to the M4 macro 'kpse_libs_pkgs' in 'm4/kpse-pkgs.m4'--before
1560 any other libraries from the TeX Live tree on which it depends.
1561
1562 As with program modules, the subdirectory 'libs/LIB' must contain the
1563 sources and build system for the library (and any installable support
1564 programs) and a fragment 'ac/withenable.ac' that contains the M4 macro
1565 'KPSE_WITH_LIB' defined in 'm4/kpse-setup.m4' with 'LIB' as the
1566 mandatory first argument and two optional arguments: a list of required
1567 libraries from the TL tree, and a list of options: for libraries,
1568 currently there is only one--specify 'tree' if this library cannot be
1569 replaced by a system version.
1570
1571 If a system version can be used, a second fragment 'ac/LIB.ac' is
1572 needed, containing the M4 macro 'KPSE_TRY_LIB' (or 'KPSE_TRY_LIBXX')
1573 with 'LIB' as the mandatory first argument and two additional arguments
1574 for the Autoconf macro 'AC_LANG_PROGRAM' used to compile and link a
1575 small C (or C++) program as sanity check for using the system library.
1576
1577 In addition a file 'm4/kpse-LIB-flags' (at the top level) must define
1578 the M4 macro 'KPSE_LIB_FLAGS' (all uppercase) setting up the 'make'
1579 variables 'LIB_INCLUDES', 'LIB_LIBS', 'LIB_DEPEND', and 'LIB_RULE' with
1580 the values required for 'CPPFLAGS', 'LDADD', dependencies, and a
1581 (multi-line) 'make' rule to rebuild the library when necessary. All of
1582 that is needed for the library from the TL tree and, if supported, for a
1583 system version.
1584
1585 If a system library is allowed, 'KPSE_LIB_FLAGS' also provides the
1586 configure option '--with-system-LIB' and uses the additional M4 macro
1587 'KPSE_LIB_SYSTEM_FLAGS' to generate the 'make' variables for a system
1588 library. In addition, the definition of the M4 macro
1589 'KPSE_ALL_SYSTEM_FLAGS' in 'm4/kpse-pkgs.m4' must be extended by the
1590 line:
1591 'AC_REQUIRE([KPSE_LIB_SYSTEM_FLAGS])'
1592
1593 
1594 File: tlbuild.info, Node: Adding a new TeX-specific library module, Prev: Adding a new generic library module, Up: Extending TeX Live
1595
1596 6.6.4 Adding a new TeX-specific library module
1597 ----------------------------------------------
1598
1599 A TeX-specific library module in a subdirectory 'texk/LIB' may depend on
1600 other TeX-specific libraries but must not depend on any generic library
1601 from the TL tree. It is included in the same general ways as a generic
1602 library (see the previous section), with these modifications:
1603
1604 * The library name 'LIB' is added to the M4 macro
1605 'kpse_texlibs_pkgs', which is also in 'm4/kpse-pkgs.m4'.
1606
1607 * The fragment 'ac/withenable.ac' must use 'KPSE_WITH_TEXLIB'.
1608
1609 
1610 File: tlbuild.info, Node: Configure options, Next: Coding conventions, Prev: Layout and infrastructure, Up: Top
1611
1612 7 Configure options
1613 *******************
1614
1615 Corresponding to the large number of program and library modules there
1616 are a large number 'configure' options, most of which are described
1617 here. The command
1618 'configure --help'
1619 at the top level gives an exhaustive list of all global options and a
1620 few important module-specific ones, whereas, e.g.,
1621 'texk/lcdf-typetools/configure --help'
1622 also displays the 'lcdf-typetools' specific options, which are not shown
1623 at the top level.
1624
1625 The help text also mentions several influential environment
1626 variables, but for TeX Live it is better to specify them as assignments
1627 on the command line.
1628
1629 The './Build' script used to make the binaries shipped with TeX Live
1630 invokes the top-level 'configure' with a few additional options (*note
1631 Building::). The defaults discussed below are those for the actual
1632 'configure' script; invoking 'configure' via './Build' yields different
1633 results.
1634
1635 Defaults for most options are set at the top level and propagated
1636 explicitly to all subdirectories. Options specified on the command line
1637 are checked for consistency but never modified.
1638
1639 * Menu:
1640
1641 * Global configure options::
1642 * Program-specific configure options::
1643 * Library-specific configure options::
1644 * Variables for configure::
1645
1646 
1647 File: tlbuild.info, Node: Global configure options, Next: Program-specific configure options, Up: Configure options
1648
1649 7.1 Global configure options
1650 ============================
1651
1652 Here are the global configure options.
1653
1654 * Menu:
1655
1656 * --disable-native-texlive-build::
1657 * --prefix --bindir ...::
1658 * --disable-largefile::
1659 * --disable-missing::
1660 * --enable-compiler-warnings=LEVEL::
1661 * --enable-cxx-runtime-hack::
1662 * --enable-maintainer-mode::
1663 * --enable-multiplatform::
1664 * --enable-shared::
1665 * --enable-silent-rules::
1666 * --without-ln-s::
1667 * --without-x::
1668
1669 
1670 File: tlbuild.info, Node: --disable-native-texlive-build, Next: --prefix --bindir ..., Up: Global configure options
1671
1672 7.1.1 '--disable-native-texlive-build'
1673 --------------------------------------
1674
1675 If enabled (the default), build for a TL binary distribution as shipped
1676 by the TeX user groups. This requires GNU 'make' and implies
1677 '--enable-multiplatform' and '--enable-cxx-runtime-hack' (unless they
1678 are explicitly disabled), and enforces '--disable-shared'.
1679
1680 If building TL for a GNU/Linux or other distribution, this should be
1681 disabled and system versions of most libraries should be used (*note
1682 Distro builds::).
1683
1684 A related option, '--enable-texlive-build', is automatically passed
1685 to all subdirectories (and cannot be disabled). Subdirectories that can
1686 also be built independently from the TL tree (such as 'utils/xindy' and
1687 'texk/dvipng') but cooperate with TL can use this option to enable
1688 TL-specific adaptations, such as installation paths.
1689
1690 
1691 File: tlbuild.info, Node: --prefix --bindir ..., Next: --disable-largefile, Prev: --disable-native-texlive-build, Up: Global configure options
1692
1693 7.1.2 '--prefix', '--bindir', ...
1694 ---------------------------------
1695
1696 These standard Autoconf options specify various installation directories
1697 as usual. For the complete list, *note Installation directories::.
1698
1699 Also as usual, all values are prefixed by the value of 'DESTDIR', if
1700 set, on the 'make' command line (*note Installation in a temporary
1701 location: (automake)Staged Installs.).
1702
1703 
1704 File: tlbuild.info, Node: --disable-largefile, Next: --disable-missing, Prev: --prefix --bindir ..., Up: Global configure options
1705
1706 7.1.3 '--disable-largefile'
1707 ---------------------------
1708
1709 Omit large file support (LFS), which is needed on most 32-bit Unix
1710 systems for files with 2GB or more. Regardless of this option, the size
1711 of 'DVI' and 'GF' files must always be <2GB, due to the file format
1712 specifications.
1713
1714 With LFS, there is no fixed limit on the size of PDF files created by
1715 'pdftex' or PostScript files created by 'dvips'.
1716
1717 
1718 File: tlbuild.info, Node: --disable-missing, Next: --enable-compiler-warnings=LEVEL, Prev: --disable-largefile, Up: Global configure options
1719
1720 7.1.4 '--disable-missing'
1721 -------------------------
1722
1723 Immediately terminate the build process if a requested program or
1724 feature must be disabled, e.g., due to missing libraries. This can help
1725 when figuring out a specific (sub)set of modules to enable.
1726
1727 
1728 File: tlbuild.info, Node: --enable-compiler-warnings=LEVEL, Next: --enable-cxx-runtime-hack, Prev: --disable-missing, Up: Global configure options
1729
1730 7.1.5 '--enable-compiler-warnings='LEVEL
1731 ----------------------------------------
1732
1733 Enable various levels of compiler warnings for C, C++, and/or
1734 Objective C: the LEVEL value can be one of: 'no min yes max all'. The
1735 default is 'yes' in 'maintainer-mode' (see below) and 'min' otherwise.
1736 This option defines the variables 'WARNING_[OBJ]C[XX]FLAGS', but these
1737 variables are not consistently used in all library and program modules.
1738 At present, these warning flags assume options from the GNU compilers.
1739
1740 
1741 File: tlbuild.info, Node: --enable-cxx-runtime-hack, Next: --enable-maintainer-mode, Prev: --enable-compiler-warnings=LEVEL, Up: Global configure options
1742
1743 7.1.6 '--enable-cxx-runtime-hack'
1744 ---------------------------------
1745
1746 If enabled (as it is for the native TL build), when using 'g++', try to
1747 statically link with 'libstdc++', thus improving portability of the
1748 resulting binary. *Note Macros for compilers::.
1749
1750 
1751 File: tlbuild.info, Node: --enable-maintainer-mode, Next: --enable-multiplatform, Prev: --enable-cxx-runtime-hack, Up: Global configure options
1752
1753 7.1.7 '--enable-maintainer-mode'
1754 --------------------------------
1755
1756 Enable 'make' rules and dependencies not useful (and sometimes
1757 confusing) to the casual user. This requires current versions of the
1758 GNU build tools (*note Build system tools::), as it automatically
1759 rebuilds infrastructure files as needed. *Note 'missing' and
1760 'AM_MAINTAINER_MODE': (automake)maintainer-mode.
1761
1762 
1763 File: tlbuild.info, Node: --enable-multiplatform, Next: --enable-shared, Prev: --enable-maintainer-mode, Up: Global configure options
1764
1765 7.1.8 '--enable-multiplatform'
1766 ------------------------------
1767
1768 If enabled (as it is for the native TL build) and '--bindir=DIR' or
1769 '--libdir=DIR' are not specified, install executables and libraries in
1770 per-platform subdirectories of 'EPREFIX/bin' and 'EPREFIX/lib' where
1771 EPREFIX is the value given or implied for 'exec_prefix'. In any case,
1772 the values for 'bindir' and 'libdir' are automatically propagated to all
1773 subdirectories.
1774
1775 
1776 File: tlbuild.info, Node: --enable-shared, Next: --enable-silent-rules, Prev: --enable-multiplatform, Up: Global configure options
1777
1778 7.1.9 '--enable-shared'
1779 -----------------------
1780
1781 Build shared versions of the TeX-specific libraries such as
1782 'libkpathsea'. This is not allowed for a native TL build (i.e.,
1783 '--disable-native-texlive-build' must also be specified).
1784
1785 
1786 File: tlbuild.info, Node: --enable-silent-rules, Next: --without-ln-s, Prev: --enable-shared, Up: Global configure options
1787
1788 7.1.10 '--enable-silent-rules'
1789 ------------------------------
1790
1791 Enable the use of less verbose build rules. When using GNU 'make' (or
1792 any 'make' implementation supporting nested variable expansions), you
1793 can specify 'V=1' on the 'make' command line to get more verbosity, or
1794 'V=0' to get less, regardless of this option.
1795
1796 
1797 File: tlbuild.info, Node: --without-ln-s, Next: --without-x, Prev: --enable-silent-rules, Up: Global configure options
1798
1799 7.1.11 '--without-ln-s'
1800 -----------------------
1801
1802 Required when using a system without a working 'ln -s' to build binaries
1803 for a Unix-like system. However, 'make install' will not create
1804 anything useful, and might fail.
1805
1806 
1807 File: tlbuild.info, Node: --without-x, Prev: --without-ln-s, Up: Global configure options
1808
1809 7.1.12 '--without-x'
1810 --------------------
1811
1812 Disable all programs using the X Window System.
1813
1814 
1815 File: tlbuild.info, Node: Program-specific configure options, Next: Library-specific configure options, Prev: Global configure options, Up: Configure options
1816
1817 7.2 Program-specific configure options
1818 ======================================
1819
1820 Here are (some of) the program-specific 'configure' options.
1821
1822 * Menu:
1823
1824 * --enable-PROG --disable-PROG::
1825 * --disable-all-pkgs::
1826 * Configure options for texk/web2c::
1827 * Configure options for texk/bibtex-x::
1828 * Configure options for texk/dvipdfm-x::
1829 * Configure options for texk/dvisvgm::
1830 * Configure options for texk/texlive::
1831 * Configure options for texk/xdvik::
1832 * Configure options for utils/xindy::
1833
1834 
1835 File: tlbuild.info, Node: --enable-PROG --disable-PROG, Next: --disable-all-pkgs, Up: Program-specific configure options
1836
1837 7.2.1 '--enable-PROG', '--disable-PROG'
1838 ---------------------------------------
1839
1840 Do or do not build and install the program(s) of module 'PROG'.
1841
1842 
1843 File: tlbuild.info, Node: --disable-all-pkgs, Next: Configure options for texk/web2c, Prev: --enable-PROG --disable-PROG, Up: Program-specific configure options
1844
1845 7.2.2 '--disable-all-pkgs'
1846 --------------------------
1847
1848 Do not build any program modules by default--only those explicitly
1849 enabled. This is useful when one wants to work on only a single
1850 program, which is specified with an additional '--enable' option, e.g.,
1851 '--enable-dvipdfm-x'. It's still simplest to check out and configure
1852 the whole source tree, but at least only the program you are interested
1853 in, and its dependencies, are built. *Note Build one package::.
1854
1855 Without this option, all modules are built except those that are
1856 explicitly disabled or specify 'disable' in their 'ac/withenable.ac'
1857 fragment.
1858
1859 
1860 File: tlbuild.info, Node: Configure options for texk/web2c, Next: Configure options for texk/bibtex-x, Prev: --disable-all-pkgs, Up: Program-specific configure options
1861
1862 7.2.3 Configure options for 'texk/web2c'
1863 ----------------------------------------
1864
1865 '--with-banner-add=STR'
1866 Add 'STR' to the default version string (which is ''TeX Live YEAR'' or
1867 ''Web2C YEAR'') appended to banner lines. This is ignored for a native
1868 TL build, but distro builds should specify, e.g., '/SOMEDISTRO'.
1869
1870 '--with-editor=CMD'
1871 Specify the command 'CMD' to invoke from the 'e' option of TeX and
1872 friends, replacing the default 'vi +%d '%s'' for Unix or 'texworks
1873 --position=%d "%s"' for Windows.
1874
1875 '--with-fontconfig-includes=DIR', '--with-fontconfig-libdir=DIR'
1876 Building XeTeX on non-Mac systems requires the 'fontconfig' library
1877 headers and code. If one or both of these options are given, the
1878 required flags are derived from them; otherwise, they are determined via
1879 'pkg-config' (if present).
1880
1881 '--with-mf-x-toolkit'
1882 Use the X toolkit ('libXt') for Metafont (the default is to use the
1883 lowest-level 'Xlib' support; it seems this has the best chance of
1884 working across X installations nowadays).
1885
1886 '--disable-dump-share'
1887 Make the 'fmt'/'base' dump files architecture dependent (somewhat faster
1888 on LittleEndian architectures).
1889
1890 '--disable-ipc'
1891 Disable TeX's '--ipc' option.
1892
1893 '--disable-mf-nowin'
1894 Do not build a separate non-graphically-capable Metafont ('mf-nowin').
1895
1896 '--disable-tex', '--enable-etex', ...
1897 Do not or do build the various TeX, Metafont, and MetaPost engines
1898 (defaults are defined in the fragment 'texk/web2c/ac/web2c.ac').
1899
1900 '--disable-web-progs'
1901 Do not build the original WEB programs 'bibtex', ..., 'weave'. Useful
1902 if, e.g., you only want to (re)build some engines.
1903
1904 '--enable-auto-core'
1905 This option causes TeX and Metafont to produce a core dump when a
1906 particular hacky filename is encountered, for use in creating preloaded
1907 binaries. This is rarely done nowadays.
1908
1909 '--enable-libtool-hack'
1910 If enabled (which is the default for all platforms), prevents 'libtool'
1911 from linking explicitly with dependencies of 'libfontconfig' such as
1912 'libexpat'.
1913
1914 '--enable-*win'
1915 Include various types of non-X window support for Metafont (EPSF output,
1916 'mftalk', old graphics terminals, ...).
1917
1918 '--enable-tex-synctex', '--disable-etex-synctex', ...
1919 Build the TeX engines with or without 'SyncTeX' support; ignored for a
1920 native TeX Live build. Defaults are defined in 'texk/web2c/ac/web2c.ac'
1921 (*note Autoconf macros::).
1922
1923 '--disable-synctex'
1924 Do not build the 'SyncTeX' library and tool.
1925
1926 
1927 File: tlbuild.info, Node: Configure options for texk/bibtex-x, Next: Configure options for texk/dvipdfm-x, Prev: Configure options for texk/web2c, Up: Program-specific configure options
1928
1929 7.2.4 Configure options for 'texk/bibtex-x'
1930 -------------------------------------------
1931
1932 The programs 'bibtex8' and 'bibtexu' have been merged into the module
1933 'bibtex-x' (extended BibTeX).
1934
1935 '--disable-bibtex8'
1936 Do not build the 'bibtex8' program.
1937
1938 '--disable-bibtexu'
1939 Do not build the 'bibtexu' program (building 'bibtexu' requires 'ICU'
1940 libraries).
1941
1942 
1943 File: tlbuild.info, Node: Configure options for texk/dvipdfm-x, Next: Configure options for texk/dvisvgm, Prev: Configure options for texk/bibtex-x, Up: Program-specific configure options
1944
1945 7.2.5 Configure options for 'texk/dvipdfm-x'
1946 --------------------------------------------
1947
1948 The former modules 'dvipdfmx' (extended DVI to PDF converter) and
1949 'xdvipdfmx' (the same, as used by XeTeX) have been merged into
1950 'dvipdfm-x' at the source level. Two separate binaries are still
1951 created by default. In addition, 'dvipdfm' is created as a symlink to
1952 'dvipdfmx', with backward-compatible (very slightly different) behavior.
1953
1954 '--disable-dvipdfmx'
1955 Do not build the 'dvipdfmx' program or make the 'dvipdfm' symlink.
1956
1957 '--disable-xdvipdfmx'
1958 Do not build the 'xdvipdfmx' program.
1959
1960 
1961 File: tlbuild.info, Node: Configure options for texk/dvisvgm, Next: Configure options for texk/texlive, Prev: Configure options for texk/dvipdfm-x, Up: Program-specific configure options
1962
1963 7.2.6 Configure options for 'texk/dvisvgm'
1964 ------------------------------------------
1965
1966 '--with-system-libgs'
1967 Build 'dvisvgm' using installed Ghostscript ('gs') headers and library
1968 (not allowed for a native TL build). The default is to load the 'gs'
1969 library at runtime if possible, else to disable support for PostScript
1970 specials.
1971
1972 '--without-libgs'
1973 Build 'dvisvgm' without PostScript support at all. Because the dynamic
1974 loading just mentioned defeats all attempts at static linking, the
1975 result can crash due to library incompatibilities, e.g., on CentOS 5.
1976
1977 '--with-libgs-includes=DIR', '--with-libgs-libdir=DIR'
1978 Specify non-standard locations of the Ghostscript headers and library.
1979
1980 
1981 File: tlbuild.info, Node: Configure options for texk/texlive, Next: Configure options for texk/xdvik, Prev: Configure options for texk/dvisvgm, Up: Program-specific configure options
1982
1983 7.2.7 Configure options for 'texk/texlive'
1984 ------------------------------------------
1985
1986 '--disable-linked-scripts'
1987 Do not install the "linked scripts" (*note Linked scripts::), except for
1988 the TL scripts required to run 'texlinks'.
1989
1990 
1991 File: tlbuild.info, Node: Configure options for texk/xdvik, Next: Configure options for utils/xindy, Prev: Configure options for texk/texlive, Up: Program-specific configure options
1992
1993 7.2.8 Configure options for 'texk/xdvik'
1994 ----------------------------------------
1995
1996 '--with-gs=FILENAME'
1997 Hardwire the location of Ghostscript ('gs') as called by Xdvik.
1998
1999 '--with-xdvi-x-toolkit=KIT'
2000 Use toolkit 'KIT' for 'xdvik', one of: 'motif xaw xaw3d neXtaw'. The
2001 default is 'motif' if available, else 'xaw'.
2002
2003 '--enable-xi2-scrolling'
2004 Use XInput 2.1 "smooth scrolling" if available (default: yes, except for
2005 a native TL build).
2006
2007 
2008 File: tlbuild.info, Node: Configure options for utils/xindy, Prev: Configure options for texk/xdvik, Up: Program-specific configure options
2009
2010 7.2.9 Configure options for 'utils/xindy'
2011 -----------------------------------------
2012
2013 '--enable-xindy-rules'
2014 Build and install 'xindy' rules (default: yes, except for a native TL
2015 build).
2016
2017 '--enable-xindy-docs'
2018 Build and install 'xindy' documentation (default: yes, except for a
2019 native TL build).
2020
2021 '--with-clisp-runtime=FILENAME'
2022 Specifies the full path for the Clisp runtime file ('lisp.run' or
2023 'lisp.exe') to be installed. When specified as 'default' (the default
2024 for a native TL build) the path is determined by the Clisp executable;
2025 the value 'system' (not allowed for a native TL build, but the default
2026 otherwise) indicates that 'xindy' will use the installed version of
2027 'clisp' (which must be identical to the one used to build 'xindy').
2028
2029 
2030 File: tlbuild.info, Node: Library-specific configure options, Next: Variables for configure, Prev: Program-specific configure options, Up: Configure options
2031
2032 7.3 Library-specific configure options
2033 ======================================
2034
2035 Here are (some of) the library-specific 'configure' options, starting
2036 with this generic one:
2037
2038 '--with-system-LIB'
2039
2040 Use an installed (system) version of the library 'LIB'; this option
2041 exists for most libraries, but is not allowed for a native TL build.
2042 Using a system version implies also using the system versions of all
2043 libraries that LIB depends on.
2044
2045 For many libraries '--with-LIB-includes=DIR' and
2046 '--with-LIB-libdir=DIR' can specify non-standard search locations;
2047 others use 'pkg-config' or similar to determine the required flags.
2048
2049 The top-level 'configure' script performs a consistency check for all
2050 required system libraries and bails out if tests fail.
2051
2052 * Menu:
2053
2054 * Configure options for kpathsea::
2055
2056 
2057 File: tlbuild.info, Node: Configure options for kpathsea, Up: Library-specific configure options
2058
2059 7.3.1 Configure options for 'kpathsea'
2060 --------------------------------------
2061
2062 '--enable-CMD-default', '--disable-CMD-default'
2063 Determine the compile time default for whether or not to run CMD, which
2064 is one of:
2065 'mkocp'
2066 (Omega compiled translation process file)
2067 'mkofm'
2068 (Omega font metrics file)
2069 'mktexfmt'
2070 (format/base dump file)
2071 'mktexmf'
2072 (Metafont source)
2073 'mktexpk'
2074 (PK bitmap font)
2075 'mktextex'
2076 (TeX source)
2077 'mktextfm'
2078 (TFM file)
2079
2080 to generate the specified type of file dynamically. The default can be
2081 overridden by the user in any case (*note kpathsea library::).
2082
2083 
2084 File: tlbuild.info, Node: Variables for configure, Prev: Library-specific configure options, Up: Configure options
2085
2086 7.4 Variables for configure
2087 ===========================
2088
2089 The values for these variables can be specified as 'configure' arguments
2090 of the form 'VAR=VALUE'. They can also be defined in the environment,
2091 but that might not work for cross compilations.
2092
2093 'CC'
2094 'CXX'
2095 'CPPFLAGS'
2096 And plenty more. As usual with Autoconf, these variables specify
2097 the name (or full path) of compilers, preprocessor flags, and
2098 similar. *Note (autoconf)Preset Output Variables::.
2099
2100 'CLISP'
2101 Name (or full path) of the 'clisp' executable, used to build
2102 'xindy'.
2103
2104 'FT2_CONFIG'
2105 'ICU_CONFIG'
2106 'PKG_CONFIG'
2107 These specify the name (or path) for the 'freetype-config',
2108 'icu-config', and 'pkg-config' commands used to determine the flags
2109 required for system versions of 'libfreetype', the ICU libraries,
2110 and other libraries, respectively.
2111
2112 'KPSEWHICH'
2113 Name (or path) of an installed 'kpsewhich' binary, used by 'make
2114 check' to determine the location of, e.g., 'cmbx10.tfm'.
2115
2116 'MAKE'
2117 'SED'
2118 And more. Name (or path) of the 'make', 'sed', and similar
2119 programs; used at the top level and propagated to all
2120 subdirectories.
2121
2122 'PERL'
2123 'LATEX'
2124 'PDFLATEX'
2125 Name (or full path) for the 'perl', 'latex', and 'pdflatex'
2126 commands used, e.g., to build the 'xindy' documentation.
2127
2128 
2129 File: tlbuild.info, Node: Coding conventions, Next: Continuous integration, Prev: Configure options, Up: Top
2130
2131 8 Coding conventions
2132 ********************
2133
2134 Ideally, building all of TeX Live with '--enable-compiler-warnings=max'
2135 should produce no (GCC) compiler warnings at all. In spite of
2136 considerable efforts into that direction we are still far from that goal
2137 and there are reasons that we may never fully reach it. Below are some
2138 rules about declarations of functions or variables and the use of
2139 'const'. These rules should be applied to the code maintained in the
2140 TeX Live tree and for other packages whose maintainers are willing to
2141 accept patches.
2142
2143 * Menu:
2144
2145 * Declarations and definitions::
2146 * Const::
2147
2148 
2149 File: tlbuild.info, Node: Declarations and definitions, Next: Const, Up: Coding conventions
2150
2151 8.1 Declarations and definitions
2152 ================================
2153
2154 C standards
2155 ...........
2156
2157 The TeX Live build system no longer supports pre-ANSI C compilers. Thus
2158 all function prototypes and definitions must conform to the ANSI C
2159 standard (including 'void' in the declaration of C functions with no
2160 parameters). On the other hand, TL is built for a wide variety of
2161 systems, not all of which support the C99 standard. Therefore using C99
2162 features should be avoided if that can easily be done. In particular, C
2163 code must not contain declarations after statements or C++-style
2164 comments.
2165
2166 If some C99 (or later) constructs must be used, the module should
2167 verify that they are available and otherwise provide an alternative.
2168 For example, the module 'texk/chktex' uses the C99 function 'stpcpy()'
2169 that may or may not be available on a particular system. It uses
2170 'AC_CHECK_DECLS([stpcpy])' in 'configure.ac' to test this, and provides
2171 a perhaps less efficient alternative (in the file 'Utility.h'):
2172
2173 #if !(defined HAVE_DECL_STPCPY && HAVE_DECL_STPCPY)
2174 static inline char *stpcpy(char *dest, const char *src)
2175 {
2176 return strcpy(dest, src) + strlen(src);
2177 }
2178 #endif
2179
2180 Static functions
2181 ................
2182
2183 Functions used in only one file should be declared 'static'; they
2184 require no prototype except in forward declarations.
2185
2186 Extern functions
2187 ................
2188
2189 Functions not declared 'static', usually because they are used in
2190 several files, require an ('extern') prototype in exactly one header
2191 file, which is included in the file defining the function and in all
2192 files using that function--this is the only way to guarantee consistency
2193 between definition and use. There should be no 'extern' declarations
2194 sprinkled throughout the C code (with or without comments as to where
2195 that function is defined).
2196
2197 Variable declarations
2198 .....................
2199
2200 The declaration of global variables follows analogous rules: they are
2201 either declared 'static' if used in only one file or declared 'extern'
2202 in exactly one header and instantiated in exactly one file.
2203
2204 
2205 File: tlbuild.info, Node: Const, Prev: Declarations and definitions, Up: Coding conventions
2206
2207 8.2 Const
2208 =========
2209
2210 The 'const' feature of C is valuable, but easy to mis-use.
2211
2212 Function parameters
2213 ...................
2214
2215 Ideally, a function parameter not modified by the function should be
2216 declared as 'const'. This is important in particular for strings
2217 ('char*') because the actual arguments are often string literals. It is
2218 perfectly legitimate and safe to use a type 'char*' value for a type
2219 'const char*' variable (in an assignment, as initializer, as function
2220 argument, or as return value). It is equally safe to use a type
2221 'char**' value for a type 'const char*const*' variable, but not for a
2222 type 'const char**' variable since that might cause modification of a
2223 quantity supposed to be constant.
2224
2225 Getting all 'const' qualifiers right can get quite involved but can
2226 almost always be done. There are only a couple notable exceptions: the
2227 X11 headers are full of declarations that ought to use 'const' but do
2228 not; at one time, 'libfreetype' also did not fully specify 'const', but
2229 this has not been checked recently.
2230
2231 What must be avoided with 'const'
2232 .................................
2233
2234 The GCC compiler warnings "assignment discards qualifiers..." and
2235 analogous warnings for "initialization", "passing arg", or "return" must
2236 be strenuously avoided in our own code. The only exception is when they
2237 are caused by X11 declarations or other third party code.
2238
2239 What should be avoided with 'const'
2240 ...................................
2241
2242 A type cast, e.g., from 'const char*' to 'char*' does not solve any
2243 problems; depending on warning options, it may only hide them.
2244 Therefore such casts should be avoided whenever possible and otherwise
2245 must be carefully analyzed to make sure that they cannot cause the
2246 modification of quantities supposed to be constant.
2247
2248 
2249 File: tlbuild.info, Node: Continuous integration, Next: install-tl, Prev: Coding conventions, Up: Top
2250
2251 9 Continuous integration
2252 ************************
2253
2254 The TeX Live sources are subjected to continuous integration testing on
2255 Travis-CI (<https://travis-ci.org/TeX-Live/texlive-source>) via a
2256 git-svn mirror of the sources that is pushed to Github
2257 (<https://github.com/TeX-Live/texlive-source>). The git-svn mirror is
2258 updated (currently) at 30 minute intervals, and only the last commit
2259 pushed is tested on Travis-CI.
2260
2261 * Menu:
2262
2263 * Transfer from Subversion to Github::
2264 * Automatic update of the Git mirror::
2265 * CI testing on Travis-CI::
2266 * Releases on Github::
2267
2268 
2269 File: tlbuild.info, Node: Transfer from Subversion to Github, Next: Automatic update of the Git mirror, Up: Continuous integration
2270
2271 9.1 Transfer from Subversion to Github
2272 ======================================
2273
2274 The git-svn program (<https://git-scm.com/docs/git-svn>) is used to
2275 check out the subtree 'Build/source' of the canonical Subversion
2276 repository. The author index file used is not maintained in either Git
2277 or Subversion but can be provided on request.
2278
2279 The initial checkout was done by invoking
2280 git svn --authors-file usermap clone \
2281 svn://[email protected]/texlive/trunk/Build/source
2282
2283 where the 'usermap' file maps Subversion user names to name and emails
2284 of the authors. Anonymous checkout is also possible:
2285 git svn --authors-file usermap clone \
2286 svn://tug.org/texlive/trunk/Build/source
2287
2288 In the following, we will use _admin_ to refer to a user who has
2289 read/write access to the TeX Live subversion repository, and is also an
2290 administrator of the ''TeX-Live'' team at Github. The above initial
2291 checkout has been carried out by _admin_ on the server 'texlive.info'.
2292
2293 On Github, a new git repository named 'texlive-source' was created by
2294 _admin_ within the 'TeX-Live' "organization"
2295 (<https://github.com/TeX-Live>). The remote was added to the checkout
2296 with 'git remote add origin [email protected]:TeX-Live/texlive-source.git'.
2297
2298 To automate the update on Github, a new ssh key was generated and
2299 added to the 'texlive-source' repository on Github as deployment key.
2300 Thus, pushes using this key can only go to the 'texlive-source'
2301 repository and not anywhere else.
2302
2303 The usage of 'git-svn' requires a strict discipline to keep a linear
2304 history in the master branch. Since we are aiming at a pure mirror
2305 facility on Github, we have decided to further restrict the 'master'
2306 branch of the 'texlive-source' repository on Github to changes by
2307 _admin_.
2308
2309 This setup allows other developers to branch off 'master' and push
2310 their branches to the Github repository, but all updates need to come
2311 from the local 'master' (not the one on Github) to Subversion, back to
2312 'master' on 'texlive.info', and from there to Github.
2313
2314 
2315 File: tlbuild.info, Node: Automatic update of the Git mirror, Next: CI testing on Travis-CI, Prev: Transfer from Subversion to Github, Up: Continuous integration
2316
2317 9.2 Automatic update of the Git mirror
2318 ======================================
2319
2320 _admin_ has installed a cron job on 'texlive.info' running every 30
2321 minute which essentially runs 'git svn rebase' and 'git push' in the
2322 'master' branch of the checkout. The first command fetches the changes
2323 from the Subversion repository and updates the 'master' branch with
2324 them, and the second pushes changes (if any) to Github.
2325
2326 
2327 File: tlbuild.info, Node: CI testing on Travis-CI, Next: Releases on Github, Prev: Automatic update of the Git mirror, Up: Continuous integration
2328
2329 9.3 CI testing on Travis-CI
2330 ===========================
2331
2332 The 'source' tree of TeX Live contains a top-level file '.travis.yml'
2333 which controls the automatic testing on Travis-CI. _admin_ has
2334 registered with Travis-CI and allowed access to the Github's 'TeX-Live'
2335 organization's 'texlive-source' repository. The default settings are to
2336 build the last commit of each push. No further action is necessary on
2337 Travis-CI.
2338
2339 If changes have been pushed via the cron job above, Travis-CI will
2340 automatically checkout the last pushed commit and try building it.
2341
2342 
2343 File: tlbuild.info, Node: Releases on Github, Prev: CI testing on Travis-CI, Up: Continuous integration
2344
2345 9.4 Releases on Github
2346 ======================
2347
2348 Given a git checkout of 'texlive-source':
2349
2350 git pull
2351 git tag build-svnNNNN
2352 git push --tags
2353
2354 and the result will appear at
2355 <https://github.com/TeX-Live/texlive-source/releases>. Releases can
2356 also be made manually from that web page (see 'tl-update-bindir' for
2357 hints).
2358
2359 
2360 File: tlbuild.info, Node: install-tl, Next: tlmgr, Prev: Continuous integration, Up: Top
2361
2362 Appendix A install-tl
2363 *********************
2364
2365 * Menu:
2366
2367 * install-tl NAME::
2368 * install-tl SYNOPSIS::
2369 * install-tl DESCRIPTION::
2370 * install-tl REFERENCES::
2371 * install-tl EXAMPLES::
2372 * install-tl OPTIONS::
2373 * install-tl PROFILES::
2374 * install-tl ENVIRONMENT VARIABLES::
2375 * install-tl DIRECTORY TREES::
2376 * install-tl BUGS::
2377 * install-tl AUTHORS AND COPYRIGHT::
2378
2379 
2380 File: tlbuild.info, Node: install-tl NAME, Next: install-tl SYNOPSIS, Up: install-tl
2381
2382 A.1 install-tl NAME
2383 ===================
2384
2385 install-tl - TeX Live cross-platform installer
2386
2387 
2388 File: tlbuild.info, Node: install-tl SYNOPSIS, Next: install-tl DESCRIPTION, Prev: install-tl NAME, Up: install-tl
2389
2390 A.2 install-tl SYNOPSIS
2391 =======================
2392
2393 install-tl [_option_]...
2394
2395 install-tl-windows.bat [_option_]...
2396
2397 
2398 File: tlbuild.info, Node: install-tl DESCRIPTION, Next: install-tl REFERENCES, Prev: install-tl SYNOPSIS, Up: install-tl
2399
2400 A.3 install-tl DESCRIPTION
2401 ==========================
2402
2403 This installer creates a runnable TeX Live installation from various
2404 media, including over the network, from local hard disk, a DVD, etc.
2405 The installer works on all platforms supported by TeX Live. For
2406 information on initially downloading TeX Live, see
2407 <https://tug.org/texlive/acquire.html>.
2408
2409 The basic idea of TeX Live installation is for you to choose one of
2410 the top-level _schemes_, each of which is defined as a different set of
2411 _collections_ and _packages_, where a collection is a set of packages,
2412 and a package is what contains actual files. Each package is in exactly
2413 one collection, while schemes can contain any combination of packages
2414 and collections.
2415
2416 Within the installer, you can choose a scheme, and further customize
2417 the set of collections to install, but not the set of the packages. To
2418 work at the package level, use 'tlmgr' (reference just below) after the
2419 initial installation is complete.
2420
2421 The default is 'scheme-full', which installs everything, and this is
2422 highly recommended.
2423
2424 
2425 File: tlbuild.info, Node: install-tl REFERENCES, Next: install-tl EXAMPLES, Prev: install-tl DESCRIPTION, Up: install-tl
2426
2427 A.4 REFERENCES
2428 ==============
2429
2430 Post-installation configuration, package updates, and more, are handled
2431 through *tlmgr*(1), the TeX Live Manager
2432 (<https://tug.org/texlive/tlmgr.html>).
2433
2434 The most up-to-date version of this installer documentation is on the
2435 Internet at <https://tug.org/texlive/doc/install-tl.html>.
2436
2437 For step-by-step instructions, see
2438 <https://tug.org/texlive/quickinstall.html>.
2439
2440 For the full documentation of TeX Live, see
2441 <https://tug.org/texlive/doc>.
2442
2443 
2444 File: tlbuild.info, Node: install-tl EXAMPLES, Next: install-tl OPTIONS, Prev: install-tl REFERENCES, Up: install-tl
2445
2446 A.5 install-tl EXAMPLES
2447 =======================
2448
2449 With no options, 'install-tl' drops you into an interactive menu where
2450 essentially all default settings can be changed. With options, you can
2451 initialize the settings in various ways, or perform the installation
2452 without interaction. Some examples:
2453
2454 'install-tl --paper=letter'
2455
2456 Initialize paper size setting. The only values allowed are
2457 'letter' and (the default) 'a4'.
2458
2459 'install-tl --scheme' _scheme_
2460
2461 Initialize the installation scheme; the default is 'full'. For a
2462 list of schemes, see the interactive 'S' menu.
2463
2464 'install-tl --no-interaction'
2465
2466 Perform the installation immediately after parsing options, without
2467 entering the interactive menu.
2468
2469 'install-tl --profile' _texlive.profile_
2470
2471 Install, without interaction, according to the given TL profile
2472 file; see *note PROFILES: install-tl PROFILES. below. To
2473 initialize from the profile and then enter the interactive menu,
2474 add '--init-from-profile'.
2475
2476 Full documentation follows.
2477
2478 
2479 File: tlbuild.info, Node: install-tl OPTIONS, Next: install-tl PROFILES, Prev: install-tl EXAMPLES, Up: install-tl
2480
2481 A.6 install-tl OPTIONS
2482 ======================
2483
2484 As usual, all options can be specified in any order, and with either a
2485 leading '-' or '--'. An argument value can be separated from its option
2486 by either a space or '='.
2487
2488 The options relating to customization of the installation can also be
2489 selected in the interactive installation menus (GUI or text).
2490
2491 *-gui* [[=]_module_]
2492
2493 *-no-gui*
2494
2495 If no _module_ is given, starts the Tcl/Tk (see below) GUI
2496 installer.
2497
2498 If _module_ is given loads the given installer module. Currently
2499 the following modules are supported:
2500
2501 'text'
2502
2503 The text mode user interface (default on Unix systems,
2504 including Macs). Same as the '-no-gui' option.
2505
2506 'tcl' (or "perltk" or "wizard" or "expert" or nothing)
2507
2508 The Tcl/Tk user interface (default on Windows). It starts
2509 with a small number of configuration options, roughly
2510 equivalent to what the former wizard option offers, but a
2511 button 'Advanced' takes you to a screen with roughly the same
2512 options as the former 'perltk' interface.
2513
2514 The default GUI requires Tcl/Tk. This was standard on Macs, but
2515 has been removed in the latest macOS releases. It's often already
2516 installed on GNU/Linux, or can be easily installed through a distro
2517 package manager. For Windows, TeX Live provides a Tcl/Tk runtime.
2518
2519 *-lang* _llcode_
2520
2521 By default, the Tcl GUI uses the language detection built into
2522 Tcl/Tk. If that fails you can select a different language by
2523 giving this option with a language code (based on ISO 639-1).
2524 Currently supported (but not necessarily completely translated)
2525 are: English (en, default), Czech (cs), German (de), French (fr),
2526 Italian (it), Japanese (ja), Dutch (nl), Polish (pl), Brazilian
2527 Portuguese (pt_BR), Russian (ru), Slovak (sk), Slovenian (sl),
2528 Serbian (sr), Ukrainian (uk), Vietnamese (vi), simplified Chinese
2529 (zh_CN), and traditional Chinese (zh_TW).
2530
2531 *-repository* _url|path_
2532
2533 Specify the package repository to be used as the source of the
2534 installation. In short, this can be a directory name or a url
2535 using http(s), ftp, or scp. The documentation for 'tlmgr' has the
2536 details (<https://tug.org/texlive/doc/tlmgr.html#OPTIONS>).
2537
2538 For installation, the default is to pick a mirror automatically,
2539 using <https://mirror.ctan.org/systems/texlive/tlnet>; the chosen
2540 mirror is then used for the entire download. You can use the
2541 special argument 'ctan' as an abbreviation for this. (See
2542 <https://ctan.org> for more about CTAN and its mirrors.)
2543
2544 After installation is complete, you can use that installation as
2545 the repository for another installation. If you chose to install
2546 less than the full scheme containing all packages, the list of
2547 available schemes will be adjusted accordingly.
2548
2549 *-select-repository*
2550
2551 This option allows you to choose a particular mirror from the
2552 current list of active CTAN mirrors. This option is supported in
2553 the 'text' and 'gui' installer modes, and will also offer to
2554 install from local media if available, or from a repository
2555 specified on the command line. It's useful when the (default)
2556 automatic redirection does not choose a good host for you.
2557
2558 *-all-options*
2559
2560 Normally options not relevant to the current platform are not shown
2561 (e.g., when running on Unix, Windows-specific options are omitted).
2562 Giving this command line option allows configuring such "foreign"
2563 settings.
2564
2565 *-custom-bin* _path_
2566
2567 If you have built your own set of TeX Live binaries (e.g., because
2568 precompiled binaries were not provided by TL for your platform),
2569 this option allows you to specify the _path_ to a directory where
2570 the binaries for the current system are present. The installation
2571 will continue as usual, but at the end all files from _path_ are
2572 copied over to 'bin/custom/' under your installation directory and
2573 this 'bin/custom/' directory is what will be added to the path for
2574 the post-install actions. To install multiple custom binary sets,
2575 manually rename 'custom' before doing each.
2576
2577 For more information on custom binaries, see
2578 <https://tug.org/texlive/custom-bin.html>. For general information
2579 on building TeX Live, see <https://tug.org/texlive/build.html>.
2580
2581 *-debug-fakenet*
2582
2583 Pretend we're doing a network install. This is for the sole
2584 purpose of testing the code to handle broken downloads, via moving
2585 package files aside in a tlnet mirror hierarchy.
2586
2587 *-debug-setup-vars*
2588
2589 Print final values of directory variables; for more debugging
2590 information on how they were set, also specify '-v'.
2591
2592 *-debug-translation*
2593
2594 In the former Perl/Tk GUI modes, this option reported any missing,
2595 or more likely untranslated, messages to standard error. Not yet
2596 implemented for the Tcl interface. Helpful for translators to see
2597 what remains to be done.
2598
2599 *-force-platform* _platform_
2600
2601 Instead of auto-detecting the current platform, use _platform_.
2602 Binaries for this platform must be present in 'bin/'_platform_'/'
2603 and they must be runnable, or installation will fail.
2604 '-force-arch' is a synonym.
2605
2606 *-help*, *--help*, *-?*
2607
2608 Display this help and exit. (This help is also on the web at
2609 <https://tug.org/texlive/doc/install-tl.html>). Sometimes the
2610 'perldoc' and/or 'PAGER' programs on the system have problems,
2611 possibly resulting in control characters being literally output.
2612 This can't always be detected, but you can set the 'NOPERLDOC'
2613 environment variable and 'perldoc' will not be used.
2614
2615 *-in-place*
2616
2617 This is a quick-and-dirty installation option in case you already
2618 have an rsync or svn checkout of TeX Live. It will use the
2619 checkout as-is and will just do the necessary post-install. Be
2620 warned that the file 'tlpkg/texlive.tlpdb' may be rewritten, that
2621 removal has to be done manually, and that the only realistic way to
2622 maintain this installation is to redo it from time to time. This
2623 option is not available via the installer interfaces. USE AT YOUR
2624 OWN RISK.
2625
2626 *-init-from-profile* _profile_file_
2627
2628 Similar to *-profile* (see *note PROFILES: install-tl PROFILES.
2629 below), but only initializes the installation configuration from
2630 _profile_file_ and then starts a normal interactive session.
2631 Environment variables are not ignored.
2632
2633 *-logfile* _file_
2634
2635 Write both all messages (informational, debugging, warnings) to
2636 _file_, in addition to standard output or standard error.
2637
2638 If this option is not given, the installer will create a log file
2639 in the root of the writable installation tree, for example,
2640 '/usr/local/texlive/YYYY/install-tl.log' for the _YYYY_ release.
2641
2642 *-no-cls*
2643
2644 For the text mode installer only: do not clear the screen when
2645 entering a new menu. For debugging.
2646
2647 *-no-continue*
2648
2649 Quit early on installation failure of a non-core package.
2650
2651 By default, a few core packages are installed first; then, a failed
2652 installation of any other (non-core) package is noted, but does not
2653 stop the installation. Any such failed packages are retried, once.
2654
2655 If the retry also fails, by default the installer proceeds to
2656 completion anyway, with the idea that it was a transient network
2657 problem and reinstallation will succeed later. If this option is
2658 specified, and the retry fails, the installer aborts.
2659
2660 *-no-doc-install*
2661
2662 *-no-src-install*
2663
2664 Do not install the documentation resp. source package files, both
2665 for the immediate installation and for future updates. After
2666 installation, inclusion of the doc/src files can be re-enabled via
2667 'tlmgr':
2668
2669 tlmgr option docfiles 1
2670 tlmgr option srcfiles 1
2671
2672 If you later find that you want the doc/src files for a package
2673 that has been installed without them, you can get them like this
2674 (using the 'fontspec' package as the example):
2675
2676 tlmgr install --reinstall --with-doc --with-src fontspec
2677
2678 The source files mentioned here are those relating to TeX packages,
2679 such as '.dtx' files. The sources that are compiled to make the
2680 binaries are available separately: see
2681 <https://tug.org/texlive/svn/>.
2682
2683 *-no-installation*
2684
2685 Do not perform any installation. This is for debugging the
2686 initialization and setup routines without touching the disk.
2687
2688 *-no-interaction*
2689
2690 Do not enter the interactive menu; immediately perform the
2691 installation after initialization and option parsing. Also omit
2692 the check for a previous installation and asking about importing
2693 previous settings.
2694
2695 *-no-persistent-downloads*
2696
2697 *-persistent-downloads*
2698
2699 For network installs, activating this option makes the installer
2700 try to set up a persistent connection using the 'LWP' Perl module.
2701 This opens only one connection between your computer and the server
2702 per session and reuses it, instead of initiating a new download for
2703 each package, which typically yields a significant speed-up.
2704
2705 This option is turned on by default, and the installation program
2706 will fall back to using 'wget' if this is not possible. To disable
2707 usage of LWP and persistent connections, use
2708 '-no-persistent-downloads'.
2709
2710 *-no-verify-downloads*
2711
2712 By default, if a GnuPG 'gpg' binary is found in PATH, downloads are
2713 verified against a cryptographic signature. This option disables
2714 such verification. The full description is in the Crytographic
2715 Verification section of the 'tlmgr' documentation, e.g.,
2716 <https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION>
2717
2718 *-non-admin*
2719
2720 For Windows only: configure for the current user, not for all
2721 users.
2722
2723 *-paper* 'a4'*|*'letter'
2724
2725 Set the default paper size for all TeX Live programs, as specified.
2726 The default is 'a4'. The paper size can be set after installation
2727 with the 'tlmgr paper' command.
2728
2729 *-portable*
2730
2731 Install for portable use, e.g., on a USB stick. See the
2732 'instopt_portable' description below for details.
2733
2734 *-print-platform*
2735
2736 Print the TeX Live identifier for the detected platform
2737 (hardware/operating system) combination to standard output, and
2738 exit. '-print-arch' is a synonym.
2739
2740 *-profile* _profile_file_
2741
2742 Load _profile_file_ and do the installation with no user
2743 interaction, that is, a batch (unattended) install. Environment
2744 variables are ignored. See *note PROFILES: install-tl PROFILES.
2745 below.
2746
2747 *-q*
2748
2749 Omit normal informational messages.
2750
2751 *-scheme* _scheme_
2752
2753 Schemes are the highest level of package grouping in TeX Live; the
2754 default is to use the 'full' scheme, which includes everything.
2755 This option overrides that default. The _scheme_ argument value
2756 may optionally have a prefix 'scheme-'. The list of supported
2757 scheme names depends on what your package repository provides; see
2758 the interactive menu list.
2759
2760 *-texdir* _dir_
2761
2762 Specify the system installation directory; the default is
2763 '/usr/local/texlive/YYYY' for release YYYY. Specifying this option
2764 also causes the 'TEXMFLOCAL', 'TEXMFSYSCONFIG', and 'TEXMFSYSVAR'
2765 directories to be set as subdirectories of _dir_, so they don't
2766 have to be set individually.
2767
2768 There is a brief summary of these directories trees at *note
2769 DIRECTORY TREES: install-tl DIRECTORY TREES. below; for details on
2770 the trees set up by default, and their intended usage, see the main
2771 TeX Live documentation at <https://tug.org/texlive/doc>.
2772
2773 *-texuserdir* _dir_
2774
2775 Specify the user installation directory; the default is
2776 '~/.texliveYYYY' (except on Macs, where there is no leading dot).
2777 Specifying this also causes the 'TEXMFHOME', 'TEXMFCONFIG', and
2778 'TEXMFVAR' directories to be set as subdirectories of _dir_.
2779
2780 *-texmflocal* _dir_
2781
2782 Specify the 'TEXMFLOCAL' directory; the default is
2783 '/usr/local/texlive/texmf-local', that is, one level up from the
2784 main installation. This is so locally-installed packages can be
2785 easily used across releases, which is usually desirable.
2786 Specifying the '-texdir' option changes this, putting 'TEXMFLOCAL'
2787 under the main tree. The '-texmflocal' option can be used to
2788 specify an explicit directory.
2789
2790 Anything installed here must follow the TeX directory structure
2791 (TDS), e.g., 'TEXMFHOME/tex/latex/mypkg/mypkg.sty'. TDS reference:
2792 <https://tug.org/tds>.
2793
2794 *-texmfhome* _dir_
2795
2796 Specify the 'TEXMFHOME' directory; the default is '~/texmf', except
2797 on Macs, where it is '~/Library/texmf'. Analogously to
2798 'TEXMFLOCAL', the '-texuserdir' option changes this default.
2799
2800 Also as with 'TEXMFLOCAL', anything installed here must follow the
2801 TDS.
2802
2803 *-texmfsysconfig* _dir_
2804
2805 *-texmfsysvar* _dir_
2806
2807 Specify the 'TEXMFSYSCONFIG' and 'TEXMFSYSVAR' system directories.
2808
2809 *-texmfconfig* _dir_
2810
2811 *-texmfvar* _dir_
2812
2813 Specify the 'TEXMFCONFIG' and 'TEXMFVAR' user directories. The
2814 defaults are '~/.texliveYYYY/texmf-{config,var}', except on Macs,
2815 where the leading dot is omitted ('~/texliveYYYY/...').
2816
2817 *-v*
2818
2819 Include verbose debugging messages; repeat for maximum debugging:
2820 '-v -v'. (Further repeats are accepted but ignored.)
2821
2822 *-version*, *--version*
2823
2824 Output version information and exit. If '-v' is also given, the
2825 versions of the TeX Live modules used are also reported.
2826
2827 
2828 File: tlbuild.info, Node: install-tl PROFILES, Next: install-tl ENVIRONMENT VARIABLES, Prev: install-tl OPTIONS, Up: install-tl
2829
2830 A.7 PROFILES
2831 ============
2832
2833 A _profile_ file normally contains all the values needed to perform an
2834 installation. After a normal installation has finished, a profile for
2835 that exact installation is written to the file 'tlpkg/texlive.profile'.
2836 In addition, from the text menu one can select 'P' to save the current
2837 setup as a profile at any time. These are small text files; feel free
2838 to peruse and edit them according to your needs.
2839
2840 Such a profile file can be given as the argument to '-profile', for
2841 example to redo the exact same installation on a different system.
2842 Alternatively, you can use a custom profile, most easily created by
2843 starting from a generated one and changing values. An empty profile
2844 file will cause the installer to use the defaults.
2845
2846 As mentioned above, the installer only supports selection by scheme
2847 and collections, not individual packages, so packages cannot be
2848 specified in profile files either. Use 'tlmgr' to work at the package
2849 level.
2850
2851 Within a profile file, each line consists of
2852
2853 _variable_ [_value_]
2854
2855 except for comment lines starting with '#'. The possible variable
2856 names are listed below. Values, when present, are either '0' or '1' for
2857 booleans, or strings (which must be specified without any quote
2858 characters). Leading whitespace is ignored.
2859
2860 If the variable 'selected_scheme' is defined and _no_ collection
2861 variables at all are defined, then the collections required by the
2862 specified scheme (which might change over time) are installed, without
2863 explicitly listing them. This eases maintenance of profile files. If
2864 any collections are specified in a profile, though, then the scheme is
2865 ignored and all desired collections must be given explicitly.
2866
2867 For example, a line
2868
2869 selected_scheme scheme-small
2870
2871 along with definitions for the installation directories (given below
2872 under "path options") suffices to install the "small" scheme with all
2873 default options. The schemes are described in the 'S' menu in the text
2874 installer, or equivalent.
2875
2876 In addition to 'selected_scheme', here are the other variable names
2877 supported in a profile:
2878
2879 *collection options* (prefix 'collection-')
2880
2881 Collections are specified with a variable name with the prefix
2882 'collection-' followed by a collection name; there is no value. For
2883 instance, 'collection-basic'. The collections are described in the 'C'
2884 menu.
2885
2886 Schemes and collections (and packages) are ultimately defined by the
2887 files in the 'tlpkg/tlpsrc/' source directory.
2888
2889 *path options*
2890
2891 It is best to define all of these, even though they may not be used
2892 in a given installation, so as to avoid unintentionally getting a
2893 default value that could cause problems later.
2894
2895 TEXDIR
2896 TEXMFLOCAL
2897 TEXMFSYSCONFIG
2898 TEXMFSYSVAR
2899 TEXMFCONFIG
2900 TEXMFVAR
2901 TEXMFHOME
2902
2903 *installer options* (prefix 'instopt_')
2904
2905 'instopt_adjustpath' (default 0 on Unix, 1 on Windows)
2906
2907 Adjust 'PATH' environment variable.
2908
2909 'instopt_adjustrepo' (default 1)
2910
2911 Set remote repository to a multiplexed CTAN mirror after
2912 installation; see '-repository' above.
2913
2914 'instopt_letter' (default 0)
2915
2916 Set letter size paper as the default, instead of a4.
2917
2918 'instopt_portable' (default 0)
2919
2920 Install for portable use, e.g., on a USB stick, without touching
2921 the host system. Specifically, this forces the user directories
2922 'TEXMFHOME', 'TEXMFCONFIG', 'TEXMFVAR' to be identical to the
2923 system directories 'TEXMFLOCAL', 'TEXMFSYSCONFIG', 'TEXMFSYSVAR',
2924 respectively (regardless of other options and environment
2925 variable.)
2926
2927 In addition, on Windows, it disables the desktop integration, path
2928 adjustment, and file associations actions usually performed.
2929
2930 'instopt_write18_restricted' (default 1)
2931
2932 Enable '\write18' for a restricted set of programs.
2933
2934 *tlpdb options* (prefix 'tlpdbopt_')
2935
2936 The definitive list is given in 'tlpkg/TeXLive/TLConfig.pm', in the
2937 hash '%TeXLive::TLConfig::TLPDBOptions', together with explanations.
2938 All items given there _except_ for 'tlpdbopt_location' can be specified.
2939 Here is the current list:
2940
2941 tlpdbopt_autobackup
2942 tlpdbopt_backupdir
2943 tlpdbopt_create_formats
2944 tlpdbopt_desktop_integration
2945 tlpdbopt_file_assocs
2946 tlpdbopt_generate_updmap
2947 tlpdbopt_install_docfiles
2948 tlpdbopt_install_srcfiles
2949 tlpdbopt_post_code
2950 tlpdbopt_sys_bin
2951 tlpdbopt_sys_info
2952 tlpdbopt_sys_man
2953 tlpdbopt_w32_multi_user
2954
2955 *platform options* (prefix 'binary_')
2956
2957 For each supported platform in TeX Live (directories under 'bin/'),
2958 the variable 'binary_'_PLATFORM_ can be set with value 1. For example:
2959
2960 binary_x86_64-linux 1
2961
2962 If no 'binary_' settings are made, the default is whatever the
2963 current machine is running.
2964
2965 In releases before 2017, many profile variables had different names
2966 (not documented here; see the 'install-tl' source). They are accepted
2967 and transformed to the names given above. When a profile is written,
2968 the names above are always used.
2969
2970 For more details on all of the above options, consult the TeX Live
2971 installation manual, linked from <https://tug.org/texlive/doc>.
2972
2973 
2974 File: tlbuild.info, Node: install-tl ENVIRONMENT VARIABLES, Next: install-tl DIRECTORY TREES, Prev: install-tl PROFILES, Up: install-tl
2975
2976 A.8 ENVIRONMENT VARIABLES
2977 =========================
2978
2979 For ease in scripting and debugging, 'install-tl' looks for the
2980 following environment variables. They are not of interest for normal
2981 user installations.
2982
2983 'NOPERLDOC'
2984
2985 Don't try to run the '--help' message through 'perldoc'.
2986
2987 'TEXLIVE_DOWNLOADER'
2988
2989 'TL_DOWNLOAD_PROGRAM'
2990
2991 'TL_DOWNLOAD_ARGS'
2992
2993 'TEXLIVE_PREFER_OWN'
2994
2995 These override the normal choice of the download and other utility
2996 programs; see the 'tlmgr' documentation, e.g.,
2997 <https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES>.
2998
2999 'TEXLIVE_INSTALL_ENV_NOCHECK'
3000
3001 Omit the check for environment variables containing the string
3002 'tex'. People developing TeX-related software are likely to have
3003 many such variables.
3004
3005 'TEXLIVE_INSTALL_NO_CONTEXT_CACHE'
3006
3007 Omit creating the ConTeXt cache. This is useful for
3008 redistributors.
3009
3010 'TEXLIVE_INSTALL_NO_DISKCHECK'
3011
3012 If set to 1, omit free disk space check. By default, if a
3013 POSIX-compliant 'df' program (supporting '-Pk') is available, the
3014 installer checks for available disk space in the selected
3015 installation location, and will abort installation if there is
3016 insufficient disk space, plus a margin of 100MB. An equivalent
3017 check is made on Windows (not involving 'df').
3018
3019 'TEXLIVE_INSTALL_NO_RESUME'
3020
3021 Omit check for installing on top of a previous installation and
3022 then asking about importing previous settings.
3023
3024 'TEXLIVE_INSTALL_NO_WELCOME'
3025
3026 Omit printing the welcome message after successful installation,
3027 e.g., when testing.
3028
3029 'TEXLIVE_INSTALL_PAPER'
3030
3031 Set the default paper size for all relevant programs; must be
3032 either 'letter' or 'a4'. The default is 'a4'.
3033
3034 'TEXLIVE_INSTALL_PREFIX'
3035
3036 'TEXLIVE_INSTALL_TEXMFCONFIG'
3037
3038 'TEXLIVE_INSTALL_TEXMFVAR'
3039
3040 'TEXLIVE_INSTALL_TEXMFHOME'
3041
3042 'TEXLIVE_INSTALL_TEXMFLOCAL'
3043
3044 'TEXLIVE_INSTALL_TEXMFSYSCONFIG'
3045
3046 'TEXLIVE_INSTALL_TEXMFSYSVAR'
3047
3048 Specify the respective directories. 'TEXLIVE_INSTALL_PREFIX'
3049 defaults to '/usr/local/texlive'. All the defaults can be seen by
3050 running the installer interactively and then typing 'D' for the
3051 directory menu.
3052
3053 The various command line options for specifying directories
3054 override these environment variables; since specifying both is
3055 usually accidental, a warning is given if the values are different.
3056
3057 
3058 File: tlbuild.info, Node: install-tl DIRECTORY TREES, Next: install-tl BUGS, Prev: install-tl ENVIRONMENT VARIABLES, Up: install-tl
3059
3060 A.9 DIRECTORY TREES
3061 ===================
3062
3063 There are a plethora of ways to specify the plethora of directory trees
3064 used by TeX Live. By far the simplest, and recommended, approach is not
3065 to change anything. The defaults suffice for the vast majority of
3066 installations.
3067
3068 But, for the sake of explanation, here is a table of the trees and
3069 the command line options that change them. The first group of three are
3070 system directories, and the second group of three are user directories;
3071 the two groups are quite analogous.
3072
3073 +----------------+--------------------------------------+--------------+------------------+
3074 | tree | default | group change | single change |
3075 +----------------+--------------------------------------+--------------+------------------+
3076 | TEXMFLOCAL | /usr/local/texlive/texmf-local | --texdir | --texmflocal |
3077 | TEXMFSYSVAR | /usr/local/texlive/YYYY/texmf-var | --texdir | --texmfsysvar |
3078 | TEXMFSYSCONFIG | /usr/local/texlive/YYYY/texmf-config | --texdir | --texmfsysconfig |
3079 +----------------+--------------------------------------+--------------+------------------+
3080 | TEXMFHOME | ~/texmf | --texuserdir | --texmfhome |
3081 | TEXMFVAR | ~/.texliveYYYY/texmf-var | --texuserdir | --texmfvar |
3082 | TEXMFCONFIG | ~/.texliveYYYY/texmf-config | --texuserdir | --texmfconfig |
3083 +----------------+--------------------------------------+--------------+------------------+
3084
3085 In addition, as mentioned in the previous section, each tree has an
3086 environment variable 'TEXLIVE_INSTALL_'_tree_ which overrides the
3087 default; command line and profile settings both override environment
3088 variable settings.
3089
3090 The defaults vary slightly on Macs, as explained above in *note
3091 OPTIONS: install-tl OPTIONS.
3092
3093 For the user trees, the default value uses '~', and this is left as a
3094 literal '~' in 'texmf.cnf'. That way, each user can have their own
3095 'TEXMFHOME', etc., as intended. On the other hand, for the system
3096 trees, if '~' is used during the installation, this is assumed to simply
3097 be a typing shorthand, and the expanded home directory is written in
3098 'texmf.cnf', since it doesn't make sense to have user-specific system
3099 directories.
3100
3101 For more on the directory trees and their intended usage, see the
3102 main TeX Live documentation at <https://tug.org/texlive/doc>.
3103
3104 
3105 File: tlbuild.info, Node: install-tl BUGS, Next: install-tl AUTHORS AND COPYRIGHT, Prev: install-tl DIRECTORY TREES, Up: install-tl
3106
3107 A.10 install-tl BUGS
3108 ====================
3109
3110 The 'install-tl' script copies itself into the installed tree. Usually,
3111 it can be run from there, using the installed tree as the source for
3112 another installation. Occasionally, however, there may be
3113 incompatibilities in the code of the new 'install-tl' and the
3114 infrastructure, resulting in (probably) inscrutable Perl errors. The
3115 way forward is to run 'install-tl' out of the installer package
3116 ('install-tl-unx.tar.gz' or 'install-tl.zip') instead of the
3117 installation. Feel free to also report the issue; usually the code can
3118 be easily synced up again.
3119
3120 By the way, do not try to use 'install-tl' to adjust options or
3121 installed packages in an existing installed tree. Use 'tlmgr' instead.
3122
3123 
3124 File: tlbuild.info, Node: install-tl AUTHORS AND COPYRIGHT, Prev: install-tl BUGS, Up: install-tl
3125
3126 A.11 AUTHORS AND COPYRIGHT
3127 ==========================
3128
3129 This script and its documentation were written for the TeX Live
3130 distribution (<https://tug.org/texlive>) and both are licensed under the
3131 GNU General Public License Version 2 or later.
3132
3133 $Id: install-tl 75865 2025-07-22 20:56:23Z karl $
3134
3135 
3136 File: tlbuild.info, Node: tlmgr, Next: Index, Prev: install-tl, Up: Top
3137
3138 Appendix B tlmgr
3139 ****************
3140
3141 * Menu:
3142
3143 * tlmgr NAME::
3144 * tlmgr SYNOPSIS::
3145 * tlmgr DESCRIPTION::
3146 * tlmgr EXAMPLES::
3147 * tlmgr OPTIONS::
3148 * tlmgr ACTIONS::
3149 * tlmgr CONFIGURATION FILE FOR TLMGR::
3150 * tlmgr CRYPTOGRAPHIC VERIFICATION::
3151 * tlmgr USER MODE::
3152 * tlmgr MULTIPLE REPOSITORIES::
3153 * tlmgr GUI FOR TLMGR::
3154 * tlmgr MACHINE-READABLE OUTPUT::
3155 * tlmgr ENVIRONMENT VARIABLES::
3156 * tlmgr AUTHORS AND COPYRIGHT::
3157
3158 
3159 File: tlbuild.info, Node: tlmgr NAME, Next: tlmgr SYNOPSIS, Up: tlmgr
3160
3161 B.1 tlmgr NAME
3162 ==============
3163
3164 tlmgr - the native TeX Live Manager
3165
3166 
3167 File: tlbuild.info, Node: tlmgr SYNOPSIS, Next: tlmgr DESCRIPTION, Prev: tlmgr NAME, Up: tlmgr
3168
3169 B.2 tlmgr SYNOPSIS
3170 ==================
3171
3172 tlmgr [_option_...] _action_ [_option_...] [_operand_...]
3173
3174 
3175 File: tlbuild.info, Node: tlmgr DESCRIPTION, Next: tlmgr EXAMPLES, Prev: tlmgr SYNOPSIS, Up: tlmgr
3176
3177 B.3 tlmgr DESCRIPTION
3178 =====================
3179
3180 *tlmgr* manages an existing TeX Live installation, both packages and
3181 configuration options. For information on initially downloading and
3182 installing TeX Live, see <https://tug.org/texlive/acquire.html>.
3183
3184 The most up-to-date version of this documentation (updated nightly
3185 from the development sources) is available at
3186 <https://tug.org/texlive/tlmgr.html>, along with procedures for updating
3187 'tlmgr' itself and information about test versions.
3188
3189 TeX Live is organized into a few top-level _schemes_, each of which
3190 is specified as a different set of _collections_ and _packages_, where a
3191 collection is a set of packages, and a package is what contains actual
3192 files. Schemes typically contain a mix of collections and packages, but
3193 each package is included in exactly one collection, no more and no less.
3194 A TeX Live installation can be customized and managed at any level.
3195
3196 See <https://tug.org/texlive/doc> for all the TeX Live documentation
3197 available.
3198
3199 
3200 File: tlbuild.info, Node: tlmgr EXAMPLES, Next: tlmgr OPTIONS, Prev: tlmgr DESCRIPTION, Up: tlmgr
3201
3202 B.4 tlmgr EXAMPLES
3203 ==================
3204
3205 After successfully installing TeX Live, here are a few common operations
3206 with 'tlmgr':
3207
3208 'tlmgr option repository ctan'
3209
3210 'tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet'
3211
3212 Tell 'tlmgr' to use a nearby CTAN mirror for future updates; useful
3213 if you installed TeX Live from the DVD image and want to have
3214 continuing updates. The two commands are equivalent; 'ctan' is
3215 just an alias for the given url.
3216
3217 Caveat: 'mirror.ctan.org' resolves to many different hosts, and
3218 they are not perfectly synchronized; we recommend updating only
3219 daily (at most), and not more often. You can choose a particular
3220 mirror if problems; the list of all CTAN mirrors with the status of
3221 each is at <https://ctan.org/mirrors/mirmon>.
3222
3223 'tlmgr update --list'
3224
3225 Report what would be updated without actually updating anything.
3226
3227 'tlmgr update --all'
3228
3229 Make your local TeX installation correspond to what is in the
3230 package repository (typically useful when updating from CTAN).
3231
3232 'tlmgr info' _what_
3233
3234 Display detailed information about a package _what_, such as the
3235 installation status and description, of searches for _what_ in all
3236 packages.
3237
3238 'tlmgr bug' _what_
3239
3240 Display available bug-reporting information for _what_, a package
3241 or file name.
3242
3243 For all the capabilities and details of 'tlmgr', please read the
3244 following voluminous information.
3245
3246 
3247 File: tlbuild.info, Node: tlmgr OPTIONS, Next: tlmgr ACTIONS, Prev: tlmgr EXAMPLES, Up: tlmgr
3248
3249 B.5 tlmgr OPTIONS
3250 =================
3251
3252 The following options to 'tlmgr' are global options, not specific to any
3253 action. All options, whether global or action-specific, can be given
3254 anywhere on the command line, and in any order. The first non-option
3255 argument will be the main action. In all cases, '--'_option_ and
3256 '-'_option_ are equivalent, and an '=' is optional between an option
3257 name and its value.
3258
3259 *--repository* _url|path_
3260
3261 Specify the package repository from which packages should be
3262 installed or updated, either a local directory or network location,
3263 as below. This overridesthe default package repository found in
3264 the installation's TeX Live Package Database (a.k.a. the TLPDB,
3265 which is given entirely in the file 'tlpkg/texlive.tlpdb').
3266
3267 This '--repository' option changes the location only for the
3268 current run; to make a permanent change, use 'option repository'
3269 (see the *note option: tlmgr option. action).
3270
3271 As an example, you can choose a particular CTAN mirror with
3272 something like this:
3273
3274 -repository http://ctan.example.org/its/ctan/dir/systems/texlive/tlnet
3275
3276 Of course a real hostname and its particular top-level CTAN
3277 directory have to be specified. The list of CTAN mirrors is
3278 available at <https://ctan.org/mirrors/mirmon>.
3279
3280 Here's an example of using a local directory:
3281
3282 -repository /local/TL/repository
3283
3284 For backward compatibility and convenience, '--location' and
3285 '--repo' are accepted as aliases for this option.
3286
3287 Locations can be specified as any of the following:
3288
3289 '/some/local/dir'
3290
3291 'file:/some/local/dir'
3292
3293 Equivalent ways of specifying a local directory.
3294
3295 'ctan'
3296
3297 'https://mirror.ctan.org/systems/texlive/tlnet'
3298
3299 Pick a CTAN mirror automatically, trying for one that is both
3300 nearby and up-to-date. The chosen mirror is used for the
3301 entire download. The bare 'ctan' is merely an alias for the
3302 full url. (See <https://ctan.org> for more about CTAN and its
3303 mirrors.)
3304
3305 'http://server/path/to/tlnet'
3306
3307 Standard HTTP. If the (default) LWP method is used, persistent
3308 connections are supported. TL can also use 'curl' or 'wget'
3309 to do the downloads, or an arbitrary user-specified program,
3310 as described in the 'tlmgr' documentation
3311 (<https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES>).
3312
3313 'https://server/path/to/tlnet'
3314
3315 Again, if the (default) LWP method is used, this supports
3316 persistent connections. Unfortunately, some versions of
3317 'wget' and 'curl' do not support https, and even when 'wget'
3318 supports https, certificates may be rejected even when the
3319 certificate is fine, due to a lack of local certificate roots.
3320 The simplest workaround for this problem is to use http or
3321 ftp.
3322
3323 'ftp://server/path/to/tlnet'
3324
3325 If the (default) LWP method is used, persistent connections
3326 are supported.
3327
3328 'user@machine:/path/to/tlnet'
3329
3330 'scp://user@machine/path/to/tlnet'
3331
3332 'ssh://user@machine/path/to/tlnet'
3333
3334 These forms are equivalent; they all use 'scp' to transfer
3335 files. Using 'ssh-agent' is recommended. (Info:
3336 <https://en.wikipedia.org/wiki/OpenSSH>,
3337 <https://en.wikipedia.org/wiki/Ssh-agent>.)
3338
3339 If the repository is on the network, trailing '/' characters and/or
3340 trailing '/tlpkg' and/or '/archive' components are ignored.
3341
3342 *--gui* [_action_]
3343
3344 Two notable GUI front-ends for 'tlmgr', 'tlshell' and 'tlcockpit',
3345 are started up as separate programs; see their own documentation.
3346
3347 'tlmgr' itself has a graphical interface as well as the command
3348 line interface. You can give the option to invoke it, '--gui',
3349 together with an action to be brought directly into the respective
3350 screen of the GUI. For example, running
3351
3352 tlmgr --gui update
3353
3354 starts you directly at the update screen. If no action is given,
3355 the GUI will be started at the main screen. See *note GUI FOR
3356 TLMGR: tlmgr GUI FOR TLMGR.
3357
3358 However, the native GUI requires Perl/TK, which is no longer
3359 included in TeX Live's Perl distribution for Windows. You may find
3360 'tlshell' or 'tlcockpit' easier to work with.
3361
3362 *--gui-lang* _llcode_
3363
3364 By default, the GUI tries to deduce your language from the
3365 environment (on Windows via the registry, on Unix via
3366 'LC_MESSAGES'). If that fails you can select a different language
3367 by giving this option with a language code (based on ISO 639-1).
3368 Currently supported (but not necessarily completely translated)
3369 are: English (en, default), Czech (cs), German (de), French (fr),
3370 Italian (it), Japanese (ja), Dutch (nl), Polish (pl),
3371 Brazilian Portuguese (pt_BR), Russian (ru), Slovak (sk),
3372 Slovenian (sl), Serbian (sr), Ukrainian (uk), Vietnamese (vi),
3373 simplified Chinese (zh_CN), and traditional Chinese (zh_TW).
3374
3375 tlshell shares its message catalog with tlmgr.
3376
3377 *--command-logfile* _file_
3378
3379 'tlmgr' logs the output of all programs invoked (mktexlr, mtxrun,
3380 fmtutil, updmap) to a separate log file, by default
3381 'TEXMFSYSVAR/web2c/tlmgr-commands.log'. This option allows you to
3382 specify a different file for the log.
3383
3384 *--debug-translation*
3385
3386 In GUI mode, this switch tells 'tlmgr' to report any untranslated
3387 (or missing) messages to standard error. This can help translators
3388 to see what remains to be done.
3389
3390 *--machine-readable*
3391
3392 Instead of the normal output intended for human consumption, write
3393 (to standard output) a fixed format more suitable for machine
3394 parsing. See the *note MACHINE-READABLE OUTPUT: tlmgr
3395 MACHINE-READABLE OUTPUT. section below.
3396
3397 *--no-execute-actions*
3398
3399 Suppress the execution of the execute actions as defined in the
3400 tlpsrc files. Unless you are going to do the postprocessing
3401 yourself (as, for example, 'install-tl' does), this shouldn't be
3402 specified. Otherwise, format files and the filename database will
3403 become stale, among other problems.
3404
3405 *--package-logfile* _file_
3406
3407 'tlmgr' logs all package actions (install, remove, update, failed
3408 updates, failed restores) to a separate log file, by default
3409 'TEXMFSYSVAR/web2c/tlmgr.log'. This option allows you to specify a
3410 different file for the log.
3411
3412 *--pause*
3413
3414 This option makes 'tlmgr' wait for user input before exiting.
3415 Useful on Windows to avoid disappearing command windows.
3416
3417 *--persistent-downloads*
3418
3419 *--no-persistent-downloads*
3420
3421 For network-based installations, this option (on by default) makes
3422 'tlmgr' try to set up a persistent connection (using the 'LWP' Perl
3423 module). The idea is to open and reuse only one connection per
3424 session between your computer and the server, instead of initiating
3425 a new download for each package.
3426
3427 If this is not possible, 'tlmgr' will fall back to using 'wget'.
3428 To disable these persistent connections, use
3429 '--no-persistent-downloads'.
3430
3431 *--pin-file*
3432
3433 Change the pinning file location from
3434 'TEXMFLOCAL/tlpkg/pinning.txt' (see *note Pinning: tlmgr Pinning.
3435 below). Documented only for completeness, as this is only useful
3436 in debugging.
3437
3438 *--usermode*
3439
3440 Activates user mode for this run of 'tlmgr'; see *note USER MODE:
3441 tlmgr USER MODE. below.
3442
3443 *--usertree* _dir_
3444
3445 Uses _dir_ for the tree in user mode; see *note USER MODE: tlmgr
3446 USER MODE. below.
3447
3448 *--verify-repo=[none|main|all]*
3449
3450 Defines the level of verification done: If 'none' is specified, no
3451 verification whatsoever is done. If 'main' is given and a working
3452 GnuPG ('gpg') binary is available, all repositories are checked,
3453 but only the main repository is required to be signed. If 'all' is
3454 given, then all repositories need to be signed. See *note
3455 CRYPTOGRAPHIC VERIFICATION: tlmgr CRYPTOGRAPHIC VERIFICATION. below
3456 for details.
3457
3458 The standard options for TeX Live programs are also accepted:
3459 '--help/-h/-?', '--version', '-q' (no informational messages), '-v'
3460 (debugging messages, can be repeated). For the details about these, see
3461 the 'TeXLive::TLUtils' documentation.
3462
3463 The '--version' option shows version information about the TeX Live
3464 release and about the 'tlmgr' script itself. If '-v' is also given,
3465 revision number for the loaded TeX Live Perl modules are shown, too.
3466
3467 
3468 File: tlbuild.info, Node: tlmgr ACTIONS, Next: tlmgr CONFIGURATION FILE FOR TLMGR, Prev: tlmgr OPTIONS, Up: tlmgr
3469
3470 B.6 ACTIONS
3471 ===========
3472
3473 * Menu:
3474
3475 * tlmgr help::
3476 * tlmgr version::
3477 * tlmgr backup::
3478 * tlmgr bug [_search-string_]::
3479 * tlmgr candidates _pkg_::
3480 * tlmgr check [_option_...] [depends|executes|files|runfiles|texmfdbs|all]::
3481 * tlmgr conf::
3482 * tlmgr dump-tlpdb [_option_...] [--json]::
3483 * tlmgr generate::
3484 * tlmgr gui::
3485 * tlmgr info::
3486 * tlmgr init-usertree::
3487 * tlmgr install [_option_...] _pkg_...::
3488 * tlmgr key::
3489 * tlmgr list::
3490 * tlmgr option::
3491 * tlmgr paper::
3492 * tlmgr path::
3493 * tlmgr pinning::
3494 * tlmgr platform::
3495 * tlmgr postaction::
3496 * tlmgr print-platform::
3497 * tlmgr print-platform-info::
3498 * tlmgr remove [_option_...] _pkg_...::
3499 * tlmgr repository::
3500 * tlmgr restore::
3501 * tlmgr search::
3502 * tlmgr shell::
3503 * tlmgr show::
3504 * tlmgr uninstall::
3505 * tlmgr update [_option_...] [_pkg_...]::
3506
3507 
3508 File: tlbuild.info, Node: tlmgr help, Next: tlmgr version, Up: tlmgr ACTIONS
3509
3510 B.6.1 help
3511 ----------
3512
3513 Display this help information and exit (same as '--help', and on the web
3514 at <https://tug.org/texlive/doc/tlmgr.html>). Sometimes the 'perldoc'
3515 and/or 'PAGER' programs on the system have problems, resulting in
3516 control characters being literally output. This can't always be
3517 detected, but you can set the 'NOPERLDOC' environment variable and
3518 'perldoc' will not be used.
3519
3520 
3521 File: tlbuild.info, Node: tlmgr version, Next: tlmgr backup, Prev: tlmgr help, Up: tlmgr ACTIONS
3522
3523 B.6.2 version
3524 -------------
3525
3526 Gives version information (same as '--version').
3527
3528 If '-v' has been given the revisions of the used modules are
3529 reported, too.
3530
3531 
3532 File: tlbuild.info, Node: tlmgr backup, Next: tlmgr bug [_search-string_], Prev: tlmgr version, Up: tlmgr ACTIONS
3533
3534 B.6.3 backup
3535 ------------
3536
3537 *backup [_option_...] --all*
3538
3539 *backup [_option_...] _pkg_...*
3540
3541 If the '--clean' option is not specified, this action makes a
3542 backup of the given packages, or all packages given '--all'. These
3543 backups are saved to the value of the '--backupdir' option, if that
3544 is an existing and writable directory. If '--backupdir' is not
3545 given, the 'backupdir' option setting in the TLPDB is used, if
3546 present. If both are missing, no backups are made. (The installer
3547 sets 'backupdir' to '.../tlpkg/backups', under the TL root
3548 installation directory, so it is usually defined; see the *note
3549 option: tlmgr option. description for more information.)
3550
3551 If the '--clean' option is specified, backups are pruned (removed)
3552 instead of saved. The optional integer value _N_ may be specified
3553 to set the number of backups that will be retained when cleaning.
3554 If 'N' is not given, the value of the 'autobackup' option is used.
3555 If both are missing, an error is issued. For more details of
3556 backup pruning, see the 'option' action.
3557
3558 Options:
3559
3560 *--backupdir* _directory_
3561
3562 Overrides the 'backupdir' option setting in the TLPDB. The
3563 _directory_ argument is required and must specify an existing,
3564 writable directory where backups are to be placed.
3565
3566 *--all*
3567
3568 If '--clean' is not specified, make a backup of all packages
3569 in the TeX Live installation; this will take quite a lot of
3570 space and time. If '--clean' is specified, all packages are
3571 pruned.
3572
3573 *--clean*[=_N_]
3574
3575 Instead of making backups, prune the backup directory of old
3576 backups, as explained above. The optional integer argument
3577 _N_ overrides the 'autobackup' option set in the TLPDB. You
3578 must use '--all' or a list of packages together with this
3579 option, as desired.
3580
3581 *--dry-run*
3582
3583 Nothing is actually backed up or removed; instead, the actions
3584 to be performed are written to the terminal.
3585
3586 
3587 File: tlbuild.info, Node: tlmgr bug [_search-string_], Next: tlmgr candidates _pkg_, Prev: tlmgr backup, Up: tlmgr ACTIONS
3588
3589 B.6.4 bug [_search-string_]
3590 ---------------------------
3591
3592 Searches for _search-string_ (prompted for, if not given) as a package
3593 name and in package descriptions, as complete words, and in filenames,
3594 as any substring, and outputs bug-reporting and other information for
3595 the package selected from the results.
3596
3597 The search is equivalent to 'tlmgr search --word --file'
3598 _search-string_. Thus, _search-string_ is interpreted as a (Perl)
3599 regular expression.
3600
3601 
3602 File: tlbuild.info, Node: tlmgr candidates _pkg_, Next: tlmgr check [_option_...] [depends|executes|files|runfiles|texmfdbs|all], Prev: tlmgr bug [_search-string_], Up: tlmgr ACTIONS
3603
3604 B.6.5 candidates _pkg_
3605 ----------------------
3606
3607 Shows the available candidate repositories for package _pkg_. See *note
3608 MULTIPLE REPOSITORIES: tlmgr MULTIPLE REPOSITORIES. below.
3609
3610 
3611 File: tlbuild.info, Node: tlmgr check [_option_...] [depends|executes|files|runfiles|texmfdbs|all], Next: tlmgr conf, Prev: tlmgr candidates _pkg_, Up: tlmgr ACTIONS
3612
3613 B.6.6 check [_option_...] [depends|executes|files|runfiles|texmfdbs|all]
3614 ------------------------------------------------------------------------
3615
3616 Execute one (or all) check(s) of the consistency of the installation.
3617 If no problems are found, there will be no output. (To get a view of
3618 what is being done, run 'tlmgr -v check'.)
3619
3620 *depends*
3621
3622 Lists those packages which occur as dependencies in an installed
3623 collection, but are themselves not installed, and those packages
3624 which are not contained in any collection.
3625
3626 If you call 'tlmgr check collections' this test will be carried out
3627 instead since former versions for 'tlmgr' called it that way.
3628
3629 *executes*
3630
3631 Check that the files referred to by 'execute' directives in the TeX
3632 Live Database are present.
3633
3634 *files*
3635
3636 Checks that all files listed in the local TLPDB ('texlive.tlpdb')
3637 are actually present, and lists those missing.
3638
3639 *runfiles*
3640
3641 List those filenames that are occurring more than one time in the
3642 runfiles sections, except for known duplicates.
3643
3644 *texmfdbs*
3645
3646 Checks related to the 'ls-R' files. If you have defined new trees,
3647 or changed the 'TEXMF' or 'TEXMFDBS' variables, it can't hurt to
3648 run this. It checks that:
3649
3650 - all items in 'TEXMFDBS' have the '!!' prefix.
3651
3652 - all items in 'TEXMFBDS' have an 'ls-R' file (if they exist at all).
3653
3654 - all items in 'TEXMF' with '!!' are listed in 'TEXMFDBS'.
3655
3656 - all items in 'TEXMF' with an 'ls-R' file are listed in 'TEXMFDBS'.
3657
3658 Options:
3659
3660 *--use-svn*
3661
3662 Use the output of 'svn status' instead of listing the files; for
3663 checking the TL development repository. (This is run nightly.)
3664
3665 
3666 File: tlbuild.info, Node: tlmgr conf, Next: tlmgr dump-tlpdb [_option_...] [--json], Prev: tlmgr check [_option_...] [depends|executes|files|runfiles|texmfdbs|all], Up: tlmgr ACTIONS
3667
3668 B.6.7 conf
3669 ----------
3670
3671 *conf [texmf|tlmgr|updmap [--conffile _file_] [--delete] [_key_ [_value_]]]*
3672
3673 *conf auxtrees [--conffile _file_] [show|add|remove] [_value_]*
3674
3675 With only 'conf', show general configuration information for TeX
3676 Live, including active configuration files, path settings, and
3677 more. This is like running 'texconfig conf', but works on all
3678 supported platforms.
3679
3680 With one of 'conf texmf', 'conf tlmgr', or 'conf updmap', shows all
3681 key/value pairs (i.e., all settings) as saved in 'ROOT/texmf.cnf',
3682 the user-specific 'tlmgr' configuration file (see below), or the
3683 first found (via 'kpsewhich') 'updmap.cfg' file, respectively.
3684
3685 If _key_ is given in addition, shows the value of only that _key_
3686 in the respective file. If option _--delete_ is also given, the
3687 value in the given configuration file is entirely removed (not just
3688 commented out).
3689
3690 If _value_ is given in addition, _key_ is set to _value_ in the
3691 respective file. _No error checking is done!_
3692
3693 The 'PATH' value shown by 'conf' is as used by 'tlmgr'. The
3694 directory in which the 'tlmgr' executable is found is automatically
3695 prepended to the PATH value inherited from the environment.
3696
3697 Here is a practical example of changing configuration values. If
3698 the execution of (some or all) system commands via '\write18' was
3699 left enabled during installation, you can disable it afterwards:
3700
3701 tlmgr conf texmf shell_escape 0
3702
3703 The subcommand 'auxtrees' allows adding and removing arbitrary
3704 additional texmf trees, completely under user control. 'auxtrees
3705 show' shows the list of additional trees, 'auxtrees add' _tree_
3706 adds a tree to the list, and 'auxtrees remove' _tree_ removes a
3707 tree from the list (if present). The trees should not contain an
3708 'ls-R' file (or files will not be found if the 'ls-R' becomes
3709 stale). This works by manipulating the Kpathsea variable
3710 'TEXMFAUXTREES', in (by default) 'ROOT/texmf.cnf'. Example:
3711
3712 tlmgr conf auxtrees add /quick/test/tree
3713 tlmgr conf auxtrees remove /quick/test/tree
3714
3715 In all cases the configuration file can be explicitly specified via
3716 the option '--conffile' _file_, e.g., if you don't want to change
3717 the system-wide configuration.
3718
3719 Warning: The general facility for changing configuration values is
3720 here, but tinkering with settings in this way is strongly
3721 discouraged. Again, no error checking on either keys or values is
3722 done, so any sort of breakage is possible.
3723
3724 
3725 File: tlbuild.info, Node: tlmgr dump-tlpdb [_option_...] [--json], Next: tlmgr generate, Prev: tlmgr conf, Up: tlmgr ACTIONS
3726
3727 B.6.8 dump-tlpdb [_option_...] [--json]
3728 ---------------------------------------
3729
3730 Dump complete local or remote TLPDB to standard output, as-is. The
3731 output is analogous to the '--machine-readable' output; see *note
3732 MACHINE-READABLE OUTPUT: tlmgr MACHINE-READABLE OUTPUT. section.
3733
3734 Options:
3735
3736 *--local*
3737
3738 Dump the local TLPDB.
3739
3740 *--remote*
3741
3742 Dump the remote TLPDB.
3743
3744 *--json*
3745
3746 Instead of dumping the actual content, the database is dumped as
3747 JSON. For the format of JSON output see
3748 'tlpkg/doc/json-formats.txt', format definition 'TLPDB'.
3749
3750 Exactly one of '--local' and '--remote' must be given.
3751
3752 In either case, the first line of the output specifies the repository
3753 location, in this format:
3754
3755 "location-url" "\t" location
3756
3757 where 'location-url' is the literal field name, followed by a tab,
3758 and _location_ is the file or url to the repository.
3759
3760 Line endings may be either LF or CRLF depending on the current
3761 platform.
3762
3763 
3764 File: tlbuild.info, Node: tlmgr generate, Next: tlmgr gui, Prev: tlmgr dump-tlpdb [_option_...] [--json], Up: tlmgr ACTIONS
3765
3766 B.6.9 generate
3767 --------------
3768
3769 *generate [_option_...] language*
3770
3771 *generate [_option_...] language.dat*
3772
3773 *generate [_option_...] language.def*
3774
3775 *generate [_option_...] language.dat.lua*
3776
3777 The 'generate' action overwrites any manual changes made in the
3778 respective files: it recreates them from scratch based on the
3779 information of the installed packages, plus local adaptations. The TeX
3780 Live installer and 'tlmgr' routinely call 'generate' for all of these
3781 files.
3782
3783 For managing your own fonts, please read the 'updmap --help'
3784 information and/or <https://tug.org/fonts/fontinstall.html>.
3785
3786 For managing your own formats, please read the 'fmtutil --help'
3787 information.
3788
3789 In more detail: 'generate' remakes any of the configuration files
3790 'language.dat', 'language.def', and 'language.dat.lua' from the
3791 information present in the local TLPDB, plus locally-maintained files.
3792
3793 The locally-maintained files are 'language-local.dat',
3794 'language-local.def', or 'language-local.dat.lua', searched for in
3795 'TEXMFLOCAL' in the respective directories. If local additions are
3796 present, the final file is made by starting with the main file, omitting
3797 any entries that the local file specifies to be disabled, and finally
3798 appending the local file.
3799
3800 (Historical note: The formerly supported 'updmap-local.cfg' and
3801 'fmtutil-local.cnf' are no longer read, since 'updmap' and 'fmtutil' now
3802 reads and supports multiple configuration files. Thus, local additions
3803 can and should be put into an 'updmap.cfg' of 'fmtutil.cnf' file in
3804 'TEXMFLOCAL'. The 'generate updmap' and 'generate fmtutil' actions no
3805 longer exist.)
3806
3807 Local files specify entries to be disabled with a comment line,
3808 namely one of these:
3809
3810 %!NAME
3811 --!NAME
3812
3813 where 'language.dat' and 'language.def' use '%', and
3814 'language.dat.lua' use '--'. In all cases, the _name_ is the respective
3815 format name or hyphenation pattern identifier. Examples:
3816
3817 %!german
3818 --!usenglishmax
3819
3820 (Of course, you're not likely to actually want to disable those
3821 particular items. They're just examples.)
3822
3823 After such a disabling line, the local file can include another entry
3824 for the same item, if a different definition is desired. In general,
3825 except for the special disabling lines, the local files follow the same
3826 syntax as the master files.
3827
3828 The form 'generate language' recreates all three files
3829 'language.dat', 'language.def', and 'language.dat.lua', while the forms
3830 with an extension recreates only that given language file.
3831
3832 Options:
3833
3834 *--dest* _output_file_
3835
3836 specifies the output file (defaults to the respective location in
3837 'TEXMFSYSVAR'). If '--dest' is given to 'generate language', it
3838 serves as a basename onto which '.dat' will be appended for the
3839 name of the 'language.dat' output file, '.def' will be appended to
3840 the value for the name of the 'language.def' output file, and
3841 '.dat.lua' to the name of the 'language.dat.lua' file. (This is
3842 just to avoid overwriting; if you want a specific name for each
3843 output file, we recommend invoking 'tlmgr' twice.)
3844
3845 *--localcfg* _local_conf_file_
3846
3847 specifies the (optional) local additions (defaults to the
3848 respective location in 'TEXMFLOCAL').
3849
3850 *--rebuild-sys*
3851
3852 tells 'tlmgr' to run necessary programs after config files have
3853 been regenerated. These are: 'fmtutil-sys --all' after 'generate
3854 fmtutil', 'fmtutil-sys --byhyphen .../language.dat' after 'generate
3855 language.dat', and 'fmtutil-sys --byhyphen .../language.def' after
3856 'generate language.def'.
3857
3858 These subsequent calls cause the newly-generated files to actually
3859 take effect. This is not done by default since those calls are
3860 lengthy processes and one might want to made several related
3861 changes in succession before invoking these programs.
3862
3863 The respective locations are as follows:
3864
3865 tex/generic/config/language.dat (and language-local.dat)
3866 tex/generic/config/language.def (and language-local.def)
3867 tex/generic/config/language.dat.lua (and language-local.dat.lua)
3868
3869 
3870 File: tlbuild.info, Node: tlmgr gui, Next: tlmgr info, Prev: tlmgr generate, Up: tlmgr ACTIONS
3871
3872 B.6.10 gui
3873 ----------
3874
3875 Start the graphical user interface. See *GUI* below.
3876
3877 
3878 File: tlbuild.info, Node: tlmgr info, Next: tlmgr init-usertree, Prev: tlmgr gui, Up: tlmgr ACTIONS
3879
3880 B.6.11 info
3881 -----------
3882
3883 *info [_option_...] _pkg_...*
3884
3885 *info [_option_...] collections*
3886
3887 *info [_option_...] schemes*
3888
3889 With no argument, lists all packages available at the package
3890 repository, prefixing those already installed with 'i'.
3891
3892 With the single word 'collections' or 'schemes' as the argument,
3893 lists the request type instead of all packages.
3894
3895 With any other arguments, display information about _pkg_: the
3896 name, category, short and long description, sizes, installation
3897 status, and TeX Live revision number. If _pkg_ is not locally
3898 installed, searches in the remote installation source.
3899
3900 For normal packages (not collections or schemes), the sizes of the
3901 four groups of files (run/src/doc/bin files) are shown separately.
3902 For collections, the cumulative size is shown, including all
3903 directly-dependent packages (but not dependent collections). For
3904 schemes, the cumulative size is also shown, including all
3905 directly-dependent collections and packages.
3906
3907 If _pkg_ is not found locally or remotely, the search action is
3908 used and lists matching packages and files.
3909
3910 It also displays information taken from the TeX Catalogue, namely
3911 the package version, date, and license. Consider these, especially
3912 the package version, as approximations only, due to timing skew of
3913 the updates of the different pieces. By contrast, the 'revision'
3914 value comes directly from TL and is reliable.
3915
3916 The former actions 'show' and 'list' are merged into this action,
3917 but are still supported for backward compatibility.
3918
3919 Options:
3920
3921 *--list*
3922
3923 If the option '--list' is given with a package, the list of
3924 contained files is also shown, including those for
3925 platform-specific dependencies. When given with schemes and
3926 collections, '--list' outputs their dependencies in a similar
3927 way.
3928
3929 *--only-files*
3930
3931 If this option is given, only the files for a given package
3932 are listed, no further information. If more than one package
3933 name is given, each file list is preceded by the package name.
3934
3935 *--only-installed*
3936
3937 If this option is given, the installation source will not be
3938 used; only locally installed packages, collections, or schemes
3939 are listed.
3940
3941 *--only-remote*
3942
3943 Only list packages from the remote repository. Useful when
3944 checking what is available in a remote repository using 'tlmgr
3945 --repo ... --only-remote info'. Note that '--only-installed'
3946 and '--only-remote' cannot both be specified.
3947
3948 *--data 'item1,item2,...'*
3949
3950 If the option '--data' is given, its argument must be a comma
3951 or colon separated list of field names from: 'name',
3952 'category', 'localrev', 'remoterev', 'shortdesc', 'longdesc',
3953 'installed', 'size', 'relocatable', 'depends', 'cat-version',
3954 'cat-date', 'cat-license', plus various 'cat-contact-*' fields
3955 (see below).
3956
3957 The 'cat-*' fields all come from the TeX Catalogue
3958 (<https://ctan.org/pkg/catalogue>). For each, there are two
3959 more variants with prefix 'l' and 'r', e.g., 'lcat-version'
3960 and 'rcat-version', which indicate the local and remote
3961 information, respectively. The variants without 'l' and 'r'
3962 show the most current one, which is normally the remote value.
3963
3964 The requested packages' information is listed in CSV format,
3965 one package per line, and the column information is given by
3966 the 'itemN'. The 'depends' column contains the names of all
3967 the dependencies separated by ':' characters.
3968
3969 At this writing, the 'cat-contact-*' fields include: 'home',
3970 'repository', 'support', 'bugs', 'announce', 'development'.
3971 Each may be empty or a url value. A brief description is on
3972 the CTAN upload page for new packages:
3973 <https://ctan.org/upload>.
3974
3975 *--json*
3976
3977 If '--json' is specified, the output is a JSON encoded array
3978 where each array element is the JSON representation of a
3979 single 'TLPOBJ' but with additional information. For details
3980 see 'tlpkg/doc/json-formats.txt', format definition:
3981 'TLPOBJINFO'. If both '--json' and '--data' are given,
3982 '--json' takes precedence.
3983
3984 
3985 File: tlbuild.info, Node: tlmgr init-usertree, Next: tlmgr install [_option_...] _pkg_..., Prev: tlmgr info, Up: tlmgr ACTIONS
3986
3987 B.6.12 init-usertree
3988 --------------------
3989
3990 Sets up a texmf tree for so-called user mode management, either the
3991 default user tree ('TEXMFHOME'), or one specified on the command line
3992 with '--usertree'. See *note USER MODE: tlmgr USER MODE. below.
3993
3994 
3995 File: tlbuild.info, Node: tlmgr install [_option_...] _pkg_..., Next: tlmgr key, Prev: tlmgr init-usertree, Up: tlmgr ACTIONS
3996
3997 B.6.13 install [_option_...] _pkg_...
3998 -------------------------------------
3999
4000 Install each _pkg_ given on the command line, if it is not already
4001 installed. It does not touch existing packages; see the 'update' action
4002 for how to get the latest version of a package.
4003
4004 By default this also installs all packages on which the given _pkg_s
4005 are dependent. Options:
4006
4007 *--dry-run*
4008
4009 Nothing is actually installed; instead, the actions to be performed
4010 are written to the terminal.
4011
4012 *--file*
4013
4014 Instead of fetching a package from the installation repository, use
4015 the package files given on the command line. These files must be
4016 standard TeX Live package files (with contained tlpobj file).
4017
4018 *--force*
4019
4020 If updates to 'tlmgr' itself (or other parts of the basic
4021 infrastructure) are present, 'tlmgr' will bail out and not perform
4022 the installation unless this option is given. Not recommended.
4023
4024 *--no-depends*
4025
4026 Do not install dependencies. (By default, installing a package
4027 ensures that all dependencies of this package are fulfilled.)
4028
4029 *--no-depends-at-all*
4030
4031 Normally, when you install a package which ships binary files the
4032 respective binary package will also be installed. That is, for a
4033 package 'foo', the package 'foo.i386-linux' will also be installed
4034 on an 'i386-linux' system. This option suppresses this behavior,
4035 and also implies '--no-depends'. Don't use it unless you are sure
4036 of what you are doing.
4037
4038 *--reinstall*
4039
4040 Reinstall a package (including dependencies for collections) even
4041 if it already seems to be installed (i.e, is present in the TLPDB).
4042 This is useful to recover from accidental removal of files in the
4043 hierarchy.
4044
4045 When re-installing, only dependencies on normal packages are
4046 followed (i.e., not those of category Scheme or Collection).
4047
4048 *--with-doc*
4049
4050 *--with-src*
4051
4052 While not recommended, the 'install-tl' program provides an option
4053 to omit installation of all documentation and/or source files. (By
4054 default, everything is installed.) After such an installation, you
4055 may find that you want the documentation or source files for a
4056 given package after all. You can get them by using these options
4057 in conjunction with '--reinstall', as in (using the 'fontspec'
4058 package as the example):
4059
4060 tlmgr install --reinstall --with-doc --with-src fontspec
4061
4062 This action does not automatically add new symlinks in system
4063 directories; you need to run 'tlmgr path add' (*note path: tlmgr path.)
4064 yourself if you are using this feature and want new symlinks added.
4065
4066 
4067 File: tlbuild.info, Node: tlmgr key, Next: tlmgr list, Prev: tlmgr install [_option_...] _pkg_..., Up: tlmgr ACTIONS
4068
4069 B.6.14 key
4070 ----------
4071
4072 *key list*
4073
4074 *key add _file_*
4075
4076 *key remove _keyid_*
4077
4078 The action 'key' allows listing, adding and removing additional GPG
4079 keys to the set of trusted keys, that is, those that are used to
4080 verify the TeX Live databases.
4081
4082 With the 'list' argument, 'key' lists all keys.
4083
4084 The 'add' argument requires another argument, either a filename or
4085 '-' for stdin, from which the key is added. The key is added to
4086 the local keyring 'GNUPGHOME/repository-keys.gpg', which is
4087 normally 'tlpkg/gpg/repository-keys.gpg'.
4088
4089 The 'remove' argument requires a key id and removes the requested
4090 id from the local keyring.
4091
4092 
4093 File: tlbuild.info, Node: tlmgr list, Next: tlmgr option, Prev: tlmgr key, Up: tlmgr ACTIONS
4094
4095 B.6.15 list
4096 -----------
4097
4098 Synonym for *note info: tlmgr info.
4099
4100 
4101 File: tlbuild.info, Node: tlmgr option, Next: tlmgr paper, Prev: tlmgr list, Up: tlmgr ACTIONS
4102
4103 B.6.16 option
4104 -------------
4105
4106 *option [--json] [show]*
4107
4108 *option [--json] showall|help*
4109
4110 *option _key_ [_value_]*
4111
4112 The first form, 'show', shows the global TeX Live settings currently
4113 saved in the TLPDB with a short description and the 'key' used for
4114 changing it in parentheses.
4115
4116 The second form, 'showall', is similar, but also shows options which
4117 can be defined but are not currently set to any value ('help' is a
4118 synonym).
4119
4120 Both 'show...' forms take an option '--json', which dumps the option
4121 information in JSON format. In this case, both forms dump the same
4122 data. For the format of the JSON output see
4123 'tlpkg/doc/json-formats.txt', format definition 'TLOPTION'.
4124
4125 In the third form, with _key_, if _value_ is not given, the setting
4126 for _key_ is displayed. If _value_ is present, _key_ is set to _value_.
4127
4128 Possible values for _key_ are (run 'tlmgr option showall' for the
4129 definitive list):
4130
4131 repository (default package repository),
4132 formats (generate formats at installation or update time),
4133 postcode (run postinst code blobs)
4134 docfiles (install documentation files),
4135 srcfiles (install source files),
4136 backupdir (default directory for backups),
4137 autobackup (number of backups to keep).
4138 sys_bin (directory to which executables are linked by the path action)
4139 sys_man (directory to which man pages are linked by the path action)
4140 sys_info (directory to which Info files are linked by the path action)
4141 desktop_integration (Windows-only: create Start menu shortcuts)
4142 fileassocs (Windows-only: change file associations)
4143 multiuser (Windows-only: install for all users)
4144
4145 One common use of 'option' is to permanently change the installation
4146 to get further updates from the Internet, after originally installing
4147 from DVD. To do this, you can run
4148
4149 tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet
4150
4151 The 'install-tl' documentation has more information about the
4152 possible values for 'repository'. (For backward compatibility,
4153 'location' can be used as a synonym for 'repository'.)
4154
4155 If 'formats' is set (this is the default), then formats are
4156 regenerated when either the engine or the format files have changed.
4157 Disable this only when you know how and want to regenerate formats
4158 yourself whenever needed (which is often, in practice).
4159
4160 The 'postcode' option controls execution of per-package
4161 postinstallation action code. It is set by default, and again disabling
4162 is not likely to be of interest except to developers doing debugging.
4163
4164 The 'docfiles' and 'srcfiles' options control the installation of
4165 their respective file groups (documentation, sources; grouping is
4166 approximate) per package. By default both are enabled (1). Either or
4167 both can be disabled (set to 0) if disk space is limited or for minimal
4168 testing installations, etc. When disabled, the respective files are not
4169 downloaded at all.
4170
4171 The options 'autobackup' and 'backupdir' determine the defaults for
4172 the actions 'update', 'backup' and 'restore'. These three actions need
4173 a directory in which to read or write the backups. If '--backupdir' is
4174 not specified on the command line, the 'backupdir' option value is used
4175 (if set). The TL installer sets 'backupdir' to '.../tlpkg/backups',
4176 under the TL root installation directory.
4177
4178 The 'autobackup' option (de)activates automatic generation of
4179 backups. Its value is an integer. If the 'autobackup' value is '-1',
4180 no backups are removed. If 'autobackup' is 0 or more, it specifies the
4181 number of backups to keep. Thus, backups are disabled if the value is
4182 0. In the '--clean' mode of the 'backup' action this option also
4183 specifies the number to be kept. The default value is 1, so that
4184 backups are made, but only one backup is kept.
4185
4186 To setup 'autobackup' to '-1' on the command line, use:
4187
4188 tlmgr option -- autobackup -1
4189
4190 The '--' avoids having the '-1' treated as an option. (The '--'
4191 stops parsing for options at the point where it appears; this is a
4192 general feature across most Unix programs.)
4193
4194 The 'sys_bin', 'sys_man', and 'sys_info' options are used on Unix
4195 systems to control the generation of links for executables, Info files
4196 and man pages. See the 'path' action for details.
4197
4198 The last three options affect behavior on Windows installations. If
4199 'desktop_integration' is set, then some packages will install items in a
4200 sub-folder of the Start menu for 'tlmgr gui', documentation, etc. If
4201 'fileassocs' is set, Windows file associations are made (see also the
4202 'postaction' action). Finally, if 'multiuser' is set, then changes to
4203 the registry and the menus are done for all users on the system instead
4204 of only the current user. All three options are on by default.
4205
4206 
4207 File: tlbuild.info, Node: tlmgr paper, Next: tlmgr path, Prev: tlmgr option, Up: tlmgr ACTIONS
4208
4209 B.6.17 paper
4210 ------------
4211
4212 *paper [a4|letter]*
4213
4214 *<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [_papersize_|--list]*>
4215
4216 *paper --json*
4217
4218 With no arguments ('tlmgr paper'), shows the default paper size
4219 setting for all known programs.
4220
4221 With one argument (e.g., 'tlmgr paper a4'), sets the default for all
4222 known programs to that paper size.
4223
4224 With a program given as the first argument and no paper size
4225 specified (e.g., 'tlmgr dvips paper'), shows the default paper size for
4226 that program.
4227
4228 With a program given as the first argument and a paper size as the
4229 last argument (e.g., 'tlmgr dvips paper a4'), set the default for that
4230 program to that paper size.
4231
4232 If either 'pdftex' or 'context' is one of the arguments, whether
4233 implicitly or explicitly, existing formats are rebuilt (i.e., 'fmtutil
4234 --refresh' is called), unless '--no-execute-actions' is specified.
4235
4236 With a program given as the first argument and '--list' given as the
4237 last argument (e.g., 'tlmgr dvips paper --list'), shows all valid paper
4238 sizes for that program. The first size shown is the default.
4239
4240 If '--json' is specified without other options, the paper setup is
4241 dumped in JSON format. For the format of JSON output see
4242 'tlpkg/doc/json-formats.txt', format definition 'TLPAPER'.
4243
4244 Incidentally, this syntax of having a specific program name before
4245 the 'paper' keyword is unusual. It is inherited from the longstanding
4246 'texconfig' script, which supports other configuration settings for some
4247 programs, notably 'dvips'. 'tlmgr' does not support those extra
4248 settings.
4249
4250 
4251 File: tlbuild.info, Node: tlmgr path, Next: tlmgr pinning, Prev: tlmgr paper, Up: tlmgr ACTIONS
4252
4253 B.6.18 path
4254 -----------
4255
4256 *path [--windowsmode=user|admin] add*
4257
4258 *path [--windowsmode=user|admin] remove*
4259
4260 On Unix, adds or removes symlinks for executables, man pages, and
4261 info pages in the system directories specified by the respective
4262 options (see the *note option: tlmgr option. description above).
4263 Does not change any initialization files, either system or
4264 personal. Furthermore, any executables added or removed by future
4265 updates are not taken care of automatically; this command must be
4266 rerun as needed.
4267
4268 On Windows, the registry part where the binary directory is added
4269 or removed is determined in the following way:
4270
4271 If the user has admin rights, and the option '--windowsmode' is not
4272 given, the setting _w32_multi_user_ determines the location (i.e.,
4273 if it is on then the system path, otherwise the user path is
4274 changed).
4275
4276 If the user has admin rights, and the option '--windowsmode' is
4277 given, this option determines the path to be adjusted.
4278
4279 If the user does not have admin rights, and the option
4280 '--windowsmode' is not given, and the setting _w32_multi_user_ is
4281 off, the user path is changed, while if the setting
4282 _w32_multi_user_ is on, a warning is issued that the caller does
4283 not have enough privileges.
4284
4285 If the user does not have admin rights, and the option
4286 '--windowsmode' is given, it must be 'user' and the user path will
4287 be adjusted. If a user without admin rights uses the option
4288 '--windowsmode admin' a warning is issued that the caller does not
4289 have enough privileges.
4290
4291 
4292 File: tlbuild.info, Node: tlmgr pinning, Next: tlmgr platform, Prev: tlmgr path, Up: tlmgr ACTIONS
4293
4294 B.6.19 pinning
4295 --------------
4296
4297 The 'pinning' action manages the pinning file, see *note Pinning: tlmgr
4298 Pinning. below.
4299
4300 'pinning show'
4301
4302 Shows the current pinning data.
4303
4304 'pinning add' _repo_ _pkgglob_...
4305
4306 Pins the packages matching the _pkgglob_(s) to the repository
4307 _repo_.
4308
4309 'pinning remove' _repo_ _pkgglob_...
4310
4311 Any packages recorded in the pinning file matching the <pkgglob>s
4312 for the given repository _repo_ are removed.
4313
4314 'pinning remove _repo_ --all'
4315
4316 Remove all pinning data for repository _repo_.
4317
4318 
4319 File: tlbuild.info, Node: tlmgr platform, Next: tlmgr postaction, Prev: tlmgr pinning, Up: tlmgr ACTIONS
4320
4321 B.6.20 platform
4322 ---------------
4323
4324 *platform list|add|remove _platform_...*
4325
4326 *platform set _platform_*
4327
4328 *platform set auto*
4329
4330 'platform list' lists the TeX Live names of all the platforms
4331 (a.k.a. architectures), ('i386-linux', ...) available at the
4332 package repository.
4333
4334 'platform add' _platform_... adds the executables for each given
4335 platform _platform_ to the installation from the repository.
4336
4337 'platform remove' _platform_... removes the executables for each
4338 given platform _platform_ from the installation, but keeps the
4339 currently running platform in any case.
4340
4341 'platform set' _platform_ switches TeX Live to always use the given
4342 platform instead of auto detection.
4343
4344 'platform set auto' switches TeX Live to auto detection mode for
4345 platform.
4346
4347 Platform detection is needed to select the proper 'xz' and 'wget'
4348 binaries that are shipped with TeX Live.
4349
4350 'arch' is a synonym for 'platform'.
4351
4352 Options:
4353
4354 *--dry-run*
4355
4356 Nothing is actually installed; instead, the actions to be
4357 performed are written to the terminal.
4358
4359 
4360 File: tlbuild.info, Node: tlmgr postaction, Next: tlmgr print-platform, Prev: tlmgr platform, Up: tlmgr ACTIONS
4361
4362 B.6.21 postaction
4363 -----------------
4364
4365 *postaction [_option_...] install [shortcut|fileassoc|script] [_pkg_...]*
4366
4367 *postaction [_option_...] remove [shortcut|fileassoc|script] [_pkg_...]*
4368
4369 Carry out the postaction 'shortcut', 'fileassoc', or 'script' given
4370 as the second required argument in install or remove mode (which is
4371 the first required argument), for either the packages given on the
4372 command line, or for all if '--all' is given.
4373
4374 Options:
4375
4376 *--windowsmode=[user|admin]*
4377
4378 If the option '--windowsmode' is given the value 'user', all
4379 actions will only be carried out in the user-accessible parts
4380 of the registry/filesystem, while the value 'admin' selects
4381 the system-wide parts of the registry for the file
4382 associations. If you do not have enough permissions, using
4383 '--windowsmode=admin' will not succeed.
4384
4385 *--fileassocmode=[1|2]*
4386
4387 '--fileassocmode' specifies the action for file associations.
4388 If it is set to 1 (the default), only new associations are
4389 added; if it is set to 2, all associations are set to the TeX
4390 Live programs. (See also 'option fileassocs'.)
4391
4392 *--all*
4393
4394 Carry out the postactions for all packages
4395
4396 
4397 File: tlbuild.info, Node: tlmgr print-platform, Next: tlmgr print-platform-info, Prev: tlmgr postaction, Up: tlmgr ACTIONS
4398
4399 B.6.22 print-platform
4400 ---------------------
4401
4402 Print the TeX Live identifier for the detected platform
4403 (hardware/operating system) combination to standard output, and exit.
4404 '--print-arch' is a synonym.
4405
4406 
4407 File: tlbuild.info, Node: tlmgr print-platform-info, Next: tlmgr remove [_option_...] _pkg_..., Prev: tlmgr print-platform, Up: tlmgr ACTIONS
4408
4409 B.6.23 print-platform-info
4410 --------------------------
4411
4412 Print the TeX Live platform identifier, TL platform long name, and
4413 original output from guess.
4414
4415 
4416 File: tlbuild.info, Node: tlmgr remove [_option_...] _pkg_..., Next: tlmgr repository, Prev: tlmgr print-platform-info, Up: tlmgr ACTIONS
4417
4418 B.6.24 remove [_option_...] _pkg_...
4419 ------------------------------------
4420
4421 Remove each _pkg_ specified. Removing a collection removes all package
4422 dependencies (unless '--no-depends' is specified), but not any
4423 collection dependencies of that collection. However, when removing a
4424 package, dependencies are never removed. Options:
4425
4426 *--all*
4427
4428 Uninstalls all of TeX Live, asking for confirmation unless
4429 '--force' is also specified.
4430
4431 *--backup*
4432
4433 *--backupdir* _directory_
4434
4435 These options behave just as with the *note update: tlmgr update
4436 [_option_...] [_pkg_...]. action (q.v.), except they apply to
4437 making backups of packages before they are removed. The default is
4438 to make such a backup, that is, to save a copy of packages before
4439 removal.
4440
4441 The *note restore: tlmgr restore. action explains how to restore
4442 from a backup.
4443
4444 *--no-depends*
4445
4446 Do not remove dependent packages.
4447
4448 *--no-depends-at-all*
4449
4450 See above under *note install: tlmgr install [_option_...]
4451 _pkg_.... (and beware).
4452
4453 *--force*
4454
4455 By default, removal of a package or collection that is a dependency
4456 of another collection or scheme is not allowed. With this option,
4457 the package will be removed unconditionally. Use with care.
4458
4459 A package that has been removed using the '--force' option because
4460 it is still listed in an installed collection or scheme will not be
4461 updated, and will be mentioned as 'forcibly removed' in the output
4462 of 'tlmgr update --list'.
4463
4464 *--dry-run*
4465
4466 Nothing is actually removed; instead, the actions to be performed
4467 are written to the terminal.
4468
4469 Except with '--all', this 'remove' action does not automatically
4470 remove symlinks to executables from system directories; you need to run
4471 'tlmgr path remove' (*note path: tlmgr path.) yourself if you remove an
4472 individual package with a symlink in a system directory.
4473
4474 
4475 File: tlbuild.info, Node: tlmgr repository, Next: tlmgr restore, Prev: tlmgr remove [_option_...] _pkg_..., Up: tlmgr ACTIONS
4476
4477 B.6.25 repository
4478 -----------------
4479
4480 *repository list*
4481
4482 *repository list _path|url|tag_*
4483
4484 *repository add _path_ [_tag_]*
4485
4486 *repository remove _path|tag_*
4487
4488 *repository set _path_[#_tag_] [_path_[#_tag_] ...]*
4489
4490 *repository status*
4491
4492 This action manages the list of repositories. See MULTIPLE
4493 REPOSITORIES (https://metacpan.org/pod/MULTIPLE REPOSITORIES) below
4494 for detailed explanations.
4495
4496 The first form, 'repository list', lists all configured
4497 repositories and the respective tags if set. If a path, url, or
4498 tag is given after the 'list' keyword, it is interpreted as the
4499 source from which to initialize a TL database and lists the
4500 contained packages. This can also be an otherwise-unused
4501 repository, either local or remote. If the option
4502 '--with-platforms' is specified in addition, for each package the
4503 available platforms (if any) are also listed.
4504
4505 The form 'repository add' adds a repository (optionally attaching a
4506 tag) to the list of repositories, while 'repository remove' removes
4507 a repository, either by full path/url, or by tag.
4508
4509 The form 'repository set' sets the list of available repositories
4510 to the items given on the command line, overwriting previous
4511 settings.
4512
4513 The form 'repository status' reports the verification status of the
4514 loaded repositories with the format of one repository per line with
4515 fields separated by a single space:
4516
4517 The tag (which can be the same as the url);
4518
4519 = the url;
4520
4521 = iff machine-readable output is specified, the verification
4522 code (a number);
4523
4524 = a textual description of the verification status, as the
4525 last field extending to the end of line.
4526
4527 That is, in normal (not machine-readable) output, the third field
4528 (numeric verification status) is not present.
4529
4530 In all cases, one of the repositories must be tagged as 'main';
4531 otherwise, all operations will fail!
4532
4533 
4534 File: tlbuild.info, Node: tlmgr restore, Next: tlmgr search, Prev: tlmgr repository, Up: tlmgr ACTIONS
4535
4536 B.6.26 restore
4537 --------------
4538
4539 *restore [_option_...] _pkg_ [_rev_]*
4540
4541 *restore [_option_...] --all*
4542
4543 Restore a package from a previously-made backup.
4544
4545 If '--all' is given, try to restore the latest revision of all
4546 package backups found in the backup directory.
4547
4548 Otherwise, if neither _pkg_ nor _rev_ are given, list the available
4549 backup revisions for all packages. With _pkg_ given but no _rev_,
4550 list all available backup revisions of _pkg_.
4551
4552 When listing available packages, 'tlmgr' shows the revision, and in
4553 parenthesis the creation time if available (in format yyyy-mm-dd
4554 hh:mm).
4555
4556 If (and only if) both _pkg_ and a valid revision number _rev_ are
4557 specified, try to restore the package from the specified backup.
4558
4559 Options:
4560
4561 *--all*
4562
4563 Try to restore the latest revision of all package backups
4564 found in the backup directory. Additional non-option
4565 arguments (like _pkg_) are not allowed.
4566
4567 *--backupdir* _directory_
4568
4569 Specify the directory where the backups are to be found. If
4570 not given it will be taken from the configuration setting in
4571 the TLPDB.
4572
4573 *--dry-run*
4574
4575 Nothing is actually restored; instead, the actions to be
4576 performed are written to the terminal.
4577
4578 *--force*
4579
4580 Don't ask questions.
4581
4582 *--json*
4583
4584 When listing backups, the option '--json' writes JSON output.
4585 The format is an array of JSON objects ('name', 'rev',
4586 'date'). For details see 'tlpkg/doc/json-formats.txt', format
4587 definition: 'TLBACKUPS'. If both '--json' and '--data' are
4588 given, '--json' takes precedence.
4589
4590 
4591 File: tlbuild.info, Node: tlmgr search, Next: tlmgr shell, Prev: tlmgr restore, Up: tlmgr ACTIONS
4592
4593 B.6.27 search
4594 -------------
4595
4596 *search [_option_...] _what_*
4597
4598 *search [_option_...] --file _what_*
4599
4600 *search [_option_...] --all _what_*
4601
4602 By default, search the names, short descriptions, and long
4603 descriptions of all locally installed packages for the argument
4604 _what_, interpreted as a (Perl) regular expression.
4605
4606 Options:
4607
4608 *--file*
4609
4610 List all filenames containing _what_.
4611
4612 *--all*
4613
4614 Search everything: package names, descriptions and filenames.
4615
4616 *--global*
4617
4618 Search the TeX Live Database of the installation medium,
4619 instead of the local installation.
4620
4621 *--word*
4622
4623 Restrict the search of package names and descriptions (but not
4624 filenames) to match only full words. For example, searching
4625 for 'table' with this option will not output packages
4626 containing the word 'tables' (unless they also contain the
4627 word 'table' on its own).
4628
4629 *--json*
4630
4631 Output search results as a JSON hash with two keys: *files*
4632 and *packages*. For the format of the JSON output see
4633 'tlpkg/doc/json-formats.txt', format definition 'TLSEARCH'.
4634
4635 
4636 File: tlbuild.info, Node: tlmgr shell, Next: tlmgr show, Prev: tlmgr search, Up: tlmgr ACTIONS
4637
4638 B.6.28 shell
4639 ------------
4640
4641 Starts an interactive mode, where tlmgr prompts for commands. This can
4642 be used directly, or for scripting. The first line of output is
4643 'protocol' _n_, where _n_ is an unsigned number identifying the protocol
4644 version (currently 1).
4645
4646 In general, tlmgr actions that can be given on the command line
4647 translate to commands in this shell mode. For example, you can say
4648 'update --list' to see what would be updated. The TLPDB is loaded the
4649 first time it is needed (not at the beginning), and used for the rest of
4650 the session.
4651
4652 Besides these actions, a few commands are specific to shell mode:
4653
4654 protocol
4655
4656 Print 'protocol _n_', the current protocol version.
4657
4658 help
4659
4660 Print pointers to this documentation.
4661
4662 version
4663
4664 Print tlmgr version information.
4665
4666 quit, end, bye, byebye, EOF
4667
4668 Exit.
4669
4670 restart
4671
4672 Restart 'tlmgr shell' with the original command line; most useful
4673 when developing 'tlmgr'.
4674
4675 load [local|remote]
4676
4677 Explicitly load the local or remote, respectively, TLPDB.
4678
4679 save
4680
4681 Save the local TLPDB, presumably after other operations have
4682 changed it.
4683
4684 get [_var_] =item set [_var_ [_val_]]
4685
4686 Get the value of _var_, or set it to _val_. Possible _var_ names:
4687 'debug-translation', 'machine-readable', 'no-execute-actions',
4688 'require-verification', 'verify-downloads', 'repository', and
4689 'prompt'. All except 'repository' and 'prompt' are booleans,
4690 taking values 0 and 1, and behave like the corresponding command
4691 line option. The 'repository' variable takes a string, and sets
4692 the remote repository location. The 'prompt' variable takes a
4693 string, and sets the current default prompt.
4694
4695 If _var_ or then _val_ is not specified, it is prompted for.
4696
4697 
4698 File: tlbuild.info, Node: tlmgr show, Next: tlmgr uninstall, Prev: tlmgr shell, Up: tlmgr ACTIONS
4699
4700 B.6.29 show
4701 -----------
4702
4703 Synonym for *note info: tlmgr info.
4704
4705 
4706 File: tlbuild.info, Node: tlmgr uninstall, Next: tlmgr update [_option_...] [_pkg_...], Prev: tlmgr show, Up: tlmgr ACTIONS
4707
4708 B.6.30 uninstall
4709 ----------------
4710
4711 Synonym for *note remove: tlmgr remove [_option_...] _pkg_....
4712
4713 
4714 File: tlbuild.info, Node: tlmgr update [_option_...] [_pkg_...], Prev: tlmgr uninstall, Up: tlmgr ACTIONS
4715
4716 B.6.31 update [_option_...] [_pkg_...]
4717 --------------------------------------
4718
4719 Updates the packages given as arguments to the latest version available
4720 at the installation source. Either '--all' or at least one _pkg_ name
4721 must be specified. Options:
4722
4723 *--all*
4724
4725 Update all installed packages except for 'tlmgr' itself. If
4726 updates to 'tlmgr' itself are present, this gives an error, unless
4727 also the option '--force' or '--self' is given. (See below.)
4728
4729 In addition to updating the installed packages, during the update
4730 of a collection the local installation is (by default) synchronized
4731 to the status of the collection on the server, for both additions
4732 and removals.
4733
4734 This means that if a package has been removed on the server (and
4735 thus has also been removed from the respective collection), 'tlmgr'
4736 will remove the package in the local installation. This is called
4737 "auto-remove" and is announced as such when using the option
4738 '--list'. This auto-removal can be suppressed using the option
4739 '--no-auto-remove' (not recommended, see option description).
4740
4741 Analogously, if a package has been added to a collection on the
4742 server that is also installed locally, it will be added to the
4743 local installation. This is called "auto-install" and is announced
4744 as such when using the option '--list'. This auto-installation can
4745 be suppressed using the option '--no-auto-install' (also not
4746 recommended).
4747
4748 An exception to the collection dependency checks (including the
4749 auto-installation of packages just mentioned) are those that have
4750 been "forcibly removed" by you, that is, you called 'tlmgr remove
4751 --force' on them. (See the 'remove' action documentation.) To
4752 reinstall any such forcibly removed packages use
4753 '--reinstall-forcibly-removed'.
4754
4755 To reiterate: automatic removals and additions are entirely
4756 determined by comparison of collections. Thus, if you manually
4757 install an individual package 'foo' which is later removed from the
4758 server, 'tlmgr' will not notice and will not remove it locally.
4759 (It has to be this way, without major rearchitecture work, because
4760 the tlpdb does not record the repository from which packages come
4761 from.)
4762
4763 If you want to exclude some packages from the current update run
4764 (e.g., due to a slow link), see the '--exclude' option below.
4765
4766 *--self*
4767
4768 Update 'tlmgr' itself (that is, the infrastructure packages) if
4769 updates to it are present. On Windows this includes updates to the
4770 private Perl interpreter shipped inside TeX Live.
4771
4772 If this option is given together with either '--all' or a list of
4773 packages, then 'tlmgr' will be updated first and, if this update
4774 succeeds, the new version will be restarted to complete the rest of
4775 the updates.
4776
4777 In short:
4778
4779 tlmgr update --self # update infrastructure only
4780 tlmgr update --self --all # update infrastructure and all packages
4781 tlmgr update --force --all # update all packages but *not* infrastructure
4782 # ... this last at your own risk, not recommended!
4783
4784 *--dry-run*
4785
4786 Nothing is actually installed; instead, the actions to be performed
4787 are written to the terminal. This is a more detailed report than
4788 '--list'.
4789
4790 *--list* [_pkg_]
4791
4792 Concisely list the packages which would be updated, newly
4793 installed, or removed, without actually changing anything. If
4794 '--all' is also given, all available updates are listed. If
4795 '--self' is given, but not '--all', only updates to the critical
4796 packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
4797 are listed. If neither '--all' nor '--self' is given, and in
4798 addition no _pkg_ is given, then '--all' is assumed (thus, 'tlmgr
4799 update --list' is the same as 'tlmgr update --list --all'). If
4800 neither '--all' nor '--self' is given, but specific package names
4801 are given, those packages are checked for updates.
4802
4803 *--exclude* _pkg_
4804
4805 Exclude _pkg_ from the update process. If this option is given
4806 more than once, its arguments accumulate.
4807
4808 An argument _pkg_ excludes both the package _pkg_ itself and all
4809 its related platform-specific packages _pkg.ARCH_. For example,
4810
4811 tlmgr update --all --exclude a2ping
4812
4813 will not update 'a2ping', 'a2ping.i386-linux', or any other
4814 'a2ping.'_ARCH_ package.
4815
4816 If this option specifies a package that would otherwise be a
4817 candidate for auto-installation, auto-removal, or reinstallation of
4818 a forcibly removed package, 'tlmgr' quits with an error message.
4819 Excludes are not supported in these circumstances.
4820
4821 This option can also be set permanently in the tlmgr config file
4822 with the key 'update-exclude'.
4823
4824 *--no-auto-remove* [_pkg_...]
4825
4826 By default, 'tlmgr' tries to remove packages in an existing
4827 collection which have disappeared on the server, as described above
4828 under '--all'. This option prevents such removals, either for all
4829 packages (with '--all'), or for just the given _pkg_ names. This
4830 can lead to an inconsistent TeX installation, since packages are
4831 not infrequently renamed or replaced by their authors. Therefore
4832 this is not recommended.
4833
4834 *--no-auto-install* [_pkg_...]
4835
4836 Under normal circumstances 'tlmgr' will install packages which are
4837 new on the server, as described above under '--all'. This option
4838 prevents any such automatic installation, either for all packages
4839 (with '--all'), or the given _pkg_ names.
4840
4841 Furthermore, after the 'tlmgr' run using this has finished, the
4842 packages that would have been auto-installed _will be considered as
4843 forcibly removed_. So, if 'foobar' is the only new package on the
4844 server, then
4845
4846 tlmgr update --all --no-auto-install
4847
4848 is equivalent to
4849
4850 tlmgr update --all
4851 tlmgr remove --force foobar
4852
4853 Again, since packages are sometimes renamed or replaced, using this
4854 option is not recommended.
4855
4856 *--reinstall-forcibly-removed*
4857
4858 Under normal circumstances 'tlmgr' will not install packages that
4859 have been forcibly removed by the user; that is, removed with
4860 'remove --force', or whose installation was prohibited by
4861 '--no-auto-install' during an earlier update.
4862
4863 This option makes 'tlmgr' ignore the forcible removals and
4864 re-install all such packages. This can be used to completely
4865 synchronize an installation with the server's idea of what is
4866 available:
4867
4868 tlmgr update --reinstall-forcibly-removed --all
4869
4870 *--backup*
4871
4872 *--backupdir* _directory_
4873
4874 These two options control the creation of backups of packages
4875 _before_ updating; that is, backing up packages as currently
4876 installed. If neither option is given, no backup will made. If
4877 '--backupdir' is given and specifies a writable directory then a
4878 backup will be made in that location. If only '--backup' is given,
4879 then a backup will be made to the directory previously set via the
4880 *note option: tlmgr option. action (see below). If both are given
4881 then a backup will be made to the specified _directory_.
4882
4883 You can also set options via the *note option: tlmgr option. action
4884 to automatically make backups for all packages, and/or keep only a
4885 certain number of backups.
4886
4887 'tlmgr' always makes a temporary backup when updating packages, in
4888 case of download or other failure during an update. In contrast,
4889 the purpose of this '--backup' option is to save a persistent
4890 backup in case the actual _content_ of the update causes problems,
4891 e.g., introduces an TeX incompatibility.
4892
4893 The *note restore: tlmgr restore. action explains how to restore
4894 from a backup.
4895
4896 *--no-depends*
4897
4898 If you call for updating a package normally all depending packages
4899 will also be checked for updates and updated if necessary. This
4900 switch suppresses this behavior.
4901
4902 *--no-depends-at-all*
4903
4904 See above under *note install: tlmgr install [_option_...]
4905 _pkg_.... (and beware).
4906
4907 *--force*
4908
4909 Force update of normal packages, without updating 'tlmgr' itself
4910 (unless the '--self' option is also given). Not recommended.
4911
4912 Also, 'update --list' is still performed regardless of this option.
4913
4914 If the package on the server is older than the package already
4915 installed (e.g., if the selected mirror is out of date), 'tlmgr' does
4916 not downgrade. Also, packages for uninstalled platforms are not
4917 installed.
4918
4919 'tlmgr' saves one copy of the main 'texlive.tlpdb' file used for an
4920 update with a suffix representing the repository url, as in
4921 'tlpkg/texlive.tlpdb.main.'_long-hash-string_. Thus, even when many
4922 mirrors are used, only one main 'tlpdb' backup is kept. For non-main
4923 repositories, which do not generally have (m)any mirrors, no pruning of
4924 backups is done.
4925
4926 This action does not automatically add or remove new symlinks in
4927 system directories; you need to run 'tlmgr' *note path: tlmgr path.
4928 yourself if you are using this feature and want new symlinks added.
4929
4930 
4931 File: tlbuild.info, Node: tlmgr CONFIGURATION FILE FOR TLMGR, Next: tlmgr CRYPTOGRAPHIC VERIFICATION, Prev: tlmgr ACTIONS, Up: tlmgr
4932
4933 B.7 CONFIGURATION FILE FOR TLMGR
4934 ================================
4935
4936 'tlmgr' reads two configuration files: one is system-wide, in
4937 'TEXMFSYSCONFIG/tlmgr/config', and the other is user-specific, in
4938 'TEXMFCONFIG/tlmgr/config'. The user-specific one is the default for
4939 the 'conf tlmgr' action. (Run 'kpsewhich -var-value=TEXMFSYSCONFIG' or
4940 '... TEXMFCONFIG ...' to see the actual directory names.)
4941
4942 A few defaults corresponding to command-line options can be set in
4943 these configuration files. In addition, the system-wide file can
4944 contain a directive to restrict the allowed actions.
4945
4946 In these config files, empty lines and lines starting with # are
4947 ignored. All other lines must look like:
4948
4949 key = value
4950
4951 where the spaces are optional but the '=' is required.
4952
4953 The allowed keys are:
4954
4955 'auto-remove =' 0 or 1 (default 1), same as command-line option.
4956
4957 'gui-expertmode =' 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings.
4958
4959 'gui-lang =' _llcode_, with a language code value as with the command-line option.
4960
4961 'no-checksums =' 0 or 1 (default 0, see below).
4962
4963 'persistent-downloads =' 0 or 1 (default 1), same as command-line option.
4964
4965 'require-verification =' 0 or 1 (default 0), same as command-line option.
4966
4967 'tkfontscale =' _floating-point number_ (default 1.0); scaling factor for fonts in the Tk-based frontends.
4968
4969 'update-exclude =' _comma-separated list of packages_ (no spaces allowed). Same as the command line option '--exclude' for the 'update' action.
4970
4971 'verify-downloads =' 0 or 1 (default 1), same as command-line option.
4972
4973 The system-wide config file can contain one additional key:
4974
4975 'allowed-actions =' _action1_[,_action2_,...] The value is a comma-separated list (no spaces) of 'tlmgr' actions which are allowed to be executed when 'tlmgr' is invoked in system mode (that is, without '--usermode'). This allows distributors to include 'tlmgr' in their packaging, but allow only a restricted set of actions that do not interfere with their distro package manager. For native TeX Live installations, it doesn't make sense to set this.
4976
4977 Finally, the 'no-checksums' key needs more explanation. By default,
4978 package checksums computed and stored on the server (in the TLPDB) are
4979 compared to checksums computed locally after downloading.
4980 'no-checksums' disables this process. The checksum algorithm is
4981 SHA-512. Your system must have one of (looked for in this order) the
4982 Perl 'Digest::SHA' module, the 'openssl' program
4983 (<https://openssl.org>), the 'sha512sum' program (from GNU Coreutils,
4984 <https://www.gnu.org/software/coreutils>), or finally the 'shasum'
4985 program (just to support old Macs). If none of these are available, a
4986 warning is issued and 'tlmgr' proceeds without checking checksums.
4987 'no-checksums' avoids the warning. (Incidentally, other SHA
4988 implementations, such as the pure Perl and pure Lua modules, are much
4989 too slow to be usable in our context.)
4990
4991 
4992 File: tlbuild.info, Node: tlmgr CRYPTOGRAPHIC VERIFICATION, Next: tlmgr USER MODE, Prev: tlmgr CONFIGURATION FILE FOR TLMGR, Up: tlmgr
4993
4994 B.8 CRYPTOGRAPHIC VERIFICATION
4995 ==============================
4996
4997 'tlmgr' and 'install-tl' perform cryptographic verification if possible.
4998 If verification is performed and successful, the programs report
4999 '(verified)' after loading the TLPDB; otherwise, they report '(not
5000 verified)'. But either way, by default the installation and/or updates
5001 proceed normally.
5002
5003 If a program named 'gpg' is available (that is, found in 'PATH'), by
5004 default cryptographic signatures will be checked: we require the main
5005 repository be signed, but not any additional repositories. If 'gpg' is
5006 not available, by default signatures are not checked and no verification
5007 is carried out, but 'tlmgr' still proceeds normally.
5008
5009 The behavior of the verification can be controlled by the command
5010 line and config file option 'verify-repo' which takes one of the
5011 following values: 'none', 'main', or 'all'. With 'none', no
5012 verification whatsoever is attempted. With 'main' (the default)
5013 verification is required only for the main repository, and only if 'gpg'
5014 is available; though attempted for all, missing signatures of subsidiary
5015 repositories will not result in an error. Finally, in the case of
5016 'all', 'gpg' must be available and all repositories need to be signed.
5017
5018 In all cases, if a signature is checked and fails to verify, an error
5019 is raised.
5020
5021 Cryptographic verification requires checksum checking (described just
5022 above) to succeed, and a working GnuPG ('gpg') program (see below for
5023 search method). Then, unless cryptographic verification has been
5024 disabled, a signature file ('texlive.tlpdb.*.asc') of the checksum file
5025 is downloaded and the signature verified. The signature is created by
5026 the TeX Live Distribution GPG key 0x0D5E5D9106BAB6BC, which in turn is
5027 signed by Karl Berry's key 0x0716748A30D155AD and Norbert Preining's key
5028 0x6CACA448860CDC13. All of these keys are obtainable from the standard
5029 key servers.
5030
5031 Additional trusted keys can be added using the 'key' action.
5032
5033 * Menu:
5034
5035 * tlmgr Configuration of GnuPG invocation::
5036
5037 
5038 File: tlbuild.info, Node: tlmgr Configuration of GnuPG invocation, Up: tlmgr CRYPTOGRAPHIC VERIFICATION
5039
5040 B.8.1 Configuration of GnuPG invocation
5041 ---------------------------------------
5042
5043 The executable used for GnuPG is searched as follows: If the environment
5044 variable 'TL_GNUPG' is set, it is tested and used; otherwise 'gpg' is
5045 checked; finally 'gpg2' is checked.
5046
5047 Further adaptation of the 'gpg' invocation can be made using the two
5048 environment variables 'TL_GNUPGHOME', which is passed to 'gpg' as the
5049 value for '--homedir', and 'TL_GNUPGARGS', which replaces the default
5050 options '--no-secmem-warning --no-permission-warning'.
5051
5052 
5053 File: tlbuild.info, Node: tlmgr USER MODE, Next: tlmgr MULTIPLE REPOSITORIES, Prev: tlmgr CRYPTOGRAPHIC VERIFICATION, Up: tlmgr
5054
5055 B.9 USER MODE
5056 =============
5057
5058 'tlmgr' provides a restricted way, called "user mode", to manage
5059 arbitrary texmf trees in the same way as the main installation. For
5060 example, this allows people without write permissions on the
5061 installation location to update/install packages into a tree of their
5062 own.
5063
5064 'tlmgr' is switched into user mode with the command line option
5065 '--usermode'. It does not switch automatically, nor is there any
5066 configuration file setting for it. Thus, this option has to be
5067 explicitly given every time user mode is to be activated.
5068
5069 This mode of 'tlmgr' works on a user tree, by default the value of
5070 the 'TEXMFHOME' variable. This can be overridden with the command line
5071 option '--usertree'. In the following when we speak of the user tree we
5072 mean either 'TEXMFHOME' or the one given on the command line.
5073
5074 Not all actions are allowed in user mode; 'tlmgr' will warn you and
5075 not carry out any problematic actions. Currently not supported (and
5076 probably will never be) is the 'platform' action. The 'gui' action is
5077 currently not supported, but may be in a future release.
5078
5079 Some 'tlmgr' actions don't need any write permissions and thus work
5080 the same in user mode and normal mode. Currently these are: 'check',
5081 'help', 'list', 'print-platform', 'print-platform-info', 'search',
5082 'show', 'version'.
5083
5084 On the other hand, most of the actions dealing with package
5085 management do need write permissions, and thus behave differently in
5086 user mode, as described below: 'install', 'update', 'remove', 'option',
5087 'paper', 'generate', 'backup', 'restore', 'uninstall', 'symlinks'.
5088
5089 Before using 'tlmgr' in user mode, you have to set up the user tree
5090 with the 'init-usertree' action. This creates _usertree_'/web2c' and
5091 _usertree_'/tlpkg/tlpobj', and a minimal
5092 _usertree_'/tlpkg/texlive.tlpdb'. At that point, you can tell 'tlmgr'
5093 to do the (supported) actions by adding the '--usermode' command line
5094 option.
5095
5096 In user mode the file _usertree_'/tlpkg/texlive.tlpdb' contains only
5097 the packages that have been installed into the user tree using 'tlmgr',
5098 plus additional options from the "virtual" package
5099 '00texlive.installation' (similar to the main installation's
5100 'texlive.tlpdb').
5101
5102 All actions on packages in user mode can only be carried out on
5103 packages that are known as 'relocatable'. This excludes all packages
5104 containing executables and a few other core packages. Of the 2500 or so
5105 packages currently in TeX Live the vast majority are relocatable and can
5106 be installed into a user tree.
5107
5108 Description of changes of actions in user mode:
5109
5110 * Menu:
5111
5112 * tlmgr User mode install::
5113 * tlmgr User mode backup, restore, remove, update::
5114 * tlmgr User mode generate, option, paper::
5115 * tlmgr User mode logs::
5116
5117 
5118 File: tlbuild.info, Node: tlmgr User mode install, Next: tlmgr User mode backup, restore, remove, update, Up: tlmgr USER MODE
5119
5120 B.9.1 User mode install
5121 -----------------------
5122
5123 In user mode, the 'install' action checks that the package and all
5124 dependencies are all either relocated or already installed in the system
5125 installation. If this is the case, it unpacks all containers to be
5126 installed into the user tree (to repeat, that's either 'TEXMFHOME' or
5127 the value of '--usertree') and add the respective packages to the user
5128 tree's 'texlive.tlpdb' (creating it if need be).
5129
5130 Currently installing a collection in user mode installs all dependent
5131 packages, but in contrast to normal mode, does _not_ install dependent
5132 collections. For example, in normal mode 'tlmgr install
5133 collection-context' would install 'collection-basic' and other
5134 collections, while in user mode, _only_ the packages mentioned in
5135 'collection-context' are installed.
5136
5137 If a package shipping map files is installed in user mode, a backup
5138 of the user's 'updmap.cfg' in 'USERTREE/web2c/' is made, and then this
5139 file regenerated from the list of installed packages.
5140
5141 
5142 File: tlbuild.info, Node: tlmgr User mode backup, restore, remove, update, Next: tlmgr User mode generate, option, paper, Prev: tlmgr User mode install, Up: tlmgr USER MODE
5143
5144 B.9.2 User mode backup, restore, remove, update
5145 -----------------------------------------------
5146
5147 In user mode, these actions check that all packages to be acted on are
5148 installed in the user tree before proceeding; otherwise, they behave
5149 just as in normal mode.
5150
5151 
5152 File: tlbuild.info, Node: tlmgr User mode generate, option, paper, Next: tlmgr User mode logs, Prev: tlmgr User mode backup, restore, remove, update, Up: tlmgr USER MODE
5153
5154 B.9.3 User mode generate, option, paper
5155 ---------------------------------------
5156
5157 In user mode, these actions operate only on the user tree's
5158 configuration files and/or 'texlive.tlpdb'.
5159
5160 
5161 File: tlbuild.info, Node: tlmgr User mode logs, Prev: tlmgr User mode generate, option, paper, Up: tlmgr USER MODE
5162
5163 B.9.4 User mode logs
5164 --------------------
5165
5166 In user mode, 'tlmgr.log' and <tlmgr-commands.log> are written in the
5167 'TEXMFVAR/web2c/' directlry instead of 'TEXMFSYSVAR/web2c/'.
5168
5169 
5170 File: tlbuild.info, Node: tlmgr MULTIPLE REPOSITORIES, Next: tlmgr GUI FOR TLMGR, Prev: tlmgr USER MODE, Up: tlmgr
5171
5172 B.10 MULTIPLE REPOSITORIES
5173 ==========================
5174
5175 The main TeX Live repository contains a vast array of packages.
5176 Nevertheless, additional local repositories can be useful to provide
5177 locally-installed resources, such as proprietary fonts and house styles.
5178 Also, alternative package repositories distribute packages that cannot
5179 or should not be included in TeX Live, for whatever reason.
5180
5181 The simplest and most reliable method is to temporarily set the
5182 installation source to any repository (with the '-repository' or 'option
5183 repository' command line options), and perform your operations.
5184
5185 When you are using multiple repositories over a sustained length of
5186 time, however, explicitly switching between them becomes inconvenient.
5187 Thus, it's possible to tell 'tlmgr' about additional repositories you
5188 want to use. The basic command is 'tlmgr repository add'. The rest of
5189 this section explains further.
5190
5191 When using multiple repositories, one of them has to be set as the
5192 main repository, which distributes most of the installed packages. When
5193 you switch from a single repository installation to a multiple
5194 repository installation, the previous sole repository will be set as the
5195 main repository.
5196
5197 By default, even if multiple repositories are configured, packages
5198 are _still_ _only_ installed from the main repository. Thus, simply
5199 adding a second repository does not actually enable installation of
5200 anything from there. You also have to specify which packages should be
5201 taken from the new repository, by specifying so-called "pinning" rules,
5202 described next.
5203
5204 * Menu:
5205
5206 * tlmgr Pinning::
5207
5208 
5209 File: tlbuild.info, Node: tlmgr Pinning, Up: tlmgr MULTIPLE REPOSITORIES
5210
5211 B.10.1 Pinning
5212 --------------
5213
5214 When a package 'foo' is pinned to a repository, a package 'foo' in any
5215 other repository, even if it has a higher revision number, will not be
5216 considered an installable candidate.
5217
5218 As mentioned above, by default everything is pinned to the main
5219 repository. Let's now go through an example of setting up a second
5220 repository and enabling updates of a package from it.
5221
5222 First, check that we have support for multiple repositories, and have
5223 only one enabled (as is the case by default):
5224
5225 $ tlmgr repository list
5226 List of repositories (with tags if set):
5227 /var/www/norbert/tlnet
5228
5229 Ok. Let's add the 'tlcontrib' repository (this is a real repository
5230 hosted at <http://contrib.texlive.info>) with the tag 'tlcontrib':
5231
5232 $ tlmgr repository add http://contrib.texlive.info/current tlcontrib
5233
5234 Check the repository list again:
5235
5236 $ tlmgr repository list
5237 List of repositories (with tags if set):
5238 http://contrib.texlive.info/current (tlcontrib)
5239 /var/www/norbert/tlnet (main)
5240
5241 Now we specify a pinning entry to get the package 'classico' from
5242 'tlcontrib':
5243
5244 $ tlmgr pinning add tlcontrib classico
5245
5246 Check that we can find 'classico':
5247
5248 $ tlmgr show classico
5249 package: classico
5250 ...
5251 shortdesc: URW Classico fonts
5252 ...
5253
5254 - install 'classico':
5255
5256 $ tlmgr install classico
5257 tlmgr: package repositories:
5258 ...
5259 [1/1, ??:??/??:??] install: classico @tlcontrib [737k]
5260
5261 In the output here you can see that the 'classico' package has been
5262 installed from the 'tlcontrib' repository ('@tlcontrib').
5263
5264 Finally, 'tlmgr pinning' also supports removing certain or all
5265 packages from a given repository:
5266
5267 $ tlmgr pinning remove tlcontrib classico # remove just classico
5268 $ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib
5269
5270 A summary of 'tlmgr pinning' actions is given above.
5271
5272 
5273 File: tlbuild.info, Node: tlmgr GUI FOR TLMGR, Next: tlmgr MACHINE-READABLE OUTPUT, Prev: tlmgr MULTIPLE REPOSITORIES, Up: tlmgr
5274
5275 B.11 GUI FOR TLMGR
5276 ==================
5277
5278 The graphical user interface for 'tlmgr' requires Perl/Tk
5279 <https://search.cpan.org/search?query=perl%2Ftk>. For Unix-based
5280 systems Perl/Tk (as well as Perl of course) has to be installed outside
5281 of TL. <https://tug.org/texlive/distro.html#perltk> has a list of
5282 invocations for some distros. For Windows the necessary modules are no
5283 longer shipped within TeX Live, so you'll have to have an external Perl
5284 available that includes them.
5285
5286 We are talking here about the GUI built into tlmgr itself, not about
5287 the other tlmgr GUIs, which are: tlshell (Tcl/Tk-based), tlcockpit
5288 (Java-based) and, only on Macs, TeX Live Utility. These are invoked as
5289 separate programs.
5290
5291 The GUI mode of tlmgr is started with the invocation 'tlmgr gui';
5292 assuming Tk is loadable, the graphical user interface will be shown.
5293 The main window contains a menu bar, the main display, and a status area
5294 where messages normally shown on the console are displayed.
5295
5296 Within the main display there are three main parts: the 'Display
5297 configuration' area, the list of packages, and the action buttons.
5298
5299 Also, at the top right the currently loaded repository is shown; this
5300 also acts as a button and when clicked will try to load the default
5301 repository. To load a different repository, see the 'tlmgr' menu item.
5302
5303 Finally, the status area at the bottom of the window gives additional
5304 information about what is going on.
5305
5306 * Menu:
5307
5308 * tlmgr Main display::
5309 * tlmgr Menu bar::
5310 * tlmgr GUI options::
5311
5312 
5313 File: tlbuild.info, Node: tlmgr Main display, Next: tlmgr Menu bar, Up: tlmgr GUI FOR TLMGR
5314
5315 B.11.1 Main display
5316 -------------------
5317
5318 * Menu:
5319
5320 * tlmgr Display configuration area::
5321 * tlmgr Package list area::
5322 * tlmgr Main display action buttons::
5323
5324 
5325 File: tlbuild.info, Node: tlmgr Display configuration area, Next: tlmgr Package list area, Up: tlmgr Main display
5326
5327 B.11.1.1 Display configuration area
5328 ...................................
5329
5330 The first part of the main display allows you to specify (filter) which
5331 packages are shown. By default, all are shown. Changes here are
5332 reflected right away.
5333
5334 Status
5335
5336 Select whether to show all packages (the default), only those
5337 installed, only those _not_ installed, or only those with update
5338 available.
5339
5340 Category
5341
5342 Select which categories are shown: packages, collections, and/or
5343 schemes. These are briefly explained in the *note DESCRIPTION:
5344 tlmgr DESCRIPTION. section above.
5345
5346 Match
5347
5348 Select packages matching for a specific pattern. By default, this
5349 searches both descriptions and filenames. You can also select a
5350 subset for searching.
5351
5352 Selection
5353
5354 Select packages to those selected, those not selected, or all.
5355 Here, "selected" means that the checkbox in the beginning of the
5356 line of a package is ticked.
5357
5358 Display configuration buttons
5359
5360 To the right there are three buttons: select all packages, select
5361 none (a.k.a. deselect all), and reset all these filters to the
5362 defaults, i.e., show all available.
5363
5364 
5365 File: tlbuild.info, Node: tlmgr Package list area, Next: tlmgr Main display action buttons, Prev: tlmgr Display configuration area, Up: tlmgr Main display
5366
5367 B.11.1.2 Package list area
5368 ..........................
5369
5370 The second are of the main display lists all installed packages. If a
5371 repository is loaded, those that are available but not installed are
5372 also listed.
5373
5374 Double clicking on a package line pops up an informational window
5375 with further details: the long description, included files, etc.
5376
5377 Each line of the package list consists of the following items:
5378
5379 a checkbox
5380
5381 Used to select particular packages; some of the action buttons (see
5382 below) work only on the selected packages.
5383
5384 package name
5385
5386 The name (identifier) of the package as given in the database.
5387
5388 local revision (and version)
5389
5390 If the package is installed the TeX Live revision number for the
5391 installed package will be shown. If there is a catalogue version
5392 given in the database for this package, it will be shown in
5393 parentheses. However, the catalogue version, unlike the TL
5394 revision, is not guaranteed to reflect what is actually installed.
5395
5396 remote revision (and version)
5397
5398 If a repository has been loaded the revision of the package in the
5399 repository (if present) is shown. As with the local column, if a
5400 catalogue version is provided it will be displayed. And also as
5401 with the local column, the catalogue version may be stale.
5402
5403 short description
5404
5405 The short description of the package.
5406
5407 
5408 File: tlbuild.info, Node: tlmgr Main display action buttons, Prev: tlmgr Package list area, Up: tlmgr Main display
5409
5410 B.11.1.3 Main display action buttons
5411 ....................................
5412
5413 Below the list of packages are several buttons:
5414
5415 Update all installed
5416
5417 This calls 'tlmgr update --all', i.e., tries to update all
5418 available packages. Below this button is a toggle to allow
5419 reinstallation of previously removed packages as part of this
5420 action.
5421
5422 The other four buttons only work on the selected packages, i.e.,
5423 those where the checkbox at the beginning of the package line is
5424 ticked.
5425
5426 Update
5427
5428 Update only the selected packages.
5429
5430 Install
5431
5432 Install the selected packages; acts like 'tlmgr install', i.e.,
5433 also installs dependencies. Thus, installing a collection installs
5434 all its constituent packages.
5435
5436 Remove
5437
5438 Removes the selected packages; acts like 'tlmgr remove', i.e., it
5439 will also remove dependencies of collections (but not dependencies
5440 of normal packages).
5441
5442 Backup
5443
5444 Makes a backup of the selected packages; acts like 'tlmgr backup'.
5445 This action needs the option 'backupdir' set (see 'Options -'
5446 General>).
5447
5448 
5449 File: tlbuild.info, Node: tlmgr Menu bar, Next: tlmgr GUI options, Prev: tlmgr Main display, Up: tlmgr GUI FOR TLMGR
5450
5451 B.11.2 Menu bar
5452 ---------------
5453
5454 The following entries can be found in the menu bar:
5455
5456 'tlmgr' menu
5457
5458 The items here load various repositories: the default as specified
5459 in the TeX Live database, the default network repository, the
5460 repository specified on the command line (if any), and an
5461 arbitrarily manually-entered one. Also has the so-necessary 'quit'
5462 operation.
5463
5464 'Options menu'
5465
5466 Provides access to several groups of options: 'Paper'
5467 (configuration of default paper sizes), 'Platforms' (only on Unix,
5468 configuration of the supported/installed platforms), 'GUI Language'
5469 (select language used in the GUI interface), and 'General'
5470 (everything else).
5471
5472 Several toggles are also here. The first is 'Expert options',
5473 which is set by default. If you turn this off, the next time you
5474 start the GUI a simplified screen will be shown that display only
5475 the most important functionality. This setting is saved in the
5476 configuration file of 'tlmgr'; see *note CONFIGURATION FILE FOR
5477 TLMGR: tlmgr CONFIGURATION FILE FOR TLMGR. for details.
5478
5479 The other toggles are all off by default: for debugging output, to
5480 disable the automatic installation of new packages, and to disable
5481 the automatic removal of packages deleted from the server. Playing
5482 with the choices of what is or isn't installed may lead to an
5483 inconsistent TeX Live installation; e.g., when a package is
5484 renamed.
5485
5486 'Actions menu'
5487
5488 Provides access to several actions: update the filename database
5489 (aka 'ls-R', 'mktexlsr', 'texhash'), rebuild all formats
5490 ('fmtutil-sys --all'), update the font map database ('updmap-sys'),
5491 restore from a backup of a package, and use of symbolic links in
5492 system directories (not on Windows).
5493
5494 The final action is to remove the entire TeX Live installation
5495 (also not on Windows).
5496
5497 'Help menu'
5498
5499 Provides access to the TeX Live manual (also on the web at
5500 <https://tug.org/texlive/doc.html>) and the usual "About" box.
5501
5502 
5503 File: tlbuild.info, Node: tlmgr GUI options, Prev: tlmgr Menu bar, Up: tlmgr GUI FOR TLMGR
5504
5505 B.11.3 GUI options
5506 ------------------
5507
5508 Some generic Perl/Tk options can be specified with 'tlmgr gui' to
5509 control the display:
5510
5511 '-background' _color_
5512
5513 Set background color.
5514
5515 '-font "' _fontname_ _fontsize_ '"'
5516
5517 Set font, e.g., 'tlmgr gui -font "helvetica 18"'. The argument to
5518 '-font' must be quoted, i.e., passed as a single string.
5519
5520 '-foreground' _color_
5521
5522 Set foreground color.
5523
5524 '-geometry' _geomspec_
5525
5526 Set the X geometry, e.g., 'tlmgr gui -geometry 1024x512-0+0'
5527 creates the window of (approximately) the given size in the
5528 upper-right corner of the display.
5529
5530 '-xrm' _xresource_
5531
5532 Pass the arbitrary X resource string _xresource_.
5533
5534 A few other obscure options are recognized but not mentioned here.
5535 See the Perl/Tk documentation (<https://search.cpan.org/perldoc?Tk>) for
5536 the complete list, and any X documentation for general information.
5537
5538 
5539 File: tlbuild.info, Node: tlmgr MACHINE-READABLE OUTPUT, Next: tlmgr ENVIRONMENT VARIABLES, Prev: tlmgr GUI FOR TLMGR, Up: tlmgr
5540
5541 B.12 MACHINE-READABLE OUTPUT
5542 ============================
5543
5544 With the '--machine-readable' option, 'tlmgr' writes to stdout in the
5545 fixed line-oriented format described here, and the usual informational
5546 messages for human consumption are written to stderr (normally they are
5547 written to stdout). The idea is that a program can get all the
5548 information it needs by reading stdout.
5549
5550 Currently this option only applies to the *note update: tlmgr update
5551 [_option_...] [_pkg_...], *note install: tlmgr install [_option_...]
5552 _pkg_..., and *note option: tlmgr option. actions.
5553
5554 * Menu:
5555
5556 * tlmgr Machine-readable update and install output::
5557 * tlmgr Machine-readable option output::
5558
5559 
5560 File: tlbuild.info, Node: tlmgr Machine-readable update and install output, Next: tlmgr Machine-readable option output, Up: tlmgr MACHINE-READABLE OUTPUT
5561
5562 B.12.1 Machine-readable 'update' and 'install' output
5563 -----------------------------------------------------
5564
5565 The output format is as follows:
5566
5567 fieldname "\t" value
5568 ...
5569 "end-of-header"
5570 pkgname status localrev serverrev size runtime esttot
5571 ...
5572 "end-of-updates"
5573 other output from post actions, not in machine readable form
5574
5575 The header section currently has two fields: 'location-url' (the
5576 repository source from which updates are being drawn), and 'total-bytes'
5577 (the total number of bytes to be downloaded).
5578
5579 The _localrev_ and _serverrev_ fields for each package are the
5580 revision numbers in the local installation and server repository,
5581 respectively. The _size_ field is the number of bytes to be downloaded,
5582 i.e., the size of the compressed tar file for a network installation,
5583 not the unpacked size. The runtime and esttot fields are only present
5584 for updated and auto-install packages, and contain the currently passed
5585 time since start of installation/updates and the estimated total time.
5586
5587 Line endings may be either LF or CRLF depending on the current
5588 platform.
5589
5590 'location-url' _location_
5591
5592 The _location_ may be a url (including 'file:///foo/bar/...'), or a
5593 directory name ('/foo/bar'). It is the package repository from
5594 which the new package information was drawn.
5595
5596 'total-bytes' _count_
5597
5598 The _count_ is simply a decimal number, the sum of the sizes of all
5599 the packages that need updating or installing (which are listed
5600 subsequently).
5601
5602 Then comes a line with only the literal string 'end-of-header'.
5603
5604 Each following line until a line with literal string 'end-of-updates'
5605 reports on one package. The fields on each line are separated by a tab.
5606 Here are the fields.
5607
5608 _pkgname_
5609
5610 The TeX Live package identifier, with a possible platform suffix
5611 for executables. For instance, 'pdftex' and 'pdftex.i386-linux'
5612 are given as two separate packages, one on each line.
5613
5614 _status_
5615
5616 The status of the package update. One character, as follows:
5617
5618 'd'
5619
5620 The package was removed on the server.
5621
5622 'f'
5623
5624 The package was removed in the local installation, even though
5625 a collection depended on it. (E.g., the user ran 'tlmgr
5626 remove --force'.)
5627
5628 'u'
5629
5630 Normal update is needed.
5631
5632 'r'
5633
5634 Reversed non-update: the locally-installed version is newer
5635 than the version on the server.
5636
5637 'a'
5638
5639 Automatically-determined need for installation, the package is
5640 new on the server and is (most probably) part of an installed
5641 collection.
5642
5643 'i'
5644
5645 Package will be installed and isn't present in the local
5646 installation (action install).
5647
5648 'I'
5649
5650 Package is already present but will be reinstalled (action
5651 install).
5652
5653 _localrev_
5654
5655 The revision number of the installed package, or '-' if it is not
5656 present locally.
5657
5658 _serverrev_
5659
5660 The revision number of the package on the server, or '-' if it is
5661 not present on the server.
5662
5663 _size_
5664
5665 The size in bytes of the package on the server. The sum of all the
5666 package sizes is given in the 'total-bytes' header field mentioned
5667 above.
5668
5669 _runtime_
5670
5671 The run time since start of installations or updates.
5672
5673 _esttot_
5674
5675 The estimated total time.
5676
5677 
5678 File: tlbuild.info, Node: tlmgr Machine-readable option output, Prev: tlmgr Machine-readable update and install output, Up: tlmgr MACHINE-READABLE OUTPUT
5679
5680 B.12.2 Machine-readable 'option' output
5681 ---------------------------------------
5682
5683 The output format is as follows:
5684
5685 key "\t" value
5686
5687 If a value is not saved in the database the string '(not set)' is
5688 shown.
5689
5690 If you are developing a program that uses this output, and find that
5691 changes would be helpful, do not hesitate to write the mailing list.
5692
5693 
5694 File: tlbuild.info, Node: tlmgr ENVIRONMENT VARIABLES, Next: tlmgr AUTHORS AND COPYRIGHT, Prev: tlmgr MACHINE-READABLE OUTPUT, Up: tlmgr
5695
5696 B.13 ENVIRONMENT VARIABLES
5697 ==========================
5698
5699 'tlmgr' uses many of the standard TeX environment variables, as reported
5700 by, e.g., 'tlmgr conf' (*note conf: tlmgr conf.).
5701
5702 In addition, for ease in scripting and debugging, 'tlmgr' looks for
5703 the following environment variables. These are not of interest for
5704 normal user installations.
5705
5706 'TEXLIVE_COMPRESSOR'
5707
5708 This variable allows selecting a different compressor program for
5709 backups and intermediate rollback containers. The order of
5710 selection is:
5711
5712 1. If the environment variable 'TEXLIVE_COMPRESSOR' is defined,
5713 use it; abort if it doesn't work. Possible values: 'lz4',
5714 'gzip', 'xz'. The necessary options are added internally.
5715
5716 2. If lz4 is available (either from the system or TL) and
5717 working, use that.
5718
5719 3. If gzip is available (from the system) and working, use that.
5720
5721 4. If xz is available (either from the system or TL) and working,
5722 use that.
5723
5724 lz4 and gzip are faster in creating tlmgr's local backups, hence
5725 they are preferred. The unconditional use of xz for the tlnet
5726 containers is unaffected, to minimize download sizes.
5727
5728 'TEXLIVE_DOWNLOADER'
5729
5730 'TL_DOWNLOAD_PROGRAM'
5731
5732 'TL_DOWNLOAD_ARGS'
5733
5734 These options allow selecting different download programs then the
5735 ones automatically selected by the installer. The order of
5736 selection is:
5737
5738 1. If the environment variable 'TEXLIVE_DOWNLOADER' is defined,
5739 use it; abort if the specified program doesn't work. Possible
5740 values: 'lwp', 'curl', 'wget'. The necessary options are
5741 added internally.
5742
5743 2. If the environment variable 'TL_DOWNLOAD_PROGRAM' is defined
5744 (can be any value), use it together with 'TL_DOWNLOAD_ARGS';
5745 abort if it doesn't work.
5746
5747 3. If LWP is available and working, use that (by far the most
5748 efficient method, as it supports persistent downloads).
5749
5750 4. If curl is available (from the system) and working, use that.
5751
5752 5. If wget is available (either from the system or TL) and
5753 working, use that.
5754
5755 TL provides 'wget' binaries for platforms where necessary, so some
5756 download method should always be available.
5757
5758 'TEXLIVE_PREFER_OWN'
5759
5760 By default, compression and download programs provided by the
5761 system, i.e., found along 'PATH' are preferred over those shipped
5762 with TeX Live.
5763
5764 This can create problems with systems that are too old, and so can
5765 be overridden by setting the environment variable
5766 'TEXLIVE_PREFER_OWN' to 1. In this case, executables shipped with
5767 TL will be preferred.
5768
5769 Extra compression/download programs not provided by TL, such as
5770 gzip, lwp, and curl, are still checked for on the system and used
5771 if available, per the above. 'TEXLIVE_PREFER_OWN' only applies
5772 when the program being checked for is shipped with TL, namely the
5773 lz4 and xz compressors and wget downloader.
5774
5775 Exception: on Windows, the 'tar.exe' shipped with TL is always
5776 used, regardless of any setting.
5777
5778 
5779 File: tlbuild.info, Node: tlmgr AUTHORS AND COPYRIGHT, Prev: tlmgr ENVIRONMENT VARIABLES, Up: tlmgr
5780
5781 B.14 AUTHORS AND COPYRIGHT
5782 ==========================
5783
5784 This script and its documentation were written for the TeX Live
5785 distribution (<https://tug.org/texlive>) and both are licensed under the
5786 GNU General Public License Version 2 or later.
5787
5788 $Id: tlmgr.pl 77655 2026-02-07 15:38:21Z karl $
5789
5790 
5791 File: tlbuild.info, Node: Index, Prev: tlmgr, Up: Top
5792
5793 Index
5794 *****
5795
5796 [index]
5797 * Menu:
5798
5799 * --bindir configure option: --prefix --bindir ....
5800 (line 6)
5801 * --bindir configure option <1>: --enable-multiplatform.
5802 (line 6)
5803 * --build=HOST: Cross configuring. (line 6)
5804 * --disable-all-packages: Build one package. (line 6)
5805 * --disable-all-pkgs: --disable-all-pkgs. (line 6)
5806 * --disable-bibtex8: Configure options for texk/bibtex-x.
5807 (line 9)
5808 * --disable-bibtexu: Configure options for texk/bibtex-x.
5809 (line 12)
5810 * --disable-dump-share: Configure options for texk/web2c.
5811 (line 27)
5812 * --disable-dvipdfmx: Configure options for texk/dvipdfm-x.
5813 (line 12)
5814 * --disable-etex-synctex: Configure options for texk/web2c.
5815 (line 59)
5816 * --disable-ipc: Configure options for texk/web2c.
5817 (line 31)
5818 * --disable-largefile: --disable-largefile. (line 6)
5819 * --disable-linked-scripts: Configure options for texk/texlive.
5820 (line 6)
5821 * --disable-mf-nowin: Configure options for texk/web2c.
5822 (line 34)
5823 * --disable-missing: --disable-missing. (line 6)
5824 * --disable-native-texlive-build: --disable-native-texlive-build.
5825 (line 6)
5826 * --disable-PROG: --enable-PROG --disable-PROG.
5827 (line 6)
5828 * --disable-synctex: Configure options for texk/web2c.
5829 (line 64)
5830 * --disable-tex: Configure options for texk/web2c.
5831 (line 37)
5832 * --disable-web-progs: Configure options for texk/web2c.
5833 (line 41)
5834 * --disable-xdvipdfmx: Configure options for texk/dvipdfm-x.
5835 (line 15)
5836 * --enable-*win for Metafont window support: Configure options for texk/web2c.
5837 (line 55)
5838 * --enable-auto-core: Configure options for texk/web2c.
5839 (line 45)
5840 * --enable-compiler-warnings=LEVEL: --enable-compiler-warnings=LEVEL.
5841 (line 6)
5842 * --enable-cxx-runtime-hack: Macros for compilers.
5843 (line 30)
5844 * --enable-etex: Configure options for texk/web2c.
5845 (line 37)
5846 * --enable-libtool-hack: Configure options for texk/web2c.
5847 (line 50)
5848 * --enable-maintainer-mode: Build system tools. (line 28)
5849 * --enable-maintainer-mode <1>: --enable-maintainer-mode.
5850 (line 6)
5851 * --enable-missing to ignore dependencies: Build one package. (line 94)
5852 * --enable-mktextfm-default: kpathsea library. (line 18)
5853 * --enable-multiplatform: --enable-multiplatform.
5854 (line 6)
5855 * --enable-PROG: --enable-PROG --disable-PROG.
5856 (line 6)
5857 * --enable-shared: --enable-shared. (line 6)
5858 * --enable-silent-rules: --enable-silent-rules.
5859 (line 6)
5860 * --enable-tex-synctex: Configure options for texk/web2c.
5861 (line 59)
5862 * --enable-texlive-build: --disable-native-texlive-build.
5863 (line 15)
5864 * --enable-xi2-scrolling: Configure options for texk/xdvik.
5865 (line 13)
5866 * --enable-xindy-docs: Configure options for utils/xindy.
5867 (line 10)
5868 * --enable-xindy-rules: Configure options for utils/xindy.
5869 (line 6)
5870 * --host=HOST: Cross configuring. (line 6)
5871 * --libdir configure option: --enable-multiplatform.
5872 (line 6)
5873 * --no-print-directory GNU make option: Build one engine. (line 61)
5874 * --prefix configure option: --prefix --bindir ....
5875 (line 6)
5876 * --with-banner-add=STR: Configure options for texk/web2c.
5877 (line 6)
5878 * --with-clisp-runtime=FILENAME: Configure options for utils/xindy.
5879 (line 14)
5880 * --with-editor=CMD: Configure options for texk/web2c.
5881 (line 11)
5882 * --with-fontconfig-includes=DIR: Configure options for texk/web2c.
5883 (line 16)
5884 * --with-fontconfig-libdir=DIR: Configure options for texk/web2c.
5885 (line 16)
5886 * --with-gs=FILENAME: Configure options for texk/xdvik.
5887 (line 6)
5888 * --with-LIB-includes=DIR, -libdir: Library-specific configure options.
5889 (line 16)
5890 * --with-libgs-includes, -libdir: Configure options for texk/dvisvgm.
5891 (line 17)
5892 * --with-system-kpathsea: kpathsea library. (line 13)
5893 * --with-system-LIB: Adding a new generic library module.
5894 (line 34)
5895 * --with-system-LIB <1>: Library-specific configure options.
5896 (line 9)
5897 * --with-system-libgs: Configure options for texk/dvisvgm.
5898 (line 6)
5899 * --with-xdvi-x-toolkit: xdvik package. (line 21)
5900 * --with-xdvi-x-toolkit=KIT: Configure options for texk/xdvik.
5901 (line 9)
5902 * --without-libgs: Configure options for texk/dvisvgm.
5903 (line 12)
5904 * --without-ln-s: --without-ln-s. (line 6)
5905 * --without-x: --without-x. (line 6)
5906 * -C configure option: Build in parallel. (line 15)
5907 * -fvisibility-inlines-hidden: Macros for compilers.
5908 (line 19)
5909 * -fvisibility=hidden: Macros for compilers.
5910 (line 19)
5911 * -j make option: Build in parallel. (line 6)
5912 * $@ target in normal make rules: Prerequisites. (line 13)
5913 * ac/withenable.ac: Adding a new program module.
5914 (line 42)
5915 * adapting TeX Live for distros: Distro builds. (line 54)
5916 * adding a new engine: Adding a new engine. (line 6)
5917 * adding a new generic library: Adding a new generic library module.
5918 (line 6)
5919 * adding a new program: Adding a new program module.
5920 (line 6)
5921 * adding a new TeX-specific library: Adding a new TeX-specific library module.
5922 (line 6)
5923 * adding to TeX Live: Extending TeX Live. (line 6)
5924 * am/ top-level directory: Top-level directories.
5925 (line 14)
5926 * ANSI C: Declarations and definitions.
5927 (line 6)
5928 * ApplicationServices Mac framework, required by xetex: Prerequisites.
5929 (line 40)
5930 * asymptote: Linked scripts. (line 26)
5931 * asymptote <1>: asymptote. (line 6)
5932 * Autoconf: Overview of build system.
5933 (line 6)
5934 * autoconf macros: Autoconf macros. (line 6)
5935 * Autoconf, new package using only: Extending TeX Live. (line 20)
5936 * Automake: Overview of build system.
5937 (line 6)
5938 * autoreconf, for new program: Adding a new program module.
5939 (line 76)
5940 * biber: Linked scripts. (line 26)
5941 * bibtex-x: Configure options for texk/bibtex-x.
5942 (line 6)
5943 * bibtex8: Configure options for texk/bibtex-x.
5944 (line 6)
5945 * bibtexu: Configure options for texk/bibtex-x.
5946 (line 6)
5947 * BSD distro: Distro builds. (line 6)
5948 * build directory, required: Building. (line 17)
5949 * build iteration: Build iteration. (line 6)
5950 * build on demand: Build one package. (line 6)
5951 * build one engine: Build one engine. (line 6)
5952 * build one package: Build one package. (line 6)
5953 * Build script: Building. (line 6)
5954 * build system, design of: Overview of build system.
5955 (line 6)
5956 * build-aux/ top-level directory: Top-level directories.
5957 (line 30)
5958 * BUILDCC, BUILDCFLAGS, ...: Cross configuring. (line 42)
5959 * building: Building. (line 6)
5960 * building a distribution: Build distribution. (line 6)
5961 * building in parallel: Build in parallel. (line 6)
5962 * C, ANSI, required: Declarations and definitions.
5963 (line 6)
5964 * C++11, removing dependent sources: Build one package. (line 85)
5965 * C++11, required: Prerequisites. (line 17)
5966 * C99, avoided: Declarations and definitions.
5967 (line 6)
5968 * cache file, for configure: Build in parallel. (line 15)
5969 * cache for configure: Build in parallel. (line 6)
5970 * callexe.c: Macros for Windows. (line 32)
5971 * CC: Variables for configure.
5972 (line 10)
5973 * CC_BUILD: Cross problems. (line 13)
5974 * CC=C-COMPILER: Build one package. (line 77)
5975 * ChangeLog: Adding a new program module.
5976 (line 73)
5977 * chktex: Declarations and definitions.
5978 (line 18)
5979 * clisp: Variables for configure.
5980 (line 18)
5981 * CLISP: Variables for configure.
5982 (line 17)
5983 * CLISP <1>: Configure options for utils/xindy.
5984 (line 14)
5985 * clisp, required by xindy: Prerequisites. (line 44)
5986 * Cocoa Mac framework, required by xetex: Prerequisites. (line 40)
5987 * coding conventions: Coding conventions. (line 6)
5988 * compilers, C and C++11: Prerequisites. (line 6)
5989 * config.guess, config.sub, ...: Top-level directories.
5990 (line 30)
5991 * configure options: Configure options. (line 6)
5992 * configure options, for bibtex-x: Configure options for texk/bibtex-x.
5993 (line 6)
5994 * configure options, for dvipdfm-x: Configure options for texk/dvipdfm-x.
5995 (line 6)
5996 * configure options, for dvisvgm: Configure options for texk/dvisvgm.
5997 (line 6)
5998 * configure options, for kpathsea: Configure options for kpathsea.
5999 (line 6)
6000 * configure options, for texk/texlive: Configure options for texk/texlive.
6001 (line 6)
6002 * configure options, for web2c: Configure options for texk/web2c.
6003 (line 6)
6004 * configure options, for xdvik: Configure options for texk/xdvik.
6005 (line 6)
6006 * configure options, for xindy: Configure options for utils/xindy.
6007 (line 6)
6008 * configure options, global: Global configure options.
6009 (line 6)
6010 * configure options, library-specific: Library-specific configure options.
6011 (line 6)
6012 * configure options, program-specific: Program-specific configure options.
6013 (line 6)
6014 * configure problems, work around by removing: Build one package.
6015 (line 106)
6016 * configure variables: Variables for configure.
6017 (line 6)
6018 * configure.ac: Adding a new program module.
6019 (line 45)
6020 * configuring, for cross compilation: Cross configuring. (line 6)
6021 * const: Const. (line 6)
6022 * continuous integration: Continuous integration.
6023 (line 6)
6024 * conventions, coding: Coding conventions. (line 6)
6025 * CPPFLAGS: Variables for configure.
6026 (line 12)
6027 * cross compilation: Cross compilation. (line 6)
6028 * cross compilation configuring: Cross configuring. (line 6)
6029 * cross compilation problems: Cross problems. (line 6)
6030 * cross compilation, with host binary: xdvik package. (line 14)
6031 * ctangle: Cross problems. (line 26)
6032 * CXX: Variables for configure.
6033 (line 11)
6034 * CXX=C++-COMPILER: Build one package. (line 77)
6035 * declarations and definitions, in source code: Declarations and definitions.
6036 (line 6)
6037 * declarations before statements, avoiding: Declarations and definitions.
6038 (line 6)
6039 * dependencies, with several output files: Build in parallel. (line 6)
6040 * DESTDIR: --prefix --bindir ....
6041 (line 9)
6042 * directories, for installation: Installation directories.
6043 (line 6)
6044 * directories, top-level: Top-level directories.
6045 (line 6)
6046 * discards qualifiers warning: Const. (line 30)
6047 * dist and distcheck targets for make: Build distribution. (line 6)
6048 * distribution tarball, making: Build distribution. (line 6)
6049 * distro, building for: Distro builds. (line 6)
6050 * dvipdfm-x: Configure options for texk/dvipdfm-x.
6051 (line 6)
6052 * dvipdfmx: Configure options for texk/dvipdfm-x.
6053 (line 6)
6054 * dvisvgm: Configure options for texk/dvisvgm.
6055 (line 6)
6056 * dvisvgm, requires C++11: Prerequisites. (line 17)
6057 * engine, adding new: Adding a new engine. (line 6)
6058 * engine, building one: Build one engine. (line 6)
6059 * environment variables, for configure: Configure options. (line 16)
6060 * exec_prefix: --enable-multiplatform.
6061 (line 6)
6062 * extending TeX Live: Extending TeX Live. (line 6)
6063 * extern functions: Declarations and definitions.
6064 (line 41)
6065 * flags, macros for library and header: Macros for library and header flags.
6066 (line 6)
6067 * fontconfig library, required by xetex: Prerequisites. (line 40)
6068 * freetype cross compiling: Cross problems. (line 13)
6069 * freetype library: freetype library. (line 6)
6070 * freetype-config: freetype library. (line 13)
6071 * freetype-config <1>: Variables for configure.
6072 (line 24)
6073 * FreeType, requires gmake: Prerequisites. (line 13)
6074 * FT2_CONFIG: Variables for configure.
6075 (line 21)
6076 * gcc, default compilers: Build one package. (line 77)
6077 * general setup macros: General setup macros.
6078 (line 6)
6079 * generic library module, adding: Adding a new generic library module.
6080 (line 6)
6081 * Ghostscript location for Xdvik: Configure options for texk/xdvik.
6082 (line 6)
6083 * git-svn: Transfer from Subversion to Github.
6084 (line 6)
6085 * global configure options: Global configure options.
6086 (line 6)
6087 * gmake, required: Prerequisites. (line 13)
6088 * GNU make, required: Prerequisites. (line 13)
6089 * GNU tools, needed for building: Build system tools. (line 6)
6090 * GNU/Linux distro: Distro builds. (line 6)
6091 * Gnulib, used for common files: Top-level directories.
6092 (line 30)
6093 * HarfBuzz, requires C++11: Prerequisites. (line 17)
6094 * ICU cross compiling: Cross problems. (line 20)
6095 * ICU libraries: Variables for configure.
6096 (line 24)
6097 * ICU_CONFIG: Variables for configure.
6098 (line 22)
6099 * icu-config: Variables for configure.
6100 (line 24)
6101 * ICU, requires C++11: Prerequisites. (line 17)
6102 * infrastructure, tools needed for: Build system tools. (line 6)
6103 * inst/ top-level directory: Top-level directories.
6104 (line 39)
6105 * install-tl, TeX Live installer: Installing. (line 8)
6106 * installation directories: Installation directories.
6107 (line 6)
6108 * installing: Installing. (line 6)
6109 * interprocess communication: Configure options for texk/web2c.
6110 (line 31)
6111 * introduction: Introduction. (line 6)
6112 * iteration through sources, by configure and make: Build iteration.
6113 (line 6)
6114 * kpathsea library: kpathsea library. (line 6)
6115 * kpathsea.ac: kpathsea library. (line 18)
6116 * KPSE_ADD_FLAGS: Macros for library and header flags.
6117 (line 20)
6118 * KPSE_ALL_SYSTEM_FLAGS: Adding a new generic library module.
6119 (line 34)
6120 * KPSE_BASIC: General setup macros.
6121 (line 8)
6122 * KPSE_CHECK_LATEX: Macros for programs. (line 8)
6123 * KPSE_CHECK_PDFLATEX: Macros for programs. (line 15)
6124 * KPSE_CHECK_PERL: Macros for programs. (line 18)
6125 * KPSE_CHECK_WIN32: Macros for Windows. (line 9)
6126 * KPSE_COMMON: General setup macros.
6127 (line 16)
6128 * KPSE_COMPILER_VISIBILITY: Macros for compilers.
6129 (line 18)
6130 * KPSE_COMPILER_WARNINGS: Macros for compilers.
6131 (line 8)
6132 * KPSE_COND_MINGW32: Macros for Windows. (line 19)
6133 * KPSE_COND_WIN32: Macros for Windows. (line 15)
6134 * KPSE_COND_WIN32_WRAP: Macros for Windows. (line 24)
6135 * kpse_cv_cxx_hack: Macros for compilers.
6136 (line 34)
6137 * kpse_cv_have_win32: Macros for Windows. (line 10)
6138 * kpse_cv_visibility_c[xx]flags: Macros for compilers.
6139 (line 26)
6140 * kpse_cv_warning_cflags: Macros for compilers.
6141 (line 15)
6142 * KPSE_CXX_HACK: Macros for compilers.
6143 (line 29)
6144 * KPSE_ENABLE_PROG: Adding a new program module.
6145 (line 14)
6146 * KPSE_LARGEFILE: Macros for libraries.
6147 (line 8)
6148 * KPSE_LIB_FLAGS: Macros for library and header flags.
6149 (line 6)
6150 * KPSE_LIB_FLAGS <1>: Adding a new generic library module.
6151 (line 26)
6152 * KPSE_LIB_SYSTEM_FLAGS: Adding a new generic library module.
6153 (line 34)
6154 * KPSE_LIBPNG_FLAGS: Macros for library and header flags.
6155 (line 10)
6156 * KPSE_LIBPNG_FLAGS <1>: png library. (line 45)
6157 * kpse_libs_pkgs: Adding a new generic library module.
6158 (line 6)
6159 * KPSE_PROG_LEX: Macros for programs. (line 21)
6160 * KPSE_RESTORE_FLAGS: Macros for library and header flags.
6161 (line 24)
6162 * kpse_texk_pkgs: Adding a new program module.
6163 (line 6)
6164 * kpse_texlibs_pkgs: Adding a new TeX-specific library module.
6165 (line 11)
6166 * KPSE_TRY_LIB: png library. (line 17)
6167 * KPSE_TRY_LIB <1>: Adding a new generic library module.
6168 (line 20)
6169 * KPSE_TRY_LIBXX: png library. (line 30)
6170 * KPSE_TRY_LIBXX <1>: Adding a new generic library module.
6171 (line 20)
6172 * kpse_utils_pkgs: Adding a new program module.
6173 (line 10)
6174 * KPSE_WIN32_CALL: Macros for Windows. (line 31)
6175 * KPSE_WITH_LIB: Adding a new generic library module.
6176 (line 11)
6177 * KPSE_WITH_TEXLIB: Adding a new TeX-specific library module.
6178 (line 14)
6179 * kpse-libpng-flags.m4: png library. (line 45)
6180 * kpse-pkgs.m4: Overview of build system.
6181 (line 30)
6182 * kpse-zlib-flags.m4: zlib library. (line 6)
6183 * kpsewhich: Variables for configure.
6184 (line 30)
6185 * KPSEWHICH: Variables for configure.
6186 (line 29)
6187 * large file support: --disable-largefile. (line 6)
6188 * LATEX: Variables for configure.
6189 (line 40)
6190 * layout of sources: Layout and infrastructure.
6191 (line 6)
6192 * LFS (large file support): --disable-largefile. (line 6)
6193 * libexpat, dependency of libfontconfig: Configure options for texk/web2c.
6194 (line 50)
6195 * libfontconfig, hack for avoiding linking dependencies: Configure options for texk/web2c.
6196 (line 50)
6197 * libfreetype: Variables for configure.
6198 (line 24)
6199 * libfreetype, and const: Const. (line 21)
6200 * libpng library: png library. (line 6)
6201 * library module, generic, adding: Adding a new generic library module.
6202 (line 6)
6203 * library module, TeX-specific, adding: Adding a new TeX-specific library module.
6204 (line 6)
6205 * library modules: Library modules. (line 6)
6206 * library-specific configure options: Library-specific configure options.
6207 (line 6)
6208 * libsigsegv, required by xindy: Prerequisites. (line 44)
6209 * libstc++, statically linking: Macros for compilers.
6210 (line 30)
6211 * Libtool: Overview of build system.
6212 (line 6)
6213 * libtool, hack for avoiding excessive linking: Configure options for texk/web2c.
6214 (line 50)
6215 * libXt: Configure options for texk/web2c.
6216 (line 22)
6217 * linked scripts: Linked scripts. (line 6)
6218 * linking C++ libraries statically: Macros for compilers.
6219 (line 30)
6220 * lisp.run, lisp.exe: Configure options for utils/xindy.
6221 (line 14)
6222 * LittleEndian architectures: Configure options for texk/web2c.
6223 (line 27)
6224 * m4/ top-level directory: Top-level directories.
6225 (line 14)
6226 * macros, for compilers: Macros for compilers.
6227 (line 6)
6228 * macros, for libraries: Macros for libraries.
6229 (line 6)
6230 * macros, for library and header flags: Macros for library and header flags.
6231 (line 6)
6232 * macros, for programs: Macros for programs. (line 6)
6233 * macros, for Windows: Macros for Windows. (line 6)
6234 * macros, general setup: General setup macros.
6235 (line 6)
6236 * MAKE: Variables for configure.
6237 (line 33)
6238 * make -t: Build system tools. (line 43)
6239 * make rules, verbose vs. silent: --enable-silent-rules.
6240 (line 6)
6241 * Makefile.am: Adding a new program module.
6242 (line 46)
6243 * mf-nowin: Configure options for texk/web2c.
6244 (line 34)
6245 * mingw32: Cross configuring. (line 27)
6246 * MINGW32, Automake conditional: Macros for Windows. (line 20)
6247 * mktex.ac: kpathsea library. (line 18)
6248 * mktextfm: kpathsea library. (line 18)
6249 * modules, for libraries: Library modules. (line 6)
6250 * modules, for programs: Program modules. (line 6)
6251 * motif: Configure options for texk/xdvik.
6252 (line 9)
6253 * native cross compilation: Cross compilation. (line 10)
6254 * new package using Autoconf only: Extending TeX Live. (line 20)
6255 * NEWPROG-SRC, original source subdirectory: Adding a new program module.
6256 (line 33)
6257 * OBJCXX=OBJC-COMPILER: Build one package. (line 77)
6258 * one engine, building: Build one engine. (line 6)
6259 * one package, building: Build one package. (line 6)
6260 * OpenGL, required for Asymptote: asymptote. (line 6)
6261 * operating system distribution, building for: Distro builds. (line 6)
6262 * otangle: Cross problems. (line 26)
6263 * overall build process: Building. (line 6)
6264 * parallel build: Build in parallel. (line 6)
6265 * paths, for installation: Installation directories.
6266 (line 6)
6267 * PDF files, size of: --disable-largefile. (line 11)
6268 * PDFLATEX: Variables for configure.
6269 (line 41)
6270 * PERL: Variables for configure.
6271 (line 39)
6272 * perl, required by web2c, etc.: Prerequisites. (line 29)
6273 * PKG_CONFIG: Variables for configure.
6274 (line 23)
6275 * plain.tex, not in source tree: Installing. (line 8)
6276 * png library: png library. (line 6)
6277 * PostScript files, size of: --disable-largefile. (line 11)
6278 * Preining, Norbert: Distro builds. (line 54)
6279 * preloaded binaries: Configure options for texk/web2c.
6280 (line 45)
6281 * prerequisites for building: Prerequisites. (line 6)
6282 * program module, adding: Adding a new program module.
6283 (line 6)
6284 * program modules: Program modules. (line 6)
6285 * program-specific configure options: Program-specific configure options.
6286 (line 6)
6287 * proxy build system: png library. (line 35)
6288 * Python, required by ICU: Prerequisites. (line 23)
6289 * reautoconf: Build system tools. (line 28)
6290 * reautoconf, for new program: Adding a new program module.
6291 (line 89)
6292 * removing build directories: Build one package. (line 106)
6293 * requirements for building: Prerequisites. (line 6)
6294 * runscript.exe: Macros for Windows. (line 25)
6295 * scripts-targets.lst: Linked scripts. (line 35)
6296 * scripts, linked and not maintained: Linked scripts. (line 6)
6297 * scrolling, smooth: Configure options for texk/xdvik.
6298 (line 13)
6299 * SED: Variables for configure.
6300 (line 34)
6301 * setup macros, general: General setup macros.
6302 (line 6)
6303 * shared libraries, using vs. avoiding: Distro builds. (line 11)
6304 * size of PDF and PS files: --disable-largefile. (line 11)
6305 * size of source tree: Build one package. (line 63)
6306 * source code declarations: Declarations and definitions.
6307 (line 6)
6308 * source directory building, not supported: Building. (line 17)
6309 * source tree: Layout and infrastructure.
6310 (line 6)
6311 * squeeze: Cross problems. (line 13)
6312 * squeeze/configure.ac: xdvik package. (line 14)
6313 * static functions: Declarations and definitions.
6314 (line 35)
6315 * static linking for C++: Macros for compilers.
6316 (line 30)
6317 * stpcpy: Declarations and definitions.
6318 (line 18)
6319 * Subversion repository: Build system tools. (line 38)
6320 * support files, separate from build: Installing. (line 8)
6321 * symbolic links, used for scripts: Linked scripts. (line 6)
6322 * symlinks, used for scripts: Linked scripts. (line 6)
6323 * synctex: Configure options for texk/web2c.
6324 (line 59)
6325 * synctex <1>: Configure options for texk/web2c.
6326 (line 64)
6327 * system distribution, building for: Distro builds. (line 6)
6328 * t1utils package: t1utils package. (line 6)
6329 * tangle: Cross problems. (line 26)
6330 * tests, running: Overview of build system.
6331 (line 6)
6332 * TeX-specific library module, adding: Adding a new TeX-specific library module.
6333 (line 6)
6334 * texlive.tlpdb, TeX Live database: Installing. (line 8)
6335 * TEXMFCNF for running standalone: Build one package. (line 44)
6336 * TEXMFROOT for running standalone: Build one package. (line 44)
6337 * tie: Cross problems. (line 26)
6338 * timestamps, in repository: Build system tools. (line 38)
6339 * TL_MAKE_FLAGS: Build in parallel. (line 11)
6340 * TLpatches/patch-...: Adding a new program module.
6341 (line 68)
6342 * TLpatches/TL-Changes: Adding a new program module.
6343 (line 64)
6344 * tools, for building: Build system tools. (line 6)
6345 * top-level directories: Top-level directories.
6346 (line 6)
6347 * touching files to avoid rerunning: Build system tools. (line 43)
6348 * Travis-CI: Continuous integration.
6349 (line 6)
6350 * travis.yml: CI testing on Travis-CI.
6351 (line 6)
6352 * type cast from const, avoiding: Const. (line 38)
6353 * use-commit-times, Subversion: Build system tools. (line 38)
6354 * variable declarations, in source code: Declarations and definitions.
6355 (line 52)
6356 * variables for configure: Variables for configure.
6357 (line 6)
6358 * WARNING_C[XX]FLAGS: Macros for compilers.
6359 (line 9)
6360 * warning, discards qualifiers: Const. (line 30)
6361 * web2c program: Cross problems. (line 13)
6362 * web2c.ac: Configure options for texk/web2c.
6363 (line 37)
6364 * wget: Linked scripts. (line 26)
6365 * WIN32_WRAP, Automake conditional: Macros for Windows. (line 25)
6366 * WIN32, Automake conditional: Macros for Windows. (line 16)
6367 * Windows, invoking scripts on: Linked scripts. (line 6)
6368 * Windows, macros for: Macros for Windows. (line 6)
6369 * withenable.ac, for new modules: Adding a new program module.
6370 (line 14)
6371 * Work/ top-level directory: Top-level directories.
6372 (line 39)
6373 * wrapper binary for scripts on Windows: Linked scripts. (line 6)
6374 * wrapper build system: freetype library. (line 6)
6375 * wrapper for scripts, on Windows: Linked scripts. (line 18)
6376 * X toolkit: Configure options for texk/web2c.
6377 (line 22)
6378 * X11 development, required by X clients: Prerequisites. (line 36)
6379 * X11 headers, and const: Const. (line 21)
6380 * xasy: asymptote. (line 6)
6381 * xaw: Configure options for texk/xdvik.
6382 (line 9)
6383 * xdvik: xdvik package. (line 6)
6384 * xdvik <1>: Configure options for texk/xdvik.
6385 (line 6)
6386 * xdvipdfmx: Configure options for texk/dvipdfm-x.
6387 (line 6)
6388 * xindy: Linked scripts. (line 26)
6389 * xindy <1>: xindy package. (line 6)
6390 * xindy <2>: Configure options for utils/xindy.
6391 (line 6)
6392 * xindy cross compiling requires clisp: Cross problems. (line 33)
6393 * XInput: Configure options for texk/xdvik.
6394 (line 13)
6395 * Xlib: Configure options for texk/web2c.
6396 (line 22)
6397 * xz: Linked scripts. (line 26)
6398 * zlib library: zlib library. (line 6)
6399
6400 
6401 Tag Table:
6402 Node: Top1208
6403 Node: Introduction2118
6404 Node: Overview of build system3951
6405 Node: Prerequisites6002
6406 Ref: Prerequisites-Footnote-19008
6407 Node: Building9311
6408 Node: Build iteration10659
6409 Node: Build in parallel11703
6410 Node: Build distribution12454
6411 Node: Build one package13282
6412 Node: Build one engine17995
6413 Node: Cross compilation20600
6414 Node: Cross configuring21879
6415 Node: Cross problems23556
6416 Node: Installing25218
6417 Node: Installation directories26707
6418 Node: Linked scripts28525
6419 Node: Distro builds31409
6420 Node: Layout and infrastructure33785
6421 Node: Build system tools34616
6422 Node: Top-level directories36833
6423 Node: Autoconf macros39069
6424 Node: General setup macros39831
6425 Node: Macros for programs40706
6426 Node: Macros for compilers41507
6427 Node: Macros for libraries42971
6428 Node: Macros for library and header flags43397
6429 Node: Macros for Windows45308
6430 Node: Library modules46908
6431 Node: png library47397
6432 Node: zlib library49745
6433 Node: freetype library50260
6434 Node: kpathsea library50956
6435 Node: Program modules52338
6436 Node: t1utils package52766
6437 Node: xindy package53311
6438 Node: xdvik package54434
6439 Node: asymptote55493
6440 Node: Extending TeX Live55997
6441 Node: Adding a new program module57322
6442 Node: Adding a new engine62111
6443 Node: Adding a new generic library module63896
6444 Node: Adding a new TeX-specific library module66117
6445 Node: Configure options66815
6446 Node: Global configure options68196
6447 Node: --disable-native-texlive-build68738
6448 Node: --prefix --bindir ...69700
6449 Node: --disable-largefile70240
6450 Node: --disable-missing70782
6451 Node: --enable-compiler-warnings=LEVEL71183
6452 Node: --enable-cxx-runtime-hack71839
6453 Node: --enable-maintainer-mode72259
6454 Node: --enable-multiplatform72788
6455 Node: --enable-shared73361
6456 Node: --enable-silent-rules73732
6457 Node: --without-ln-s74184
6458 Node: --without-x74531
6459 Node: Program-specific configure options74719
6460 Node: --enable-PROG --disable-PROG75362
6461 Node: --disable-all-pkgs75635
6462 Node: Configure options for texk/web2c76418
6463 Node: Configure options for texk/bibtex-x78982
6464 Node: Configure options for texk/dvipdfm-x79525
6465 Node: Configure options for texk/dvisvgm80301
6466 Node: Configure options for texk/texlive81182
6467 Node: Configure options for texk/xdvik81603
6468 Node: Configure options for utils/xindy82224
6469 Node: Library-specific configure options83114
6470 Node: Configure options for kpathsea84075
6471 Node: Variables for configure84779
6472 Node: Coding conventions86205
6473 Node: Declarations and definitions86920
6474 Node: Const89094
6475 Node: Continuous integration90958
6476 Node: Transfer from Subversion to Github91622
6477 Node: Automatic update of the Git mirror93784
6478 Node: CI testing on Travis-CI94366
6479 Node: Releases on Github95075
6480 Node: install-tl95515
6481 Node: install-tl NAME95959
6482 Node: install-tl SYNOPSIS96139
6483 Node: install-tl DESCRIPTION96377
6484 Node: install-tl REFERENCES97574
6485 Node: install-tl EXAMPLES98183
6486 Ref: install-tl install-tl --paper=letter98634
6487 Ref: install-tl install-tl --scheme _scheme_98770
6488 Ref: install-tl install-tl --no-interaction98925
6489 Ref: install-tl install-tl --profile _texlive.profile_99077
6490 Node: install-tl OPTIONS99345
6491 Ref: install-tl *-gui* [[=]_module_]99842
6492 Ref: install-tl *-no-gui*99853
6493 Ref: install-tl text100061
6494 Ref: install-tl tcl (or "perltk" or "wizard" or "expert" or nothing)100246
6495 Ref: install-tl *-lang* _llcode_100878
6496 Ref: install-tl *-repository* _url|path_101502
6497 Ref: install-tl *-select-repository*102396
6498 Ref: install-tl *-all-options*102814
6499 Ref: install-tl *-custom-bin* _path_103069
6500 Ref: install-tl *-debug-fakenet*103901
6501 Ref: install-tl *-debug-setup-vars*104115
6502 Ref: install-tl *-debug-translation*104263
6503 Ref: install-tl *-force-platform* _platform_104539
6504 Ref: install-tl *-help*, *--help*, *-?*104797
6505 Ref: install-tl *-in-place*105210
6506 Ref: install-tl *-init-from-profile* _profile_file_105755
6507 Ref: install-tl *-logfile* _file_106024
6508 Ref: install-tl *-no-cls*106375
6509 Ref: install-tl *-no-continue*106502
6510 Ref: install-tl *-no-doc-install*107073
6511 Ref: install-tl *-no-src-install*107092
6512 Ref: install-tl *-no-installation*107883
6513 Ref: install-tl *-no-interaction*108034
6514 Ref: install-tl *-no-persistent-downloads*108291
6515 Ref: install-tl *-persistent-downloads*108316
6516 Ref: install-tl *-no-verify-downloads*108923
6517 Ref: install-tl *-non-admin*109286
6518 Ref: install-tl *-paper* a4*|*letter109392
6519 Ref: install-tl *-portable*109588
6520 Ref: install-tl *-print-platform*109725
6521 Ref: install-tl *-profile* _profile_file_109923
6522 Ref: install-tl *-q*110144
6523 Ref: install-tl *-scheme* _scheme_110206
6524 Ref: install-tl *-texdir* _dir_110607
6525 Ref: install-tl *-texuserdir* _dir_111212
6526 Ref: install-tl *-texmflocal* _dir_111501
6527 Ref: install-tl *-texmfhome* _dir_112126
6528 Ref: install-tl *-texmfsysconfig* _dir_112435
6529 Ref: install-tl *-texmfsysvar* _dir_112457
6530 Ref: install-tl *-texmfconfig* _dir_112552
6531 Ref: install-tl *-texmfvar* _dir_112571
6532 Ref: install-tl *-v*112779
6533 Ref: install-tl *-version*, *--version*112935
6534 Node: install-tl PROFILES113069
6535 Ref: install-tl instopt_adjustpath (default 0 on Unix, 1 on Windows)116085
6536 Ref: install-tl instopt_adjustrepo (default 1)116161
6537 Ref: install-tl instopt_letter (default 0)116298
6538 Ref: install-tl instopt_portable (default 0)116389
6539 Ref: install-tl instopt_write18_restricted (default 1)116928
6540 Node: install-tl ENVIRONMENT VARIABLES118267
6541 Ref: install-tl NOPERLDOC118630
6542 Ref: install-tl TEXLIVE_DOWNLOADER118715
6543 Ref: install-tl TL_DOWNLOAD_PROGRAM118738
6544 Ref: install-tl TL_DOWNLOAD_ARGS118758
6545 Ref: install-tl TEXLIVE_PREFER_OWN118780
6546 Ref: install-tl TEXLIVE_INSTALL_ENV_NOCHECK119005
6547 Ref: install-tl TEXLIVE_INSTALL_NO_CONTEXT_CACHE119207
6548 Ref: install-tl TEXLIVE_INSTALL_NO_DISKCHECK119319
6549 Ref: install-tl TEXLIVE_INSTALL_NO_RESUME119735
6550 Ref: install-tl TEXLIVE_INSTALL_NO_WELCOME119887
6551 Ref: install-tl TEXLIVE_INSTALL_PAPER120008
6552 Ref: install-tl TEXLIVE_INSTALL_PREFIX120154
6553 Ref: install-tl TEXLIVE_INSTALL_TEXMFCONFIG120185
6554 Ref: install-tl TEXLIVE_INSTALL_TEXMFVAR120213
6555 Ref: install-tl TEXLIVE_INSTALL_TEXMFHOME120242
6556 Ref: install-tl TEXLIVE_INSTALL_TEXMFLOCAL120272
6557 Ref: install-tl TEXLIVE_INSTALL_TEXMFSYSCONFIG120306
6558 Ref: install-tl TEXLIVE_INSTALL_TEXMFSYSVAR120337
6559 Node: install-tl DIRECTORY TREES120775
6560 Node: install-tl BUGS123359
6561 Node: install-tl AUTHORS AND COPYRIGHT124239
6562 Node: tlmgr124637
6563 Node: tlmgr NAME125122
6564 Node: tlmgr SYNOPSIS125266
6565 Node: tlmgr DESCRIPTION125468
6566 Node: tlmgr EXAMPLES126579
6567 Ref: tlmgr tlmgr option repository ctan126842
6568 Ref: tlmgr tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet126915
6569 Ref: tlmgr tlmgr update --list127520
6570 Ref: tlmgr tlmgr update --all127613
6571 Ref: tlmgr tlmgr info _what_127770
6572 Ref: tlmgr tlmgr bug _what_127948
6573 Node: tlmgr OPTIONS128143
6574 Ref: tlmgr *--repository* _url|path_128676
6575 Ref: tlmgr /some/local/dir129862
6576 Ref: tlmgr file:/some/local/dir129891
6577 Ref: tlmgr ctan129964
6578 Ref: tlmgr https://mirror.ctan.org/systems/texlive/tlnet130018
6579 Ref: tlmgr http://server/path/to/tlnet130359
6580 Ref: tlmgr https://server/path/to/tlnet130740
6581 Ref: tlmgr ftp://server/path/to/tlnet131208
6582 Ref: tlmgr user@machine:/path/to/tlnet131340
6583 Ref: tlmgr scp://user@machine/path/to/tlnet131381
6584 Ref: tlmgr ssh://user@machine/path/to/tlnet131422
6585 Ref: tlmgr *--gui* [_action_]131816
6586 Ref: tlmgr *--gui-lang* _llcode_132630
6587 Ref: tlmgr *--command-logfile* _file_133372
6588 Ref: tlmgr *--debug-translation*133639
6589 Ref: tlmgr *--machine-readable*133843
6590 Ref: tlmgr *--no-execute-actions*134112
6591 Ref: tlmgr *--package-logfile* _file_134459
6592 Ref: tlmgr *--pause*134714
6593 Ref: tlmgr *--persistent-downloads*134870
6594 Ref: tlmgr *--no-persistent-downloads*134899
6595 Ref: tlmgr *--pin-file*135394
6596 Ref: tlmgr *--usermode*135613
6597 Ref: tlmgr *--usertree* _dir_135734
6598 Ref: tlmgr *--verify-repo=[none|main|all]*135861
6599 Node: tlmgr ACTIONS136760
6600 Node: tlmgr help137653
6601 Node: tlmgr version138130
6602 Node: tlmgr backup138393
6603 Ref: tlmgr *backup [_option_...] --all*138570
6604 Ref: tlmgr *backup [_option_...] _pkg_...*138603
6605 Ref: tlmgr *--backupdir* _directory_139670
6606 Ref: tlmgr *--all*139888
6607 Ref: tlmgr *--clean*[=_N_]140141
6608 Ref: tlmgr *--dry-run*140469
6609 Node: tlmgr bug [_search-string_]140599
6610 Node: tlmgr candidates _pkg_141186
6611 Node: tlmgr check [_option_...] [depends|executes|files|runfiles|texmfdbs|all]141556
6612 Ref: tlmgr *depends*142070
6613 Ref: tlmgr *executes*142412
6614 Ref: tlmgr *files*142527
6615 Ref: tlmgr *runfiles*142663
6616 Ref: tlmgr *texmfdbs*142800
6617 Ref: tlmgr - all items in TEXMFDBS have the !! prefix.143030
6618 Ref: tlmgr - all items in TEXMFBDS have an ls-R file (if they exist at all).143106
6619 Ref: tlmgr - all items in TEXMF with !! are listed in TEXMFDBS.143171
6620 Ref: tlmgr - all items in TEXMF with an ls-R file are listed in TEXMFDBS.143246
6621 Ref: tlmgr *--use-svn*143272
6622 Node: tlmgr conf143413
6623 Ref: tlmgr *conf [texmf|tlmgr|updmap [--conffile _file_] [--delete] [_key_ [_value_]]]*143703
6624 Ref: tlmgr *conf auxtrees [--conffile _file_] [show|add|remove] [_value_]*143768
6625 Node: tlmgr dump-tlpdb [_option_...] [--json]146184
6626 Ref: tlmgr *--local*146620
6627 Ref: tlmgr *--remote*146660
6628 Ref: tlmgr *--json*146699
6629 Node: tlmgr generate147271
6630 Ref: tlmgr *generate [_option_...] language*147467
6631 Ref: tlmgr *generate [_option_...] language.dat*147506
6632 Ref: tlmgr *generate [_option_...] language.def*147545
6633 Ref: tlmgr *generate [_option_...] language.dat.lua*147588
6634 Ref: tlmgr *--dest* _output_file_149918
6635 Ref: tlmgr *--localcfg* _local_conf_file_150495
6636 Ref: tlmgr *--rebuild-sys*150619
6637 Node: tlmgr gui151434
6638 Node: tlmgr info151614
6639 Ref: tlmgr *info [_option_...] _pkg_...*151776
6640 Ref: tlmgr *info [_option_...] collections*151810
6641 Ref: tlmgr *info [_option_...] schemes*151840
6642 Ref: tlmgr *--list*153371
6643 Ref: tlmgr *--only-files*153682
6644 Ref: tlmgr *--only-installed*153923
6645 Ref: tlmgr *--only-remote*154112
6646 Ref: tlmgr *--data item1,item2,...*154417
6647 Ref: tlmgr *--json* 1155790
6648 Node: tlmgr init-usertree156168
6649 Node: tlmgr install [_option_...] _pkg_...156549
6650 Ref: tlmgr *--dry-run* 1157058
6651 Ref: tlmgr *--file*157176
6652 Ref: tlmgr *--force*157399
6653 Ref: tlmgr *--no-depends*157620
6654 Ref: tlmgr *--no-depends-at-all*157780
6655 Ref: tlmgr *--reinstall*158181
6656 Ref: tlmgr *--with-doc*158560
6657 Ref: tlmgr *--with-src*158574
6658 Node: tlmgr key159302
6659 Ref: tlmgr *key list*159460
6660 Ref: tlmgr *key add _file_*159478
6661 Ref: tlmgr *key remove _keyid_*159500
6662 Node: tlmgr list160094
6663 Node: tlmgr option160256
6664 Ref: tlmgr *option [--json] [show]*160412
6665 Ref: tlmgr *option [--json] showall|help*160444
6666 Ref: tlmgr *option _key_ [_value_]*160470
6667 Node: tlmgr paper165047
6668 Ref: tlmgr *paper [a4|letter]*165196
6669 Ref: tlmgr *<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [_papersize_|--list]*>165273
6670 Ref: tlmgr *paper --json*165289
6671 Node: tlmgr path166711
6672 Ref: tlmgr *path [--windowsmode=user|admin] add*166877
6673 Ref: tlmgr *path [--windowsmode=user|admin] remove*166919
6674 Node: tlmgr pinning168434
6675 Ref: tlmgr pinning show168675
6676 Ref: tlmgr pinning add _repo_ _pkgglob_...168748
6677 Ref: tlmgr pinning remove _repo_ _pkgglob_...168867
6678 Ref: tlmgr pinning remove _repo_ --all169020
6679 Node: tlmgr platform169074
6680 Ref: tlmgr *platform list|add|remove _platform_...*169260
6681 Ref: tlmgr *platform set _platform_*169287
6682 Ref: tlmgr *platform set auto*169308
6683 Ref: tlmgr *--dry-run* 2170186
6684 Node: tlmgr postaction170305
6685 Ref: tlmgr *postaction [_option_...] install [shortcut|fileassoc|script] [_pkg_...]*170535
6686 Ref: tlmgr *postaction [_option_...] remove [shortcut|fileassoc|script] [_pkg_...]*170609
6687 Ref: tlmgr *--windowsmode=[user|admin]*170929
6688 Ref: tlmgr *--fileassocmode=[1|2]*171354
6689 Ref: tlmgr *--all* 1171640
6690 Node: tlmgr print-platform171695
6691 Node: tlmgr print-platform-info172026
6692 Node: tlmgr remove [_option_...] _pkg_...172326
6693 Ref: tlmgr *--all* 2172811
6694 Ref: tlmgr *--backup*172922
6695 Ref: tlmgr *--backupdir* _directory_ 1172949
6696 Ref: tlmgr *--no-depends* 1173354
6697 Ref: tlmgr *--no-depends-at-all* 1173417
6698 Ref: tlmgr *--force* 1173524
6699 Ref: tlmgr *--dry-run* 3173998
6700 Node: tlmgr repository174375
6701 Ref: tlmgr *repository list*174563
6702 Ref: tlmgr *repository list _path|url|tag_*174597
6703 Ref: tlmgr *repository add _path_ [_tag_]*174630
6704 Ref: tlmgr *repository remove _path|tag_*174662
6705 Ref: tlmgr *repository set _path_[#_tag_] [_path_[#_tag_] ...]*174716
6706 Ref: tlmgr *repository status*174737
6707 Ref: tlmgr The tag (which can be the same as the url);176008
6708 Node: tlmgr restore176486
6709 Ref: tlmgr *restore [_option_...] _pkg_ [_rev_]*176665
6710 Ref: tlmgr *restore [_option_...] --all*176696
6711 Ref: tlmgr *--all* 3177397
6712 Ref: tlmgr *--backupdir* _directory_ 2177612
6713 Ref: tlmgr *--dry-run* 4177794
6714 Ref: tlmgr *--force* 2177927
6715 Ref: tlmgr *--json* 2177974
6716 Node: tlmgr search178300
6717 Ref: tlmgr *search [_option_...] _what_*178464
6718 Ref: tlmgr *search [_option_...] --file _what_*178502
6719 Ref: tlmgr *search [_option_...] --all _what_*178539
6720 Ref: tlmgr *--file* 1178760
6721 Ref: tlmgr *--all* 4178823
6722 Ref: tlmgr *--global*178913
6723 Ref: tlmgr *--word*179041
6724 Ref: tlmgr *--json* 3179370
6725 Node: tlmgr shell179577
6726 Ref: tlmgr protocol180312
6727 Ref: tlmgr help 1180376
6728 Ref: tlmgr version 1180429
6729 Ref: tlmgr quit, end, bye, byebye, EOF180497
6730 Ref: tlmgr restart180518
6731 Ref: tlmgr load [local|remote]180641
6732 Ref: tlmgr save180711
6733 Ref: tlmgr get [_var_] =item set [_var_ [_val_]]180834
6734 Node: tlmgr show181435
6735 Node: tlmgr uninstall181602
6736 Node: tlmgr update [_option_...] [_pkg_...]181834
6737 Ref: tlmgr *--all* 5182206
6738 Ref: tlmgr *--self*184386
6739 Ref: tlmgr *--dry-run* 5185151
6740 Ref: tlmgr *--list* [_pkg_]185329
6741 Ref: tlmgr *--exclude* _pkg_186019
6742 Ref: tlmgr *--no-auto-remove* [_pkg_...]186820
6743 Ref: tlmgr *--no-auto-install* [_pkg_...]187305
6744 Ref: tlmgr *--reinstall-forcibly-removed*188068
6745 Ref: tlmgr *--backup* 1188604
6746 Ref: tlmgr *--backupdir* _directory_ 3188631
6747 Ref: tlmgr *--no-depends* 2189798
6748 Ref: tlmgr *--no-depends-at-all* 2190002
6749 Ref: tlmgr *--force* 3190109
6750 Node: tlmgr CONFIGURATION FILE FOR TLMGR191100
6751 Ref: tlmgr auto-remove = 0 or 1 (default 1), same as command-line option.192102
6752 Ref: tlmgr gui-expertmode = 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings.192234
6753 Ref: tlmgr gui-lang = _llcode_, with a language code value as with the command-line option.192318
6754 Ref: tlmgr no-checksums = 0 or 1 (default 0, see below).192367
6755 Ref: tlmgr persistent-downloads = 0 or 1 (default 1), same as command-line option.192442
6756 Ref: tlmgr require-verification = 0 or 1 (default 0), same as command-line option.192517
6757 Ref: tlmgr tkfontscale = _floating-point number_ (default 1.0); scaling factor for fonts in the Tk-based frontends.192625
6758 Ref: tlmgr update-exclude = _comma-separated list of packages_ (no spaces allowed). Same as the command line option --exclude for the update action.192770
6759 Ref: tlmgr verify-downloads = 0 or 1 (default 1), same as command-line option.192841
6760 Ref: tlmgr allowed-actions = _action1_[,_action2_,...] The value is a comma-separated list (no spaces) of tlmgr actions which are allowed to be executed when tlmgr is invoked in system mode (that is, without --usermode). This allows distributors to include tlmgr in their packaging, but allow only a restricted set of actions that do not interfere with their distro package manager. For native TeX Live installations, it doesn't make sense to set this.193358
6761 Node: tlmgr CRYPTOGRAPHIC VERIFICATION194190
6762 Node: tlmgr Configuration of GnuPG invocation196363
6763 Node: tlmgr USER MODE197001
6764 Node: tlmgr User mode install199872
6765 Node: tlmgr User mode backup, restore, remove, update201018
6766 Node: tlmgr User mode generate, option, paper201464
6767 Node: tlmgr User mode logs201831
6768 Node: tlmgr MULTIPLE REPOSITORIES202129
6769 Node: tlmgr Pinning203858
6770 Node: tlmgr GUI FOR TLMGR205781
6771 Node: tlmgr Main display207430
6772 Node: tlmgr Display configuration area207682
6773 Ref: tlmgr Status208043
6774 Ref: tlmgr Category208207
6775 Ref: tlmgr Match208393
6776 Ref: tlmgr Selection208574
6777 Ref: tlmgr Display configuration buttons208778
6778 Node: tlmgr Package list area208961
6779 Ref: tlmgr a checkbox209545
6780 Ref: tlmgr package name209681
6781 Ref: tlmgr local revision (and version)209780
6782 Ref: tlmgr remote revision (and version)210155
6783 Ref: tlmgr short description210452
6784 Node: tlmgr Main display action buttons210497
6785 Ref: tlmgr Update all installed210763
6786 Ref: tlmgr Update211135
6787 Ref: tlmgr Install211185
6788 Ref: tlmgr Remove211371
6789 Ref: tlmgr Backup211549
6790 Node: tlmgr Menu bar211706
6791 Ref: tlmgr tlmgr menu211929
6792 Ref: tlmgr Options menu212237
6793 Ref: tlmgr Actions menu213320
6794 Ref: tlmgr Help menu213748
6795 Node: tlmgr GUI options213882
6796 Ref: tlmgr -background _color_214128
6797 Ref: tlmgr -font " _fontname_ _fontsize_ "214193
6798 Ref: tlmgr -foreground _color_214351
6799 Ref: tlmgr -geometry _geomspec_214403
6800 Ref: tlmgr -xrm _xresource_214595
6801 Node: tlmgr MACHINE-READABLE OUTPUT214864
6802 Node: tlmgr Machine-readable update and install output215678
6803 Ref: tlmgr location-url _location_216954
6804 Ref: tlmgr total-bytes _count_217170
6805 Ref: tlmgr _pkgname_217580
6806 Ref: tlmgr _status_217790
6807 Ref: tlmgr d217868
6808 Ref: tlmgr f217928
6809 Ref: tlmgr u218107
6810 Ref: tlmgr r218153
6811 Ref: tlmgr a218276
6812 Ref: tlmgr i218454
6813 Ref: tlmgr I218573
6814 Ref: tlmgr _localrev_218675
6815 Ref: tlmgr _serverrev_218782
6816 Ref: tlmgr _size_218894
6817 Ref: tlmgr _runtime_219063
6818 Ref: tlmgr _esttot_219133
6819 Node: tlmgr Machine-readable option output219166
6820 Node: tlmgr ENVIRONMENT VARIABLES219678
6821 Ref: tlmgr TEXLIVE_COMPRESSOR220189
6822 Ref: tlmgr TEXLIVE_DOWNLOADER221037
6823 Ref: tlmgr TL_DOWNLOAD_PROGRAM221060
6824 Ref: tlmgr TL_DOWNLOAD_ARGS221080
6825 Ref: tlmgr TEXLIVE_PREFER_OWN222106
6826 Node: tlmgr AUTHORS AND COPYRIGHT222930
6827 Node: Index223328
6828 
6829 End Tag Table
6830
6831 
6832 Local Variables:
6833 coding: utf-8
6834 End: