From ad547a6b5986815fda458221149728d9d9ab1d87 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 25 Feb 2021 19:22:25 +0000 Subject: restore Build,TODO from r57911 git-svn-id: svn://tug.org/texlive/trunk@57915 c570f23f-e606-0410-a88d-b1316a301751 --- Build/source/doc/ChangeLog | 139 + Build/source/doc/Makefile.am | 93 + Build/source/doc/Makefile.in | 978 ++++ Build/source/doc/README.solaris | 182 + Build/source/doc/build-tools.txt | 7 + Build/source/doc/buildinfo.sh | 60 + Build/source/doc/splitinfo.gawk | 46 + Build/source/doc/tlbuild-incl/install-tl.texi | 577 +++ Build/source/doc/tlbuild-incl/tlmgr.texi | 2742 +++++++++++ Build/source/doc/tlbuild.info | 6335 +++++++++++++++++++++++++ Build/source/doc/tlbuild.texi | 2689 +++++++++++ 11 files changed, 13848 insertions(+) create mode 100644 Build/source/doc/ChangeLog create mode 100644 Build/source/doc/Makefile.am create mode 100644 Build/source/doc/Makefile.in create mode 100644 Build/source/doc/README.solaris create mode 100644 Build/source/doc/build-tools.txt create mode 100755 Build/source/doc/buildinfo.sh create mode 100644 Build/source/doc/splitinfo.gawk create mode 100644 Build/source/doc/tlbuild-incl/install-tl.texi create mode 100644 Build/source/doc/tlbuild-incl/tlmgr.texi create mode 100644 Build/source/doc/tlbuild.info create mode 100644 Build/source/doc/tlbuild.texi (limited to 'Build/source/doc') diff --git a/Build/source/doc/ChangeLog b/Build/source/doc/ChangeLog new file mode 100644 index 00000000000..b6fc24a842a --- /dev/null +++ b/Build/source/doc/ChangeLog @@ -0,0 +1,139 @@ +2021-02-09 Karl Berry + + * tlbuild.texi (Adding a new program module): emphasize requirement + for configure, etc., to be committed. + +2020-11-28 Karl Berry + + * tlbuild.texi (Adding a new program module): more explicit + info. Suggested by Bob Tennent. + +2020-08-31 Karl Berry + + * tlbuild.texi (Build one engine): rewrite procedure. + * build-tools.txt: bison 3.7.1. + +2020-05-14 Karl Berry + + * tlbuild.texi: remove poppler references. + * build-tools.txt: bison 3.6.1. + +2020-03-13 Karl Berry + + * tlbuild.texi: update for 2020. + + * build-tools.txt: bison 3.5.2. + +2019-12-22 Karl Berry + + * build-tools.txt: bison 3.5. + +2019-08-11 Karl Berry + + * tlbuild.texi (Build one package): rm sources to build without C++11. + +2018-04-10 Karl Berry + + * tlbuild.texi (Cross compilation): move to under Building. + (Continuous integration): restrucuture. + + * Makefile.am (*_node_{good,bad}): update for current pod doc. + ($(mydoc)-incl.texi): hint to symlink scripts for pod2texi. + +2018-02-20 Karl Berry + + * tlbuild.texi (Continuous integration): Texinfo syntax, wording. + +2018-02-20 Norbert Preining + + * tlbuild.texi (Continuous integration): new chapter. + +2018-02-10 Karl Berry + + * tlbuild.texi (Adding a new program module): more specifics + on our usual layout and new files. + (version): (February) 2018. + +2017-03-22 Karl Berry + + * tlbuild.texi: we now default to gcc for ICU too. + +2017-03-19 Karl Berry + + * tlbuild.texi: TLPATCHES -> TLpatches. + (direntry): add install-tl and tlmgr entries. + +2016-01-21 Karl Berry + + * tlbuild.texi (Cross problems): Lua[JIT]TeX no longer uses + pdflua.c and thus no txt2zlib, so remove paragraph. + From Luigi, 18 Jan 2016 09:11:53. + + * build-tools.txt (flex): now at 2.6.0. + (makeinfo): texinfo-6.1. + +2015-05-28 Peter Breitenlohner + + * README.solaris (new): Moved from ../ to here. + * Makefile.am: Adapted. + +2015-03-24 Peter Breitenlohner + + * tlbuild.texi: Add '--disable-synctex'. + +2015-03-18 Peter Breitenlohner + + * build-tools.txt: Using bison 3.0.4 and libtool 2.4.6. + * tlbuild.texi: Minor updates. + +2015-01-20 Peter Breitenlohner + + * build-tools.txt: Using bison 3.0.3 and libtool 2.4.5. + +2014-12-09 Peter Breitenlohner + + * tlbuild.texi: Fixed a few typos. + +2014-12-08 Peter Breitenlohner + + * build-tools.txt: Using libtool 2.4.4. + +2014-06-16 Peter Breitenlohner + + * tlbuild.texi: Drop '--with-xindy-recode'. + +2014-05-20 Karl Berry + + * tlbuild-incl/install-tl.texi, + * tlbuild-incl/tlmgr.texi: new files, generated from the pod doc. + * tlbuild.texi: @include them. + * Makefile.am (tlbuild_TEXINFOS): add them. + ($(mydoc)-incl.texi): new phony target to run pod2texi; + currently requires development texinfo, + and thus is not intended to be invoked except by hand. + (readme-install): new phony target. + * splitinfo.gawk: quit at appendix too. + +2014-05-20 Peter Breitenlohner + + * Makefile.am (EXTRA_DIST): no ${PDFS} any more. + +2014-05-01 Karl Berry + + * tlbuild.texi (Building): split into sections. + Give full example of working on a single program. + +2014-04-09 Karl Berry + Peter Breitenlohner + + * texlive.texi: Update for Texinfo, etc. + * build.texi, build-tools (removed): Moved ... + * tlbuild.texi, build-tools.txt (new): ... to here. + * splitinfo.gawk (new): Awk script to generate README.* files. + * Makefile.am: Adapted. + +2013-12-14 Peter Breitenlohner + + * doc/build.texi: Fixed some typos. + +(This ChangeLog file is in the public domain.) diff --git a/Build/source/doc/Makefile.am b/Build/source/doc/Makefile.am new file mode 100644 index 00000000000..d254f6fa0ea --- /dev/null +++ b/Build/source/doc/Makefile.am @@ -0,0 +1,93 @@ +## $Id$ +## Makefile.am for the TeX Live subdirectory ./doc/ +## +## Copyright 2015-2020 Karl Berry +## Copyright 2013-2015 Peter Breitenlohner +## You may freely use, modify and/or distribute this file. +## +## The info files +info_TEXINFOS = tlbuild.texi +tlbuild_TEXINFOS = build-tools.txt \ + tlbuild-incl/install-tl.texi tlbuild-incl/tlmgr.texi + +EXTRA_DIST = \ + README.solaris \ + splitinfo.gawk + +# no reasonable way to avoid it with the pod doc. +MAKEINFOFLAGS = --set INFO_SPECIAL_CHARS_WARNING=0 + +# autogenerate the top-level README files. +readme-files: tlbuild.info + rm -f README.* + $(MAKEINFO) $(MAKEINFOFLAGS) --plaintext -o - $(srcdir)/tlbuild.texi \ + | tee /tmp/a \ + | gawk -f $(srcdir)/splitinfo.gawk + ls -l README.* +# head -8 README.* +readme-install: readme-files + cp -p README.* $(top_srcdir)/ + svn diff $(top_srcdir)/README.* >/tmp/sd + svn status $(top_srcdir)/README.* +# +.PHONY: readme-files readme-install script-links + +# autogenerate texinfo from install-tl and tlmgr pod. +# none of this is intended to be executed except manually. +mydoc = tlbuild + +# Needs to be the pod2texi from at least Texinfo 6.3. +pod2texi = pod2texi +pod2texi_args = \ + --appendix-sections \ + --base-level=section \ + --no-fill-section-gaps \ + --preamble='' + +# We use complicated section names in the tlmgr pod, and consequently +# complicated section references, schematically like this: +# L> +# Unfortunately, the Pod module does not pass the necessary information +# in the callbacks to allow pod2texi to preserve the I<>. It seems +# better to kludge in some substitutions here than reimplement a whole +# pod parser. Sigh. +# +# The \@... in the replacements are escaping the @ in a Perl +# double-quote context, i.e., not an array. +# +update_node_bad = ref{tlmgr update [option...] [pkg...], +update_node_good = ref{tlmgr update [\@emph{option}...] [\@emph{pkg}...], +# +update_node_bad2 = [option...] [pkg...], update +update_node_good2 = [\@emph{option}...] [@emph{pkg}...], update +# +remove_node_bad = ref{tlmgr remove [option...] pkg..., +remove_node_good = ref{tlmgr remove [\@emph{option}...] \@emph{pkg}..., +# +install_node_bad = ref{tlmgr install [option...] pkg..., +install_node_good = ref{tlmgr install [\@emph{option}...] \@emph{pkg}..., + +# we don't actually use the (autogenerated) -incl.texi file, +# but it makes for a convenient target. + +# First make symlinks in build dir: +Master = $(top_srcdir)/../../Master +script-links: + rm -f tlmgr.pl install-tl + ln -s $(Master)/install-tl . + ln -s $(Master)/texmf-dist/scripts/texlive/tlmgr.pl . + +$(mydoc)-incl.texi: install-tl tlmgr.pl + $(pod2texi) -o $@ --subdir=$(mydoc)-incl $(pod2texi_args) $^ + cp $(mydoc)-incl/tlmgr.texi $(mydoc)-incl/tlmgr.texi.orig + perl -pi \ + -e 's/\Q$(update_node_bad)\E/$(update_node_good)/' \ + -e ';s/\Q$(update_node_bad2)\E/$(update_node_good2),/' \ + -e ';' \ + -e 's/\Q$(remove_node_bad)\E/$(remove_node_good)/' \ + -e ';' \ + -e 's/\Q$(install_node_bad)\E/$(install_node_good)/' \ + $(mydoc)-incl/tlmgr.texi + cp $(mydoc)-incl/tlmgr.texi $(srcdir)/$(mydoc)-incl/ + cp $(mydoc)-incl/install-tl.texi $(srcdir)/$(mydoc)-incl/ +.PHONY: $(mydoc)-incl.texi diff --git a/Build/source/doc/Makefile.in b/Build/source/doc/Makefile.in new file mode 100644 index 00000000000..5373491f09e --- /dev/null +++ b/Build/source/doc/Makefile.in @@ -0,0 +1,978 @@ +# Makefile.in generated by automake 1.16.3 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2020 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/kpse-cairo-flags.m4 \ + $(top_srcdir)/m4/kpse-common.m4 \ + $(top_srcdir)/m4/kpse-cxx-hack.m4 \ + $(top_srcdir)/m4/kpse-freetype2-flags.m4 \ + $(top_srcdir)/m4/kpse-gd-flags.m4 \ + $(top_srcdir)/m4/kpse-gmp-flags.m4 \ + $(top_srcdir)/m4/kpse-graphite2-flags.m4 \ + $(top_srcdir)/m4/kpse-harfbuzz-flags.m4 \ + $(top_srcdir)/m4/kpse-icu-flags.m4 \ + $(top_srcdir)/m4/kpse-kpathsea-flags.m4 \ + $(top_srcdir)/m4/kpse-libpaper-flags.m4 \ + $(top_srcdir)/m4/kpse-libpng-flags.m4 \ + $(top_srcdir)/m4/kpse-lt-hack.m4 \ + $(top_srcdir)/m4/kpse-mktex.m4 \ + $(top_srcdir)/m4/kpse-mpfr-flags.m4 \ + $(top_srcdir)/m4/kpse-options.m4 \ + $(top_srcdir)/m4/kpse-pixman-flags.m4 \ + $(top_srcdir)/m4/kpse-pkgs.m4 \ + $(top_srcdir)/m4/kpse-pplib-flags.m4 \ + $(top_srcdir)/m4/kpse-ptexenc-flags.m4 \ + $(top_srcdir)/m4/kpse-setup.m4 \ + $(top_srcdir)/m4/kpse-teckit-flags.m4 \ + $(top_srcdir)/m4/kpse-warnings.m4 \ + $(top_srcdir)/m4/kpse-web2c.m4 $(top_srcdir)/m4/kpse-win32.m4 \ + $(top_srcdir)/m4/kpse-xpdf-flags.m4 \ + $(top_srcdir)/m4/kpse-zlib-flags.m4 \ + $(top_srcdir)/m4/kpse-zziplib-flags.m4 \ + $(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \ + $(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \ + $(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/tardate.ac \ + $(top_srcdir)/version.ac \ + $(top_srcdir)/utils/autosp/ac/withenable.ac \ + $(top_srcdir)/utils/axodraw2/ac/withenable.ac \ + $(top_srcdir)/utils/devnag/ac/withenable.ac \ + $(top_srcdir)/utils/lacheck/ac/withenable.ac \ + $(top_srcdir)/utils/m-tx/ac/withenable.ac \ + $(top_srcdir)/utils/pmx/ac/withenable.ac \ + $(top_srcdir)/utils/ps2eps/ac/withenable.ac \ + $(top_srcdir)/utils/t1utils/ac/withenable.ac \ + $(top_srcdir)/utils/texdoctk/ac/withenable.ac \ + $(top_srcdir)/utils/tpic2pdftex/ac/withenable.ac \ + $(top_srcdir)/utils/vlna/ac/withenable.ac \ + $(top_srcdir)/utils/xindy/ac/withenable.ac \ + $(top_srcdir)/utils/xindy/ac/xindy.ac \ + $(top_srcdir)/utils/xindy/ac/clisp.ac \ + $(top_srcdir)/utils/xml2pmx/ac/withenable.ac \ + $(top_srcdir)/utils/xpdfopen/ac/withenable.ac \ + $(top_srcdir)/texk/web2c/ac/withenable.ac \ + $(top_srcdir)/texk/web2c/ac/web2c.ac \ + $(top_srcdir)/texk/afm2pl/ac/withenable.ac \ + $(top_srcdir)/texk/bibtex-x/ac/withenable.ac \ + $(top_srcdir)/texk/bibtex-x/ac/bibtex-x.ac \ + $(top_srcdir)/texk/chktex/ac/withenable.ac \ + $(top_srcdir)/texk/cjkutils/ac/withenable.ac \ + $(top_srcdir)/texk/detex/ac/withenable.ac \ + $(top_srcdir)/texk/dtl/ac/withenable.ac \ + $(top_srcdir)/texk/dvi2tty/ac/withenable.ac \ + $(top_srcdir)/texk/dvidvi/ac/withenable.ac \ + $(top_srcdir)/texk/dviljk/ac/withenable.ac \ + $(top_srcdir)/texk/dviout-util/ac/withenable.ac \ + $(top_srcdir)/texk/dvipdfm-x/ac/withenable.ac \ + $(top_srcdir)/texk/dvipng/ac/withenable.ac \ + $(top_srcdir)/texk/dvipng/ac/dvipng.ac \ + $(top_srcdir)/texk/dvipos/ac/withenable.ac \ + $(top_srcdir)/texk/dvipsk/ac/withenable.ac \ + $(top_srcdir)/texk/dvisvgm/ac/withenable.ac \ + $(top_srcdir)/texk/gregorio/ac/withenable.ac \ + $(top_srcdir)/texk/gsftopk/ac/withenable.ac \ + $(top_srcdir)/texk/lcdf-typetools/ac/withenable.ac \ + $(top_srcdir)/texk/lcdf-typetools/ac/lcdf-typetools.ac \ + $(top_srcdir)/texk/makeindexk/ac/withenable.ac \ + $(top_srcdir)/texk/makejvf/ac/withenable.ac \ + $(top_srcdir)/texk/mendexk/ac/withenable.ac \ + $(top_srcdir)/texk/musixtnt/ac/withenable.ac \ + $(top_srcdir)/texk/ps2pk/ac/withenable.ac \ + $(top_srcdir)/texk/psutils/ac/withenable.ac \ + $(top_srcdir)/texk/seetexk/ac/withenable.ac \ + $(top_srcdir)/texk/tex4htk/ac/withenable.ac \ + $(top_srcdir)/texk/ttf2pk2/ac/withenable.ac \ + $(top_srcdir)/texk/ttfdump/ac/withenable.ac \ + $(top_srcdir)/texk/upmendex/ac/withenable.ac \ + $(top_srcdir)/texk/xdvik/ac/withenable.ac \ + $(top_srcdir)/texk/xdvik/ac/xdvik.ac \ + $(top_srcdir)/texk/texlive/ac/withenable.ac \ + $(top_srcdir)/texk/texlive/ac/texlive.ac \ + $(top_srcdir)/libs/pplib/ac/withenable.ac \ + $(top_srcdir)/libs/harfbuzz/ac/withenable.ac \ + $(top_srcdir)/libs/icu/ac/withenable.ac \ + $(top_srcdir)/libs/teckit/ac/withenable.ac \ + $(top_srcdir)/libs/graphite2/ac/withenable.ac \ + $(top_srcdir)/libs/zziplib/ac/withenable.ac \ + $(top_srcdir)/libs/xpdf/ac/withenable.ac \ + $(top_srcdir)/libs/mpfr/ac/withenable.ac \ + $(top_srcdir)/libs/gmp/ac/withenable.ac \ + $(top_srcdir)/libs/cairo/ac/withenable.ac \ + $(top_srcdir)/libs/pixman/ac/withenable.ac \ + $(top_srcdir)/libs/gd/ac/withenable.ac \ + $(top_srcdir)/libs/freetype2/ac/withenable.ac \ + $(top_srcdir)/libs/libpng/ac/withenable.ac \ + $(top_srcdir)/libs/libpaper/ac/withenable.ac \ + $(top_srcdir)/libs/luajit/ac/withenable.ac \ + $(top_srcdir)/libs/lua53/ac/withenable.ac \ + $(top_srcdir)/libs/zlib/ac/withenable.ac \ + $(top_srcdir)/texk/ptexenc/ac/withenable.ac \ + $(top_srcdir)/texk/kpathsea/ac/withenable.ac \ + $(top_srcdir)/texk/kpathsea/ac/mktex.ac \ + $(top_srcdir)/texk/kpathsea/ac/kpathsea.ac \ + $(top_srcdir)/texk/ptexenc/ac/ptexenc.ac \ + $(top_srcdir)/libs/zlib/ac/zlib.ac \ + $(top_srcdir)/libs/libpaper/ac/libpaper.ac \ + $(top_srcdir)/libs/libpng/ac/libpng.ac \ + $(top_srcdir)/libs/freetype2/ac/freetype2.ac \ + $(top_srcdir)/libs/gd/ac/gd.ac \ + $(top_srcdir)/libs/pixman/ac/pixman.ac \ + $(top_srcdir)/libs/cairo/ac/cairo.ac \ + $(top_srcdir)/libs/gmp/ac/gmp.ac \ + $(top_srcdir)/libs/mpfr/ac/mpfr.ac \ + $(top_srcdir)/libs/xpdf/ac/xpdf.ac \ + $(top_srcdir)/libs/zziplib/ac/zziplib.ac \ + $(top_srcdir)/libs/graphite2/ac/graphite2.ac \ + $(top_srcdir)/libs/teckit/ac/teckit.ac \ + $(top_srcdir)/libs/icu/ac/icu.ac \ + $(top_srcdir)/libs/harfbuzz/ac/harfbuzz.ac \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +AM_V_DVIPS = $(am__v_DVIPS_@AM_V@) +am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@) +am__v_DVIPS_0 = @echo " DVIPS " $@; +am__v_DVIPS_1 = +AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@) +am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@) +am__v_MAKEINFO_0 = @echo " MAKEINFO" $@; +am__v_MAKEINFO_1 = +AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@) +am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@) +am__v_INFOHTML_0 = @echo " INFOHTML" $@; +am__v_INFOHTML_1 = +AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@) +am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@) +am__v_TEXI2DVI_0 = @echo " TEXI2DVI" $@; +am__v_TEXI2DVI_1 = +AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@) +am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@) +am__v_TEXI2PDF_0 = @echo " TEXI2PDF" $@; +am__v_TEXI2PDF_1 = +AM_V_texinfo = $(am__v_texinfo_@AM_V@) +am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@) +am__v_texinfo_0 = -q +am__v_texinfo_1 = +AM_V_texidevnull = $(am__v_texidevnull_@AM_V@) +am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@) +am__v_texidevnull_0 = > /dev/null +am__v_texidevnull_1 = +INFO_DEPS = $(srcdir)/tlbuild.info +TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex +am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux +DVIS = tlbuild.dvi +PDFS = tlbuild.pdf +PSS = tlbuild.ps +HTMLS = tlbuild.html +TEXINFOS = tlbuild.texi +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__installdirs = "$(DESTDIR)$(infodir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(srcdir)/Makefile.in $(tlbuild_TEXINFOS) \ + $(top_srcdir)/build-aux/texinfo.tex ChangeLog +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +AR = @AR@ +AS = @AS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CONF_SUBDIRS = @CONF_SUBDIRS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +FT2_CONFIG = @FT2_CONFIG@ +GREP = @GREP@ +ICU_CONFIG = @ICU_CONFIG@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MAKE_SUBDIRS = @MAKE_SUBDIRS@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PKG_CONFIG = @PKG_CONFIG@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +WARNING_CFLAGS = @WARNING_CFLAGS@ +WARNING_CXXFLAGS = @WARNING_CXXFLAGS@ +XMKMF = @XMKMF@ +X_CFLAGS = @X_CFLAGS@ +X_EXTRA_LIBS = @X_EXTRA_LIBS@ +X_LIBS = @X_LIBS@ +X_PRE_LIBS = @X_PRE_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +subdirs = @subdirs@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +info_TEXINFOS = tlbuild.texi +tlbuild_TEXINFOS = build-tools.txt \ + tlbuild-incl/install-tl.texi tlbuild-incl/tlmgr.texi + +EXTRA_DIST = \ + README.solaris \ + splitinfo.gawk + + +# no reasonable way to avoid it with the pod doc. +MAKEINFOFLAGS = --set INFO_SPECIAL_CHARS_WARNING=0 + +# autogenerate texinfo from install-tl and tlmgr pod. +# none of this is intended to be executed except manually. +mydoc = tlbuild + +# Needs to be the pod2texi from at least Texinfo 6.3. +pod2texi = pod2texi +pod2texi_args = \ + --appendix-sections \ + --base-level=section \ + --no-fill-section-gaps \ + --preamble='' + + +# We use complicated section names in the tlmgr pod, and consequently +# complicated section references, schematically like this: +# L> +# Unfortunately, the Pod module does not pass the necessary information +# in the callbacks to allow pod2texi to preserve the I<>. It seems +# better to kludge in some substitutions here than reimplement a whole +# pod parser. Sigh. +# +# The \@... in the replacements are escaping the @ in a Perl +# double-quote context, i.e., not an array. +# +update_node_bad = ref{tlmgr update [option...] [pkg...], +update_node_good = ref{tlmgr update [\@emph{option}...] [\@emph{pkg}...], +# +update_node_bad2 = [option...] [pkg...], update +update_node_good2 = [\@emph{option}...] [@emph{pkg}...], update +# +remove_node_bad = ref{tlmgr remove [option...] pkg..., +remove_node_good = ref{tlmgr remove [\@emph{option}...] \@emph{pkg}..., +# +install_node_bad = ref{tlmgr install [option...] pkg..., +install_node_good = ref{tlmgr install [\@emph{option}...] \@emph{pkg}..., + +# we don't actually use the (autogenerated) -incl.texi file, +# but it makes for a convenient target. + +# First make symlinks in build dir: +Master = $(top_srcdir)/../../Master +all: all-am + +.SUFFIXES: +.SUFFIXES: .dvi .html .info .pdf .ps .texi +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign doc/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs + +.texi.info: + $(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && $(am__cd) $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + $(am__cd) $(srcdir); \ + else \ + rc=$$?; \ + $(am__cd) $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + $(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \ + $< + +.texi.pdf: + $(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \ + $< + +.texi.html: + $(AM_V_MAKEINFO)rm -rf $(@:.html=.htp) + $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@ && mv $(@:.html=.htp) $@; \ + else \ + rm -rf $(@:.html=.htp); exit 1; \ + fi +$(srcdir)/tlbuild.info: tlbuild.texi $(tlbuild_TEXINFOS) +tlbuild.dvi: tlbuild.texi $(tlbuild_TEXINFOS) +tlbuild.pdf: tlbuild.texi $(tlbuild_TEXINFOS) +tlbuild.html: tlbuild.texi $(tlbuild_TEXINFOS) +.dvi.ps: + $(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) $(AM_V_texinfo) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f "$(distdir)/$$relfile" || \ + cp -p $$file "$(distdir)/$$relfile"; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf tlbuild.t2d tlbuild.t2p + +clean-aminfo: + -test -z "tlbuild.dvi tlbuild.pdf tlbuild.ps tlbuild.html" \ + || rm -rf tlbuild.dvi tlbuild.pdf tlbuild.ps tlbuild.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) distdir-am + +distdir-am: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) +installdirs: + for dir in "$(DESTDIR)$(infodir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +html: html-am + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + $(am__strip_dir) \ + d2=$$d$$p; \ + if test -d "$$d2"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ + else \ + list2="$$list2 $$d2"; \ + fi; \ + done; \ + test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done; } +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \ + fi; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + echo "$$ifile"; \ + else : ; fi; \ + done; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done + @$(POST_INSTALL) + @if $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \ + mostlyclean-libtool + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-aminfo clean-generic \ + clean-libtool cscopelist-am ctags-am dist-info distclean \ + distclean-generic distclean-libtool distdir dvi dvi-am html \ + html-am info info-am install install-am install-data \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-pdf install-pdf-am \ + install-ps install-ps-am install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-aminfo maintainer-clean-generic mostlyclean \ + mostlyclean-aminfo mostlyclean-generic mostlyclean-libtool pdf \ + pdf-am ps ps-am tags-am uninstall uninstall-am \ + uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.PRECIOUS: Makefile + + +# autogenerate the top-level README files. +readme-files: tlbuild.info + rm -f README.* + $(MAKEINFO) $(MAKEINFOFLAGS) --plaintext -o - $(srcdir)/tlbuild.texi \ + | tee /tmp/a \ + | gawk -f $(srcdir)/splitinfo.gawk + ls -l README.* +# head -8 README.* +readme-install: readme-files + cp -p README.* $(top_srcdir)/ + svn diff $(top_srcdir)/README.* >/tmp/sd + svn status $(top_srcdir)/README.* +# +.PHONY: readme-files readme-install script-links +script-links: + rm -f tlmgr.pl install-tl + ln -s $(Master)/install-tl . + ln -s $(Master)/texmf-dist/scripts/texlive/tlmgr.pl . + +$(mydoc)-incl.texi: install-tl tlmgr.pl + $(pod2texi) -o $@ --subdir=$(mydoc)-incl $(pod2texi_args) $^ + cp $(mydoc)-incl/tlmgr.texi $(mydoc)-incl/tlmgr.texi.orig + perl -pi \ + -e 's/\Q$(update_node_bad)\E/$(update_node_good)/' \ + -e ';s/\Q$(update_node_bad2)\E/$(update_node_good2),/' \ + -e ';' \ + -e 's/\Q$(remove_node_bad)\E/$(remove_node_good)/' \ + -e ';' \ + -e 's/\Q$(install_node_bad)\E/$(install_node_good)/' \ + $(mydoc)-incl/tlmgr.texi + cp $(mydoc)-incl/tlmgr.texi $(srcdir)/$(mydoc)-incl/ + cp $(mydoc)-incl/install-tl.texi $(srcdir)/$(mydoc)-incl/ +.PHONY: $(mydoc)-incl.texi + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/Build/source/doc/README.solaris b/Build/source/doc/README.solaris new file mode 100644 index 00000000000..6b13f3feb48 --- /dev/null +++ b/Build/source/doc/README.solaris @@ -0,0 +1,182 @@ +(This file public domain. Originally written by Mojca Miklavec, 2015-16.) + +Compiling TeX binaries on Solaris + +Solaris 9 has been out of official support for a while and making +software compile on that platform is challenging, so it hardly makes any +sense to try to support it. + +Solaris 10 reaches end of support in January 2021: + http://en.wikipedia.org/wiki/Solaris_(operating_system)#Version_history +and TeX Live binaries try to stay compatible with that OS version. + +Every once in a while a new Update is shipped: + U1 2006-01 + U2 2006-06 + U3 2006-11 + U4 2007-08 + U5 2008-05 + U6 2008-10 + U7 2009-05 + U8 2009-10 + U9 2010-09 + U10 2011-08 + U11 2013-01 +and the problem is that binaries compiled on an updated system might not +run on an older one. + +You can check the libc version with +> pvs -no /usr/lib/libc.so + +> pvs -d /lib/libc.so.1 | grep SUNW + SUNW_1.23; + SUNW_1.22.7; + SUNW_1.22.6; + /.../ + SUNW_1.1; + SUNW_0.9; + SUNW_0.8; + SUNW_0.7; + +Building for 64-bit +=================== + +All binaries have been compiled with gcc-5.5. +The only thing that is needed to build for 64-bit is to define + export CC="/path/to/gcc-5.5 -m64" + export CXX="/path/to/g++-5.5 -m64" + +Building wget +============= + +Building wget on the latest version of Solaris 10 will make the binary +useless on older Updates of Solaris 10 as it would depend on SUNW_1.22.7. + +One option to build wget in a "compatible way" would be to build it on +Solaris 9 with "cc". The other hack is the usage of map files. + +To make it work on older systems the following hack was used (thanks to +the OpenCSW community): + https://buildfarm.opencsw.org/source/xref/opencsw/csw/mgar/pkg/wget/trunk/files/map.wget + +> cat mapfile +libc.so - SUNW_1.22 SUNWprivate_1.1 $ADDVERS=SUNW_1.22; + +export LD_OPTIONS="-M $PWD/mapfile" + +And the following configuration was used to get rid of dependencies (which +are not installed on Solaris by default): + +> ./configure --enable-ipv6 --disable-iri --disable-nls \ + --disable-ntlm --disable-pcre --without-libiconv-prefix \ + --without-libintl-prefix --without-libuuid --without-libpsl \ + --without-ssl --without-zlib + +The binary was built with gcc 5.2. +The definition '#define _XOPEN_SOURCE 500' has been removed from 'src/sysdep.h' +to avoid compile error due to the fact that GCC 5 switched to -std=99. + +On i386 and x86_64 one has to manually add "-lsocket -lnsl" to the last linker command. +This should be reported upstream. + +> pvs Master/tlpkg/installer/wget/wget.sparc-solaris + libsocket.so.1 (SUNW_1.4); + libnsl.so.1 (SUNW_1.7); + librt.so.1 (SUNW_1.2); + libc.so.1 (SUNW_1.22, SUNWprivate_1.1); + +> ./Master/tlpkg/installer/wget/wget.sparc-solaris --version + GNU Wget 1.17.1 built on solaris2.10. + +digest -gpgme -https +ipv6 -iri +large-file -metalink -nls -ntlm + +opie -psl -ssl + +(That list of configure options is current as of the above version of +wget; not all those dependencies are present in earlier versions.) + +Building xz +=========== + +The xz binaries would likewise depend on SUNW_1.22.6 by default, so we +used the same hack with a map file to make it work on slightly older +systems. + +> cat mapfile +libc.so - SUNW_1.22 SUNWprivate_1.1 $ADDVERS=SUNW_1.22; + +> export LD_OPTIONS="-M $PWD/mapfile" +> ./configure --disable-nls --disable-shared + +> pvs Master/tlpkg/installer/xz/xz.sparc-solaris + librt.so.1 (SUNW_1.2); + libpthread.so.1 (SUNW_1.2); + libc.so.1 (SUNW_1.22); +> pvs Master/tlpkg/installer/xz/xzdec.sparc-solaris + libc.so.1 (SUNW_1.22); + +If users need binaries to run on even older systems, we can target what +is desired by changing the map file. + +Building asymptote +================== + +Asymptote has been built with the following flags: + +export CC=/opt/csw/bin/gcc-5.5 +export CXX=/opt/csw/bin/g++-5.5 +./configure --prefix=/tmp/asyinst --enable-texlive-build \ + --disable-fftw --disable-offscreen --disable-sigsegv \ + --disable-gl --disable-gsl --disable-readline + +Even though GL, GSL and readline should generally not be disabled, +the resulting binaries would not be portable enough otherwise. + +Because a newer gcc compiler was used we had to link statically against stdlib. +The following patch/hack took care of this: + +--- Makefile.in.orig ++++ Makefile.in +@@ -12,7 +12,7 @@ + GCPPLIB = @GCPPLIB@ + GCLIBS = $(GCPPLIB) $(GCLIB) + LFLAGS = @LDFLAGS@ +-LIBS = $(LFLAGS) @PTHREAD_LIBS@ @GLEW@ @LIBS@ $(GCLIBS) ++LIBS = $(LFLAGS) $(GCLIBS) -nodefaultlibs -Wl,-Bstatic -lstdc++ -Wl,-Bdynamic @PTHREAD_LIBS@ @GLEW@ @LIBS@ -lgcc_eh -lgcc -lc -lm + DOSLIBS = $(subst -lncurses, -ltermcap, $(LIBS)) -lgdi32 -lwinmm -s -static + + PERL = perl +------ + +The resulting binary depends on: + +> pvs asy + libnsl.so.1 (SUNW_0.7); + librt.so.1 (SUNW_1.2); + libm.so.2 (SUNW_1.2); + libc.so.1 (SUNW_1.22, SUNWprivate_1.1); +> ldd asy + libnsl.so.1 => /lib/libnsl.so.1 + librt.so.1 => /lib/librt.so.1 + libz.so.1 => /usr/lib/libz.so.1 + libm.so.2 => /lib/libm.so.2 + libc.so.1 => /lib/libc.so.1 + libmp.so.2 => /lib/libmp.so.2 + libmd.so.1 => /lib/libmd.so.1 + libscf.so.1 => /lib/libscf.so.1 + libaio.so.1 => /lib/libaio.so.1 + libdoor.so.1 => /lib/libdoor.so.1 + libuutil.so.1 => /lib/libuutil.so.1 + libgen.so.1 => /lib/libgen.so.1 + +Building texlive +================ + +Additional settings were needed to compile TeX Live with gcc 5.5: + * ./Build --without-iconv + +The '--without-iconv' makes sure to avoid linking against libiconv +which is not available on SunOS by default. + +luajittex seems to be broken on Solaris 10 x86_64 (even if it works +with Solaris 11) and doesn't support Sparc, so it was only compiled +for i386. + diff --git a/Build/source/doc/build-tools.txt b/Build/source/doc/build-tools.txt new file mode 100644 index 00000000000..45f6623d97f --- /dev/null +++ b/Build/source/doc/build-tools.txt @@ -0,0 +1,7 @@ +autoconf (GNU Autoconf) 2.69 +automake (GNU automake) 1.16.2 +bison (GNU Bison) 3.7.4 +flex 2.6.0 +ltmain.sh (GNU libtool) 2.4.6 +m4 (GNU M4) 1.4.18 +makeinfo (GNU texinfo) 6.7 diff --git a/Build/source/doc/buildinfo.sh b/Build/source/doc/buildinfo.sh new file mode 100755 index 00000000000..fe889022a8a --- /dev/null +++ b/Build/source/doc/buildinfo.sh @@ -0,0 +1,60 @@ +#!/bin/sh +# $Id$ +# Public domain. Report basics of current system; run from top-level +# Makefile so any make overrides will be taken into account. (And from +# Build.) buildenv.log with full environment dump is also created. + +do_config_status=true +if test "x$1" = x--no-config-status; then + shift + do_config_status=false +fi + +printf 'UNAME\t"%s"\n' "`uname -a`" + +# /etc/issue often contains only placeholders, so don't bother with it. + +# Return version identification for $1, by calling it with --version. +# gcc on Macs, when linked to cc, has a useless "Configured with:" as +# the first line. Likely we'll need to generalize for other compilers. +# We intentionally don't quote $1 in case CC was set to something like +# "cc --someopt". +compiler_version () { + $1 --version 2>&1 | grep -v '^Configured' | sed 1q +} + +printf 'MAKE\t"%s"\n' "${MAKE-make}" +printf 'MAKE-v\t"%s"\n' "`${MAKE-make} -v 2>&1 | sed 1q`" +# BSD make does not give version info with -v, but the +# first line of the usage message is sort of an identifier. + +# our configure defaults to using gcc and g++, so we will too. +printf 'CC\t"%s"\n' "${CC-gcc}" +printf 'CFLAGS\t"%s"\n' "${CFLAGS}" +printf 'CC-v\t"%s"\n' "`compiler_version ${CC-gcc}`" +# +printf 'CXX\t"%s"\n' "${CXX-g++}" +printf 'CXXFLAGS\t"%s"\n' "${CXXFLAGS}" +printf 'CXX-v\t"%s"\n' "`compiler_version ${CXX-g++}`" +# +printf 'OBJCXX\t"%s"\n' "${OBJCXX-cc}" +printf 'OBJCXXFLAGS\t"%s"\n' "${OBJCXXFLAGS}" +# +printf 'LDFLAGS\t"%s"\n' "${LDFLAGS}" + +# Some Linux-based systems provide this, but don't worry if not there. +# Let's hope that other systems are sufficiently identified by uname, +# don't feel like doing a big system-information hunt. But if we do: +# http://www.datadisk.co.uk/html_docs/misc/unix_commands.htm +if test -n "`lsb_release -a 2>/dev/null`"; then + printf '\nLSB_RELEASE\n' + lsb_release -a 2>&1 +fi + +# the whole configure line and more, if requested. +# (We want this from make, but not from Build.) +$do_config_status \ +&& test -s config.status \ +&& (printf '\nCONFIG_STATUS\n'; ./config.status --version | sed -n '1,/^$/p') + +exit 0 diff --git a/Build/source/doc/splitinfo.gawk b/Build/source/doc/splitinfo.gawk new file mode 100644 index 00000000000..bc5b3229950 --- /dev/null +++ b/Build/source/doc/splitinfo.gawk @@ -0,0 +1,46 @@ +# $Id$ +# Public domain. Originally written 2014 by Karl Berry. +# Split chapter 2 of plain text output from makeinfo, +# making each section into a separate README file. + +BEGIN { + lastline = ""; # have to read one line ahead + outfile = ""; # where we are currently outputting +} + +{ + if (/^[*]+$/) { # starting new chapter + # if we're at the index or an appendix, quit. + if (lastline == "Index" || lastline ~ /^Appendix /) exit (0); + + # move on unless starting a chapter we want (not top, intro, etc.) + if (lastline !~ /^[2-9]/) next; + + # ok, we want this chapter. if we had a file open already, close it. + if (outfile) close (outfile); + + # turn chapter title into filename and start new. + outfile = tolower (lastline); # all lowercase + chapnum = substr (outfile, 0, 1); # chapter number + sub ("^. ", "", outfile); # remove chapnum and following space + sub (" .*", "", outfile); # remove next space and everything + # after, leaving just the first word. + + # start numbering the README files at 0. + chapnum = chapnum - 2; + outfile = "README." chapnum outfile; # prefix "README. + # + print "(This file was generated by makeinfo and splitinfo.gawk.)">outfile; + print "(Released under the old-style GNU documentation license;" >outfile; + print " see sources or other output files for full text.)" >outfile; + print "" >outfile; + print lastline >outfile; + # $0 will be printed as lastline, next time through. + + # splitting output. + } else if (outfile) { + print lastline >outfile; + } + + lastline = $0; +} diff --git a/Build/source/doc/tlbuild-incl/install-tl.texi b/Build/source/doc/tlbuild-incl/install-tl.texi new file mode 100644 index 00000000000..6e0e4d00997 --- /dev/null +++ b/Build/source/doc/tlbuild-incl/install-tl.texi @@ -0,0 +1,577 @@ +@node install-tl +@appendix install-tl + +@menu +* install-tl NAME:: +* install-tl SYNOPSIS:: +* install-tl DESCRIPTION:: +* install-tl REFERENCES:: +* install-tl OPTIONS:: +* install-tl PROFILES:: +* install-tl ENVIRONMENT VARIABLES:: +* install-tl AUTHORS AND COPYRIGHT:: +@end menu + +@node install-tl NAME +@appendixsec NAME + +install-tl - TeX Live cross-platform installer + +@node install-tl SYNOPSIS +@appendixsec SYNOPSIS + +install-tl [@emph{option}]... + +install-tl-windows.bat [@emph{option}]... + +install-tl-advanced.bat [@emph{option}]... + +@node install-tl DESCRIPTION +@appendixsec DESCRIPTION + +This installer creates a runnable TeX Live installation from various +media, including over the network, from local hard disk, a DVD, etc. The +installer works on all platforms supported by TeX Live. For information +on initially downloading TeX Live, see +@url{https://tug.org/texlive/acquire.html}. + +The basic idea of TeX Live installation is for you to choose one of the +top-level @emph{schemes}, each of which is defined as a different set of +@emph{collections} and @emph{packages}, where a collection is a set of packages, +and a package is what contains actual files. + +Within the installer, you can choose a scheme, and further customize the +set of collections to install, but not the set of the packages. To work +at the package level, use @code{tlmgr} (reference just below) after the +initial installation is complete. + +The default is @code{scheme-full}, which installs everything, and this is +highly recommended. + +@node install-tl REFERENCES +@appendixsec REFERENCES + +Post-installation configuration, package updates, and more, are +handled through @strong{tlmgr}(1), the TeX Live Manager +(@url{https://tug.org/texlive/tlmgr.html}). + +The most up-to-date version of this installer documentation is on the +Internet at @url{https://tug.org/texlive/doc/install-tl.html}. + +For the full documentation of TeX Live, see +@url{https://tug.org/texlive/doc}. + +@node install-tl OPTIONS +@appendixsec OPTIONS + +As usual, all options can be specified in any order, and with either a +leading @code{-} or @code{--}. An argument value can be separated from its +option by either a space or @code{=}. + +@table @asis +@item @strong{-gui} [[=]@emph{module}] +@anchor{install-tl @strong{-gui} [[=]@emph{module}]} + +If no @emph{module} is given, starts the Tcl/Tk (see below) GUI installer. + +If @emph{module} is given loads the given installer module. Currently the +following modules are supported: + +@table @asis +@item @code{text} +@anchor{install-tl @code{text}} + +The text mode user interface (default on Unix systems). Same as the +@code{-no-gui} option. + +@item @code{tcl} +@anchor{install-tl @code{tcl}} + +The Tcl/Tk user interface (default on Macs and Windows). It starts +with a small number of configuration options, roughly equivalent +to what the wizard option below offers, but a button @code{Advanced} +takes you to a screen with roughly the same options as the @code{perltk} +interface. + +@item @code{wizard} +@anchor{install-tl @code{wizard}} + +The wizard mode user interface, asking only minimal questions before +installing all of TeX Live. + +@item @code{expert} +@anchor{install-tl @code{expert}} + +A generic name for, currently, @code{perltk}; it may select a different GUI +in the future. + +@item @code{perltk} +@anchor{install-tl @code{perltk}} + +The expert GUI installer, providing access to more options. + +@end table + +The @code{perltk} and @code{wizard} modules require the Perl/Tk module +(@url{https://tug.org/texlive/distro.html#perltk}). if Perl/Tk is not +available, installation continues in text mode, except on Windows, +where all gui options except @code{text} are diverted to the default +@code{tcl} GUI. + +The @code{tcl} GUI requires Tcl/Tk. This is standard on Macs and is often +already installed on GNU/Linux. For Windows, TeX Live provides a Tcl/Tk +runtime. + +@item @strong{-no-gui} +@anchor{install-tl @strong{-no-gui}} + +Use the text mode installer (default except on Windows and Macs). + +@item @strong{-lang} @emph{llcode} +@anchor{install-tl @strong{-lang} @emph{llcode}} + +By default, the GUI tries to deduce your language from the +environment. The Tcl GUI uses the language detection built into +Tcl/Tk; the Perl/Tk GUIs use the @code{LC_MESSAGES} environment +variable. If that fails you can select a different language by +giving this option with a language code (based on ISO 639-1). +Currently supported (but not necessarily completely translated) are: +English (en, default), Czech (cs), German (de), French (fr), Italian +(it), Japanese (ja), Dutch (nl), Polish (pl), Brazilian Portuguese +(pt_BR), Russian (ru), Slovak (sk), Slovenian (sl), Serbian (sr), +Ukrainian (uk), Vietnamese (vi), simplified Chinese (zh_CN), and +traditional Chinese (zh_TW). + +@item @strong{-repository} @emph{url|path} +@anchor{install-tl @strong{-repository} @emph{url|path}} + +Specify the package repository to be used as the source of the +installation. In short, this can be a directory name or a url using +http(s), ftp, or scp. The documentation for @code{tlmgr} has the details +(@url{https://tug.org/texlive/doc/tlmgr.html#OPTIONS}). + +For installation, the default is to pick a mirror automatically, using +@url{http://mirror.ctan.org/systems/texlive/tlnet}; the chosen mirror is +used for the entire download. You can use the special argument @code{ctan} +as an abbreviation for this. (See @url{https://ctan.org} for more about CTAN +and its mirrors.) + +After installation is complete, you can use that installation as the +repository for another installation. If you chose to install less than +the full scheme containing all packages, the list of available schemes +will be adjusted accordingly. + +@item @strong{-select-repository} +@anchor{install-tl @strong{-select-repository}} + +This option allows you to choose a particular mirror from the current +list of active CTAN mirrors. This option is supported in the @code{text}, +@code{wizard} and @code{perltk} installer modes, and will also offer to install +from local media if available, or from a repository specified on the +command line. It's useful when the (default) automatic redirection does +not choose a good host for you. + +@item @strong{-all-options} +@anchor{install-tl @strong{-all-options}} + +Normally options not relevant to the current platform are not shown +(e.g., when running on Unix, Windows-specific options are omitted). +Giving this command line option allows configuring such "foreign" +settings. + +@item @strong{-custom-bin} @emph{path} +@anchor{install-tl @strong{-custom-bin} @emph{path}} + +If you have built your own set of TeX Live binaries (perhaps because +your platform was not supported by TeX Live out of the box), this option +allows you to specify the @emph{path} to a directory where the binaries for +the current system are present. The installation will continue as +usual, but at the end all files from @emph{path} are copied over to +@code{bin/custom/} under your installation directory and this @code{bin/custom/} +directory is what will be added to the path for the post-install +actions. To install multiple custom binary sets, manually rename +@code{custom} before doing each. + +For more information on custom binaries, see +@url{https://tug.org/texlive/custom-bin.html}. For general information on +building TeX Live, see @url{https://tug.org/texlive/build.html}. + +@item @strong{-debug-translation} +@anchor{install-tl @strong{-debug-translation}} + +In the Perl/Tk GUI modes, this option reports any missing, or more +likely untranslated, messages to standard error. Helpful for +translators to see what remains to be done. + +@item @strong{-force-platform} @emph{platform} +@anchor{install-tl @strong{-force-platform} @emph{platform}} + +Instead of auto-detecting the current platform, use @emph{platform}. +Binaries for this platform must be present and they must actually be +runnable, or installation will fail. @code{-force-arch} is a synonym. + +@item @strong{-help}, @strong{--help}, @strong{-?} +@anchor{install-tl @strong{-help}@comma{} @strong{--help}@comma{} @strong{-?}} + +Display this help and exit. (This help is also on the web at +@url{https://tug.org/texlive/doc/install-tl.html}). Sometimes the @code{perldoc} +and/or @code{PAGER} programs on the system have problems, possibly resulting +in control characters being literally output. This can't always be +detected, but you can set the @code{NOPERLDOC} environment variable and +@code{perldoc} will not be used. + +@item @strong{-in-place} +@anchor{install-tl @strong{-in-place}} + +This is a quick-and-dirty installation option in case you already have +an rsync or svn checkout of TeX Live. It will use the checkout as-is +and will just do the necessary post-install. Be warned that the file +@code{tlpkg/texlive.tlpdb} may be rewritten, that removal has to be done +manually, and that the only realistic way to maintain this installation +is to redo it from time to time. This option is not available via the +installer interfaces. USE AT YOUR OWN RISK. + +@item @strong{-init-from-profile} @emph{profile_file} +@anchor{install-tl @strong{-init-from-profile} @emph{profile_file}} + +Similar to @strong{-profile} (see @ref{install-tl PROFILES,, PROFILES} below), but only initializes +the installation configuration from @emph{profile_file} and then starts a +normal interactive session. Environment variables are not ignored. + +@item @strong{-logfile} @emph{file} +@anchor{install-tl @strong{-logfile} @emph{file}} + +Write both all messages (informational, debugging, warnings) to @emph{file}, +in addition to standard output or standard error. + +If this option is not given, the installer will create a log file +in the root of the writable installation tree, +for example, @code{/usr/local/texlive/YYYY/install-tl.log} for the @emph{YYYY} +release. + +@item @strong{-no-cls} +@anchor{install-tl @strong{-no-cls}} + +For the text mode installer only: do not clear the screen when entering +a new menu (for debugging purposes). + +@item @strong{-no-persistent-downloads} +@anchor{install-tl @strong{-no-persistent-downloads}} + +@item @strong{-persistent-downloads} +@anchor{install-tl @strong{-persistent-downloads}} + +For network installs, activating this option makes the installer try to +set up a persistent connection using the @code{Net::LWP} Perl module. This +opens only one connection between your computer and the server per +session and reuses it, instead of initiating a new download for each +package, which typically yields a significant speed-up. + +This option is turned on by default, and the installation program will +fall back to using @code{wget} if this is not possible. To disable usage of +LWP and persistent connections, use @code{-no-persistent-downloads}. + +@item @strong{-no-verify-downloads} +@anchor{install-tl @strong{-no-verify-downloads}} + +By default, if a GnuPG @code{gpg} binary is found in PATH, downloads are +verified against a cryptographic signature. This option disables such +verification. The full description is in the Crytographic Verification +section of the @code{tlmgr} documentation, e.g., +@url{https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION} + +@item @strong{-non-admin} +@anchor{install-tl @strong{-non-admin}} + +For Windows only: configure for the current user, not for all users. + +@item @strong{-portable} +@anchor{install-tl @strong{-portable}} + +Install for portable use, e.g., on a USB stick. Also selectable from +within the perltk and text installers. + +@item @strong{-print-platform} +@anchor{install-tl @strong{-print-platform}} + +Print the TeX Live identifier for the detected platform +(hardware/operating system) combination to standard output, and exit. +@code{-print-arch} is a synonym. + +@item @strong{-profile} @emph{profile_file} +@anchor{install-tl @strong{-profile} @emph{profile_file}} + +Load @emph{profile_file} and do the installation with no user interaction, +that is, a batch (unattended) install. Environment variables are +ignored. See @ref{install-tl PROFILES,, PROFILES} below. + +@item @strong{-q} +@anchor{install-tl @strong{-q}} + +Omit normal informational messages. + +@item @strong{-scheme} @emph{scheme} +@anchor{install-tl @strong{-scheme} @emph{scheme}} + +Schemes are the highest level of package grouping in TeX Live; the +default is to use the @code{full} scheme, which includes everything. This +option overrides that default. You can change the scheme again before +the actual installation with the usual menu. The @emph{scheme} argument may +optionally have a prefix @code{scheme-}. The list of supported scheme names +depends on what your package repository provides; see the interactive +menu list. + +@item @strong{-v} +@anchor{install-tl @strong{-v}} + +Include verbose debugging messages; repeat for maximum debugging: @code{-v +-v}. (Further repeats are accepted but ignored.) + +@item @strong{-version}, @strong{--version} +@anchor{install-tl @strong{-version}@comma{} @strong{--version}} + +Output version information and exit. If @code{-v} is also given, the +versions of the TeX Live modules used are also reported. + +@end table + +@node install-tl PROFILES +@appendixsec PROFILES + +A @emph{profile} file contains all the values needed to perform an +installation. After a normal installation has finished, a profile for +that exact installation is written to the file @code{tlpkg/texlive.profile}. +In addition, from the text menu one can select @code{P} to save the current +setup as a profile at any time. + +Such a profile file can be given as the argument to @code{-profile}, for +example to redo the exact same installation on a different system. +Alternatively, you can use a custom profile, most easily created by +starting from a generated one and changing values, or an empty file, +which will take all the defaults. + +As mentioned above, the installer only supports selection by scheme and +collections, not individual packages, so packages cannot be specified in +profile files either. Use @code{tlmgr} to work at the package level. + +Within a profile file, each line consists of + +@emph{variable} [@emph{value}] + +except for comment lines starting with @code{#}. The possible variable +names are listed below. Values, when present, are either @code{0} or @code{1} +for booleans, or strings (which must be specified without any quote +characters). Leading whitespace is ignored. + +If the variable @code{selected_scheme} is defined and @emph{no} collection +variables at all are defined, then the collections required by the +specified scheme (which might change over time) are installed, without +explicitly listing them. This eases maintenance of profile files. If +any collections are specified in a profile, though, then all desired +collections must be given explicitly. + +For example, a line + +@verbatim + selected_scheme scheme-small +@end verbatim + +along with definitions for the installation directories (given below +under "path options") suffices to install the "small" scheme with all +default options. The schemes are described in the @code{S} menu in the +text installer, or equivalent. + +Besides @code{selected_scheme}, here is the list of variable names supported +in a profile: + +@strong{collection options} (prefix @code{collection-}) + +Collections are specified with a variable name with the prefix +@code{collection-} followed by a collection name; there is no value. For +instance, @code{collection-basic}. The collections are described in the +@code{C} menu. + +Schemes and collections (and packages) are ultimately defined by the +files in the @code{tlpkg/tlpsrc/} source directory. + +@strong{path options} + +It is best to define all of these, even though they may not be used in +the installation, so as to avoid unintentionally getting a default value +that could cause problems later. + +@verbatim + TEXDIR + TEXMFCONFIG + TEXMFVAR + TEXMFHOME + TEXMFLOCAL + TEXMFSYSCONFIG + TEXMFSYSVAR +@end verbatim + +@strong{installer options} (prefix @code{instopt_}) + +@table @asis +@item @code{instopt_adjustpath} (default 0 on Unix, 1 on Windows) +@anchor{install-tl @code{instopt_adjustpath} (default 0 on Unix@comma{} 1 on Windows)} + +Adjust @code{PATH} environment variable. + +@item @code{instopt_adjustrepo} (default 1) +@anchor{install-tl @code{instopt_adjustrepo} (default 1)} + +Set remote repository to a multiplexed CTAN mirror after installation; +see @code{-repository} above. + +@item @code{instopt_letter} (default 0) +@anchor{install-tl @code{instopt_letter} (default 0)} + +Set letter size paper as the default, instead of a4. + +@item @code{instopt_portable} (default 0) +@anchor{install-tl @code{instopt_portable} (default 0)} + +Install for portable use, e.g., on a USB stick. + +@item @code{instopt_write18_restricted} (default 1) +@anchor{install-tl @code{instopt_write18_restricted} (default 1)} + +Enable @code{\write18} for a restricted set of programs. + +@end table + +@strong{tlpdb options} (prefix @code{tlpdbopt_}) + +The definitive list is given in @code{tlpkg/TeXLive/TLConfig.pm}, in the hash +@code{%TeXLive::TLConfig::TLPDBOptions}, together with explanations. All +items given there @emph{except} for @code{tlpdbopt_location} can be specified. +Here is the current list: + +@verbatim + tlpdbopt_autobackup + tlpdbopt_backupdir + tlpdbopt_create_formats + tlpdbopt_desktop_integration + tlpdbopt_file_assocs + tlpdbopt_generate_updmap + tlpdbopt_install_docfiles + tlpdbopt_install_srcfiles + tlpdbopt_post_code + tlpdbopt_sys_bin + tlpdbopt_sys_info + tlpdbopt_sys_man + tlpdbopt_w32_multi_user +@end verbatim + +@strong{platform options} (prefix @code{binary_}) + +For each supported platform in TeX Live (directories under @code{bin/}), the +variable @code{binary_}@emph{PLATFORM} can be set with value 1. For example: + +@verbatim + binary_x86_64-linux 1 +@end verbatim + +If no @code{binary_} settings are made, the default is whatever the +current machine is running. + +In releases before 2017, many profile variables had different +names (not documented here; see the @code{install-tl} source). They are +accepted and transformed to the names given above. When a profile is +written, the names above are always used. + +For more details on all of the above options, consult the TeX Live +installation manual, linked from @url{https://tug.org/texlive/doc}. + +@node install-tl ENVIRONMENT VARIABLES +@appendixsec ENVIRONMENT VARIABLES + +For ease in scripting and debugging, @code{install-tl} looks for the +following environment variables. They are not of interest for normal +user installations. + +@table @asis +@item @code{TEXLIVE_DOWNLOADER} +@anchor{install-tl @code{TEXLIVE_DOWNLOADER}} + +@item @code{TL_DOWNLOAD_PROGRAM} +@anchor{install-tl @code{TL_DOWNLOAD_PROGRAM}} + +@item @code{TL_DOWNLOAD_ARGS} +@anchor{install-tl @code{TL_DOWNLOAD_ARGS}} + +These override the normal choice of a download program; see the @code{tlmgr} +documentation, e.g., +@url{https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES}. + +@item @code{TEXLIVE_INSTALL_ENV_NOCHECK} +@anchor{install-tl @code{TEXLIVE_INSTALL_ENV_NOCHECK}} + +Omit the check for environment variables containing the string @code{tex}. +People developing TeX-related software are likely to have many such +variables. + +@item @code{TEXLIVE_INSTALL_NO_CONTEXT_CACHE} +@anchor{install-tl @code{TEXLIVE_INSTALL_NO_CONTEXT_CACHE}} + +Omit creating the ConTeXt cache. This is useful for redistributors. + +@item @code{TEXLIVE_INSTALL_NO_IMPORT} +@anchor{install-tl @code{TEXLIVE_INSTALL_NO_IMPORT}} + +Omit check for installing on top of a previous installation and then +asking about importing previous settings. + +@item @code{TEXLIVE_INSTALL_NO_WELCOME} +@anchor{install-tl @code{TEXLIVE_INSTALL_NO_WELCOME}} + +Omit printing the welcome message after successful installation, e.g., +when testing. + +@item @code{TEXLIVE_INSTALL_PREFIX} +@anchor{install-tl @code{TEXLIVE_INSTALL_PREFIX}} + +@item @code{TEXLIVE_INSTALL_TEXDIR} +@anchor{install-tl @code{TEXLIVE_INSTALL_TEXDIR}} + +@item @code{TEXLIVE_INSTALL_TEXMFCONFIG} +@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFCONFIG}} + +@item @code{TEXLIVE_INSTALL_TEXMFVAR} +@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFVAR}} + +@item @code{TEXLIVE_INSTALL_TEXMFHOME} +@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFHOME}} + +@item @code{TEXLIVE_INSTALL_TEXMFLOCAL} +@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFLOCAL}} + +@item @code{TEXLIVE_INSTALL_TEXMFSYSCONFIG} +@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFSYSCONFIG}} + +@item @code{TEXLIVE_INSTALL_TEXMFSYSVAR} +@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFSYSVAR}} + +Specify the respective directories. @code{TEXLIVE_INSTALL_PREFIX} defaults +to @code{/usr/local/texlive}, while @code{TEXLIVE_INSTALL_TEXDIR} defaults to +the release directory within that prefix, e.g., +@code{/usr/local/texlive/2016}. All the defaults can be seen by running the +installer interactively and then typing @code{D} for the directory menu. + +@item @code{NOPERLDOC} +@anchor{install-tl @code{NOPERLDOC}} + +Don't try to run the @code{--help} message through @code{perldoc}. + +@end table + +@node install-tl AUTHORS AND COPYRIGHT +@appendixsec AUTHORS AND COPYRIGHT + +This script and its documentation were written for the TeX Live +distribution (@url{https://tug.org/texlive}) and both are licensed under the +GNU General Public License Version 2 or later. + +$Id: install-tl 54143 2020-03-06 23:51:18Z karl $ + diff --git a/Build/source/doc/tlbuild-incl/tlmgr.texi b/Build/source/doc/tlbuild-incl/tlmgr.texi new file mode 100644 index 00000000000..690b33848d6 --- /dev/null +++ b/Build/source/doc/tlbuild-incl/tlmgr.texi @@ -0,0 +1,2742 @@ +@node tlmgr +@appendix tlmgr + +@menu +* tlmgr NAME:: +* tlmgr SYNOPSIS:: +* tlmgr DESCRIPTION:: +* tlmgr EXAMPLES:: +* tlmgr OPTIONS:: +* tlmgr ACTIONS:: +* tlmgr CONFIGURATION FILE FOR TLMGR:: +* tlmgr CRYPTOGRAPHIC VERIFICATION:: +* tlmgr USER MODE:: +* tlmgr MULTIPLE REPOSITORIES:: +* tlmgr GUI FOR TLMGR:: +* tlmgr MACHINE-READABLE OUTPUT:: +* tlmgr ENVIRONMENT VARIABLES:: +* tlmgr AUTHORS AND COPYRIGHT:: +@end menu + +@node tlmgr NAME +@appendixsec NAME + +tlmgr - the native TeX Live Manager + +@node tlmgr SYNOPSIS +@appendixsec SYNOPSIS + +tlmgr [@emph{option}...] @emph{action} [@emph{option}...] [@emph{operand}...] + +@node tlmgr DESCRIPTION +@appendixsec DESCRIPTION + +@strong{tlmgr} manages an existing TeX Live installation, both packages and +configuration options. For information on initially downloading and +installing TeX Live, see @url{https://tug.org/texlive/acquire.html}. + +The most up-to-date version of this documentation (updated nightly from +the development sources) is available at +@url{https://tug.org/texlive/tlmgr.html}, along with procedures for updating +@code{tlmgr} itself and information about test versions. + +TeX Live is organized into a few top-level @emph{schemes}, each of which is +specified as a different set of @emph{collections} and @emph{packages}, where a +collection is a set of packages, and a package is what contains actual +files. Schemes typically contain a mix of collections and packages, but +each package is included in exactly one collection, no more and no less. +A TeX Live installation can be customized and managed at any level. + +See @url{https://tug.org/texlive/doc} for all the TeX Live documentation +available. + +@node tlmgr EXAMPLES +@appendixsec EXAMPLES + +After successfully installing TeX Live, here are a few common operations +with @code{tlmgr}: + +@table @asis +@item @code{tlmgr option repository ctan} +@anchor{tlmgr @code{tlmgr option repository ctan}} + +@item @code{tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet} +@anchor{tlmgr @code{tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet}} + +Tell @code{tlmgr} to use a nearby CTAN mirror for future updates; useful if +you installed TeX Live from the DVD image and want to have continuing +updates. The two commands are equivalent; @code{ctan} is just an alias for +the given url. + +Caveat: @code{mirror.ctan.org} resolves to many different hosts, and they +are not perfectly synchronized; we recommend updating only daily (at +most), and not more often. You can choose a particular mirror if +problems; the list of all CTAN mirrors with the status of each is at +@url{https://ctan.org/mirrors/mirmon}. + +@item @code{tlmgr update --list} +@anchor{tlmgr @code{tlmgr update --list}} + +Report what would be updated without actually updating anything. + +@item @code{tlmgr update --all} +@anchor{tlmgr @code{tlmgr update --all}} + +Make your local TeX installation correspond to what is in the package +repository (typically useful when updating from CTAN). + +@item @code{tlmgr info} @emph{what} +@anchor{tlmgr @code{tlmgr info} @emph{what}} + +Display detailed information about a package @emph{what}, such as the installation +status and description, of searches for @emph{what} in all packages. + +@end table + +For all the capabilities and details of @code{tlmgr}, please read the +following voluminous information. + +@node tlmgr OPTIONS +@appendixsec OPTIONS + +The following options to @code{tlmgr} are global options, not specific to +any action. All options, whether global or action-specific, can be +given anywhere on the command line, and in any order. The first +non-option argument will be the main action. In all cases, +@code{--}@emph{option} and @code{-}@emph{option} are equivalent, and an @code{=} is optional +between an option name and its value. + +@table @asis +@item @strong{--repository} @emph{url|path} +@anchor{tlmgr @strong{--repository} @emph{url|path}} + +Specify the package repository from which packages should be installed +or updated, either a local directory or network location, as below. This +overridesthe default package repository found in the installation's TeX +Live Package Database (a.k.a. the TLPDB, which is given entirely in the +file @code{tlpkg/texlive.tlpdb}). + +This @code{--repository} option changes the location only for the current +run; to make a permanent change, use @code{option repository} (see the +@ref{tlmgr option,, option} action). + +As an example, you can choose a particular CTAN mirror with something +like this: + +@verbatim + -repository http://ctan.example.org/its/ctan/dir/systems/texlive/tlnet +@end verbatim + +Of course a real hostname and its particular top-level CTAN directory +have to be specified. The list of CTAN mirrors is available at +@url{https://ctan.org/mirrors/mirmon}. + +Here's an example of using a local directory: + +@verbatim + -repository /local/TL/repository +@end verbatim + +For backward compatibility and convenience, @code{--location} and @code{--repo} +are accepted as aliases for this option. + +Locations can be specified as any of the following: + +@table @asis +@item @code{/some/local/dir} +@anchor{tlmgr @code{/some/local/dir}} + +@item @code{file:/some/local/dir} +@anchor{tlmgr @code{file:/some/local/dir}} + +Equivalent ways of specifying a local directory. + +@item @code{ctan} +@anchor{tlmgr @code{ctan}} + +@item @code{http://mirror.ctan.org/systems/texlive/tlnet} +@anchor{tlmgr @code{http://mirror.ctan.org/systems/texlive/tlnet}} + +Pick a CTAN mirror automatically, trying for one that is both nearby and +up-to-date. The chosen mirror is used for the entire download. The bare +@code{ctan} is merely an alias for the full url. (See @url{https://ctan.org} for +more about CTAN and its mirrors.) + +@item @code{http://server/path/to/tlnet} +@anchor{tlmgr @code{http://server/path/to/tlnet}} + +Standard HTTP. If the (default) LWP method is used, persistent +connections are supported. TL can also use @code{curl} or @code{wget} to do the +downloads, or an arbitrary user-specified program, as described in the +@code{tlmgr} documentation +(@url{https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES}). + +@item @code{https://server/path/to/tlnet} +@anchor{tlmgr @code{https://server/path/to/tlnet}} + +Again, if the (default) LWP method is used, this supports persistent +connections. Unfortunately, some versions of @code{wget} and @code{curl} do not +support https, and even when @code{wget} supports https, certificates may be +rejected even when the certificate is fine, due to a lack of local +certificate roots. The simplest workaround for this problem is to use +http or ftp. + +@item @code{ftp://server/path/to/tlnet} +@anchor{tlmgr @code{ftp://server/path/to/tlnet}} + +If the (default) LWP method is used, persistent connections are +supported. + +@item @code{user@@machine:/path/to/tlnet} +@anchor{tlmgr @code{user@@machine:/path/to/tlnet}} + +@item @code{scp://user@@machine/path/to/tlnet} +@anchor{tlmgr @code{scp://user@@machine/path/to/tlnet}} + +@item @code{ssh://user@@machine/path/to/tlnet} +@anchor{tlmgr @code{ssh://user@@machine/path/to/tlnet}} + +These forms are equivalent; they all use @code{scp} to transfer files. Using +@code{ssh-agent} is recommended. (Info: +@url{https://en.wikipedia.org/wiki/OpenSSH}, +@url{https://en.wikipedia.org/wiki/Ssh-agent}.) + +@end table + +If the repository is on the network, trailing @code{/} characters and/or +trailing @code{/tlpkg} and/or @code{/archive} components are ignored. + +@item @strong{--gui} [@emph{action}] +@anchor{tlmgr @strong{--gui} [@emph{action}]} + +Two notable GUI front-ends for @code{tlmgr}, @code{tlshell} and @code{tlcockpit}, +are started up as separate programs; see their own documentation. + +@code{tlmgr} itself has a graphical interface as well as the command line +interface. You can give the option to invoke it, @code{--gui}, together with +an action to be brought directly into the respective screen of the GUI. +For example, running + +@verbatim + tlmgr --gui update +@end verbatim + +starts you directly at the update screen. If no action is given, the +GUI will be started at the main screen. See @ref{tlmgr GUI FOR TLMGR,, GUI FOR TLMGR}. + +However, the native GUI requires Perl/TK, which is no longer included in +TeX Live's Perl distribution for Windows. You may find @code{tlshell} or +@code{tlcockpit} easier to work with. + +@item @strong{--gui-lang} @emph{llcode} +@anchor{tlmgr @strong{--gui-lang} @emph{llcode}} + +By default, the GUI tries to deduce your language from the environment +(on Windows via the registry, on Unix via @code{LC_MESSAGES}). If that fails +you can select a different language by giving this option with a +language code (based on ISO 639-1). Currently supported (but not +necessarily completely translated) are: @w{English (en, default)}, +@w{Czech (cs)}, @w{German (de)}, @w{French (fr)}, @w{Italian (it)}, +@w{Japanese (ja)}, @w{Dutch (nl)}, @w{Polish (pl)}, @w{Brazilian Portuguese +(pt_BR)}, @w{Russian (ru)}, @w{Slovak (sk)}, @w{Slovenian (sl)}, @w{Serbian +(sr)}, @w{Ukrainian (uk)}, @w{Vietnamese (vi)}, @w{simplified Chinese +(zh_CN)}, and @w{traditional Chinese (zh_TW)}. + +tlshell shares its message catalog with tlmgr. + +@item @strong{--debug-translation} +@anchor{tlmgr @strong{--debug-translation}} + +In GUI mode, this switch tells @code{tlmgr} to report any untranslated (or +missing) messages to standard error. This can help translators to see +what remains to be done. + +@item @strong{--machine-readable} +@anchor{tlmgr @strong{--machine-readable}} + +Instead of the normal output intended for human consumption, write (to +standard output) a fixed format more suitable for machine parsing. See +the @ref{tlmgr MACHINE-READABLE OUTPUT,, MACHINE-READABLE OUTPUT} section below. + +@item @strong{--no-execute-actions} +@anchor{tlmgr @strong{--no-execute-actions}} + +Suppress the execution of the execute actions as defined in the tlpsrc +files. Documented only for completeness, as this is only useful in +debugging. + +@item @strong{--package-logfile} @emph{file} +@anchor{tlmgr @strong{--package-logfile} @emph{file}} + +@code{tlmgr} logs all package actions (install, remove, update, failed +updates, failed restores) to a separate log file, by default +@code{TEXMFSYSVAR/web2c/tlmgr.log}. This option allows you to specify a +different file for the log. + +@item @strong{--pause} +@anchor{tlmgr @strong{--pause}} + +This option makes @code{tlmgr} wait for user input before exiting. Useful on +Windows to avoid disappearing command windows. + +@item @strong{--persistent-downloads} +@anchor{tlmgr @strong{--persistent-downloads}} + +@item @strong{--no-persistent-downloads} +@anchor{tlmgr @strong{--no-persistent-downloads}} + +For network-based installations, this option (on by default) makes +@code{tlmgr} try to set up a persistent connection (using the @code{LWP} Perl +module). The idea is to open and reuse only one connection per session +between your computer and the server, instead of initiating a new +download for each package. + +If this is not possible, @code{tlmgr} will fall back to using @code{wget}. To +disable these persistent connections, use @code{--no-persistent-downloads}. + +@item @strong{--pin-file} +@anchor{tlmgr @strong{--pin-file}} + +Change the pinning file location from @code{TEXMFLOCAL/tlpkg/pinning.txt} +(see @ref{tlmgr Pinning,, Pinning} below). Documented only for completeness, as this is +only useful in debugging. + +@item @strong{--usermode} +@anchor{tlmgr @strong{--usermode}} + +Activates user mode for this run of @code{tlmgr}; see @ref{tlmgr USER MODE,, USER MODE} below. + +@item @strong{--usertree} @emph{dir} +@anchor{tlmgr @strong{--usertree} @emph{dir}} + +Uses @emph{dir} for the tree in user mode; see @ref{tlmgr USER MODE,, USER MODE} below. + +@item @strong{--verify-repo=[none|main|all]} +@anchor{tlmgr @strong{--verify-repo=[none|main|all]}} + +Defines the level of verification done: If @code{none} is specified, no +verification whatsoever is done. If @code{main} is given and a working GnuPG +(@code{gpg}) binary is available, all repositories are checked, but only the +main repository is required to be signed. If @code{all} is given, then all +repositories need to be signed. See @ref{tlmgr CRYPTOGRAPHIC VERIFICATION,, CRYPTOGRAPHIC VERIFICATION} below +for details. + +@end table + +The standard options for TeX Live programs are also accepted: +@code{--help/-h/-?}, @code{--version}, @code{-q} (no informational messages), @code{-v} +(debugging messages, can be repeated). For the details about these, see +the @code{TeXLive::TLUtils} documentation. + +The @code{--version} option shows version information about the TeX Live +release and about the @code{tlmgr} script itself. If @code{-v} is also given, +revision number for the loaded TeX Live Perl modules are shown, too. + +@node tlmgr ACTIONS +@appendixsec ACTIONS + +@menu +* tlmgr help:: +* tlmgr version:: +* tlmgr backup:: +* tlmgr candidates @emph{pkg}:: +* tlmgr check [@emph{option}...] [depends|executes|files|runfiles|texmfdbs|all]:: +* tlmgr conf:: +* tlmgr dump-tlpdb [@emph{option}...] [--json]:: +* tlmgr generate:: +* tlmgr gui:: +* tlmgr info:: +* tlmgr init-usertree:: +* tlmgr install [@emph{option}...] @emph{pkg}...:: +* tlmgr key:: +* tlmgr list:: +* tlmgr option:: +* tlmgr paper:: +* tlmgr path:: +* tlmgr pinning:: +* tlmgr platform:: +* tlmgr postaction:: +* tlmgr print-platform:: +* tlmgr print-platform-info:: +* tlmgr remove [@emph{option}...] @emph{pkg}...:: +* tlmgr repository:: +* tlmgr restore:: +* tlmgr search:: +* tlmgr shell:: +* tlmgr show:: +* tlmgr uninstall:: +* tlmgr update [@emph{option}...] [@emph{pkg}...]:: +@end menu + +@node tlmgr help +@appendixsubsec help + +Display this help information and exit (same as @code{--help}, and on the +web at @url{https://tug.org/texlive/doc/tlmgr.html}). Sometimes the +@code{perldoc} and/or @code{PAGER} programs on the system have problems, +resulting in control characters being literally output. This can't +always be detected, but you can set the @code{NOPERLDOC} environment +variable and @code{perldoc} will not be used. + +@node tlmgr version +@appendixsubsec version + +Gives version information (same as @code{--version}). + +If @code{-v} has been given the revisions of the used modules are reported, too. + +@node tlmgr backup +@appendixsubsec backup + +@table @asis +@item @strong{backup [@emph{option}...] --all} +@anchor{tlmgr @strong{backup [@emph{option}...] --all}} + +@item @strong{backup [@emph{option}...] @emph{pkg}...} +@anchor{tlmgr @strong{backup [@emph{option}...] @emph{pkg}...}} + +If the @code{--clean} option is not specified, this action makes a backup of +the given packages, or all packages given @code{--all}. These backups are +saved to the value of the @code{--backupdir} option, if that is an existing +and writable directory. If @code{--backupdir} is not given, the @code{backupdir} +option setting in the TLPDB is used, if present. If both are missing, no +backups are made. (The installer sets @code{backupdir} to +@code{.../tlpkg/backups}, under the TL root installation directory, so it is +usually defined; see the @ref{tlmgr option,, option} description for more information.) + +If the @code{--clean} option is specified, backups are pruned (removed) +instead of saved. The optional integer value @emph{N} may be specified to +set the number of backups that will be retained when cleaning. If @code{N} +is not given, the value of the @code{autobackup} option is used. If both are +missing, an error is issued. For more details of backup pruning, see +the @code{option} action. + +Options: + +@table @asis +@item @strong{--backupdir} @emph{directory} +@anchor{tlmgr @strong{--backupdir} @emph{directory}} + +Overrides the @code{backupdir} option setting in the TLPDB. +The @emph{directory} argument is required and must specify an existing, +writable directory where backups are to be placed. + +@item @strong{--all} +@anchor{tlmgr @strong{--all}} + +If @code{--clean} is not specified, make a backup of all packages in the TeX +Live installation; this will take quite a lot of space and time. If +@code{--clean} is specified, all packages are pruned. + +@item @strong{--clean}[=@emph{N}] +@anchor{tlmgr @strong{--clean}[=@emph{N}]} + +Instead of making backups, prune the backup directory of old backups, as +explained above. The optional integer argument @emph{N} overrides the +@code{autobackup} option set in the TLPDB. You must use @code{--all} or a list +of packages together with this option, as desired. + +@item @strong{--dry-run} +@anchor{tlmgr @strong{--dry-run}} + +Nothing is actually backed up or removed; instead, the actions to be +performed are written to the terminal. + +@end table + +@end table + +@node tlmgr candidates @emph{pkg} +@appendixsubsec candidates @emph{pkg} + +Shows the available candidate repositories for package @emph{pkg}. +See @ref{tlmgr MULTIPLE REPOSITORIES,, MULTIPLE REPOSITORIES} below. + +@node tlmgr check [@emph{option}...] [depends|executes|files|runfiles|texmfdbs|all] +@appendixsubsec check [@emph{option}...] [depends|executes|files|runfiles|texmfdbs|all] + +Execute one (or all) check(s) of the consistency of the installation. +If no problems are found, there will be no output. (To get a view of +what is being done, run @code{tlmgr -v check}.) + +@table @asis +@item @strong{depends} +@anchor{tlmgr @strong{depends}} + +Lists those packages which occur as dependencies in an installed collection, +but are themselves not installed, and those packages which are not +contained in any collection. + +If you call @code{tlmgr check collections} this test will be carried out +instead since former versions for @code{tlmgr} called it that way. + +@item @strong{executes} +@anchor{tlmgr @strong{executes}} + +Check that the files referred to by @code{execute} directives in the TeX +Live Database are present. + +@item @strong{files} +@anchor{tlmgr @strong{files}} + +Checks that all files listed in the local TLPDB (@code{texlive.tlpdb}) are +actually present, and lists those missing. + +@item @strong{runfiles} +@anchor{tlmgr @strong{runfiles}} + +List those filenames that are occurring more than one time in the +runfiles sections, except for known duplicates. + +@item @strong{texmfdbs} +@anchor{tlmgr @strong{texmfdbs}} + +Checks related to the @code{ls-R} files. If you have defined new trees, or +changed the @code{TEXMF} or @code{TEXMFDBS} variables, it can't hurt to run +this. It checks that: + +@table @asis +@item - all items in @code{TEXMFDBS} have the @code{!!} prefix. +@anchor{tlmgr - all items in @code{TEXMFDBS} have the @code{!!} prefix.} + +@item - all items in @code{TEXMFBDS} have an @code{ls-R} file (if they exist at all). +@anchor{tlmgr - all items in @code{TEXMFBDS} have an @code{ls-R} file (if they exist at all).} + +@item - all items in @code{TEXMF} with @code{!!} are listed in @code{TEXMFDBS}. +@anchor{tlmgr - all items in @code{TEXMF} with @code{!!} are listed in @code{TEXMFDBS}.} + +@item - all items in @code{TEXMF} with an @code{ls-R} file are listed in @code{TEXMFDBS}. +@anchor{tlmgr - all items in @code{TEXMF} with an @code{ls-R} file are listed in @code{TEXMFDBS}.} + +@end table + +@end table + +Options: + +@table @asis +@item @strong{--use-svn} +@anchor{tlmgr @strong{--use-svn}} + +Use the output of @code{svn status} instead of listing the files; for +checking the TL development repository. (This is run nightly.) + +@end table + +@node tlmgr conf +@appendixsubsec conf + +@table @asis +@item @strong{conf [texmf|tlmgr|updmap [--conffile @emph{file}] [--delete] [@emph{key} [@emph{value}]]]} +@anchor{tlmgr @strong{conf [texmf|tlmgr|updmap [--conffile @emph{file}] [--delete] [@emph{key} [@emph{value}]]]}} + +@item @strong{conf auxtrees [--conffile @emph{file}] [show|add|remove] [@emph{value}]} +@anchor{tlmgr @strong{conf auxtrees [--conffile @emph{file}] [show|add|remove] [@emph{value}]}} + +With only @code{conf}, show general configuration information for TeX Live, +including active configuration files, path settings, and more. This is +like running @code{texconfig conf}, but works on all supported platforms. + +With one of @code{conf texmf}, @code{conf tlmgr}, or @code{conf updmap}, shows all +key/value pairs (i.e., all settings) as saved in @code{ROOT/texmf.cnf}, the +user-specific @code{tlmgr} configuration file (see below), or the first +found (via @code{kpsewhich}) @code{updmap.cfg} file, respectively. + +If @emph{key} is given in addition, shows the value of only that @emph{key} in +the respective file. If option @emph{--delete} is also given, the value in +the given configuration file is entirely removed (not just commented +out). + +If @emph{value} is given in addition, @emph{key} is set to @emph{value} in the +respective file. @emph{No error checking is done!} + +The @code{PATH} value shown by @code{conf} is as used by @code{tlmgr}. The +directory in which the @code{tlmgr} executable is found is automatically +prepended to the PATH value inherited from the environment. + +Here is a practical example of changing configuration values. If the +execution of (some or all) system commands via @code{\write18} was left +enabled during installation, you can disable it afterwards: + +@verbatim + tlmgr conf texmf shell_escape 0 +@end verbatim + +The subcommand @code{auxtrees} allows adding and removing arbitrary +additional texmf trees, completely under user control. @code{auxtrees show} +shows the list of additional trees, @code{auxtrees add} @emph{tree} adds a tree +to the list, and @code{auxtrees remove} @emph{tree} removes a tree from the list +(if present). The trees should not contain an @code{ls-R} file (or files +will not be found if the @code{ls-R} becomes stale). This works by +manipulating the Kpathsea variable @code{TEXMFAUXTREES}, in (by default) +@code{ROOT/texmf.cnf}. Example: + +@verbatim + tlmgr conf auxtrees add /quick/test/tree + tlmgr conf auxtrees remove /quick/test/tree +@end verbatim + +In all cases the configuration file can be explicitly specified via the +option @code{--conffile} @emph{file}, e.g., if you don't want to change the +system-wide configuration. + +Warning: The general facility for changing configuration values is here, +but tinkering with settings in this way is strongly discouraged. Again, +no error checking on either keys or values is done, so any sort of +breakage is possible. + +@end table + +@node tlmgr dump-tlpdb [@emph{option}...] [--json] +@appendixsubsec dump-tlpdb [@emph{option}...] [--json] + +Dump complete local or remote TLPDB to standard output, as-is. The +output is analogous to the @code{--machine-readable} output; see +@ref{tlmgr MACHINE-READABLE OUTPUT,, MACHINE-READABLE OUTPUT} section. + +Options: + +@table @asis +@item @strong{--local} +@anchor{tlmgr @strong{--local}} + +Dump the local TLPDB. + +@item @strong{--remote} +@anchor{tlmgr @strong{--remote}} + +Dump the remote TLPDB. + +@item @strong{--json} +@anchor{tlmgr @strong{--json}} + +Instead of dumping the actual content, the database is dumped as +JSON. For the format of JSON output see @code{tlpkg/doc/JSON-formats.txt}, +format definition @code{TLPDB}. + +@end table + +Exactly one of @code{--local} and @code{--remote} must be given. + +In either case, the first line of the output specifies the repository +location, in this format: + +@verbatim + "location-url" "\t" location +@end verbatim + +where @code{location-url} is the literal field name, followed by a tab, and +@emph{location} is the file or url to the repository. + +Line endings may be either LF or CRLF depending on the current platform. + +@node tlmgr generate +@appendixsubsec generate + +@table @asis +@item @strong{generate [@emph{option}...] language} +@anchor{tlmgr @strong{generate [@emph{option}...] language}} + +@item @strong{generate [@emph{option}...] language.dat} +@anchor{tlmgr @strong{generate [@emph{option}...] language.dat}} + +@item @strong{generate [@emph{option}...] language.def} +@anchor{tlmgr @strong{generate [@emph{option}...] language.def}} + +@item @strong{generate [@emph{option}...] language.dat.lua} +@anchor{tlmgr @strong{generate [@emph{option}...] language.dat.lua}} + +@end table + +The @code{generate} action overwrites any manual changes made in the +respective files: it recreates them from scratch based on the +information of the installed packages, plus local adaptions. +The TeX Live installer and @code{tlmgr} routinely call @code{generate} for +all of these files. + +For managing your own fonts, please read the @code{updmap --help} +information and/or @url{https://tug.org/fonts/fontinstall.html}. + +For managing your own formats, please read the @code{fmtutil --help} +information. + +In more detail: @code{generate} remakes any of the configuration files +@code{language.dat}, @code{language.def}, and @code{language.dat.lua} +from the information present in the local TLPDB, plus +locally-maintained files. + +The locally-maintained files are @code{language-local.dat}, +@code{language-local.def}, or @code{language-local.dat.lua}, +searched for in @code{TEXMFLOCAL} in the respective +directories. If local additions are present, the final file is made by +starting with the main file, omitting any entries that the local file +specifies to be disabled, and finally appending the local file. + +(Historical note: The formerly supported @code{updmap-local.cfg} and +@code{fmtutil-local.cnf} are no longer read, since @code{updmap} and @code{fmtutil} +now reads and supports multiple configuration files. Thus, +local additions can and should be put into an @code{updmap.cfg} of @code{fmtutil.cnf} +file in @code{TEXMFLOCAL}. The @code{generate updmap} and @code{generate fmtutil} actions +no longer exist.) + +Local files specify entries to be disabled with a comment line, namely +one of these: + +@verbatim + %!NAME + --!NAME +@end verbatim + +where @code{language.dat} and @code{language.def} use @code{%}, +and @code{language.dat.lua} use @code{--}. In all cases, the @emph{name} is +the respective format name or hyphenation pattern identifier. +Examples: + +@verbatim + %!german + --!usenglishmax +@end verbatim + +(Of course, you're not likely to actually want to disable those +particular items. They're just examples.) + +After such a disabling line, the local file can include another entry +for the same item, if a different definition is desired. In general, +except for the special disabling lines, the local files follow the same +syntax as the master files. + +The form @code{generate language} recreates all three files @code{language.dat}, +@code{language.def}, and @code{language.dat.lua}, while the forms with an +extension recreates only that given language file. + +Options: + +@table @asis +@item @strong{--dest} @emph{output_file} +@anchor{tlmgr @strong{--dest} @emph{output_file}} + +specifies the output file (defaults to the respective location in +@code{TEXMFSYSVAR}). If @code{--dest} is given to @code{generate language}, it +serves as a basename onto which @code{.dat} will be appended for the name of +the @code{language.dat} output file, @code{.def} will be appended to the value +for the name of the @code{language.def} output file, and @code{.dat.lua} to the +name of the @code{language.dat.lua} file. (This is just to avoid +overwriting; if you want a specific name for each output file, we +recommend invoking @code{tlmgr} twice.) + +@item @strong{--localcfg} @emph{local_conf_file} +@anchor{tlmgr @strong{--localcfg} @emph{local_conf_file}} + +specifies the (optional) local additions (defaults to the respective +location in @code{TEXMFLOCAL}). + +@item @strong{--rebuild-sys} +@anchor{tlmgr @strong{--rebuild-sys}} + +tells @code{tlmgr} to run necessary programs after config files have been +regenerated. These are: +@code{fmtutil-sys --all} after @code{generate fmtutil}, +@code{fmtutil-sys --byhyphen .../language.dat} after @code{generate language.dat}, +and +@code{fmtutil-sys --byhyphen .../language.def} after @code{generate language.def}. + +These subsequent calls cause the newly-generated files to actually take +effect. This is not done by default since those calls are lengthy +processes and one might want to made several related changes in +succession before invoking these programs. + +@end table + +The respective locations are as follows: + +@verbatim + tex/generic/config/language.dat (and language-local.dat) + tex/generic/config/language.def (and language-local.def) + tex/generic/config/language.dat.lua (and language-local.dat.lua) +@end verbatim + +@node tlmgr gui +@appendixsubsec gui + +Start the graphical user interface. See @strong{GUI} below. + +@node tlmgr info +@appendixsubsec info + +@table @asis +@item @strong{info [@emph{option}...] @emph{pkg}...} +@anchor{tlmgr @strong{info [@emph{option}...] @emph{pkg}...}} + +@item @strong{info [@emph{option}...] collections} +@anchor{tlmgr @strong{info [@emph{option}...] collections}} + +@item @strong{info [@emph{option}...] schemes} +@anchor{tlmgr @strong{info [@emph{option}...] schemes}} + +With no argument, lists all packages available at the package +repository, prefixing those already installed with @code{i}. + +With the single word @code{collections} or @code{schemes} as the argument, lists +the request type instead of all packages. + +With any other arguments, display information about @emph{pkg}: the name, +category, short and long description, sizes, installation status, and TeX Live +revision number. If @emph{pkg} is not locally installed, searches in the +remote installation source. + +For normal packages (not collections or schemes), the sizes of the four +groups of files (run/src/doc/bin files) are shown separately. For +collections, the cumulative size is shown, including all +directly-dependent packages (but not dependent collections). For +schemes, the cumulative size is also shown, including all +directly-dependent collections and packages. + +If @emph{pkg} is not found locally or remotely, the search action is used +and lists matching packages and files. + +It also displays information taken from the TeX Catalogue, namely the +package version, date, and license. Consider these, especially the +package version, as approximations only, due to timing skew of the +updates of the different pieces. By contrast, the @code{revision} value +comes directly from TL and is reliable. + +The former actions @code{show} and @code{list} are merged into this action, +but are still supported for backward compatibility. + +Options: + +@table @asis +@item @strong{--list} +@anchor{tlmgr @strong{--list}} + +If the option @code{--list} is given with a package, the list of contained +files is also shown, including those for platform-specific dependencies. +When given with schemes and collections, @code{--list} outputs their +dependencies in a similar way. + +@item @strong{--only-installed} +@anchor{tlmgr @strong{--only-installed}} + +If this option is given, the installation source will not be used; only +locally installed packages, collections, or schemes are listed. + +@item @strong{--only-remote} +@anchor{tlmgr @strong{--only-remote}} + +Only list packages from the remote repository. Useful when checking what +is available in a remote repository using +@code{tlmgr --repo ... --only-remote info}. Note that +@code{--only-installed} and @code{--only-remote} cannot both be specified. + +@item @strong{--data @code{item1,item2,...}} +@anchor{tlmgr @strong{--data @code{item1@comma{}item2@comma{}...}}} + +If the option @code{--data} is given, its argument must be a comma separated +list of field names from: @code{name}, @code{category}, @code{localrev}, @code{remoterev}, +@code{shortdesc}, @code{longdesc}, @code{installed}, @code{size}, @code{relocatable}, @code{depends}, +@code{cat-version}, @code{cat-date}, or @code{cat-license}. In this case the requested +packages' information is listed in CSV format one package per line, and the +column information is given by the @code{itemN}. The @code{depends} column contains +the name of all dependencies separated by @code{:}. + +@item @strong{--json} +@anchor{tlmgr @strong{--json} 1} + +In case @code{--json} is specified, the output is a +JSON encoded array where each array element is the JSON representation of +a single @code{TLPOBJ} but with additional information. For details see +@code{tlpkg/doc/JSON-formats.txt}, format definition: @code{TLPOBJINFO}. +If both @code{--json} and @code{--data} are given, @code{--json} takes precedence. + +@end table + +@end table + +@node tlmgr init-usertree +@appendixsubsec init-usertree + +Sets up a texmf tree for so-called user mode management, either the +default user tree (@code{TEXMFHOME}), or one specified on the command line +with @code{--usertree}. See @ref{tlmgr USER MODE,, USER MODE} below. + +@node tlmgr install [@emph{option}...] @emph{pkg}... +@appendixsubsec install [@emph{option}...] @emph{pkg}... + +Install each @emph{pkg} given on the command line, if it is not already +installed. It does not touch existing packages; see the @code{update} +action for how to get the latest version of a package. + +By default this also installs all packages on which the given @emph{pkg}s are +dependent. Options: + +@table @asis +@item @strong{--dry-run} +@anchor{tlmgr @strong{--dry-run} 1} + +Nothing is actually installed; instead, the actions to be performed are +written to the terminal. + +@item @strong{--file} +@anchor{tlmgr @strong{--file}} + +Instead of fetching a package from the installation repository, use +the package files given on the command line. These files must +be standard TeX Live package files (with contained tlpobj file). + +@item @strong{--force} +@anchor{tlmgr @strong{--force}} + +If updates to @code{tlmgr} itself (or other parts of the basic +infrastructure) are present, @code{tlmgr} will bail out and not perform the +installation unless this option is given. Not recommended. + +@item @strong{--no-depends} +@anchor{tlmgr @strong{--no-depends}} + +Do not install dependencies. (By default, installing a package ensures +that all dependencies of this package are fulfilled.) + +@item @strong{--no-depends-at-all} +@anchor{tlmgr @strong{--no-depends-at-all}} + +Normally, when you install a package which ships binary files the +respective binary package will also be installed. That is, for a +package @code{foo}, the package @code{foo.i386-linux} will also be installed on +an @code{i386-linux} system. This option suppresses this behavior, and also +implies @code{--no-depends}. Don't use it unless you are sure of what you +are doing. + +@item @strong{--reinstall} +@anchor{tlmgr @strong{--reinstall}} + +Reinstall a package (including dependencies for collections) even if it +already seems to be installed (i.e, is present in the TLPDB). This is +useful to recover from accidental removal of files in the hierarchy. + +When re-installing, only dependencies on normal packages are followed +(i.e., not those of category Scheme or Collection). + +@item @strong{--with-doc} +@anchor{tlmgr @strong{--with-doc}} + +@item @strong{--with-src} +@anchor{tlmgr @strong{--with-src}} + +While not recommended, the @code{install-tl} program provides an option to +omit installation of all documentation and/or source files. (By +default, everything is installed.) After such an installation, you may +find that you want the documentation or source files for a given package +after all. You can get them by using these options in conjunction with +@code{--reinstall}, as in (using the @code{fontspec} package as the example): + +@verbatim + tlmgr install --reinstall --with-doc --with-src fontspec +@end verbatim + +@end table + +This action does not automatically add new symlinks in system +directories; you need to run @code{tlmgr path add} (@ref{tlmgr path,, path}) yourself if +you are using this feature and want new symlinks added. + +@node tlmgr key +@appendixsubsec key + +@table @asis +@item @strong{key list} +@anchor{tlmgr @strong{key list}} + +@item @strong{key add @emph{file}} +@anchor{tlmgr @strong{key add @emph{file}}} + +@item @strong{key remove @emph{keyid}} +@anchor{tlmgr @strong{key remove @emph{keyid}}} + +The action @code{key} allows listing, adding and removing additional GPG +keys to the set of trusted keys, that is, those that are used to verify +the TeX Live databases. + +With the @code{list} argument, @code{key} lists all keys. + +The @code{add} argument requires another argument, either a filename or +@code{-} for stdin, from which the key is added. The key is added to the +local keyring @code{GNUPGHOME/repository-keys.gpg}, which is normally +@code{tlpkg/gpg/repository-keys.gpg}. + +The @code{remove} argument requires a key id and removes the requested id +from the local keyring. + +@end table + +@node tlmgr list +@appendixsubsec list + +Synonym for @ref{tlmgr info,, info}. + +@node tlmgr option +@appendixsubsec option + +@table @asis +@item @strong{option [--json] [show]} +@anchor{tlmgr @strong{option [--json] [show]}} + +@item @strong{option [--json] showall|help} +@anchor{tlmgr @strong{option [--json] showall|help}} + +@item @strong{option @emph{key} [@emph{value}]} +@anchor{tlmgr @strong{option @emph{key} [@emph{value}]}} + +@end table + +The first form, @code{show}, shows the global TeX Live settings currently +saved in the TLPDB with a short description and the @code{key} used for +changing it in parentheses. + +The second form, @code{showall}, is similar, but also shows options which +can be defined but are not currently set to any value (@code{help} is a +synonym). + +Both @code{show...} forms take an option @code{--json}, which dumps the option +information in JSON format. In this case, both forms dump the same +data. For the format of the JSON output see +@code{tlpkg/doc/JSON-formats.txt}, format definition @code{TLOPTION}. + +In the third form, with @emph{key}, if @emph{value} is not given, the setting +for @emph{key} is displayed. If @emph{value} is present, @emph{key} is set to +@emph{value}. + +Possible values for @emph{key} are (run @code{tlmgr option showall} for +the definitive list): + +@verbatim + repository (default package repository), + formats (generate formats at installation or update time), + postcode (run postinst code blobs) + docfiles (install documentation files), + srcfiles (install source files), + backupdir (default directory for backups), + autobackup (number of backups to keep). + sys_bin (directory to which executables are linked by the path action) + sys_man (directory to which man pages are linked by the path action) + sys_info (directory to which Info files are linked by the path action) + desktop_integration (Windows-only: create Start menu shortcuts) + fileassocs (Windows-only: change file associations) + multiuser (Windows-only: install for all users) +@end verbatim + +One common use of @code{option} is to permanently change the installation to +get further updates from the Internet, after originally installing from +DVD. To do this, you can run + +@verbatim + tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet +@end verbatim + +The @code{install-tl} documentation has more information about the possible +values for @code{repository}. (For backward compatibility, @code{location} can +be used as a synonym for @code{repository}.) + +If @code{formats} is set (this is the default), then formats are regenerated +when either the engine or the format files have changed. Disable this +only when you know how and want to regenerate formats yourself whenever +needed (which is often, in practice). + +The @code{postcode} option controls execution of per-package +postinstallation action code. It is set by default, and again disabling +is not likely to be of interest except to developers doing debugging. + +The @code{docfiles} and @code{srcfiles} options control the installation of +their respective file groups (documentation, sources; grouping is +approximate) per package. By default both are enabled (1). Either or +both can be disabled (set to 0) if disk space is limited or for minimal +testing installations, etc. When disabled, the respective files are not +downloaded at all. + +The options @code{autobackup} and @code{backupdir} determine the defaults for +the actions @code{update}, @code{backup} and @code{restore}. These three actions +need a directory in which to read or write the backups. If +@code{--backupdir} is not specified on the command line, the @code{backupdir} +option value is used (if set). The TL installer sets @code{backupdir} to +@code{.../tlpkg/backups}, under the TL root installation directory. + +The @code{autobackup} option (de)activates automatic generation of backups. +Its value is an integer. If the @code{autobackup} value is @code{-1}, no +backups are removed. If @code{autobackup} is 0 or more, it specifies the +number of backups to keep. Thus, backups are disabled if the value is +0. In the @code{--clean} mode of the @code{backup} action this option also +specifies the number to be kept. The default value is 1, so that +backups are made, but only one backup is kept. + +To setup @code{autobackup} to @code{-1} on the command line, use: + +@verbatim + tlmgr option -- autobackup -1 +@end verbatim + +The @code{--} avoids having the @code{-1} treated as an option. (The @code{--} +stops parsing for options at the point where it appears; this is a +general feature across most Unix programs.) + +The @code{sys_bin}, @code{sys_man}, and @code{sys_info} options are used on Unix +systems to control the generation of links for executables, Info files +and man pages. See the @code{path} action for details. + +The last three options affect behavior on Windows installations. If +@code{desktop_integration} is set, then some packages will install items in +a sub-folder of the Start menu for @code{tlmgr gui}, documentation, etc. If +@code{fileassocs} is set, Windows file associations are made (see also the +@code{postaction} action). Finally, if @code{multiuser} is set, then adaptions +to the registry and the menus are done for all users on the system +instead of only the current user. All three options are on by default. + +@node tlmgr paper +@appendixsubsec paper + +@table @asis +@item @strong{paper [a4|letter]} +@anchor{tlmgr @strong{paper [a4|letter]}} + +@item @strong{<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [@emph{papersize}|--list]}> +@anchor{tlmgr @strong{<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [@emph{papersize}|--list]}>} + +@item @strong{paper --json} +@anchor{tlmgr @strong{paper --json}} + +@end table + +With no arguments (@code{tlmgr paper}), shows the default paper size setting +for all known programs. + +With one argument (e.g., @code{tlmgr paper a4}), sets the default for all +known programs to that paper size. + +With a program given as the first argument and no paper size specified +(e.g., @code{tlmgr dvips paper}), shows the default paper size for that +program. + +With a program given as the first argument and a paper size as the last +argument (e.g., @code{tlmgr dvips paper a4}), set the default for that +program to that paper size. + +With a program given as the first argument and @code{--list} given as the +last argument (e.g., @code{tlmgr dvips paper --list}), shows all valid paper +sizes for that program. The first size shown is the default. + +If @code{--json} is specified without other options, the paper setup is +dumped in JSON format. For the format of JSON output see +@code{tlpkg/doc/JSON-formats.txt}, format definition @code{TLPAPER}. + +Incidentally, this syntax of having a specific program name before the +@code{paper} keyword is unusual. It is inherited from the longstanding +@code{texconfig} script, which supports other configuration settings for +some programs, notably @code{dvips}. @code{tlmgr} does not support those extra +settings. + +@node tlmgr path +@appendixsubsec path + +@table @asis +@item @strong{path [--w32mode=user|admin] add} +@anchor{tlmgr @strong{path [--w32mode=user|admin] add}} + +@item @strong{path [--w32mode=user|admin] remove} +@anchor{tlmgr @strong{path [--w32mode=user|admin] remove}} + +On Unix, adds or removes symlinks for executables, man pages, and info +pages in the system directories specified by the respective options (see +the @ref{tlmgr option,, option} description above). Does not change any initialization +files, either system or personal. Furthermore, any executables added or +removed by future updates are not taken care of automatically; this +command must be rerun as needed. + +On Windows, the registry part where the binary directory is added or +removed is determined in the following way: + +If the user has admin rights, and the option @code{--w32mode} is not given, +the setting @emph{w32_multi_user} determines the location (i.e., if it is +on then the system path, otherwise the user path is changed). + +If the user has admin rights, and the option @code{--w32mode} is given, this +option determines the path to be adjusted. + +If the user does not have admin rights, and the option @code{--w32mode} +is not given, and the setting @emph{w32_multi_user} is off, the user path +is changed, while if the setting @emph{w32_multi_user} is on, a warning is +issued that the caller does not have enough privileges. + +If the user does not have admin rights, and the option @code{--w32mode} +is given, it must be @code{user} and the user path will be adjusted. If a +user without admin rights uses the option @code{--w32mode admin} a warning +is issued that the caller does not have enough privileges. + +@end table + +@node tlmgr pinning +@appendixsubsec pinning + +The @code{pinning} action manages the pinning file, see @ref{tlmgr Pinning,, Pinning} below. + +@table @asis +@item @code{pinning show} +@anchor{tlmgr @code{pinning show}} + +Shows the current pinning data. + +@item @code{pinning add} @emph{repo} @emph{pkgglob}... +@anchor{tlmgr @code{pinning add} @emph{repo} @emph{pkgglob}...} + +Pins the packages matching the @emph{pkgglob}(s) to the repository +@emph{repo}. + +@item @code{pinning remove} @emph{repo} @emph{pkgglob}... +@anchor{tlmgr @code{pinning remove} @emph{repo} @emph{pkgglob}...} + +Any packages recorded in the pinning file matching the s for +the given repository @emph{repo} are removed. + +@item @code{pinning remove @emph{repo} --all} +@anchor{tlmgr @code{pinning remove @emph{repo} --all}} + +Remove all pinning data for repository @emph{repo}. + +@end table + +@node tlmgr platform +@appendixsubsec platform + +@table @asis +@item @strong{platform list|add|remove @emph{platform}...} +@anchor{tlmgr @strong{platform list|add|remove @emph{platform}...}} + +@item @strong{platform set @emph{platform}} +@anchor{tlmgr @strong{platform set @emph{platform}}} + +@item @strong{platform set auto} +@anchor{tlmgr @strong{platform set auto}} + +@code{platform list} lists the TeX Live names of all the platforms +(a.k.a. architectures), (@code{i386-linux}, ...) available at the package +repository. + +@code{platform add} @emph{platform}... adds the executables for each given platform +@emph{platform} to the installation from the repository. + +@code{platform remove} @emph{platform}... removes the executables for each given +platform @emph{platform} from the installation, but keeps the currently +running platform in any case. + +@code{platform set} @emph{platform} switches TeX Live to always use the given +platform instead of auto detection. + +@code{platform set auto} switches TeX Live to auto detection mode for platform. + +Platform detection is needed to select the proper @code{xz} and +@code{wget} binaries that are shipped with TeX Live. + +@code{arch} is a synonym for @code{platform}. + +Options: + +@table @asis +@item @strong{--dry-run} +@anchor{tlmgr @strong{--dry-run} 2} + +Nothing is actually installed; instead, the actions to be performed are +written to the terminal. + +@end table + +@end table + +@node tlmgr postaction +@appendixsubsec postaction + +@table @asis +@item @strong{postaction [@emph{option}...] install [shortcut|fileassoc|script] [@emph{pkg}...]} +@anchor{tlmgr @strong{postaction [@emph{option}...] install [shortcut|fileassoc|script] [@emph{pkg}...]}} + +@item @strong{postaction [@emph{option}...] remove [shortcut|fileassoc|script] [@emph{pkg}...]} +@anchor{tlmgr @strong{postaction [@emph{option}...] remove [shortcut|fileassoc|script] [@emph{pkg}...]}} + +Carry out the postaction @code{shortcut}, @code{fileassoc}, or @code{script} given +as the second required argument in install or remove mode (which is the +first required argument), for either the packages given on the command +line, or for all if @code{--all} is given. + +Options: + +@table @asis +@item @strong{--w32mode=[user|admin]} +@anchor{tlmgr @strong{--w32mode=[user|admin]}} + +If the option @code{--w32mode} is given the value @code{user}, all actions will +only be carried out in the user-accessible parts of the +registry/filesystem, while the value @code{admin} selects the system-wide +parts of the registry for the file associations. If you do not have +enough permissions, using @code{--w32mode=admin} will not succeed. + +@item @strong{--fileassocmode=[1|2]} +@anchor{tlmgr @strong{--fileassocmode=[1|2]}} + +@code{--fileassocmode} specifies the action for file associations. If it is +set to 1 (the default), only new associations are added; if it is set to +2, all associations are set to the TeX Live programs. (See also +@code{option fileassocs}.) + +@item @strong{--all} +@anchor{tlmgr @strong{--all} 1} + +Carry out the postactions for all packages + +@end table + +@end table + +@node tlmgr print-platform +@appendixsubsec print-platform + +Print the TeX Live identifier for the detected platform +(hardware/operating system) combination to standard output, and exit. +@code{--print-arch} is a synonym. + +@node tlmgr print-platform-info +@appendixsubsec print-platform-info + +Print the TeX Live platform identifier, TL platform long name, and +original output from guess. + +@node tlmgr remove [@emph{option}...] @emph{pkg}... +@appendixsubsec remove [@emph{option}...] @emph{pkg}... + +Remove each @emph{pkg} specified. Removing a collection removes all package +dependencies (unless @code{--no-depends} is specified), but not any +collection dependencies of that collection. However, when removing a +package, dependencies are never removed. Options: + +@table @asis +@item @strong{--all} +@anchor{tlmgr @strong{--all} 2} + +Uninstalls all of TeX Live, asking for confirmation unless @code{--force} is +also specified. + +@item @strong{--backup} +@anchor{tlmgr @strong{--backup}} + +@item @strong{--backupdir} @emph{directory} +@anchor{tlmgr @strong{--backupdir} @emph{directory} 1} + +These options behave just as with the @ref{tlmgr update +[@emph{option}...] [...], update,, update} action (q.v.), except they apply to making +backups of packages before they are removed. The default is to make +such a backup, that is, to save a copy of packages before removal. + +The @ref{tlmgr restore,, restore} action explains how to restore from a backup. + +@item @strong{--no-depends} +@anchor{tlmgr @strong{--no-depends} 1} + +Do not remove dependent packages. + +@item @strong{--no-depends-at-all} +@anchor{tlmgr @strong{--no-depends-at-all} 1} + +See above under @ref{tlmgr install [@emph{option}...] @emph{pkg}..., install, install} (and beware). + +@item @strong{--force} +@anchor{tlmgr @strong{--force} 1} + +By default, removal of a package or collection that is a dependency of +another collection or scheme is not allowed. With this option, the +package will be removed unconditionally. Use with care. + +A package that has been removed using the @code{--force} option because it +is still listed in an installed collection or scheme will not be +updated, and will be mentioned as @code{forcibly removed} in the output of +@code{tlmgr update --list}. + +@item @strong{--dry-run} +@anchor{tlmgr @strong{--dry-run} 3} + +Nothing is actually removed; instead, the actions to be performed are +written to the terminal. + +@end table + +This action does not automatically remove symlinks to executables from +system directories; you need to run @code{tlmgr path remove} (@ref{tlmgr path,, path}) +yourself if you are using this feature and want stale symlinks removed. + +@node tlmgr repository +@appendixsubsec repository + +@table @asis +@item @strong{repository list} +@anchor{tlmgr @strong{repository list}} + +@item @strong{repository list @emph{path|url|tag}} +@anchor{tlmgr @strong{repository list @emph{path|url|tag}}} + +@item @strong{repository add @emph{path} [@emph{tag}]} +@anchor{tlmgr @strong{repository add @emph{path} [@emph{tag}]}} + +@item @strong{repository remove @emph{path|tag}} +@anchor{tlmgr @strong{repository remove @emph{path|tag}}} + +@item @strong{repository set @emph{path}[#@emph{tag}] [@emph{path}[#@emph{tag}] ...]} +@anchor{tlmgr @strong{repository set @emph{path}[#@emph{tag}] [@emph{path}[#@emph{tag}] ...]}} + +@item @strong{repository status} +@anchor{tlmgr @strong{repository status}} + +This action manages the list of repositories. See @ref{,,, MULTIPLE_REPOSITORIES} below for detailed explanations. + +The first form, @code{repository list}, lists all configured repositories +and the respective tags if set. If a path, url, or tag is given after +the @code{list} keyword, it is interpreted as the source from which to +initialize a TL database and lists the contained packages. This can also +be an otherwise-unused repository, either local or remote. If the option +@code{--with-platforms} is specified in addition, for each package the +available platforms (if any) are also listed. + +The form @code{repository add} adds a repository (optionally attaching a +tag) to the list of repositories, while @code{repository remove} removes a +repository, either by full path/url, or by tag. + +The form @code{repository set} sets the list of available repositories to +the items given on the command line, overwriting previous settings. + +The form @code{repository status} reports the verification status of the +loaded repositories with the format of one repository per line +with fields separated by a single space: + +@table @asis +@item The tag (which can be the same as the url); +@anchor{tlmgr The tag (which can be the same as the url);} + += the url; + += iff machine-readable output is specified, the verification code (a +number); + += a textual description of the verification status, as the last field +extending to the end of line. + +@end table + +That is, in normal (not machine-readable) output, the third field +(numeric verification status) is not present. + +In all cases, one of the repositories must be tagged as @code{main}; +otherwise, all operations will fail! + +@end table + +@node tlmgr restore +@appendixsubsec restore + +@table @asis +@item @strong{restore [@emph{option}...] @emph{pkg} [@emph{rev}]} +@anchor{tlmgr @strong{restore [@emph{option}...] @emph{pkg} [@emph{rev}]}} + +@item @strong{restore [@emph{option}...] --all} +@anchor{tlmgr @strong{restore [@emph{option}...] --all}} + +Restore a package from a previously-made backup. + +If @code{--all} is given, try to restore the latest revision of all +package backups found in the backup directory. + +Otherwise, if neither @emph{pkg} nor @emph{rev} are given, list the available +backup revisions for all packages. With @emph{pkg} given but no @emph{rev}, +list all available backup revisions of @emph{pkg}. + +When listing available packages, @code{tlmgr} shows the revision, and in +parenthesis the creation time if available (in format yyyy-mm-dd hh:mm). + +If (and only if) both @emph{pkg} and a valid revision number @emph{rev} are +specified, try to restore the package from the specified backup. + +Options: + +@table @asis +@item @strong{--all} +@anchor{tlmgr @strong{--all} 3} + +Try to restore the latest revision of all package backups found in the +backup directory. Additional non-option arguments (like @emph{pkg}) are not +allowed. + +@item @strong{--backupdir} @emph{directory} +@anchor{tlmgr @strong{--backupdir} @emph{directory} 2} + +Specify the directory where the backups are to be found. If not given it +will be taken from the configuration setting in the TLPDB. + +@item @strong{--dry-run} +@anchor{tlmgr @strong{--dry-run} 4} + +Nothing is actually restored; instead, the actions to be performed are +written to the terminal. + +@item @strong{--force} +@anchor{tlmgr @strong{--force} 2} + +Don't ask questions. + +@item @strong{--json} +@anchor{tlmgr @strong{--json} 2} + +When listing backups, the option @code{--json} turn on JSON output. +The format is an array of JSON objects (@code{name}, @code{rev}, @code{date}). +For details see @code{tlpkg/doc/JSON-formats.txt}, format definition: @code{TLBACKUPS}. +If both @code{--json} and @code{--data} are given, @code{--json} takes precedence. + +@end table + +@end table + +@node tlmgr search +@appendixsubsec search + +@table @asis +@item @strong{search [@emph{option}...] @emph{what}} +@anchor{tlmgr @strong{search [@emph{option}...] @emph{what}}} + +@item @strong{search [@emph{option}...] --file @emph{what}} +@anchor{tlmgr @strong{search [@emph{option}...] --file @emph{what}}} + +@item @strong{search [@emph{option}...] --all @emph{what}} +@anchor{tlmgr @strong{search [@emph{option}...] --all @emph{what}}} + +By default, search the names, short descriptions, and long descriptions +of all locally installed packages for the argument @emph{what}, interpreted +as a (Perl) regular expression. + +Options: + +@table @asis +@item @strong{--file} +@anchor{tlmgr @strong{--file} 1} + +List all filenames containing @emph{what}. + +@item @strong{--all} +@anchor{tlmgr @strong{--all} 4} + +Search everything: package names, descriptions and filenames. + +@item @strong{--global} +@anchor{tlmgr @strong{--global}} + +Search the TeX Live Database of the installation medium, instead of the +local installation. + +@item @strong{--word} +@anchor{tlmgr @strong{--word}} + +Restrict the search of package names and descriptions (but not +filenames) to match only full words. For example, searching for +@code{table} with this option will not output packages containing the word +@code{tables} (unless they also contain the word @code{table} on its own). + +@end table + +@end table + +@node tlmgr shell +@appendixsubsec shell + +Starts an interactive mode, where tlmgr prompts for commands. This can +be used directly, or for scripting. The first line of output is +@code{protocol} @emph{n}, where @emph{n} is an unsigned number identifying the +protocol version (currently 1). + +In general, tlmgr actions that can be given on the command line +translate to commands in this shell mode. For example, you can say +@code{update --list} to see what would be updated. The TLPDB is loaded the +first time it is needed (not at the beginning), and used for the rest of +the session. + +Besides these actions, a few commands are specific to shell mode: + +@table @asis +@item protocol +@anchor{tlmgr protocol} + +Print @code{protocol @emph{n}}, the current protocol version. + +@item help +@anchor{tlmgr help 1} + +Print pointers to this documentation. + +@item version +@anchor{tlmgr version 1} + +Print tlmgr version information. + +@item quit, end, bye, byebye, EOF +@anchor{tlmgr quit@comma{} end@comma{} bye@comma{} byebye@comma{} EOF} + +Exit. + +@item restart +@anchor{tlmgr restart} + +Restart @code{tlmgr shell} with the original command line; most useful when +developing @code{tlmgr}. + +@item load [local|remote] +@anchor{tlmgr load [local|remote]} + +Explicitly load the local or remote, respectively, TLPDB. + +@item save +@anchor{tlmgr save} + +Save the local TLPDB, presumably after other operations have changed it. + +@item get [@emph{var}] =item set [@emph{var} [@emph{val}]] +@anchor{tlmgr get [@emph{var}] =item set [@emph{var} [@emph{val}]]} + +Get the value of @emph{var}, or set it to @emph{val}. Possible @emph{var} names: +@code{debug-translation}, @code{machine-readable}, @code{no-execute-actions}, +@code{require-verification}, @code{verify-downloads}, @code{repository}, and +@code{prompt}. All except @code{repository} and @code{prompt} are booleans, taking +values 0 and 1, and behave like the corresponding command line option. +The @code{repository} variable takes a string, and sets the remote +repository location. The @code{prompt} variable takes a string, and sets the +current default prompt. + +If @emph{var} or then @emph{val} is not specified, it is prompted for. + +@end table + +@node tlmgr show +@appendixsubsec show + +Synonym for @ref{tlmgr info,, info}. + +@node tlmgr uninstall +@appendixsubsec uninstall + +Synonym for @ref{tlmgr remove [@emph{option}...] @emph{pkg}..., remove, remove}. + +@node tlmgr update [@emph{option}...] [@emph{pkg}...] +@appendixsubsec update [@emph{option}...] [@emph{pkg}...] + +Updates the packages given as arguments to the latest version available +at the installation source. Either @code{--all} or at least one @emph{pkg} name +must be specified. Options: + +@table @asis +@item @strong{--all} +@anchor{tlmgr @strong{--all} 5} + +Update all installed packages except for @code{tlmgr} itself. If updates to +@code{tlmgr} itself are present, this gives an error, unless also the option +@code{--force} or @code{--self} is given. (See below.) + +In addition to updating the installed packages, during the update of a +collection the local installation is (by default) synchronized to the +status of the collection on the server, for both additions and removals. + +This means that if a package has been removed on the server (and thus +has also been removed from the respective collection), @code{tlmgr} will +remove the package in the local installation. This is called +``auto-remove'' and is announced as such when using the option +@code{--list}. This auto-removal can be suppressed using the option +@code{--no-auto-remove} (not recommended, see option description). + +Analogously, if a package has been added to a collection on the server +that is also installed locally, it will be added to the local +installation. This is called ``auto-install'' and is announced as such +when using the option @code{--list}. This auto-installation can be +suppressed using the option @code{--no-auto-install} (also not recommended). + +An exception to the collection dependency checks (including the +auto-installation of packages just mentioned) are those that have been +``forcibly removed'' by you, that is, you called @code{tlmgr remove --force} +on them. (See the @code{remove} action documentation.) To reinstall any +such forcibly removed packages use @code{--reinstall-forcibly-removed}. + +To reiterate: automatic removals and additions are entirely determined +by comparison of collections. Thus, if you manually install an +individual package @code{foo} which is later removed from the server, +@code{tlmgr} will not notice and will not remove it locally. (It has to be +this way, without major rearchitecture work, because the tlpdb does not +record the repository from which packages come from.) + +If you want to exclude some packages from the current update run (e.g., +due to a slow link), see the @code{--exclude} option below. + +@item @strong{--self} +@anchor{tlmgr @strong{--self}} + +Update @code{tlmgr} itself (that is, the infrastructure packages) if updates +to it are present. On Windows this includes updates to the private Perl +interpreter shipped inside TeX Live. + +If this option is given together with either @code{--all} or a list of +packages, then @code{tlmgr} will be updated first and, if this update +succeeds, the new version will be restarted to complete the rest of the +updates. + +In short: + +@verbatim + tlmgr update --self # update infrastructure only + tlmgr update --self --all # update infrastructure and all packages + tlmgr update --force --all # update all packages but *not* infrastructure + # ... this last at your own risk, not recommended! +@end verbatim + +@item @strong{--dry-run} +@anchor{tlmgr @strong{--dry-run} 5} + +Nothing is actually installed; instead, the actions to be performed are +written to the terminal. This is a more detailed report than @code{--list}. + +@item @strong{--list} [@emph{pkg}] +@anchor{tlmgr @strong{--list} [@emph{pkg}]} + +Concisely list the packages which would be updated, newly installed, or +removed, without actually changing anything. +If @code{--all} is also given, all available updates are listed. +If @code{--self} is given, but not @code{--all}, only updates to the +critical packages (tlmgr, texlive infrastructure, perl on Windows, etc.) +are listed. +If neither @code{--all} nor @code{--self} is given, and in addition no @emph{pkg} is +given, then @code{--all} is assumed (thus, @code{tlmgr update --list} is the +same as @code{tlmgr update --list --all}). +If neither @code{--all} nor @code{--self} is given, but specific package names are +given, those packages are checked for updates. + +@item @strong{--exclude} @emph{pkg} +@anchor{tlmgr @strong{--exclude} @emph{pkg}} + +Exclude @emph{pkg} from the update process. If this option is given more +than once, its arguments accumulate. + +An argument @emph{pkg} excludes both the package @emph{pkg} itself and all +its related platform-specific packages @emph{pkg.ARCH}. For example, + +@verbatim + tlmgr update --all --exclude a2ping +@end verbatim + +will not update @code{a2ping}, @code{a2ping.i386-linux}, or +any other @code{a2ping.}@emph{ARCH} package. + +If this option specifies a package that would otherwise be a candidate +for auto-installation, auto-removal, or reinstallation of a forcibly +removed package, @code{tlmgr} quits with an error message. Excludes are not +supported in these circumstances. + +This option can also be set permanently in the tlmgr config file with +the key @code{update-exclude}. + +@item @strong{--no-auto-remove} [@emph{pkg}...] +@anchor{tlmgr @strong{--no-auto-remove} [@emph{pkg}...]} + +By default, @code{tlmgr} tries to remove packages in an existing collection +which have disappeared on the server, as described above under @code{--all}. +This option prevents such removals, either for all packages (with +@code{--all}), or for just the given @emph{pkg} names. This can lead to an +inconsistent TeX installation, since packages are not infrequently +renamed or replaced by their authors. Therefore this is not recommended. + +@item @strong{--no-auto-install} [@emph{pkg}...] +@anchor{tlmgr @strong{--no-auto-install} [@emph{pkg}...]} + +Under normal circumstances @code{tlmgr} will install packages which are new +on the server, as described above under @code{--all}. This option prevents +any such automatic installation, either for all packages (with +@code{--all}), or the given @emph{pkg} names. + +Furthermore, after the @code{tlmgr} run using this has finished, the +packages that would have been auto-installed @emph{will be considered as +forcibly removed}. So, if @code{foobar} is the only new package on the +server, then + +@verbatim + tlmgr update --all --no-auto-install +@end verbatim + +is equivalent to + +@verbatim + tlmgr update --all + tlmgr remove --force foobar +@end verbatim + +Again, since packages are sometimes renamed or replaced, using this +option is not recommended. + +@item @strong{--reinstall-forcibly-removed} +@anchor{tlmgr @strong{--reinstall-forcibly-removed}} + +Under normal circumstances @code{tlmgr} will not install packages that have +been forcibly removed by the user; that is, removed with @code{remove +--force}, or whose installation was prohibited by @code{--no-auto-install} +during an earlier update. + +This option makes @code{tlmgr} ignore the forcible removals and re-install +all such packages. This can be used to completely synchronize an +installation with the server's idea of what is available: + +@verbatim + tlmgr update --reinstall-forcibly-removed --all +@end verbatim + +@item @strong{--backup} +@anchor{tlmgr @strong{--backup} 1} + +@item @strong{--backupdir} @emph{directory} +@anchor{tlmgr @strong{--backupdir} @emph{directory} 3} + +These two options control the creation of backups of packages @emph{before} +updating; that is, backing up packages as currently installed. If +neither option is given, no backup will made. If @code{--backupdir} is +given and specifies a writable directory then a backup will be made in +that location. If only @code{--backup} is given, then a backup will be made +to the directory previously set via the @ref{tlmgr option,, option} action (see +below). If both are given then a backup will be made to the specified +@emph{directory}. + +You can also set options via the @ref{tlmgr option,, option} action to automatically make +backups for all packages, and/or keep only a certain number of backups. + +@code{tlmgr} always makes a temporary backup when updating packages, in case +of download or other failure during an update. In contrast, the purpose +of this @code{--backup} option is to save a persistent backup in case the +actual @emph{content} of the update causes problems, e.g., introduces an TeX +incompatibility. + +The @ref{tlmgr restore,, restore} action explains how to restore from a backup. + +@item @strong{--no-depends} +@anchor{tlmgr @strong{--no-depends} 2} + +If you call for updating a package normally all depending packages +will also be checked for updates and updated if necessary. This switch +suppresses this behavior. + +@item @strong{--no-depends-at-all} +@anchor{tlmgr @strong{--no-depends-at-all} 2} + +See above under @ref{tlmgr install [@emph{option}...] @emph{pkg}..., install, install} (and beware). + +@item @strong{--force} +@anchor{tlmgr @strong{--force} 3} + +Force update of normal packages, without updating @code{tlmgr} itself +(unless the @code{--self} option is also given). Not recommended. + +Also, @code{update --list} is still performed regardless of this option. + +@end table + +If the package on the server is older than the package already installed +(e.g., if the selected mirror is out of date), @code{tlmgr} does not +downgrade. Also, packages for uninstalled platforms are not installed. + +@code{tlmgr} saves a copy of the @code{texlive.tlpdb} file used for an update +with a suffix representing the repository url, as in +@code{tlpkg/texlive.tlpdb.}@emph{long-hash-string}. These can be useful for +fallback information, but if you don't like them accumulating (e.g., +@code{mirror.ctan.org} resolves to many different hosts, each resulting in +a possibly different hash), it's harmless to delete them. + +This action does not automatically add or remove new symlinks in system +directories; you need to run @code{tlmgr} @ref{tlmgr path,, path} yourself if you are using +this feature and want new symlinks added. + +@node tlmgr CONFIGURATION FILE FOR TLMGR +@appendixsec CONFIGURATION FILE FOR TLMGR + +@code{tlmgr} reads two configuration files: one is system-wide, in +@code{TEXMFSYSCONFIG/tlmgr/config}, and the other is user-specific, in +@code{TEXMFCONFIG/tlmgr/config}. The user-specific one is the default for +the @code{conf tlmgr} action. (Run @code{kpsewhich +-var-value=TEXMFSYSCONFIG} or @code{... TEXMFCONFIG ...} to see the actual +directory names.) + +A few defaults corresponding to command-line options can be set in these +configuration files. In addition, the system-wide file can contain a +directive to restrict the allowed actions. + +In these config files, empty lines and lines starting with # are +ignored. All other lines must look like: + +@verbatim + key = value +@end verbatim + +where the spaces are optional but the @code{=} is required. + +The allowed keys are: + +@table @asis +@item @code{auto-remove}, value 0 or 1 (default 1), same as command-line option. +@anchor{tlmgr @code{auto-remove}@comma{} value 0 or 1 (default 1)@comma{} same as command-line option.} + +@item @code{gui-expertmode}, value 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings. +@anchor{tlmgr @code{gui-expertmode}@comma{} value 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings.} + +@item @code{gui-lang} @emph{llcode}, with a language code value as with the command-line option. +@anchor{tlmgr @code{gui-lang} @emph{llcode}@comma{} with a language code value as with the command-line option.} + +@item @code{no-checksums}, value 0 or 1 (default 0, see below). +@anchor{tlmgr @code{no-checksums}@comma{} value 0 or 1 (default 0@comma{} see below).} + +@item @code{persistent-downloads}, value 0 or 1 (default 1), same as command-line option. +@anchor{tlmgr @code{persistent-downloads}@comma{} value 0 or 1 (default 1)@comma{} same as command-line option.} + +@item @code{require-verification}, value 0 or 1 (default 0), same as command-line option. +@anchor{tlmgr @code{require-verification}@comma{} value 0 or 1 (default 0)@comma{} same as command-line option.} + +@item @code{update-exclude}, value: comma-separated list of packages (no space allowed). Same as the command line option @code{--exclude} for the action @code{update}. +@anchor{tlmgr @code{update-exclude}@comma{} value: comma-separated list of packages (no space allowed). Same as the command line option @code{--exclude} for the action @code{update}.} + +@item @code{verify-downloads}, value 0 or 1 (default 1), same as command-line option. +@anchor{tlmgr @code{verify-downloads}@comma{} value 0 or 1 (default 1)@comma{} same as command-line option.} + +@end table + +The system-wide config file can contain one additional key: + +@table @asis +@item @code{allowed-actions} @emph{action1} [,@emph{action},...] The value is a comma-separated list of @code{tlmgr} actions which are allowed to be executed when @code{tlmgr} is invoked in system mode (that is, without @code{--usermode}). +@anchor{tlmgr @code{allowed-actions} @emph{action1} [@comma{}@emph{action}@comma{}...] The value is a comma-separated list of @code{tlmgr} actions which are allowed to be executed when @code{tlmgr} is invoked in system mode (that is@comma{} without @code{--usermode}).} + +This allows distributors to include the @code{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. + +@end table + +The @code{no-checksums} key needs more explanation. By default, package +checksums computed and stored on the server (in the TLPDB) are compared +to checksums computed locally after downloading. @code{no-checksums} +disables this process. + +The checksum algorithm is SHA-512. Your system must have one of (looked +for in this order) the Perl @code{Digest::SHA} module, the @code{openssl} +program (@url{https://openssl.org}), the @code{sha512sum} program (from GNU +Coreutils, @url{https://www.gnu.org/software/coreutils}), or finally the +@code{shasum} program (just to support old Macs). If none of these are +available, a warning is issued and @code{tlmgr} proceeds without checking +checksums. (Incidentally, other SHA implementations, such as the pure +Perl and pure Lua modules, are much too slow to be usable in our +context.) @code{no-checksums} avoids the warning. + +@node tlmgr CRYPTOGRAPHIC VERIFICATION +@appendixsec CRYPTOGRAPHIC VERIFICATION + +@code{tlmgr} and @code{install-tl} perform cryptographic verification if +possible. If verification is performed and successful, the programs +report @code{(verified)} after loading the TLPDB; otherwise, they report +@code{(not verified)}. But either way, by default the installation and/or +updates proceed normally. + +If a program named @code{gpg} is available (that is, found in @code{PATH}), by +default cryptographic signatures will be checked: we require the main +repository be signed, but not any additional repositories. If @code{gpg} is +not available, by default signatures are not checked and no verification +is carried out, but @code{tlmgr} still proceeds normally. + +The behavior of the verification can be controlled by the command line +and config file option @code{verify-repo} which takes one of the following +values: @code{none}, @code{main}, or @code{all}. With @code{none}, no verification +whatsoever is attempted. With @code{main} (the default) verification is +required only for the main repository, and only if @code{gpg} is available; +though attempted for all, missing signatures of subsidiary repositories +will not result in an error. Finally, in the case of @code{all}, @code{gpg} +must be available and all repositories need to be signed. + +In all cases, if a signature is checked and fails to verify, an error +is raised. + +Cryptographic verification requires checksum checking (described just +above) to succeed, and a working GnuPG (@code{gpg}) program (see below for +search method). Then, unless cryptographic verification has been +disabled, a signature file (@code{texlive.tlpdb.*.asc}) of the checksum file +is downloaded and the signature verified. The signature is created by +the TeX Live Distribution GPG key 0x0D5E5D9106BAB6BC, which in turn is +signed by Karl Berry's key 0x0716748A30D155AD and +Norbert Preining's key 0x6CACA448860CDC13. All +of these keys are obtainable from the standard key servers. + +Additional trusted keys can be added using the @code{key} action. + +@menu +* tlmgr Configuration of GnuPG invocation:: +@end menu + +@node tlmgr Configuration of GnuPG invocation +@appendixsubsec Configuration of GnuPG invocation + +The executable used for GnuPG is searched as follows: If the environment +variable @code{TL_GNUPG} is set, it is tested and used; otherwise @code{gpg} is +checked; finally @code{gpg2} is checked. + +Further adaptation of the @code{gpg} invocation can be made using the two +environment variables @code{TL_GNUPGHOME}, which is passed to @code{gpg} as the +value for @code{--homedir}, and @code{TL_GNUPGARGS}, which replaces the default +options @code{--no-secmem-warning --no-permission-warning}. + +@node tlmgr USER MODE +@appendixsec USER MODE + +@code{tlmgr} provides a restricted way, called ``user mode'', to manage +arbitrary texmf trees in the same way as the main installation. For +example, this allows people without write permissions on the +installation location to update/install packages into a tree of their +own. + +@code{tlmgr} is switched into user mode with the command line option +@code{--usermode}. It does not switch automatically, nor is there any +configuration file setting for it. Thus, this option has to be +explicitly given every time user mode is to be activated. + +This mode of @code{tlmgr} works on a user tree, by default the value of the +@code{TEXMFHOME} variable. This can be overridden with the command line +option @code{--usertree}. In the following when we speak of the user tree +we mean either @code{TEXMFHOME} or the one given on the command line. + +Not all actions are allowed in user mode; @code{tlmgr} will warn you and not +carry out any problematic actions. Currently not supported (and +probably will never be) is the @code{platform} action. The @code{gui} action is +currently not supported, but may be in a future release. + +Some @code{tlmgr} actions don't need any write permissions and thus work the +same in user mode and normal mode. Currently these are: @code{check}, +@code{help}, @code{list}, @code{print-platform}, @code{print-platform-info}, @code{search}, +@code{show}, @code{version}. + +On the other hand, most of the actions dealing with package management +do need write permissions, and thus behave differently in user mode, as +described below: @code{install}, @code{update}, @code{remove}, @code{option}, @code{paper}, +@code{generate}, @code{backup}, @code{restore}, @code{uninstall}, @code{symlinks}. + +Before using @code{tlmgr} in user mode, you have to set up the user tree +with the @code{init-usertree} action. This creates @emph{usertree}@code{/web2c} and +@emph{usertree}@code{/tlpkg/tlpobj}, and a minimal +@emph{usertree}@code{/tlpkg/texlive.tlpdb}. At that point, you can tell +@code{tlmgr} to do the (supported) actions by adding the @code{--usermode} +command line option. + +In user mode the file @emph{usertree}@code{/tlpkg/texlive.tlpdb} contains only +the packages that have been installed into the user tree using @code{tlmgr}, +plus additional options from the ``virtual'' package +@code{00texlive.installation} (similar to the main installation's +@code{texlive.tlpdb}). + +All actions on packages in user mode can only be carried out on packages +that are known as @code{relocatable}. This excludes all packages containing +executables and a few other core packages. Of the 2500 or so packages +currently in TeX Live the vast majority are relocatable and can be +installed into a user tree. + +Description of changes of actions in user mode: + +@menu +* tlmgr User mode install:: +* tlmgr User mode backup@comma{} restore@comma{} remove@comma{} update:: +* tlmgr User mode generate@comma{} option@comma{} paper:: +@end menu + +@node tlmgr User mode install +@appendixsubsec User mode install + +In user mode, the @code{install} action checks that the package and all +dependencies are all either relocated or already installed in the system +installation. If this is the case, it unpacks all containers to be +installed into the user tree (to repeat, that's either @code{TEXMFHOME} or +the value of @code{--usertree}) and add the respective packages to the user +tree's @code{texlive.tlpdb} (creating it if need be). + +Currently installing a collection in user mode installs all dependent +packages, but in contrast to normal mode, does @emph{not} install dependent +collections. For example, in normal mode @code{tlmgr install +collection-context} would install @code{collection-basic} and other +collections, while in user mode, @emph{only} the packages mentioned in +@code{collection-context} are installed. + +If a package shipping map files is installed in user mode, a backup of +the user's @code{updmap.cfg} in @code{USERTREE/web2c/} is made, and then this file +regenerated from the list of installed packages. + +@node tlmgr User mode backup@comma{} restore@comma{} remove@comma{} update +@appendixsubsec User mode backup, restore, remove, update + +In user mode, these actions check that all packages to be acted on are +installed in the user tree before proceeding; otherwise, they behave +just as in normal mode. + +@node tlmgr User mode generate@comma{} option@comma{} paper +@appendixsubsec User mode generate, option, paper + +In user mode, these actions operate only on the user tree's +configuration files and/or @code{texlive.tlpdb}. +creates configuration files in user tree + +@node tlmgr MULTIPLE REPOSITORIES +@appendixsec MULTIPLE REPOSITORIES + +The main TeX Live repository contains a vast array of packages. +Nevertheless, additional local repositories can be useful to provide +locally-installed resources, such as proprietary fonts and house styles. +Also, alternative package repositories distribute packages that cannot +or should not be included in TeX Live, for whatever reason. + +The simplest and most reliable method is to temporarily set the +installation source to any repository (with the @code{-repository} or +@code{option repository} command line options), and perform your operations. + +When you are using multiple repositories over a sustained length of +time, however, explicitly switching between them becomes inconvenient. +Thus, it's possible to tell @code{tlmgr} about additional repositories you +want to use. The basic command is @code{tlmgr repository add}. The rest of +this section explains further. + +When using multiple repositories, one of them has to be set as the main +repository, which distributes most of the installed packages. When you +switch from a single repository installation to a multiple repository +installation, the previous sole repository will be set as the main +repository. + +By default, even if multiple repositories are configured, packages are +@emph{still} @emph{only} installed from the main repository. Thus, simply +adding a second repository does not actually enable installation of +anything from there. You also have to specify which packages should be +taken from the new repository, by specifying so-called ``pinning'' +rules, described next. + +@menu +* tlmgr Pinning:: +@end menu + +@node tlmgr Pinning +@appendixsubsec Pinning + +When a package @code{foo} is pinned to a repository, a package @code{foo} in any +other repository, even if it has a higher revision number, will not be +considered an installable candidate. + +As mentioned above, by default everything is pinned to the main +repository. Let's now go through an example of setting up a second +repository and enabling updates of a package from it. + +First, check that we have support for multiple repositories, and have +only one enabled (as is the case by default): + +@verbatim + $ tlmgr repository list + List of repositories (with tags if set): + /var/www/norbert/tlnet +@end verbatim + +Ok. Let's add the @code{tlcontrib} repository (this is a real +repository hosted at @url{http://contrib.texlive.info}) with the tag @code{tlcontrib}: + +@verbatim + $ tlmgr repository add http://contrib.texlive.info/current tlcontrib +@end verbatim + +Check the repository list again: + +@verbatim + $ tlmgr repository list + List of repositories (with tags if set): + http://contrib.texlive.info/current (tlcontrib) + /var/www/norbert/tlnet (main) +@end verbatim + +Now we specify a pinning entry to get the package @code{classico} from +@code{tlcontrib}: + +@verbatim + $ tlmgr pinning add tlcontrib classico +@end verbatim + +Check that we can find @code{classico}: + +@verbatim + $ tlmgr show classico + package: classico + ... + shortdesc: URW Classico fonts + ... +@end verbatim + +- install @code{classico}: + +@verbatim + $ tlmgr install classico + tlmgr: package repositories: + ... + [1/1, ??:??/??:??] install: classico @tlcontrib [737k] +@end verbatim + +In the output here you can see that the @code{classico} package has been +installed from the @code{tlcontrib} repository (@code{@@tlcontrib}). + +Finally, @code{tlmgr pinning} also supports removing certain or all packages +from a given repository: + +@verbatim + $ tlmgr pinning remove tlcontrib classico # remove just classico + $ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib +@end verbatim + +A summary of @code{tlmgr pinning} actions is given above. + +@node tlmgr GUI FOR TLMGR +@appendixsec GUI FOR TLMGR + +The graphical user interface for @code{tlmgr} requires Perl/Tk +@url{https://search.cpan.org/search?query=perl%2Ftk}. For Unix-based +systems Perl/Tk (as well as Perl of course) has to be installed +outside of TL. @url{https://tug.org/texlive/distro.html#perltk} has a +list of invocations for some distros. For Windows the necessary +modules are no longer shipped within TeX Live, so you'll have to have an +external Perl available that includes them. + +We are talking here about the GUI built into tlmgr itself, not about the +other tlmgr GUIs, which are: tlshell (Tcl/Tk-based), tlcockpit +(Java-based) and, only on Macs, TeX Live Utility. These are invoked as +separate programs. + +The GUI mode of tlmgr is started with the invocation @code{tlmgr gui}; +assuming Tk is loadable, the graphical user interface will be shown. +The main window contains a menu bar, the main display, and a status +area where messages normally shown on the console are displayed. + +Within the main display there are three main parts: the @code{Display +configuration} area, the list of packages, and the action buttons. + +Also, at the top right the currently loaded repository is shown; this +also acts as a button and when clicked will try to load the default +repository. To load a different repository, see the @code{tlmgr} menu item. + +Finally, the status area at the bottom of the window gives additional +information about what is going on. + +@menu +* tlmgr Main display:: +* tlmgr Menu bar:: +* tlmgr GUI options:: +@end menu + +@node tlmgr Main display +@appendixsubsec Main display + +@menu +* tlmgr Display configuration area:: +* tlmgr Package list area:: +* tlmgr Main display action buttons:: +@end menu + +@node tlmgr Display configuration area +@appendixsubsubsec Display configuration area + +The first part of the main display allows you to specify (filter) which +packages are shown. By default, all are shown. Changes here are +reflected right away. + +@table @asis +@item Status +@anchor{tlmgr Status} + +Select whether to show all packages (the default), only those installed, +only those @emph{not} installed, or only those with update available. + +@item Category +@anchor{tlmgr Category} + +Select which categories are shown: packages, collections, and/or +schemes. These are briefly explained in the @ref{tlmgr DESCRIPTION,, DESCRIPTION} section +above. + +@item Match +@anchor{tlmgr Match} + +Select packages matching for a specific pattern. By default, this +searches both descriptions and filenames. You can also select a subset +for searching. + +@item Selection +@anchor{tlmgr Selection} + +Select packages to those selected, those not selected, or all. Here, +``selected'' means that the checkbox in the beginning of the line of a +package is ticked. + +@item Display configuration buttons +@anchor{tlmgr Display configuration buttons} + +To the right there are three buttons: select all packages, select none +(a.k.a. deselect all), and reset all these filters to the defaults, +i.e., show all available. + +@end table + +@node tlmgr Package list area +@appendixsubsubsec Package list area + +The second are of the main display lists all installed packages. If a +repository is loaded, those that are available but not installed are +also listed. + +Double clicking on a package line pops up an informational window with +further details: the long description, included files, etc. + +Each line of the package list consists of the following items: + +@table @asis +@item a checkbox +@anchor{tlmgr a checkbox} + +Used to select particular packages; some of the action buttons (see +below) work only on the selected packages. + +@item package name +@anchor{tlmgr package name} + +The name (identifier) of the package as given in the database. + +@item local revision (and version) +@anchor{tlmgr local revision (and version)} + +If the package is installed the TeX Live revision number for the +installed package will be shown. If there is a catalogue version given +in the database for this package, it will be shown in parentheses. +However, the catalogue version, unlike the TL revision, is not +guaranteed to reflect what is actually installed. + +@item remote revision (and version) +@anchor{tlmgr remote revision (and version)} + +If a repository has been loaded the revision of the package in the +repository (if present) is shown. As with the local column, if a +catalogue version is provided it will be displayed. And also as with +the local column, the catalogue version may be stale. + +@item short description +@anchor{tlmgr short description} + +The short description of the package. + +@end table + +@node tlmgr Main display action buttons +@appendixsubsubsec Main display action buttons + +Below the list of packages are several buttons: + +@table @asis +@item Update all installed +@anchor{tlmgr Update all installed} + +This calls @code{tlmgr update --all}, i.e., tries to update all available +packages. Below this button is a toggle to allow reinstallation of +previously removed packages as part of this action. + +The other four buttons only work on the selected packages, i.e., those +where the checkbox at the beginning of the package line is ticked. + +@item Update +@anchor{tlmgr Update} + +Update only the selected packages. + +@item Install +@anchor{tlmgr Install} + +Install the selected packages; acts like @code{tlmgr install}, i.e., also +installs dependencies. Thus, installing a collection installs all its +constituent packages. + +@item Remove +@anchor{tlmgr Remove} + +Removes the selected packages; acts like @code{tlmgr remove}, i.e., it will +also remove dependencies of collections (but not dependencies of normal +packages). + +@item Backup +@anchor{tlmgr Backup} + +Makes a backup of the selected packages; acts like @code{tlmgr backup}. This +action needs the option @code{backupdir} set (see @code{Options -} General>). + +@end table + +@node tlmgr Menu bar +@appendixsubsec Menu bar + +The following entries can be found in the menu bar: + +@table @asis +@item @code{tlmgr} menu +@anchor{tlmgr @code{tlmgr} menu} + +The items here load various repositories: the default as specified in +the TeX Live database, the default network repository, the repository +specified on the command line (if any), and an arbitrarily +manually-entered one. Also has the so-necessary @code{quit} operation. + +@item @code{Options menu} +@anchor{tlmgr @code{Options menu}} + +Provides access to several groups of options: @code{Paper} (configuration of +default paper sizes), @code{Platforms} (only on Unix, configuration of the +supported/installed platforms), @code{GUI Language} (select language used in +the GUI interface), and @code{General} (everything else). + +Several toggles are also here. The first is @code{Expert options}, which is +set by default. If you turn this off, the next time you start the GUI a +simplified screen will be shown that display only the most important +functionality. This setting is saved in the configuration file of +@code{tlmgr}; see @ref{tlmgr CONFIGURATION FILE FOR TLMGR,, CONFIGURATION FILE FOR TLMGR} for details. + +The other toggles are all off by default: for debugging output, to +disable the automatic installation of new packages, and to disable the +automatic removal of packages deleted from the server. Playing with the +choices of what is or isn't installed may lead to an inconsistent TeX Live +installation; e.g., when a package is renamed. + +@item @code{Actions menu} +@anchor{tlmgr @code{Actions menu}} + +Provides access to several actions: update the filename database (aka +@code{ls-R}, @code{mktexlsr}, @code{texhash}), rebuild all formats (@code{fmtutil-sys +--all}), update the font map database (@code{updmap-sys}), restore from a backup +of a package, and use of symbolic links in system directories (not on +Windows). + +The final action is to remove the entire TeX Live installation (also not +on Windows). + +@item @code{Help menu} +@anchor{tlmgr @code{Help menu}} + +Provides access to the TeX Live manual (also on the web at +@url{https://tug.org/texlive/doc.html}) and the usual ``About'' box. + +@end table + +@node tlmgr GUI options +@appendixsubsec GUI options + +Some generic Perl/Tk options can be specified with @code{tlmgr gui} to +control the display: + +@table @asis +@item @code{-background} @emph{color} +@anchor{tlmgr @code{-background} @emph{color}} + +Set background color. + +@item @code{-font "} @emph{fontname} @emph{fontsize} @code{"} +@anchor{tlmgr @code{-font "} @emph{fontname} @emph{fontsize} @code{"}} + +Set font, e.g., @code{tlmgr gui -font "helvetica 18"}. The argument to +@code{-font} must be quoted, i.e., passed as a single string. + +@item @code{-foreground} @emph{color} +@anchor{tlmgr @code{-foreground} @emph{color}} + +Set foreground color. + +@item @code{-geometry} @emph{geomspec} +@anchor{tlmgr @code{-geometry} @emph{geomspec}} + +Set the X geometry, e.g., @code{tlmgr gui -geometry 1024x512-0+0} creates +the window of (approximately) the given size in the upper-right corner +of the display. + +@item @code{-xrm} @emph{xresource} +@anchor{tlmgr @code{-xrm} @emph{xresource}} + +Pass the arbitrary X resource string @emph{xresource}. + +@end table + +A few other obscure options are recognized but not mentioned here. See +the Perl/Tk documentation (@url{https://search.cpan.org/perldoc?Tk}) for the +complete list, and any X documentation for general information. + +@node tlmgr MACHINE-READABLE OUTPUT +@appendixsec MACHINE-READABLE OUTPUT + +With the @code{--machine-readable} option, @code{tlmgr} writes to stdout in the +fixed line-oriented format described here, and the usual informational +messages for human consumption are written to stderr (normally they are +written to stdout). The idea is that a program can get all the +information it needs by reading stdout. + +Currently this option only applies to the +@ref{tlmgr update [@emph{option}...] [@emph{pkg}...], update, update}, +@ref{tlmgr install [@emph{option}...] @emph{pkg}..., install, install}, and +@ref{tlmgr option,, option} actions. + +@menu +* tlmgr Machine-readable @code{update} and @code{install} output:: +* tlmgr Machine-readable @code{option} output:: +@end menu + +@node tlmgr Machine-readable @code{update} and @code{install} output +@appendixsubsec Machine-readable @code{update} and @code{install} output + +The output format is as follows: + +@verbatim + fieldname "\t" value + ... + "end-of-header" + pkgname status localrev serverrev size runtime esttot + ... + "end-of-updates" + other output from post actions, not in machine readable form +@end verbatim + +The header section currently has two fields: @code{location-url} (the +repository source from which updates are being drawn), and +@code{total-bytes} (the total number of bytes to be downloaded). + +The @emph{localrev} and @emph{serverrev} fields for each package are the +revision numbers in the local installation and server repository, +respectively. The @emph{size} field is the number of bytes to be +downloaded, i.e., the size of the compressed tar file for a network +installation, not the unpacked size. The runtime and esttot fields +are only present for updated and auto-install packages, and contain +the currently passed time since start of installation/updates +and the estimated total time. + +Line endings may be either LF or CRLF depending on the current platform. + +@table @asis +@item @code{location-url} @emph{location} +@anchor{tlmgr @code{location-url} @emph{location}} + +The @emph{location} may be a url (including @code{file:///foo/bar/...}), or a +directory name (@code{/foo/bar}). It is the package repository from which +the new package information was drawn. + +@item @code{total-bytes} @emph{count} +@anchor{tlmgr @code{total-bytes} @emph{count}} + +The @emph{count} is simply a decimal number, the sum of the sizes of all the +packages that need updating or installing (which are listed subsequently). + +@end table + +Then comes a line with only the literal string @code{end-of-header}. + +Each following line until a line with literal string @code{end-of-updates} +reports on one package. The fields on +each line are separated by a tab. Here are the fields. + +@table @asis +@item @emph{pkgname} +@anchor{tlmgr @emph{pkgname}} + +The TeX Live package identifier, with a possible platform suffix for +executables. For instance, @code{pdftex} and @code{pdftex.i386-linux} are given +as two separate packages, one on each line. + +@item @emph{status} +@anchor{tlmgr @emph{status}} + +The status of the package update. One character, as follows: + +@table @asis +@item @code{d} +@anchor{tlmgr @code{d}} + +The package was removed on the server. + +@item @code{f} +@anchor{tlmgr @code{f}} + +The package was removed in the local installation, even though a +collection depended on it. (E.g., the user ran @code{tlmgr remove +--force}.) + +@item @code{u} +@anchor{tlmgr @code{u}} + +Normal update is needed. + +@item @code{r} +@anchor{tlmgr @code{r}} + +Reversed non-update: the locally-installed version is newer than the +version on the server. + +@item @code{a} +@anchor{tlmgr @code{a}} + +Automatically-determined need for installation, the package is new on +the server and is (most probably) part of an installed collection. + +@item @code{i} +@anchor{tlmgr @code{i}} + +Package will be installed and isn't present in the local installation +(action install). + +@item @code{I} +@anchor{tlmgr @code{I}} + +Package is already present but will be reinstalled (action install). + +@end table + +@item @emph{localrev} +@anchor{tlmgr @emph{localrev}} + +The revision number of the installed package, or @code{-} if it is not +present locally. + +@item @emph{serverrev} +@anchor{tlmgr @emph{serverrev}} + +The revision number of the package on the server, or @code{-} if it is not +present on the server. + +@item @emph{size} +@anchor{tlmgr @emph{size}} + +The size in bytes of the package on the server. The sum of all the +package sizes is given in the @code{total-bytes} header field mentioned above. + +@item @emph{runtime} +@anchor{tlmgr @emph{runtime}} + +The run time since start of installations or updates. + +@item @emph{esttot} +@anchor{tlmgr @emph{esttot}} + +The estimated total time. + +@end table + +@node tlmgr Machine-readable @code{option} output +@appendixsubsec Machine-readable @code{option} output + +The output format is as follows: + +@verbatim + key "\t" value +@end verbatim + +If a value is not saved in the database the string @code{(not set)} is shown. + +If you are developing a program that uses this output, and find that +changes would be helpful, do not hesitate to write the mailing list. + +@node tlmgr ENVIRONMENT VARIABLES +@appendixsec ENVIRONMENT VARIABLES + +@code{tlmgr} uses many of the standard TeX environment variables, as +reported by, e.g., @code{tlmgr conf} (@ref{tlmgr conf,, conf}). + +In addition, for ease in scripting and debugging, @code{tlmgr} looks for the +following environment variables. These are not of interest for normal +user installations. + +@table @asis +@item @code{TEXLIVE_COMPRESSOR} +@anchor{tlmgr @code{TEXLIVE_COMPRESSOR}} + +This variable allows selecting a different compressor program for +backups and intermediate rollback containers. The order of selection is: + +@enumerate +@item If the environment variable @code{TEXLIVE_COMPRESSOR} is +defined, use it; abort if it doesn't work. Possible values: +@code{lz4}, @code{gzip}, @code{xz}. The necessary options are added internally. + +@item If lz4 is available (either from the system or TL) and working, use that. + +@item If gzip is available (from the system) and working, use that. + +@item If xz is available (either from the system or TL) and working, use that. + +@end enumerate + +lz4 and gzip are faster in creating tlmgr's local backups, hence they +are preferred. The unconditional use of xz for the tlnet containers is +unaffected, to minimize download sizes. + +@item @code{TEXLIVE_DOWNLOADER} +@anchor{tlmgr @code{TEXLIVE_DOWNLOADER}} + +@item @code{TL_DOWNLOAD_PROGRAM} +@anchor{tlmgr @code{TL_DOWNLOAD_PROGRAM}} + +@item @code{TL_DOWNLOAD_ARGS} +@anchor{tlmgr @code{TL_DOWNLOAD_ARGS}} + +These options allow selecting different download programs then the ones +automatically selected by the installer. The order of selection is: + +@enumerate +@item If the environment variable @code{TEXLIVE_DOWNLOADER} is defined, use it; +abort if the specified program doesn't work. Possible values: @code{lwp}, +@code{curl}, @code{wget}. The necessary options are added internally. + +@item If the environment variable @code{TL_DOWNLOAD_PROGRAM} is +defined (can be any value), use it together with +@code{TL_DOWNLOAD_ARGS}; abort if it doesn't work. + +@item If LWP is available and working, use that (by far the most +efficient method, as it supports persistent downloads). + +@item If curl is available (from the system) and working, use that. + +@item If wget is available (either from the system or TL) and working, use that. + +@end enumerate + +TL provides @code{wget} binaries for platforms where necessary, so some +download method should always be available. + +@item @code{TEXLIVE_PREFER_OWN} +@anchor{tlmgr @code{TEXLIVE_PREFER_OWN}} + +By default, compression and download programs provided by the system, +i.e., found along @code{PATH} are preferred over those shipped with TeX +Live. + +This can create problems with systems that are too old, and so can be +overridden by setting the environment variable @code{TEXLIVE_PREFER_OWN} to +1. In this case, executables shipped with TL will be preferred. + +Extra compression/download programs not provided by TL, such as gzip, +lwp, and curl, are still checked for on the system and used if +available, per the above. @code{TEXLIVE_PREFER_OWN} only applies when the +program being checked for is shipped with TL, namely the lz4 and +xz compressors and wget downloader. + +Exception: on Windows, the @code{tar.exe} shipped with TL is always used, +regardless of any setting. + +@end table + +@node tlmgr AUTHORS AND COPYRIGHT +@appendixsec AUTHORS AND COPYRIGHT + +This script and its documentation were written for the TeX Live +distribution (@url{https://tug.org/texlive}) and both are licensed under the +GNU General Public License Version 2 or later. + +$Id: tlmgr.pl 54118 2020-03-05 22:27:22Z karl $ + diff --git a/Build/source/doc/tlbuild.info b/Build/source/doc/tlbuild.info new file mode 100644 index 00000000000..6adbef66513 --- /dev/null +++ b/Build/source/doc/tlbuild.info @@ -0,0 +1,6335 @@ +This is tlbuild.info, produced by makeinfo version 5.1 from +tlbuild.texi. + +This file documents the TeX Live build system and more. + +Copyright (C) 2016-2021 Karl Berry. +Copyright (C) 2013-2015 Karl Berry & Peter Breitenlohner. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the TeX Users Group. +INFO-DIR-SECTION TeX +START-INFO-DIR-ENTRY +* TLbuild: (tlbuild). TeX Live configuration and development. +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* install-tl:: Installing TeX Live. +* tlmgr:: Managing TeX Live. +END-INFO-DIR-ENTRY + + +File: tlbuild.info, Node: Top, Next: Introduction, Up: (dir) + +Building TeX Live (2021) +************************ + +For an overview of this manual, *note Introduction::. + +* Menu: + +* Introduction:: About this manual. +* Overview of build system:: The TeX Live build system. +* Prerequisites:: Requirements for building TeX Live. +* Building:: The overall build process. +* Installing:: How and where installation happens (or not). +* Layout and infrastructure:: Autoconf macros, etc., in detail. +* Configure options:: List of all configure options. +* Coding conventions:: Conventions to follow. +* Continuous integration:: Automated build testing. +* install-tl:: The TeX Live installer. +* tlmgr:: The native TeX Live package manager. +* Index:: General index. + + +File: tlbuild.info, Node: Introduction, Next: Overview of build system, Prev: Top, Up: Top + +1 Introduction +************** + +This manual (dated February 2021) corresponds to the TeX Live 2021 +release. + + This manual is aimed at system installers and programmers, and +focuses on how to configure, build, and develop the TeX Live (TL) +sources. It is also available as plain text files in the source tree: +'source/README.*'. + + The main 'source/README' file in the TL source tree provides +maximally-terse information for doing a build, and portability +information for different systems, along with +'source/doc/README.solaris'. + + For information on acquiring the TL sources, see +. The canonical source repository uses +Subversion, and we have no plans to change this. + + This manual does not duplicate the information found in other TL +documentation resources, such as: + + * The TeX Live web pages: . + + * The web page describing how to build the binaries which are + distributed with TeX Live: . + + * The TeX Live user manual: , or + run 'texdoc texlive'. + + * Other TeX-related Texinfo manuals (*note (web2c)::, *note + (kpathsea)::, etc.): , or check the + 'TeX' category in the GNU Info system. + + * Package documentation: + , or the 'doc.html' + file at the top level of the installed TL. + + As an exception, the full documentation for 'install-tl' and 'tlmgr' +is included here as appendices, simply because it is easy to do so. The +same text is available online (linked from +, or by invoking the program with +'--help' (or look at the end of the source). + + +File: tlbuild.info, Node: Overview of build system, Next: Prerequisites, Prev: Introduction, Up: Top + +2 Overview of build system +************************** + +The TeX Live build system was redesigned in 2009 to consistently use +Autoconf, Automake, and Libtool. Thus, running + 'configure && make && make check && make install' +or the essentially-equivalent top-level 'Build' script suffices to build +and install the TL programs. The 'make check' clause performs various +tests of the generated programs--not strictly required but strongly +recommended. Running 'configure --help' will display a comprehensive +list of all 'configure' options. + + The main components of the TL build system are: + +'libs/LIB' + Generic libraries. + +'texk/LIB' + TeX-specific libraries in subdirectories, notably LIB='kpathsea'. + (The other one is 'texk/ptexenc'.) + +'texk/PROG' + TeX-specific programs (that use Kpathsea). + +'utils/PROG' + Other programs (that don't use Kpathsea). + + The primary design goal of the build system is modularity. Each +program and library module (or package) specifies its own requirements +and properties, such as required libraries, whether an installed +(system) version of a library can be used, 'configure' options to be +seen at the top level, and more. An explicit list of all available +modules is kept in a single central place: 'm4/kpse-pkgs.m4'. + + A second, related goal is to configure and build each library before +configuring any other (program or library) module which uses that +library. This allows checking for properties and features of a library +built as part of the TL tree in much the same way as for a system +version of that library. + + All generic libraries and several programs are maintained +independently. The corresponding modules use (most of) the distributed +source tree and document any modifications of that source. + + All this is for the sake of simplifying both upgrading of modules and +integrating new modules into the TL build system. (Despite all efforts, +neither task is easy.) + + +File: tlbuild.info, Node: Prerequisites, Next: Building, Prev: Overview of build system, Up: Top + +3 Prerequisites +*************** + +Overall, building the TeX Live programs, when using all libraries from +the TL source tree, requires C and C++11 compilers and GNU 'make'. If +'make' from your 'PATH' is not GNU make, you can set the 'MAKE' +environment variable to whatever is necessary. + + GNU 'make' is required only because of some third-party libraries, +notably FreeType; all the TL-maintained directories (and +Automake/Autoconf output in general) work with any reasonable 'make'. + + A C++11 compiler is similarly required because of the third-party +library ICU; the program 'dvisvgm' also requires C++11. It is possible +to build everything else with older compilers, but you have to remove +the C++11-dependent sources. *Note Build one package::. + + A few programs in the tree have additional requirements: + +'web2c' + requires 'perl' for some tests run by 'make check'. + +'xdvik' +'xpdfopen' + require X11 headers and libraries, typically in "development" + packages that are not installed by default. + +'xetex' + requires 'fontconfig' (again both headers and library), or, for + MacOSX only, the 'ApplicationServices' and 'Cocoa' frameworks. + +'xindy' + requires GNU 'clisp', 'libsigsegv', and 'libiconv'; additionally, + to build the rules and/or documentation: 'perl', 'latex', + 'pdflatex'. + +Lacking the required tools, building these programs must avoided, e.g., +'configure --without-x --disable-xetex --disable-xindy' + + Modifying source files induces more requirements, as one might +expect: + + * Modification of any '.y' or '.l' source files requires 'bison' or + 'flex' to update the corresponding C sources. + + * Modification of the sources for '.info' files requires 'makeinfo'. + + * Modification of any part of the build system (M4 macros, + 'configure.ac', 'Makefile.am', or their fragments) requires GNU M4, + GNU Autoconf, GNU Automake, and GNU Libtool to update the generated + files. Furthermore, to reliably reproduce the build files, the + original GNU releases of these tools must be used, not any distro + packaging of them. *Note Build system tools::, for more + discussion. + + If you haven't modified any source files, and infrastructure tools +such as 'autoconf' or 'makeinfo' are still being run, check your +timestamps--notably, 'use-commit-times' must be set to 'yes' in your +Subversion configuration (*note Build system tools::). Barring buggy +commits, no infrastructure tools are needed to do a normal build. + + +File: tlbuild.info, Node: Building, Next: Installing, Prev: Prerequisites, Up: Top + +4 Building +********** + +The top-level 'Build' script is intended to simplify building the +binaries distributed with TeX Live itself--we call this the "native" TL +build. It runs 'configure && make world', which builds everything in a +subdirectory of the main source tree (default 'Work/'), installs +everything in another subdirectory (default 'inst/'), and finally runs +'make check'. The exact directory and command names can be specified +via environment variables and a few leading options. All remaining +arguments (assignments or options) are passed to the 'configure' script. +Please take a look at the './Build' source file for more information; it +is a straightforward shell script. + + An alternative, and the one we will mainly discuss here, is to run +'configure' and 'make' in a suitable empty subdirectory. Building in +the source directory itself is not supported (sorry). + +* Menu: + +* Build iteration:: What 'configure' and 'make' do in TL. +* Build problems:: If the build fails. +* Build in parallel:: Simultaneous 'make' processes. +* Build distribution:: Making a distribution tarball. +* Build one package:: Example of working on just one program. +* Build one engine:: Example of building just one TeX engine. +* Cross compilation:: Building on host X for target Y. + + +File: tlbuild.info, Node: Build iteration, Next: Build problems, Up: Building + +4.1 Build iteration +=================== + +Running the top-level 'configure' script configures the top level and +the subdirectories 'libs', 'utils', and 'texk'. Running 'make' at the +top level first iterates over the TeX-specific libraries, and then runs +'make' in 'libs', 'utils', and 'texk' to iterate over the generic +libraries, utility programs, and TeX-specific programs, respectively. +These iterations consist of two steps: + + 1. For each library or program module not yet configured, run + 'configure', adding the configure option '--disable-build' if the + module need not be built, otherwise running 'make all'. + + 2. For each library or program module that must be built, run 'make' + for the selected target(s): 'default' or 'all' to (re-)build, + 'check' to run tests, 'install', etc. + + Running the top-level 'make' a second time iterates again over all +the library and program modules, and finds (should find) nothing to be +done. + + +File: tlbuild.info, Node: Build problems, Next: Build in parallel, Prev: Build iteration, Up: Building + +4.2 Build problems +================== + +If configuring or building a module fails, you should first try to find +and fix the problem. Failing that, a possible workaround is to remove +the subdirectory for that module from the build tree (so 'configure' +won't try to run there, and finally rerun the top level 'make' (or +'./Build' '--no-clean'). + + +File: tlbuild.info, Node: Build in parallel, Next: Build distribution, Prev: Build problems, Up: Building + +4.3 Build in parallel +===================== + +The TL build system carefully formulates dependencies as well as 'make' +rules when a tool (such as 'tangle', 'ctangle', and 'convert') creates +several output files. This allows for parallel builds ('make -j N' with +N>1 or even 'make -j') that can considerably speed up the TL build. + + Incidentally, a noticeable speed-up can be independently gained by +using a configure cache file, i.e., specifying the 'configure' option +'-C' (recommended). + + +File: tlbuild.info, Node: Build distribution, Next: Build one package, Prev: Build in parallel, Up: Building + +4.4 Build distribution +====================== + +Running 'make dist' at the top level creates a tarball +'tex-live-YYYY-MM-DD.tar.xz' from the TL source tree. Running 'make +distcheck' also verifies that this tarball suffices to build and install +all of TL. + + This is useful for checking consistency of the source tree and +Makefiles, but the result is not a complete or even usable TeX system, +since all the support files are lacking; *note Installing::. We do not +actually distribute any such tarball, and have no plans to do so. + + +File: tlbuild.info, Node: Build one package, Next: Build one engine, Prev: Build distribution, Up: Building + +4.5 Build one package +===================== + +To build one package, the basic idea is to use the 'configure' option +'--disable-all-pkgs' (*note '--disable-all-pkgs'::). Then all program +and library modules are configured but none are made. However, the +'Makefile's still contain all build rules and dependencies and can be +invoked to build an individual program or library, first building any +required libraries. + + Here is an example from start to finish for working on 'dvipdfm-x'. +(Unfortunately, this does not suffice for building the TeX engines; see +the next section.) + + mkdir mydir && cd mydir # new working directory + + # Get sources (), e.g.: + rsync -a --delete --exclude=.svn --exclude=Work \ + tug.org::tldevsrc/Build/source/ . + + # Create build directory: + mkdir Work && cd Work + + # Do the configure: + ../configure --disable-all-pkgs --enable-dvipdfm-x \ + -C CFLAGS=-g CXXFLAGS=-g >&outc || echo fail + + # Do the make: + make >&outm || echo fail + + # Test: + cd texk/dvipdfm-x + make check + + Then you can modify source files in 'mydir/texk/dvipdfm-x' and rerun +'make' in 'mydir/Work/texk/dvipdfm-x' to rebuild; that build directory +is where the binary ends up and where you can run a debugger, etc. + + The second line of the 'configure' invocation shows examples of extra +things you likely want to specify if you intend to hack the sources (and +not just build binaries): the '-C' speeds 'configure' by enabling a +cache file, and the 'CFLAGS' and 'CXXFLAGS' settings eliminate compiler +optimization for debugging purposes. + + Of course, you need to actually look at the output and check that +things are working. There are many 'configure' options you can tweak as +desired; check the output from 'configure --help'. It is also a good +idea to run 'make check' after making any changes, to ensure that +whatever tests have been written still pass. + + Finally, the above retrieves the entire TL source tree (several +hundred megabytes). It is natural to ask if this is really necessary. +Strictly speaking, the answer is no, but it is vastly more convenient to +do so. If you cut down the source tree, you must also give additional +'configure' flags to individually disable using system versions of +libraries, or the intricacies of the dependencies (such as 'teckit' +requiring 'zlib') will have undesired side effects. For an example of +this approach, see the 'build-pdftex.sh' script in the 'pdftex' +development source (details at ), which is indeed +such a cut-down TL source tree. + + Some libraries and programs require C++11. If you want to build with +an older compiler lacking such support, you need to (re)move those +source directories; specifying '--disable' for them does not suffice, +unfortunately. Specifically, before running 'configure': + + rm -rf libs/icu libs/graphite2 texk/dvisvgm + + Also, even with '--disable-all-pkgs', dependencies are (currently) +checked. For instance, if a (non-MacOSX) system does not have +'fontconfig', XeTeX cannot be built (*note Prerequisites::), and +'configure' will terminate even with '--disable-xetex'. To proceed +without such dependencies, specify '--enable-missing' also. (Patches to +improve this would be most welcome.) + + By default, the 'gcc' compilers will be used if present; otherwise, +individual packages may use something different. You can explicitly +specify the compilers to be used with the environment variables 'CC', +'CXX', and 'OBJCXX'. + + +File: tlbuild.info, Node: Build one engine, Next: Cross compilation, Prev: Build one package, Up: Building + +4.6 Build one engine +==================== + +Unfortunately, there is one common case where the steps in the preceding +section to build one package (*note Build one package::) do not suffice: +wanting to build one, or a subset, of the TeX engines (or other Web2c +programs). + + The simplest way to do this is to disable everything and then +explicitly specify what to make. For example, to build only the +original TeX: + + cd Work # top build directory + ../configure --without-x --disable-shared --disable-all-pkgs \ + --enable-tex --disable-synctex -C CFLAGS=-g CXXFLAGS=-g + make + cd texk/web2c # cd engine build directory + make tex # must specify target + + The first 'make' run will configure everything, and even build the +libraries, even though the packages are disabled. The source tree can +be cut down to just what is needed for the given engine (the separate +pdfTeX and LuaTeX source repositories do this, for example), but see +caveats in previous section. + + If you want to debug an X-related program or shared library setup, or +other variants, change the 'configure' options accordingly. Either +'../Build' or '../configure' can be run. + + Then it is necessary to again specify the target engine ('tex', in +the above) in the 'make'. + + All this is somewhat unfortunate. We hope to improve the situation +in the future. Patches are welcome. + + +File: tlbuild.info, Node: Cross compilation, Prev: Build one engine, Up: Building + +4.7 Cross compilation +===================== + +In a cross compilation a "build" system is used to create binaries to be +executed on a "host" system with different hardware and/or operating +system. + + In simple cases, the build system can execute binaries for the host +system. This typically occurs for bi-arch systems where, e.g., +'i386-linux' binaries can run on 'x86_64-linux' systems and 'win32' +binaries can run on 'win64' systems. Although sometimes called "native +cross", technically this is not cross compilation at all. In most such +cases it suffices to specify suitable compiler flags. It might be +useful to add the configure option '--build=HOST' to get the correct +canonical host name, but note that this should _not_ be '--host=HOST' +(*note (autoconf)Hosts and Cross-Compilation::). + + In order to build, e.g., 32-bit binaries with 'clang' on a 64-bit +MacOSX system one could use: + + TL_BUILD_ENV="CC='clang -arch i386' \ + CXX='clang++ -arch i386' \ + OBJCXX='clang++ -arch i386'" \ + ./Build --build=i386-apple-darwin + +* Menu: + +* Cross configuring:: Configuring for cross compilation. +* Cross problems:: Cross compilation problems. + + +File: tlbuild.info, Node: Cross configuring, Next: Cross problems, Up: Cross compilation + +4.7.1 Cross configuring +----------------------- + +In a standard cross compilation, binaries for the host system cannot +execute on the build system and it is necessary to specify the configure +options '--host=HOST' and '--build=BUILD' with two different values. + + Building binaries requires suitable "cross" tools, e.g., compiler, +linker, and archiver, and perhaps a "cross" version of 'pkg-config' and +similar to locate host system libraries. Autoconf expects that these +cross tools are given by their usual variables or found under their +usual name prefixed with 'HOST-'. Here a list of such tools and +corresponding variables: + + ar AR + freetype-config FT2_CONFIG + g++ CXX + gcc CC + icu-config ICU_CONFIG + objdump OBJDUMP + pkg-config PKG_CONFIG + ranlib RANLIB + strip STRIP + +In order to, e.g., build 'mingw32' binaries on 'x86_64-linux' with a +cross compiler found as 'i386-pc-mingw32-gcc' one would specify + + --host=i386-pc-mingw32 --build=x86_64-linux-gnu + +or perhaps + + --host=mingw32 --build=x86_64-linux CC=i386-pc-mingw32-gcc + +but this latter, especially, might require adding 'CXX' and others. + + Configure arguments such as 'CFLAGS=...' refer to the cross compiler. +If necessary, you can specify compilers and flags for the few auxiliary +C and C++ programs required for the build process as configure arguments + + BUILDCC=... + BUILDCPPFLAGS=... + BUILDCFLAGS=... + BUILDCXX=... + BUILDCXXFLAGS=... + BUILDLDFLAGS=... + + +File: tlbuild.info, Node: Cross problems, Prev: Cross configuring, Up: Cross compilation + +4.7.2 Cross problems +-------------------- + +The fact that binaries for the host system cannot be executed on the +build system causes some problems. + + One problem is that configure tests using 'AC_RUN_IFELSE' can compile +and link the test program but cannot execute it. Such tests should be +avoided if possible and otherwise must supply a pessimistic test result. + + Another problem arises if the build process must execute some +(auxiliary or installable) programs. Auxiliary programs can be placed +into a subdirectory that is configured natively as is done for +'texk/web2c/web2c', 'texk/dvipsk/squeeze', and 'texk/xdvik/squeeze'. +The module 'libs/freetype2' uses the value of 'CC_BUILD', 'BUILD-gcc', +'gcc', or 'cc' as the compiler for the auxiliary program. + + The situation for installable programs needed by the build process is +somewhat different. A rather expensive possibility, chosen for the ICU +libraries in module 'libs/icu', is to first compile natively for the +build system and in a second step to use these (uninstalled) programs +during the cross compilation. + + This approach would also be possible for the tools such as 'tangle' +used in the module 'texk/web2c' to build the WEB programs, but that +would require first building a native 'kpathsea' library. To avoid this +complication, cross compilation of programs written in (C)WEB requires +sufficiently recent installed versions of 'tangle', 'ctangle', +'otangle', and 'tie'. + + Building 'xindy' requires running the host system 'clisp' binary, +thus cross compilation is painful, but possible. + + +File: tlbuild.info, Node: Installing, Next: Layout and infrastructure, Prev: Building, Up: Top + +5 Installing +************ + +This section discusses the results of 'make install' in the source tree. + + The main consideration is that 'make install' is not enough to make a +usable TeX installation. Beyond the compiled binaries, (thousands of) +support files are needed; just as a first example, 'plain.tex' is not in +the source tree. + + These support files are maintained completely independently and are +not present in the TL source tree. The best basis for dealing with them +is the TeX Live (plain text) database in 'Master/tlpkg/texlive.tlpdb', +and/or the TeX Live installer, 'install-tl'. More information is under +'Master/tlpkg' and at . + +* Menu: + +* Installation directories:: The prefix, 'bindir', etc., directories. +* Linked scripts:: Scripts not maintained in the sources. +* Distro builds:: Configuring and building for OS distributions. + + +File: tlbuild.info, Node: Installation directories, Next: Linked scripts, Up: Installing + +5.1 Installation directories +============================ + +Running 'make install' (or 'make install-strip') installs executables in +'BINDIR', libraries in 'LIBDIR', headers in 'INCLUDEDIR', general data +(including "linked scripts", *note Linked scripts::) in +'DATAROOTDIR/texmf-dist', man pages in 'MANDIR', and Info files in +'INFODIR'. + + The values of these directories are determined by 'configure' and can +be specified explicitly as options such as '--prefix=PREFIX' or +'--bindir=BINDIR'; otherwise, they are given by their usual Autoconf +defaults: + + PREFIX /usr/local + EXEC_PREFIX PREFIX + BINDIR EXEC_PREFIX/bin + LIBDIR EXEC_PREFIX/lib + INCLUDEDIR PREFIX/include + DATAROOTDIR PREFIX/share + MANDIR DATAROOTDIR/man + INFODIR DATAROOTDIR/info + +except possibly modified as follows: + + * If the option '--enable-multiplatform' is given, '/PLATFORM' (i.e., + the canonical platform name) is appended to 'BINDIR' and 'LIBDIR'. + This is implied for a native TL build. + + * In a native TL build, 'DATAROOTDIR' is set to 'PREFIX', 'INFODIR' + is set to 'PREFIX/texmf-dist/doc/info', and 'MANDIR' to + 'PREFIX/texmf-dist/doc/man', corresponding to the directories used + in the TL distribution. + +The top-level 'configure' script displays all these installation paths. + + For the native TL build, the 'Build' script leaves the binaries in +'./inst/bin/STD-SYSTEM-TRIPLET'. The new binaries are not directly +usable from that location; they need to be copied to +'Master/bin/TL-PLATFORM'. The other files and directories that end up +in './inst/' are ignored. + + +File: tlbuild.info, Node: Linked scripts, Next: Distro builds, Prev: Installation directories, Up: Installing + +5.2 Linked scripts +================== + +Quite a few executables are architecture-independent shell, Perl, or +other interpreted scripts, rather than compiled binaries. A few are +maintained as part of the TL source tree, but most are maintained +elsewhere with copies under 'texk/texlive/linked_scripts'. + + These so-called "linked scripts" are installed under +'DATAROOTDIR/texmf-dist/scripts'; for Unix-like systems a symbolic link +is made in 'BINDIR'. For example, a symlink points from 'BINDIR/ps2eps' +to 'DATAROOTDIR/texmf-dist/scripts/ps2eps/ps2eps.pl'. For Windows, a +standard wrapper binary (copied to, e.g., 'BINDIR/ps2eps.exe') serves +the same purpose. The source for the wrapper is in +'texk/texlive/w32_wrapper'. + + One reason for this is to avoid having many copies of the same +script; a more important reason is that it guarantees the scripts will +stay in sync across the different supported operating systems. + + Most important of all, we want the 'BINDIR' resulting from the build +to be as close as possible to what is in the TL distribution. At +present, there are a few exceptions--Asymptote, Biber, Xindy--and each +one creates considerable extra work. We don't want to add more. (See + for information about building +those exceptions, as well as the 'xz' and 'wget' programs that are used +in the TL infrastructure.) + + +File: tlbuild.info, Node: Distro builds, Prev: Linked scripts, Up: Installing + +5.3 Distro builds +================= + +Although they use the same code base, building for the native TL +distribution as shipped by the TeX user groups is typically quite +different from a "distro" build needed by, e.g., a full GNU/Linux or BSD +operating system distribution. + + The native TL distribution uses shared libraries only when absolutely +necessary ('libc', 'libm', X11 libraries, and 'libfontconfig'). In +contrast, a distro typically wants to use as many shared libraries as +possible from elsewhere on the system, including TeX-specific libraries +such as 'libkpathsea' (even though Kpathsea has never officially been +released as a shared library). In addition, the installation paths +will, in general, be completely different. + + Here are the 'configure' options that distro builds are likely to +find most relevant: + +'--disable-native-texlive-build' + This must be specified to avoid interference from the many tweaks + we do for the native TL build. + +'--with-banner-add=/SOMEDISTRO' + This isn't technically required, but is strongly recommended, so + your build and your distro can be distinguished from others. + +'--enable-shared' + Build shared versions of the TeX-specific libraries (uses + 'libtool'). + +'--disable-static' + Do not build the static versions of the TeX-specific libraries. + +'--with-system-LIB' + Look for and use a system version of the library LIB. 'configure + --help' will give you the list of possibilities. + +'--with-LIB-includes=DIR' +'--with-LIB-libdir=DIR' + If needed, allows you to specify where the headers/code are for the + given library LIB. + +'--prefix=/usr' +'--prefix=/opt/TeXLive' + Or whatever your convention is. The default is '/usr/local' and + you shouldn't install there for a distro. + +'--libdir=\${exec_prefix}/lib64' + May be needed for 64-bit bi-architecture (GNU/Linux) systems. + + You will need to take care of the support files mentioned above +(*note Installing::), and many other issues, such as font maps, +languages, and formats, independently of the build. Norbert Preining +has written a detailed article on adapting TL for distros: +. (If the +article needs updating in the future, perhaps we will merge it into this +document.) + + +File: tlbuild.info, Node: Layout and infrastructure, Next: Configure options, Prev: Installing, Up: Top + +6 Layout and infrastructure +*************************** + +The TeX Live source tree is the subtree rooted at 'Build/source' of the +complete TL distribution and contains the sources for all executables +distributed by TL, as well as 'configure' scripts and 'make' rules to +build and install them together with some of their support files. + +* Menu: + +* Build system tools:: Modifying infrastructure files. +* Top-level directories:: libs texk utils; am auxdir build-aux m4; doc extra. +* Autoconf macros:: TL-specific Autoconf macros. +* Library modules:: Handling libraries, with examples. +* Program modules:: Handling programs, with examples. +* Extending TeX Live:: Adding a new module. + + +File: tlbuild.info, Node: Build system tools, Next: Top-level directories, Up: Layout and infrastructure + +6.1 Build system tools +====================== + +As mentioned above (*note Prerequisites::), a normal build has few +requirements. On the other hand, if you want to modify the TeX Live +infrastructure sources, such as 'configure.ac' or 'Makefile.am' files, +you will need to have several additional tools installed. + + In general, the TL build system uses the latest released versions of +the GNU build tools, installed directly from the original GNU releases +(e.g., by building them with 'configure --prefix=/usr/local/gnu' and +having 'PATH' start with '/usr/local/gnu/bin'). We have found that +trying to use the versions of these tools packaged for distros causes +many extra hassles, so don't do that, tempting as it may be. + + Currently the versions we use are: + + autoconf (GNU Autoconf) 2.69 + automake (GNU automake) 1.16.2 + bison (GNU Bison) 3.7.4 + flex 2.6.0 + ltmain.sh (GNU libtool) 2.4.6 + m4 (GNU M4) 1.4.18 + makeinfo (GNU texinfo) 6.7 + + These versions should be used to update the generated files (e.g., +'configure' or 'Makefile.in') in all or parts of the TL tree after their +dependencies have been changed. This can be done explicitly with the +top-level 'reautoconf' script or implicitly by using the configure +option '--enable-maintainer-mode'. + + It has often turned out that the bison and flex versions are not +critical; however, the autotools versions are. If you don't have the +given versions, get them before modifying the build infrastructure. + + The files in the Subversion repository (see +) are all up to date (barring bugs). For +this to be reflected by their timestamps in your checkout, be sure to +set 'use-commit-times=yes' in '~/.subversion/config' or the equivalent. + + If timestamps are wrong, you may also be able to avoid unnecessary +runs of 'bison', 'flex', or 'makeinfo' with 'touch' of the generated +('.c', '.h', or '.info') files. With '--enable-maintainer-mode' it may +also be necessary to 'touch' first 'aclocal.m4', then 'configure' and +'config.h.in' (or 'c-auto.in'), and finally all 'Makefile.in' files. + + +File: tlbuild.info, Node: Top-level directories, Next: Autoconf macros, Prev: Build system tools, Up: Layout and infrastructure + +6.2 Top-level directories +========================= + +Here is a brief description of the top-level directories in the TeX Live +source tree. + + As mentioned at the beginning of *note Overview of build system::, +the main source directories are 'texk/' (TeX-specific programs and +libraries), 'utils/' (additional programs), and 'libs/' (generic +libraries). + + In addition, the top-level directories 'am/' and 'm4/' contain +'Makefile.am' fragments and Autoconf macros, respectively, used in many +places. Specifically, the file 'm4/kpse-pkgs.m4' contains lists of all +program and library modules; missing modules are silently ignored. +(This helps in creating cut-down source trees.) + + Each module contributes fragments (in separate files) defining its +capabilities and requirements to the 'configure.ac' scripts at the +top-level and in the subdirectories 'libs', 'utils', and 'texk'. The +fragments from program modules supply 'configure' options to disable or +enable building them; those from library modules specify if an installed +(system) version of that library can be used. This ultimately +determines which modules need to be built--although all modules must be +configured for the benefit of 'make' targets such as 'dist' or +'distcheck'. + + The top-level 'build-aux/' directory contains the common files +'compile', 'config.guess', 'config.sub', 'depcomp', etc. used by most +packages. These are taken from the GNU Gnulib sources +(), which in turn synchronizes with +any ultimate upstream repository. There are independent copies of some +of these in a few other places, e.g., +'libs/freetype2/freetype-*/builds/unix/'. The 'reautoconf' script does +not touch those, but a TL cron job keeps them in sync (nightly). + + When the top-level './Build' script is used to build TL, two more two +more top-level directories appear: 'Work/' for the build tree, and +'inst/' for the install tree (from 'make install'). These names (and +everything else about 'Build''s operation) can be changed by setting +environment variables before running it; see the script source. + + +File: tlbuild.info, Node: Autoconf macros, Next: Library modules, Prev: Top-level directories, Up: Layout and infrastructure + +6.3 Autoconf macros +=================== + +Here we describe a few of the Autoconf macros used in several +modules--many more are defined in the sources; see the top-level 'm4/' +directory. These general macros are supplemented by module-specific +macros in directories such as 'texk/dvipng/m4/'; some of those are +described in following sections (*note Library modules:: and *note +Program modules::). + +* Menu: + +* Setup: General setup macros. +* Programs: Macros for programs. +* Compilers: Macros for compilers. +* Libraries: Macros for libraries. +* Flags: Macros for library and header flags. +* Windows: Macros for Windows. + + +File: tlbuild.info, Node: General setup macros, Next: Macros for programs, Up: Autoconf macros + +6.3.1 General setup macros +-------------------------- + +The TL sources use two general setup macros: + + -- Macro: KPSE_BASIC (NAME, [MORE-OPTIONS]) + Initialize the basic TL infrastructure for module NAME: + 'AM_INIT_AUTOMAKE([foreign MORE-OPTIONS])' + 'AM_MAINTAINER_MODE' + 'KPSE_COMPILER_WARNINGS' + and make sure the C compiler understands function prototypes. This + is used for all generic library and program modules. + + -- Macro: KPSE_COMMON (NAME, [MORE-OPTIONS]) + Like 'KPSE_BASIC' but add: + 'LT_PREREQ([2.2.6])' + 'LT_INIT([win32-dll])' + 'AC_SYS_LARGEFILE' + 'AC_FUNC_FSEEKO' + along with checks for frequently used functions, headers, types, + and structures. This is used for TeX-specific modules. + + +File: tlbuild.info, Node: Macros for programs, Next: Macros for compilers, Prev: General setup macros, Up: Autoconf macros + +6.3.2 Macros for programs +------------------------- + +Macros for program checks: + + -- Macro: KPSE_CHECK_LATEX + Set 'LATEX' to the first of 'latex', 'elatex', or 'lambda' which + exists in 'PATH', or to 'no' if none of them exists. Call + 'AC_SUBST' for 'LATEX'. The result of this test can be overridden + by setting the 'LATEX' environment variable or the cache variable + 'ac_cv_prog_LATEX'. + + -- Macro: KPSE_CHECK_PDFLATEX + Check for 'pdflatex' in 'PATH' and set 'PDFLATEX'. + + -- Macro: KPSE_CHECK_PERL + Check for 'perl' or 'perl5' in 'PATH' and set 'PERL'. + + -- Macro: KPSE_PROG_LEX + Call 'AC_PROG_LEX' and add the flag '-l' for 'flex'. + + +File: tlbuild.info, Node: Macros for compilers, Next: Macros for libraries, Prev: Macros for programs, Up: Autoconf macros + +6.3.3 Macros for compilers +-------------------------- + +Macros for compiler-related checks: + + -- Macro: KPSE_COMPILER_WARNINGS + When using the (Objective) C/C++ compiler, set + 'WARNING_[OBJ]C[XX]FLAGS' to suitable warning flags (depending on + the value given to or implied for '--enable-compiler-warnings'). + Call 'AC_SUBST' for them. At present this assumes GNU compiler + warning options, but could be extended to others if necessary. + + This macro caches its results in the 'kpse_cv_warning_cflags', ... + variables. + + -- Macro: KPSE_COMPILER_VISIBILITY + When using the C or C++ compiler, try to set + 'VISIBILITY_C[XX]FLAGS' to flags to hide external symbols. Call + 'AC_SUBST' for this variable. At present this only tests for the + compiler option '-fvisibility=hidden', but could be extended if + necessary. + + This macro caches its results in the 'kpse_cv_visibility_cflags' or + 'kpse_cv_visibility_cxxflags' variable. + + -- Macro: KPSE_CXX_HACK + Provide the configure option '--enable-cxx-runtime-hack'. If + enabled and when using 'g++', try to statically link with + 'libstdc++', notably improving portability of the resulting binary. + + This macro caches its result in the 'kpse_cv_cxx_hack' variable. + + +File: tlbuild.info, Node: Macros for libraries, Next: Macros for library and header flags, Prev: Macros for compilers, Up: Autoconf macros + +6.3.4 Macros for libraries +-------------------------- + +One macro for a library check: + + -- Macro: KPSE_LARGEFILE (VARIABLE, [EXTRA-DEFINE]) + Call 'AC_SYS_LARGEFILE' and 'AC_FUNC_FSEEKO' and append suitable + '-D' flags (optionally including '-DEXTRA-DEFINE') to VARIABLE. + + +File: tlbuild.info, Node: Macros for library and header flags, Next: Macros for Windows, Prev: Macros for libraries, Up: Autoconf macros + +6.3.5 Macros for library and header flags +----------------------------------------- + +Each library module 'libs/LIB' or 'texk/LIB' is supplemented by a macro +'KPSE_LIB_FLAGS' (all uppercase) that provides make variables for that +library. E.g., for 'libs/libpng': + + -- Macro: KPSE_LIBPNG_FLAGS + Provide the configure option '--with-system-libpng'. Set and + 'AC_SUBST' 'make' variables for modules using this library (either + an installed version or from the TeX Live tree): + + 'LIBPNG_INCLUDES' for use in 'CPPFLAGS', + 'LIBPNG_LIBS' for use in 'LDADD', + 'LIBPNG_DEPEND' for use as a Makefile dependency, + 'LIBPNG_RULE' for the 'make' rules to rebuild the library. + + -- Macro: KPSE_ADD_FLAGS (NAME) + Temporarily extend 'CPPFLAGS' and 'LIBS' with the values required + for the library module 'NAME'. + + -- Macro: KPSE_RESTORE_FLAGS + Restore 'CPPFLAGS' and 'LIBS' to their original values. + + As an example, the 'configure.ac' file for a hypothetical program +'utils/foo' using 'libpng', and hence 'zlib', would contain + KPSE_ZLIB_FLAGS + KPSE_LIBPNG_FLAGS + +and its 'Makefile.am' would be along these lines: + bin_PROGRAMS = foo + AM_CPPFLAGS = ${LIBPNG_INCLUDES} ${ZLIB_INCLUDES} + foo_LDADD = ${LIBPNG_LIBS} ${ZLIB_LIBS} + foo_DEPENDENCIES = ${ZLIB_DEPEND} ${LIBPNG_DEPEND} + ## Rebuild libz + @ZLIB_RULE@ + ## Rebuild libpng + @LIBPNG_RULE@ + + If it were necessary to examine whether certain 'zlib' or 'libpng' +features were available, 'configure.ac' should be continued this way: + KPSE_ADD_FLAGS([zlib]) + ... # tests for 'zlib' features, if any + KPSE_ADD_FLAGS([libpng]) + ... # tests for 'libpng' features + KPSE_RESTORE_FLAGS # restore 'CPPFLAGS' and 'LIBS' + + +File: tlbuild.info, Node: Macros for Windows, Prev: Macros for library and header flags, Up: Autoconf macros + +6.3.6 Macros for Windows +------------------------ + +Windows differs in several aspects from Unix-like systems, many of them +due to the lack of symbolic links. + + -- Macro: KPSE_CHECK_WIN32 + Check if compiling for a Windows system. The result is either 'no' + for Unix-like systems (including Cygwin), 'mingw32' for Windows + with GCC, or 'native' for Windows with MSVC. The result is cached + in the 'kpse_cv_have_win32' variable. + + -- Macro: KPSE_COND_WIN32 + Call 'KPSE_CHECK_WIN32' and define the Automake conditional 'WIN32' + ('true' if the value of 'kpse_cv_have_win32' is not 'no'). + + -- Macro: KPSE_COND_MINGW32 + Call 'KPSE_COND_WIN32' and define the Automake conditional + 'MINGW32' ('true' if the value of 'kpse_cv_have_win32' is + 'mingw32'). + + -- Macro: KPSE_COND_WIN32_WRAP + Call 'KPSE_COND_WIN32' and define the Automake conditional + 'WIN32_WRAP' ('true' if the standard Windows wrapper + ('texk/texlive/w32_wrapper/runscript.exe') exists. This wrapper is + used on Windows instead of symlinks for the "linked scripts" (*note + Linked scripts::). + + -- Macro: KPSE_WIN32_CALL + Call 'KPSE_COND_WIN32' and check if the file + 'texk/texlive/w32_wrapper/callexe.c' exists; if it does, create a + symlink in the build tree. Compiling 'callexe.c' with + '-DEXEPROG='"FOO.exe"'' and installing 'callexe.exe' as 'BAR.exe' + is used on Windows instead of a symlink 'BAR->FOO' for Unix-like + systems. + + +File: tlbuild.info, Node: Library modules, Next: Program modules, Prev: Autoconf macros, Up: Layout and infrastructure + +6.4 Library modules +=================== + +Here we discuss some specifics for a few of the libraries in TL, both +for the details themselves, and as a way of illuminating the general +structure and variation. + +* Menu: + +* 'png' library:: 'libs/libpng' +* 'zlib' library:: 'libs/zlib' +* 'freetype' library:: 'libs/freetype2' +* 'kpathsea' library:: 'texk/kpathsea' + + +File: tlbuild.info, Node: 'png' library, Next: 'zlib' library, Up: Library modules + +6.4.1 The 'png' library in 'libs/libpng' +---------------------------------------- + +The "generic" 'png' library uses the source tree in the subdirectory +'libpng-src/', with all modifications for TL recorded in 'TLpatches/*'. +The 'configure.ac' fragment 'ac/withenable.ac' contains + + KPSE_WITH_LIB([libpng], [zlib]) + +to specify the module name and indicate the dependency on 'zlib'. A +third literal argument ''tree'' would specify that the library from the +TeX Live tree cannot be replaced by a system version. That not being +the case here, a second fragment 'ac/libpng.ac' contains + + KPSE_TRY_LIB([libpng], + [#include ], + [png_structp png; png_voidp io; png_rw_ptr fn; + png_set_read_fn(png, io, fn);]) + +thus providing the simple C code + + #include + int main () + { png_structp png; png_voidp io; png_rw_ptr fn; + png_set_read_fn(png, io, fn); + return 0; } + +which Autoconf uses to verify the usability of a system version with C +code. The analogous macro 'KPSE_TRY_LIBXX' would check using C++. +These fragments are included by the 'configure.ac' at the top level of +TL ('Build/source/configure.ac'). + + For this library, like many other modules, a proxy build system for +TL is used, consisting of our own 'configure.ac', 'Makefile.am', +'include/Makefile.am'; the distributed build system is not used. +(Consequently, a few generated files and auxiliary scripts are removed +from the distributed source tree.) + + The public headers 'png.h', 'pngconf.h', and 'pnglibconf.h' are +"installed" (as symlinks) under 'include/' in the build tree exactly as +they are for a system version under, e.g., '/usr/include/'. + + The module is supplemented by the file 'm4/kpse-libpng-flags.m4' that +defines the M4 macro 'KPSE_LIBPNG_FLAGS' used by all modules depending +on this library in their 'configure.ac' to generate the 'make' variables +'LIBPNG_INCLUDES' for use in 'CPPFLAGS', 'LIBPNG_LIBS' for use in +'LDADD', 'LIBPNG_DEPEND' for use as dependencies, and 'LIBPNG_RULE' for +the 'make' rules to rebuild the library. + + 'm4/kpse-libpng-flags.m4' also supplies the configure option +'--with-system-libpng', which then uses 'pkg-config' to determine the +flags required for the system library. + + +File: tlbuild.info, Node: 'zlib' library, Next: 'freetype' library, Prev: 'png' library, Up: Library modules + +6.4.2 The 'zlib' library in 'libs/zlib' +--------------------------------------- + +This generic library is very much analogous to 'libpng', but without the +dependency on any other library. The file 'm4/kpse-zlib-flags.m4' +supplies the configure option '--with-system-zlib', as well as +'--with-zlib-includes' and '--with-zlib-libdir' to specify non-standard +locations of the 'zlib' headers and/or library. + + +File: tlbuild.info, Node: 'freetype' library, Next: 'kpathsea' library, Prev: 'zlib' library, Up: Library modules + +6.4.3 The 'freetype' library in 'libs/freetype2' +------------------------------------------------ + +This module uses a wrapper build system. In contrast to the proxy build +described earlier, the wrapper build has an almost trivial +'configure.ac' and a 'Makefile.am' which invokes the 'configure' and +'make' in the distributed source, followed by 'make install' with the TL +build tree as destination. In other words, this actually uses the build +system provided by upstream (possibly patched). + + The flags required for the system library are obtained through +'freetype-config'. + + +File: tlbuild.info, Node: 'kpathsea' library, Prev: 'freetype' library, Up: Library modules + +6.4.4 The 'kpathsea' library in 'texk/kpathsea' +----------------------------------------------- + +This is one of the TeX-specific libraries that are maintained as part of +TeX Live (*note (kpathsea)::); the other is 'ptexenc'. These TeX +libraries are Libtool libraries (static and/or shared) and are installed +by 'make install' together with the programs. They are, however, not +part of the TL DVD as distributed by TeX user groups, and have never +been officially released for standalone use. + + It is possible, and probably useful for distro builds (*note Distro +builds::), to specify the configure option '--with-system-kpathsea' in +order to use a system version of the library. Programs outside the TL +tree should use 'pkg-config' for the required flags. + + In addition to 'kpathsea/ac/withenable.ac' and +'kpathsea/ac/kpathsea.ac' here there is a third fragment +'kpathsea.ac/mktex.ac', included by both 'withenable.ac' and +'configure.ac', which supplies configure options such as +'--enable-mktextfm-default'. These determine the compile time default +of whether or not to run 'mktextfm' (and similar) to generate a missing +'.tfm' (or whatever) file. In any case, however, the command line +options '-mktex=tfm' or '-no-mktex=tfm' for the TeX-like engines +override this default. + + +File: tlbuild.info, Node: Program modules, Next: Extending TeX Live, Prev: Library modules, Up: Layout and infrastructure + +6.5 Program modules +=================== + +As with libraries (*note Library modules::), here we discuss the details +for a few of the programs in TL. + +* Menu: + +* 't1utils' package:: 'utils/t1utils' +* 'xindy' package:: 'utils/xindy' +* 'xdvik' package:: 'texk/xdvik' +* 'asymptote':: 'utils/asymptote' + + +File: tlbuild.info, Node: 't1utils' package, Next: 'xindy' package, Up: Program modules + +6.5.1 The 't1utils' package in 'utils/t1utils' +---------------------------------------------- + +Here we use the distributed source tree 't1utils-src' with modifications +documented in 'TLpatches/*' and a proxy build system consisting of +'configure.ac' and 'Makefile.am'. The fragment 'ac/withenable.ac' +contains + + KPSE_ENABLE_PROG([t1utils]) + +specifying the module name without any dependencies, and supplies the +configure option '--disable-t1utils'. + + +File: tlbuild.info, Node: 'xindy' package, Next: 'xdvik' package, Prev: 't1utils' package, Up: Program modules + +6.5.2 The 'xindy' package in 'utils/xindy' +------------------------------------------ + +This module uses the distributed source tree 'xindy-src/' with +modifications documented in 'TLpatches/*', and a wrapper 'configure.ac' +and 'Makefile.am' that descends into 'xindy-src'. + + The 'xindy' build requires a 'make' that supports a 'VPATH' build, +can handle all targets, and do not refer to '${top_srcdir}' or +'${top_builddir}'. The fragment 'xindy/ac/withenable.ac' contains + + KPSE_ENABLE_PROG([xindy], , [disable]) + m4_include(kpse_TL[utils/xindy/ac/xindy.ac]) + m4_include(kpse_TL[utils/xindy/ac/clisp.ac]) + +where 'disable' in the third argument indicates that 'xindy' is only +built if explicitly enabled by the user with 'configure --enable-xindy' +(the need for 'clisp' makes it too painful to enable by default). + + The additional fragments 'ac/xindy.ac' and 'ac/clisp.ac' specify more +'configure' options to be seen at the top level, with 'ac/xindy.ac' also +included by 'configure.ac'. + + +File: tlbuild.info, Node: 'xdvik' package, Next: 'asymptote', Prev: 'xindy' package, Up: Program modules + +6.5.3 The 'xdvik' package in 'texk/xdvik' +----------------------------------------- + +This package is maintained as part of the TeX Live tree with sources in +its own directory ('texk/xdvik/'). The fragment +'xdvik/ac/withenable.ac' contains + + dnl extra_dirs = texk/xdvik/squeeze + KPSE_ENABLE_PROG([xdvik], [kpathsea freetype2], [x]) + m4_include(kpse_TL[texk/xdvik/ac/xdvik.ac]) + +thus specifying dependencies on the 'kpathsea', 'freetype', and X11 +libraries. The M4 comment (following 'dnl') signals the subsidiary +'squeeze/configure.ac'. This is needed because the main executable +'xdvi-bin' (to be installed as, e.g., 'xdvi-xaw') is for the 'host' +system whereas the auxiliary program 'squeeze/squeeze' has to run on the +'build' system; in a cross compilation, these differ. + + The additional fragment 'ac/xdvik.ac' is also included by +'configure.ac' and supplies the configure option '--with-xdvi-x-toolkit' +also seen at the top level. + + +File: tlbuild.info, Node: 'asymptote', Prev: 'xdvik' package, Up: Program modules + +6.5.4 The subdirectory 'utils/asymptote' +---------------------------------------- + +This subdirectory contains the sources for 'asy' and 'xasy' but due to +its complexity and prerequisites (e.g., OpenGL) it is not part of the TL +build system. These programs must be built and installed independently, +but are included on the TL DVD together with their support files. See +. + + +File: tlbuild.info, Node: Extending TeX Live, Prev: Program modules, Up: Layout and infrastructure + +6.6 Extending TeX Live +====================== + +This section outlines the basic process for adding new packages to the +TL build system. + + In any case, a new package directory 'foo' should contain the +original sources, modified only with changes necessary for TL, in +'foo/foo-src'. The changes should be documented in 'foo/TLpatches/*', +and also be submitted upstream whenever reasonable. In addition, 'foo/' +will need the usual Automake build-related files ('configure.ac', +'Makefile.am', etc. Please maintain 'foo/ChangeLog' for all TL changes. + +* Menu: + +* Adding a new program module:: +* Adding a new generic library module:: +* Adding a new TeX-specific library module:: + + +File: tlbuild.info, Node: Adding a new program module, Next: Adding a new generic library module, Up: Extending TeX Live + +6.6.1 Adding a new program module +--------------------------------- + +A TeX-specific program module in a subdirectory 'texk/PROG' may use the +TeX-specific libraries and is included by adding its name 'PROG' to the +M4 list 'kpse_texk_pkgs' defined in 'm4/kpse-pkgs.m4'. + + A generic program module in a subdirectory 'utils/PROG' must not use +the TeX-specific libraries and is included by adding its name 'PROG' to +the M4 list 'kpse_utils_pkgs' in 'm4/kpse-pkgs.m4'. + + In either case, the subdirectory 'texk/PROG' or 'utils/PROG' must +provide a fragment 'ac/withenable.ac' that contains the M4 macro +'KPSE_ENABLE_PROG' defined in 'm4/kpse-setup.m4' with 'PROG' as the +mandatory first argument and three optional arguments: + + 1. a list of required libraries from the TL tree; + + 2. a list of options: 'disable' if this module is not to be built + without the configure option '--enable-PROG', 'native' if cross + compilation is not possible, 'x' if the program requires X11 + libraries; + + 3. a comment added to the help text for the 'configure' option + '--enable-PROG' or '--disable-PROG'. + + If the module requires specific 'configure' options to be seen at the +top level, they should be defined in an additional fragment 'ac/PROG.ac' +included from 'ac/withenable.ac' and 'configure.ac'. + + Usually, the new program is maintained somewhere outside of TeX Live. +In that case, as above, we put the upstream sources into a subdirectory +'PROG-src' (e.g., 'utils/newprog/newprog-src'). We do not typically run +'configure' in this original '...-src' directory, but only in our own +directory; but we do compile using the source files in '...-src'. + + So, to summarize the files that must (usually) be created inside a +new TL source directory ('texk/newprog' or 'utils/newprog'): + +'ac/withenable.ac' + The 'KPSE_ENABLE_PROG' call just explained. + +'configure.ac' +'Makefile.am' + By merging the contents of the original 'configure.ac' (if + provided) and a comparable program already in TL. In the above + example, one line that will be needed in 'configure.ac' (can be + added before the 'AC_CONFIG_FILES' at the end) is: + + AC_SUBST([NEWPROG_TREE], [newprog-src]) + + and then use '@NEWPROG_TREE@' in 'Makefile.am' where needed. + + In general, there is no magic recipe for this part of the job. + It's necessary to think about what needs to be done in the original + vs. in TeX Live. It's useful to look at the setup for the most + comparable programs already in TL that you can find. It's also + useful to grep the entire 'Build/source' tree for whatever you can + think of to investigate how something is done. Most of the + TL-specific macros are defined in 'Build/source/m4/*'. + +'TLpatches/TL-Changes' + First actions taken after getting the original source tree; + typically removal of derived or unused common files. + +'TLpatches/patch-...' + If any changes are needed to the original sources, record the + patches here so they can be applied next time. Also, send them + upstream so that we don't have to maintain them forever. + +'ChangeLog' + Record all TL-specific changes, now and in the future. + + After populating the new TL source directory ('.../newprog/', in the +above), run GNU 'autoreconf' there (*note Build system tools::). Once +that works, if you are the one who's eventually going to commit the new +package, 'svn add' the necessary files, including the generated +'Makefile.in aclocal.m4 configure', and 'svn:ignore' the Automake cache +'autom4te.cache'. (This is so people checking out the TL source tree do +not have to run any autotools, but can simply run 'configure'.) + + To reiterate: do not fail to commit the generated 'configure' and +other files. The m4 code in 'kpse-pkgs.m4' uses the existence of +'configure' to determine whether to descend into (and configure) a given +subdirectory. + + Then, run the TL tool 'reautoconf' in the top-level TL +'Build/source/' directory, to incorporate the new program into the build +tree. It is good to then rebuild the whole tree (e.g., using TL's +'Build/Build' script) to get all the necessary files generated. + + It will probably fail. So then you need to keep at it until the +program compiles and tests successfully. The most efficient way is to +rerun 'autoreconf' as needed in the new source directory +('Build/source/.../newprog'), then 'make' in the corresponding build +directory ('Build/work/.../newprog'), then 'make check', etc. In the +end, also make sure that the whole tree builds from scratch. + + After final success, don't forget to commit. (Or email the TL +maintainers with the patch.) + + Caveat: adding a new TeX engine is not completely different, but it's +not all that similar, either. In that case, the work is done inside a +new subdirectory of 'texk/web2c/'. Many things are common to all the +engines, other things need to be copied and possibly modified for each +one, yet others are unique to each. No general recipe is possible. + + +File: tlbuild.info, Node: Adding a new generic library module, Next: Adding a new TeX-specific library module, Prev: Adding a new program module, Up: Extending TeX Live + +6.6.2 Adding a new generic library module +----------------------------------------- + +A generic library module in a subdirectory 'libs/LIB' must not depend on +TeX-specific libraries, by definition. It is included by adding its +name 'LIB' to the M4 macro 'kpse_libs_pkgs' in 'm4/kpse-pkgs.m4'--before +any other libraries from the TeX Live tree on which it depends. + + As with program modules, the subdirectory 'libs/LIB' must contain the +sources and build system for the library (and any installable support +programs) and a fragment 'ac/withenable.ac' that contains the M4 macro +'KPSE_WITH_LIB' defined in 'm4/kpse-setup.m4' with 'LIB' as the +mandatory first argument and two optional arguments: a list of required +libraries from the TL tree, and a list of options: for libraries, +currently there is only one--specify 'tree' if this library cannot be +replaced by a system version. + + If a system version can be used, a second fragment 'ac/LIB.ac' is +needed, containing the M4 macro 'KPSE_TRY_LIB' (or 'KPSE_TRY_LIBXX') +with 'LIB' as the mandatory first argument and two additional arguments +for the Autoconf macro 'AC_LANG_PROGRAM' used to compile and link a +small C (or C++) program as sanity check for using the system library. + + In addition a file 'm4/kpse-LIB-flags' (at the top level) must define +the M4 macro 'KPSE_LIB_FLAGS' (all uppercase) setting up the 'make' +variables 'LIB_INCLUDES', 'LIB_LIBS', 'LIB_DEPEND', and 'LIB_RULE' with +the values required for 'CPPFLAGS', 'LDADD', dependencies, and a +(multi-line) 'make' rule to rebuild the library when necessary. All of +that is needed for the library from the TL tree and, if supported, for a +system version. + + If a system library is allowed, 'KPSE_LIB_FLAGS' also provides the +configure option '--with-system-LIB' and uses the additional M4 macro +'KPSE_LIB_SYSTEM_FLAGS' to generate the 'make' variables for a system +library. In addition, the definition of the M4 macro +'KPSE_ALL_SYSTEM_FLAGS' in 'm4/kpse-pkgs.m4' must be extended by the +line: + 'AC_REQUIRE([KPSE_LIB_SYSTEM_FLAGS])' + + +File: tlbuild.info, Node: Adding a new TeX-specific library module, Prev: Adding a new generic library module, Up: Extending TeX Live + +6.6.3 Adding a new TeX-specific library module +---------------------------------------------- + +A TeX-specific library module in a subdirectory 'texk/LIB' may depend on +other TeX-specific libraries but must not depend on any generic library +from the TL tree. It is included in the same general ways as a generic +library (see the previous section), with these modifications: + + * The library name 'LIB' is added to the M4 macro + 'kpse_texlibs_pkgs', which is also in 'm4/kpse-pkgs.m4'. + + * The fragment 'ac/withenable.ac' must use 'KPSE_WITH_TEXLIB'. + + +File: tlbuild.info, Node: Configure options, Next: Coding conventions, Prev: Layout and infrastructure, Up: Top + +7 Configure options +******************* + +Corresponding to the large number of program and library modules there +are a large number 'configure' options, most of which are described +here. The command + 'configure --help' +at the top level gives an exhaustive list of all global options and a +few important module-specific ones, whereas, e.g., + 'texk/lcdf-typetools/configure --help' +also displays the 'lcdf-typetools' specific options, which are not shown +at the top level. + + The help text also mentions several influential environment +variables, but for TeX Live it is better to specify them as assignments +on the command line. + + The './Build' script used to make the binaries shipped with TeX Live +invokes the top-level 'configure' with a few additional options (*note +Building::). The defaults discussed below are those for the actual +'configure' script; invoking 'configure' via './Build' yields different +results. + + Defaults for most options are set at the top level and propagated +explicitly to all subdirectories. Options specified on the command line +are checked for consistency but never modified. + +* Menu: + +* Global configure options:: +* Program-specific configure options:: +* Library-specific configure options:: +* Variables for configure:: + + +File: tlbuild.info, Node: Global configure options, Next: Program-specific configure options, Up: Configure options + +7.1 Global configure options +============================ + +Here are the global configure options. + +* Menu: + +* '--disable-native-texlive-build':: +* '--prefix' '--bindir' ...:: +* '--disable-largefile':: +* '--disable-missing':: +* '--enable-compiler-warnings='LEVEL:: +* '--enable-cxx-runtime-hack':: +* '--enable-maintainer-mode':: +* '--enable-multiplatform':: +* '--enable-shared':: +* '--enable-silent-rules':: +* '--without-ln-s':: +* '--without-x':: + + +File: tlbuild.info, Node: '--disable-native-texlive-build', Next: '--prefix' '--bindir' ..., Up: Global configure options + +7.1.1 '--disable-native-texlive-build' +-------------------------------------- + +If enabled (the default), build for a TL binary distribution as shipped +by the TeX user groups. This requires GNU 'make' and implies +'--enable-multiplatform' and '--enable-cxx-runtime-hack' (unless they +are explicitly disabled), and enforces '--disable-shared'. + + If building TL for a GNU/Linux or other distribution, this should be +disabled and system versions of most libraries should be used (*note +Distro builds::). + + A related option, '--enable-texlive-build', is automatically passed +to all subdirectories (and cannot be disabled). Subdirectories that can +also be built independently from the TL tree (such as 'utils/xindy' and +'texk/dvipng') but cooperate with TL can use this option to enable +TL-specific adaptations, such as installation paths. + + +File: tlbuild.info, Node: '--prefix' '--bindir' ..., Next: '--disable-largefile', Prev: '--disable-native-texlive-build', Up: Global configure options + +7.1.2 '--prefix', '--bindir', ... +--------------------------------- + +These standard Autoconf options specify various installation directories +as usual. For the complete list, *note Installation directories::. + + Also as usual, all values are prefixed by the value of 'DESTDIR', if +set, on the 'make' command line (*note Installation in a temporary +location: (automake)Staged Installs.). + + +File: tlbuild.info, Node: '--disable-largefile', Next: '--disable-missing', Prev: '--prefix' '--bindir' ..., Up: Global configure options + +7.1.3 '--disable-largefile' +--------------------------- + +Omit large file support (LFS), which is needed on most 32-bit Unix +systems for files with 2GB or more. Regardless of this option, the size +of 'DVI' and 'GF' files must always be <2GB, due to the file format +specifications. + + With LFS, there is no fixed limit on the size of PDF files created by +'pdftex' or PostScript files created by 'dvips'. + + +File: tlbuild.info, Node: '--disable-missing', Next: '--enable-compiler-warnings='LEVEL, Prev: '--disable-largefile', Up: Global configure options + +7.1.4 '--disable-missing' +------------------------- + +Immediately terminate the build process if a requested program or +feature must be disabled, e.g., due to missing libraries. This can help +when figuring out a specific (sub)set of modules to enable. + + +File: tlbuild.info, Node: '--enable-compiler-warnings='LEVEL, Next: '--enable-cxx-runtime-hack', Prev: '--disable-missing', Up: Global configure options + +7.1.5 '--enable-compiler-warnings='LEVEL +---------------------------------------- + +Enable various levels of compiler warnings for C, C++, and/or +Objective C: the LEVEL value can be one of: 'no min yes max all'. The +default is 'yes' in 'maintainer-mode' (see below) and 'min' otherwise. +This option defines the variables 'WARNING_[OBJ]C[XX]FLAGS', but these +variables are not consistently used in all library and program modules. +At present, these warning flags assume options from the GNU compilers. + + +File: tlbuild.info, Node: '--enable-cxx-runtime-hack', Next: '--enable-maintainer-mode', Prev: '--enable-compiler-warnings='LEVEL, Up: Global configure options + +7.1.6 '--enable-cxx-runtime-hack' +--------------------------------- + +If enabled (as it is for the native TL build), when using 'g++', try to +statically link with 'libstdc++', thus improving portability of the +resulting binary. *Note Macros for compilers::. + + +File: tlbuild.info, Node: '--enable-maintainer-mode', Next: '--enable-multiplatform', Prev: '--enable-cxx-runtime-hack', Up: Global configure options + +7.1.7 '--enable-maintainer-mode' +-------------------------------- + +Enable 'make' rules and dependencies not useful (and sometimes +confusing) to the casual user. This requires current versions of the +GNU build tools (*note Build system tools::), as it automatically +rebuilds infrastructure files as needed. *Note 'missing' and +'AM_MAINTAINER_MODE': (automake)maintainer-mode. + + +File: tlbuild.info, Node: '--enable-multiplatform', Next: '--enable-shared', Prev: '--enable-maintainer-mode', Up: Global configure options + +7.1.8 '--enable-multiplatform' +------------------------------ + +If enabled (as it is for the native TL build) and '--bindir=DIR' or +'--libdir=DIR' are not specified, install executables and libraries in +per-platform subdirectories of 'EPREFIX/bin' and 'EPREFIX/lib' where +EPREFIX is the value given or implied for 'exec_prefix'. In any case, +the values for 'bindir' and 'libdir' are automatically propagated to all +subdirectories. + + +File: tlbuild.info, Node: '--enable-shared', Next: '--enable-silent-rules', Prev: '--enable-multiplatform', Up: Global configure options + +7.1.9 '--enable-shared' +----------------------- + +Build shared versions of the TeX-specific libraries such as +'libkpathsea'. This is not allowed for a native TL build (i.e., +'--disable-native-texlive-build' must also be specified). + + +File: tlbuild.info, Node: '--enable-silent-rules', Next: '--without-ln-s', Prev: '--enable-shared', Up: Global configure options + +7.1.10 '--enable-silent-rules' +------------------------------ + +Enable the use of less verbose build rules. When using GNU 'make' (or +any 'make' implementation supporting nested variable expansions), you +can specify 'V=1' on the 'make' command line to get more verbosity, or +'V=0' to get less, regardless of this option. + + +File: tlbuild.info, Node: '--without-ln-s', Next: '--without-x', Prev: '--enable-silent-rules', Up: Global configure options + +7.1.11 '--without-ln-s' +----------------------- + +Required when using a system without a working 'ln -s' to build binaries +for a Unix-like system. However, 'make install' will not create +anything useful, and might fail. + + +File: tlbuild.info, Node: '--without-x', Prev: '--without-ln-s', Up: Global configure options + +7.1.12 '--without-x' +-------------------- + +Disable all programs using the X Window System. + + +File: tlbuild.info, Node: Program-specific configure options, Next: Library-specific configure options, Prev: Global configure options, Up: Configure options + +7.2 Program-specific configure options +====================================== + +Here are (some of) the program-specific 'configure' options. + +* Menu: + +* '--enable-PROG' '--disable-PROG':: +* '--disable-all-pkgs':: +* Configure options for 'texk/web2c':: +* Configure options for 'texk/bibtex-x':: +* Configure options for 'texk/dvipdfm-x':: +* Configure options for 'texk/dvisvgm':: +* Configure options for 'texk/texlive':: +* Configure options for 'texk/xdvik':: +* Configure options for 'utils/xindy':: + + +File: tlbuild.info, Node: '--enable-PROG' '--disable-PROG', Next: '--disable-all-pkgs', Up: Program-specific configure options + +7.2.1 '--enable-PROG', '--disable-PROG' +--------------------------------------- + +Do or do not build and install the program(s) of module 'PROG'. + + +File: tlbuild.info, Node: '--disable-all-pkgs', Next: Configure options for 'texk/web2c', Prev: '--enable-PROG' '--disable-PROG', Up: Program-specific configure options + +7.2.2 '--disable-all-pkgs' +-------------------------- + +Do not build any program modules by default--only those explicitly +enabled. This is useful when one wants to work on only a single +program, which is specified with an additional '--enable' option, e.g., +'--enable-dvipdfm-x'. It's still simplest to check out and configure +the whole source tree, but at least only the program you are interested +in, and its dependencies, are built. *Note Build one package::. + + Without this option, all modules are built except those that are +explicitly disabled or specify 'disable' in their 'ac/withenable.ac' +fragment. + + +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 + +7.2.3 Configure options for 'texk/web2c' +---------------------------------------- + +'--with-banner-add=STR' +Add 'STR' to the default version string (which is ''TeX Live YEAR'' or +''Web2C YEAR'') appended to banner lines. This is ignored for a native +TL build, but distro builds should specify, e.g., '/SOMEDISTRO'. + +'--with-editor=CMD' +Specify the command 'CMD' to invoke from the 'e' option of TeX and +friends, replacing the default 'vi +%d '%s'' for Unix or 'texworks +--position=%d "%s"' for Windows. + +'--with-fontconfig-includes=DIR', '--with-fontconfig-libdir=DIR' +Building XeTeX on non-Mac systems requires the 'fontconfig' library +headers and code. If one or both of these options are given, the +required flags are derived from them; otherwise, they are determined via +'pkg-config' (if present). + +'--with-mf-x-toolkit' +Use the X toolkit ('libXt') for Metafont (the default is to use the +lowest-level 'Xlib' support; it seems this has the best chance of +working across X installations nowadays). + +'--disable-dump-share' +Make the 'fmt'/'base' dump files architecture dependent (somewhat faster +on LittleEndian architectures). + +'--disable-ipc' +Disable TeX's '--ipc' option. + +'--disable-mf-nowin' +Do not build a separate non-graphically-capable Metafont ('mf-nowin'). + +'--disable-tex', '--enable-etex', ... +Do not or do build the various TeX, Metafont, and MetaPost engines +(defaults are defined in the fragment 'texk/web2c/ac/web2c.ac'). + +'--disable-web-progs' +Do not build the original WEB programs 'bibtex', ..., 'weave'. Useful +if, e.g., you only want to (re)build some engines. + +'--enable-auto-core' +This option causes TeX and Metafont to produce a core dump when a +particular hacky filename is encountered, for use in creating preloaded +binaries. This is rarely done nowadays. + +'--enable-libtool-hack' +If enabled (which is the default for all platforms), prevents 'libtool' +from linking explicitly with dependencies of 'libfontconfig' such as +'libexpat'. + +'--enable-*win' +Include various types of non-X window support for Metafont (EPSF output, +'mftalk', old graphics terminals, ...). + +'--enable-tex-synctex', '--disable-etex-synctex', ... +Build the TeX engines with or without 'SyncTeX' support; ignored for a +native TeX Live build. Defaults are defined in +'texk/web2c/ac/web2c.ac'. + +'--disable-synctex' +Do not build the 'SyncTeX' library and tool. + + +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 + +7.2.4 Configure options for 'texk/bibtex-x' +------------------------------------------- + +The programs 'bibtex8' and 'bibtexu' have been merged into the module +'bibtex-x' (extended BibTeX). + +'--disable-bibtex8' +Do not build the 'bibtex8' program. + +'--disable-bibtexu' +Do not build the 'bibtexu' program (building 'bibtexu' requires 'ICU' +libraries). + + +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 + +7.2.5 Configure options for 'texk/dvipdfm-x' +-------------------------------------------- + +The former modules 'dvipdfmx' (extended DVI to PDF converter) and +'xdvipdfmx' (the same, as used by XeTeX) have been merged into +'dvipdfm-x' at the source level. Two separate binaries are still +created by default. In addition, 'dvipdfm' is created as a symlink to +'dvipdfmx', with backward-compatible (very slightly different) behavior. + +'--disable-dvipdfmx' +Do not build the 'dvipdfmx' program or make the 'dvipdfm' symlink. + +'--disable-xdvipdfmx' +Do not build the 'xdvipdfmx' program. + + +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 + +7.2.6 Configure options for 'texk/dvisvgm' +------------------------------------------ + +'--with-system-libgs' +Build 'dvisvgm' using installed Ghostscript ('gs') headers and library +(not allowed for a native TL build). The default is to load the 'gs' +library at runtime if possible, else to disable support for PostScript +specials. + +'--without-libgs' +Build 'dvisvgm' without PostScript support at all. Because the dynamic +loading just mentioned defeats all attempts at static linking, the +result can crash due to library incompatibilities, e.g., on CentOS 5. + +'--with-libgs-includes=DIR', '--with-libgs-libdir=DIR' +Specify non-standard locations of the Ghostscript headers and library. + + +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 + +7.2.7 Configure options for 'texk/texlive' +------------------------------------------ + +'--disable-linked-scripts' +Do not install the "linked scripts" (*note Linked scripts::), except for +the TL scripts required to run 'texlinks'. + + +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 + +7.2.8 Configure options for 'texk/xdvik' +---------------------------------------- + +'--with-gs=FILENAME' +Hardwire the location of Ghostscript ('gs') as called by Xdvik. + +'--with-xdvi-x-toolkit=KIT' +Use toolkit 'KIT' for 'xdvik', one of: 'motif xaw xaw3d neXtaw'. The +default is 'motif' if available, else 'xaw'. + +'--enable-xi2-scrolling' +Use XInput 2.1 "smooth scrolling" if available (default: yes, except for +a native TL build). + + +File: tlbuild.info, Node: Configure options for 'utils/xindy', Prev: Configure options for 'texk/xdvik', Up: Program-specific configure options + +7.2.9 Configure options for 'utils/xindy' +----------------------------------------- + +'--enable-xindy-rules' +Build and install 'xindy' rules (default: yes, except for a native TL +build). + +'--enable-xindy-docs' +Build and install 'xindy' documentation (default: yes, except for a +native TL build). + +'--with-clisp-runtime=FILENAME' +Specifies the full path for the Clisp runtime file ('lisp.run' or +'lisp.exe') to be installed. When specified as 'default' (the default +for a native TL build) the path is determined by the Clisp executable; +the value 'system' (not allowed for a native TL build, but the default +otherwise) indicates that 'xindy' will use the installed version of +'clisp' (which must be identical to the one used to build 'xindy'). + + +File: tlbuild.info, Node: Library-specific configure options, Next: Variables for configure, Prev: Program-specific configure options, Up: Configure options + +7.3 Library-specific configure options +====================================== + +Here are (some of) the library-specific 'configure' options, starting +with this generic one: + +'--with-system-LIB' + + Use an installed (system) version of the library 'LIB'; this option +exists for most libraries, but is not allowed for a native TL build. +Using a system version implies also using the system versions of all +libraries that LIB depends on. + + For many libraries '--with-LIB-includes=DIR' and +'--with-LIB-libdir=DIR' can specify non-standard search locations; +others use 'pkg-config' or similar to determine the required flags. + + The top-level 'configure' script performs a consistency check for all +required system libraries and bails out if tests fail. + +* Menu: + +* Configure options for 'kpathsea':: + + +File: tlbuild.info, Node: Configure options for 'kpathsea', Up: Library-specific configure options + +7.3.1 Configure options for 'kpathsea' +-------------------------------------- + +'--enable-CMD-default', '--disable-CMD-default' +Determine the compile time default for whether or not to run CMD, which +is one of: +'mkocp' + (Omega compiled translation process file) +'mkofm' + (Omega font metrics file) +'mktexfmt' + (format/base dump file) +'mktexmf' + (Metafont source) +'mktexpk' + (PK bitmap font) +'mktextex' + (TeX source) +'mktextfm' + (TFM file) + +to generate the specified type of file dynamically. The default can be +overridden by the user in any case (*note 'kpathsea' library::). + + +File: tlbuild.info, Node: Variables for configure, Prev: Library-specific configure options, Up: Configure options + +7.4 Variables for configure +=========================== + +The values for these variables can be specified as 'configure' arguments +of the form 'VAR=VALUE'. They can also be defined in the environment, +but that might not work for cross compilations. + +'CC' +'CXX' +'CPPFLAGS' + And plenty more. As usual with Autoconf, these variables specify + the name (or full path) of compilers, preprocessor flags, and + similar. *Note (autoconf)Preset Output Variables::. + +'CLISP' + Name (or full path) of the 'clisp' executable, used to build + 'xindy'. + +'FT2_CONFIG' +'ICU_CONFIG' +'PKG_CONFIG' + These specify the name (or path) for the 'freetype-config', + 'icu-config', and 'pkg-config' commands used to determine the flags + required for system versions of 'libfreetype', the ICU libraries, + and other libraries, respectively. + +'KPSEWHICH' + Name (or path) of an installed 'kpsewhich' binary, used by 'make + check' to determine the location of, e.g., 'cmbx10.tfm'. + +'MAKE' +'SED' + And more. Name (or path) of the 'make', 'sed', and similar + programs; used at the top level and propagated to all + subdirectories. + +'PERL' +'LATEX' +'PDFLATEX' + Name (or full path) for the 'perl', 'latex', and 'pdflatex' + commands used, e.g., to build the 'xindy' documentation. + + +File: tlbuild.info, Node: Coding conventions, Next: Continuous integration, Prev: Configure options, Up: Top + +8 Coding conventions +******************** + +Ideally, building all of TeX Live with '--enable-compiler-warnings=max' +should produce no (GCC) compiler warnings at all. In spite of +considerable efforts into that direction we are still far from that goal +and there are reasons that we may never fully reach it. Below are some +rules about declarations of functions or variables and the use of +'const'. These rules should be applied to the code maintained in the +TeX Live tree and for other packages whose maintainers are willing to +accept patches. + +* Menu: + +* Declarations and definitions:: +* Const:: + + +File: tlbuild.info, Node: Declarations and definitions, Next: Const, Up: Coding conventions + +8.1 Declarations and definitions +================================ + +C standards +........... + +The TeX Live build system no longer supports pre-ANSI C compilers. Thus +all function prototypes and definitions must conform to the ANSI C +standard (including 'void' in the declaration of C functions with no +parameters). On the other hand, TL is built for a wide variety of +systems, not all of which support the C99 standard. Therefore using C99 +features should be avoided if that can easily be done. In particular, C +code must not contain declarations after statements or C++-style +comments. + + If some C99 (or later) constructs must be used, the module should +verify that they are available and otherwise provide an alternative. +For example, the module 'texk/chktex' uses the C99 function 'stpcpy()' +that may or may not be available on a particular system. It uses +'AC_CHECK_DECLS([stpcpy])' in 'configure.ac' to test this, and provides +a perhaps less efficient alternative (in the file 'Utility.h'): + + #if !(defined HAVE_DECL_STPCPY && HAVE_DECL_STPCPY) + static inline char *stpcpy(char *dest, const char *src) + { + return strcpy(dest, src) + strlen(src); + } + #endif + +Static functions +................ + +Functions used in only one file should be declared 'static'; they +require no prototype except in forward declarations. + +Extern functions +................ + +Functions not declared 'static', usually because they are used in +several files, require an ('extern') prototype in exactly one header +file, which is included in the file defining the function and in all +files using that function--this is the only way to guarantee consistency +between definition and use. There should be no 'extern' declarations +sprinkled throughout the C code (with or without comments as to where +that function is defined). + +Variable declarations +..................... + +The declaration of global variables follows analogous rules: they are +either declared 'static' if used in only one file or declared 'extern' +in exactly one header and instantiated in exactly one file. + + +File: tlbuild.info, Node: Const, Prev: Declarations and definitions, Up: Coding conventions + +8.2 Const +========= + +The 'const' feature of C is valuable, but easy to mis-use. + +Function parameters +................... + +Ideally, a function parameter not modified by the function should be +declared as 'const'. This is important in particular for strings +('char*') because the actual arguments are often string literals. It is +perfectly legitimate and safe to use a type 'char*' value for a type +'const char*' variable (in an assignment, as initializer, as function +argument, or as return value). It is equally safe to use a type +'char**' value for a type 'const char*const*' variable, but not for a +type 'const char**' variable since that might cause modification of a +quantity supposed to be constant. + + Getting all 'const' qualifiers right can get quite involved but can +almost always be done. There are only a couple notable exceptions: the +X11 headers are full of declarations that ought to use 'const' but do +not; at one time, 'libfreetype' also did not fully specify 'const', but +this has not been checked recently. + +What must be avoided with 'const' +................................. + +The GCC compiler warnings "assignment discards qualifiers..." and +analogous warnings for "initialization", "passing arg", or "return" must +be strenuously avoided in our own code. The only exception is when they +are caused by X11 declarations or other third party code. + +What should be avoided with 'const' +................................... + +A type cast, e.g., from 'const char*' to 'char*' does not solve any +problems; depending on warning options, it may only hide them. +Therefore such casts should be avoided whenever possible and otherwise +must be carefully analyzed to make sure that they cannot cause the +modification of quantities supposed to be constant. + + +File: tlbuild.info, Node: Continuous integration, Next: install-tl, Prev: Coding conventions, Up: Top + +9 Continuous integration +************************ + +The TeX Live sources are subjected to continuous integration testing on +Travis-CI () via a +git-svn mirror of the sources that is pushed to Github +(). The git-svn mirror is +updated (currently) at 30 minute intervals, and only the last commit +pushed is tested on Travis-CI. + +* Menu: + +* Transfer from Subversion to Github:: +* Automatic update of the Git mirror:: +* CI testing on Travis-CI:: +* Releases on Github:: + + +File: tlbuild.info, Node: Transfer from Subversion to Github, Next: Automatic update of the Git mirror, Up: Continuous integration + +9.1 Transfer from Subversion to Github +====================================== + +The git-svn program () is used to +check out the subtree 'Build/source' of the canonical Subversion +repository. The author index file used is not maintained in either Git +or Subversion but can be provided on request. + + The initial checkout was done by invoking + git svn --authors-file usermap clone \ + svn://USER@tug.org/texlive/trunk/Build/source + +where the 'usermap' file maps Subversion user names to name and emails +of the authors. Anonymous checkout is also possible: + git svn --authors-file usermap clone \ + svn://tug.org/texlive/trunk/Build/source + + In the following, we will use _admin_ to refer to a user who has +read/write access to the TeX Live subversion repository, and is also an +administrator of the ''TeX-Live'' team at Github. The above initial +checkout has been carried out by _admin_ on the server 'texlive.info'. + + On Github, a new git repository named 'texlive-source' was created by +_admin_ within the 'TeX-Live' "organization" +(). The remote was added to the checkout +with 'git remote add origin git@github.com:TeX-Live/texlive-source.git'. + + To automate the update on Github, a new ssh key was generated and +added to the 'texlive-source' repository on Github as deployment key. +Thus, pushes using this key can only go to the 'texlive-source' +repository and not anywhere else. + + The usage of 'git-svn' requires a strict discipline to keep a linear +history in the master branch. Since we are aiming at a pure mirror +facility on Github, we have decided to further restrict the 'master' +branch of the 'texlive-source' repository on Github to changes by +_admin_. + + This setup allows other developers to branch off 'master' and push +their branches to the Github repository, but all updates need to come +from the local 'master' (not the one on Github) to Subversion, back to +'master' on 'texlive.info', and from there to Github. + + +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 + +9.2 Automatic update of the Git mirror +====================================== + +_admin_ has installed a cron job on 'texlive.info' running every 30 +minute which essentially runs 'git svn rebase' and 'git push' in the +'master' branch of the checkout. The first command fetches the changes +from the Subversion repository and updates the 'master' branch with +them, and the second pushes changes (if any) to Github. + + +File: tlbuild.info, Node: CI testing on Travis-CI, Next: Releases on Github, Prev: Automatic update of the Git mirror, Up: Continuous integration + +9.3 CI testing on Travis-CI +=========================== + +The 'source' tree of TeX Live contains a top-level file '.travis.yml' +which controls the automatic testing on Travis-CI. _admin_ has +registered with Travis-CI and allowed access to the Github's 'TeX-Live' +organization's 'texlive-source' repository. The default settings are to +build the last commit of each push. No further action is necessary on +Travis-CI. + + If changes have been pushed via the cron job above, Travis-CI will +automatically checkout the last pushed commit and try building it. + + +File: tlbuild.info, Node: Releases on Github, Prev: CI testing on Travis-CI, Up: Continuous integration + +9.4 Releases on Github +====================== + +Given a git checkout of 'texlive-source': + + git pull + git tag build-svnNNNN + git push --tags + +and the result will appear at +. Releases can +also be made manually from that web page (see 'tl-update-bindir' for +hints). + + +File: tlbuild.info, Node: install-tl, Next: tlmgr, Prev: Continuous integration, Up: Top + +Appendix A install-tl +********************* + +* Menu: + +* install-tl NAME:: +* install-tl SYNOPSIS:: +* install-tl DESCRIPTION:: +* install-tl REFERENCES:: +* install-tl OPTIONS:: +* install-tl PROFILES:: +* install-tl ENVIRONMENT VARIABLES:: +* install-tl AUTHORS AND COPYRIGHT:: + + +File: tlbuild.info, Node: install-tl NAME, Next: install-tl SYNOPSIS, Up: install-tl + +A.1 NAME +======== + +install-tl - TeX Live cross-platform installer + + +File: tlbuild.info, Node: install-tl SYNOPSIS, Next: install-tl DESCRIPTION, Prev: install-tl NAME, Up: install-tl + +A.2 SYNOPSIS +============ + +install-tl [_option_]... + + install-tl-windows.bat [_option_]... + + install-tl-advanced.bat [_option_]... + + +File: tlbuild.info, Node: install-tl DESCRIPTION, Next: install-tl REFERENCES, Prev: install-tl SYNOPSIS, Up: install-tl + +A.3 DESCRIPTION +=============== + +This installer creates a runnable TeX Live installation from various +media, including over the network, from local hard disk, a DVD, etc. +The installer works on all platforms supported by TeX Live. For +information on initially downloading TeX Live, see +. + + The basic idea of TeX Live installation is for you to choose one of +the top-level _schemes_, each of which is defined as a different set of +_collections_ and _packages_, where a collection is a set of packages, +and a package is what contains actual files. + + Within the installer, you can choose a scheme, and further customize +the set of collections to install, but not the set of the packages. To +work at the package level, use 'tlmgr' (reference just below) after the +initial installation is complete. + + The default is 'scheme-full', which installs everything, and this is +highly recommended. + + +File: tlbuild.info, Node: install-tl REFERENCES, Next: install-tl OPTIONS, Prev: install-tl DESCRIPTION, Up: install-tl + +A.4 REFERENCES +============== + +Post-installation configuration, package updates, and more, are handled +through *tlmgr*(1), the TeX Live Manager +(). + + The most up-to-date version of this installer documentation is on the +Internet at . + + For the full documentation of TeX Live, see +. + + +File: tlbuild.info, Node: install-tl OPTIONS, Next: install-tl PROFILES, Prev: install-tl REFERENCES, Up: install-tl + +A.5 OPTIONS +=========== + +As usual, all options can be specified in any order, and with either a +leading '-' or '--'. An argument value can be separated from its option +by either a space or '='. + +*-gui* [[=]_module_] + + If no _module_ is given, starts the Tcl/Tk (see below) GUI + installer. + + If _module_ is given loads the given installer module. Currently + the following modules are supported: + + 'text' + + The text mode user interface (default on Unix systems). Same + as the '-no-gui' option. + + 'tcl' + + The Tcl/Tk user interface (default on Macs and Windows). It + starts with a small number of configuration options, roughly + equivalent to what the wizard option below offers, but a + button 'Advanced' takes you to a screen with roughly the same + options as the 'perltk' interface. + + 'wizard' + + The wizard mode user interface, asking only minimal questions + before installing all of TeX Live. + + 'expert' + + A generic name for, currently, 'perltk'; it may select a + different GUI in the future. + + 'perltk' + + The expert GUI installer, providing access to more options. + + The 'perltk' and 'wizard' modules require the Perl/Tk module + (). if Perl/Tk is not + available, installation continues in text mode, except on Windows, + where all gui options except 'text' are diverted to the default + 'tcl' GUI. + + The 'tcl' GUI requires Tcl/Tk. This is standard on Macs and is + often already installed on GNU/Linux. For Windows, TeX Live + provides a Tcl/Tk runtime. + +*-no-gui* + + Use the text mode installer (default except on Windows and Macs). + +*-lang* _llcode_ + + By default, the GUI tries to deduce your language from the + environment. The Tcl GUI uses the language detection built into + Tcl/Tk; the Perl/Tk GUIs use the 'LC_MESSAGES' environment + variable. If that fails you can select a different language by + giving this option with a language code (based on ISO 639-1). + Currently supported (but not necessarily completely translated) + are: English (en, default), Czech (cs), German (de), French (fr), + Italian (it), Japanese (ja), Dutch (nl), Polish (pl), Brazilian + Portuguese (pt_BR), Russian (ru), Slovak (sk), Slovenian (sl), + Serbian (sr), Ukrainian (uk), Vietnamese (vi), simplified Chinese + (zh_CN), and traditional Chinese (zh_TW). + +*-repository* _url|path_ + + Specify the package repository to be used as the source of the + installation. In short, this can be a directory name or a url + using http(s), ftp, or scp. The documentation for 'tlmgr' has the + details (). + + For installation, the default is to pick a mirror automatically, + using ; the chosen + mirror is used for the entire download. You can use the special + argument 'ctan' as an abbreviation for this. (See + for more about CTAN and its mirrors.) + + After installation is complete, you can use that installation as + the repository for another installation. If you chose to install + less than the full scheme containing all packages, the list of + available schemes will be adjusted accordingly. + +*-select-repository* + + This option allows you to choose a particular mirror from the + current list of active CTAN mirrors. This option is supported in + the 'text', 'wizard' and 'perltk' installer modes, and will also + offer to install from local media if available, or from a + repository specified on the command line. It's useful when the + (default) automatic redirection does not choose a good host for + you. + +*-all-options* + + Normally options not relevant to the current platform are not shown + (e.g., when running on Unix, Windows-specific options are omitted). + Giving this command line option allows configuring such "foreign" + settings. + +*-custom-bin* _path_ + + If you have built your own set of TeX Live binaries (perhaps + because your platform was not supported by TeX Live out of the + box), this option allows you to specify the _path_ to a directory + where the binaries for the current system are present. The + installation will continue as usual, but at the end all files from + _path_ are copied over to 'bin/custom/' under your installation + directory and this 'bin/custom/' directory is what will be added to + the path for the post-install actions. To install multiple custom + binary sets, manually rename 'custom' before doing each. + + For more information on custom binaries, see + . For general information + on building TeX Live, see . + +*-debug-translation* + + In the Perl/Tk GUI modes, this option reports any missing, or more + likely untranslated, messages to standard error. Helpful for + translators to see what remains to be done. + +*-force-platform* _platform_ + + Instead of auto-detecting the current platform, use _platform_. + Binaries for this platform must be present and they must actually + be runnable, or installation will fail. '-force-arch' is a + synonym. + +*-help*, *-help*, *-?* + + Display this help and exit. (This help is also on the web at + ). Sometimes the + 'perldoc' and/or 'PAGER' programs on the system have problems, + possibly resulting in control characters being literally output. + This can't always be detected, but you can set the 'NOPERLDOC' + environment variable and 'perldoc' will not be used. + +*-in-place* + + This is a quick-and-dirty installation option in case you already + have an rsync or svn checkout of TeX Live. It will use the + checkout as-is and will just do the necessary post-install. Be + warned that the file 'tlpkg/texlive.tlpdb' may be rewritten, that + removal has to be done manually, and that the only realistic way to + maintain this installation is to redo it from time to time. This + option is not available via the installer interfaces. USE AT YOUR + OWN RISK. + +*-init-from-profile* _profile_file_ + + Similar to *-profile* (see *note PROFILES: install-tl PROFILES. + below), but only initializes the installation configuration from + _profile_file_ and then starts a normal interactive session. + Environment variables are not ignored. + +*-logfile* _file_ + + Write both all messages (informational, debugging, warnings) to + _file_, in addition to standard output or standard error. + + If this option is not given, the installer will create a log file + in the root of the writable installation tree, for example, + '/usr/local/texlive/YYYY/install-tl.log' for the _YYYY_ release. + +*-no-cls* + + For the text mode installer only: do not clear the screen when + entering a new menu (for debugging purposes). + +*-no-persistent-downloads* + +*-persistent-downloads* + + For network installs, activating this option makes the installer + try to set up a persistent connection using the 'Net::LWP' Perl + module. This opens only one connection between your computer and + the server per session and reuses it, instead of initiating a new + download for each package, which typically yields a significant + speed-up. + + This option is turned on by default, and the installation program + will fall back to using 'wget' if this is not possible. To disable + usage of LWP and persistent connections, use + '-no-persistent-downloads'. + +*-no-verify-downloads* + + By default, if a GnuPG 'gpg' binary is found in PATH, downloads are + verified against a cryptographic signature. This option disables + such verification. The full description is in the Crytographic + Verification section of the 'tlmgr' documentation, e.g., + + +*-non-admin* + + For Windows only: configure for the current user, not for all + users. + +*-portable* + + Install for portable use, e.g., on a USB stick. Also selectable + from within the perltk and text installers. + +*-print-platform* + + Print the TeX Live identifier for the detected platform + (hardware/operating system) combination to standard output, and + exit. '-print-arch' is a synonym. + +*-profile* _profile_file_ + + Load _profile_file_ and do the installation with no user + interaction, that is, a batch (unattended) install. Environment + variables are ignored. See *note PROFILES: install-tl PROFILES. + below. + +*-q* + + Omit normal informational messages. + +*-scheme* _scheme_ + + Schemes are the highest level of package grouping in TeX Live; the + default is to use the 'full' scheme, which includes everything. + This option overrides that default. You can change the scheme + again before the actual installation with the usual menu. The + _scheme_ argument may optionally have a prefix 'scheme-'. The list + of supported scheme names depends on what your package repository + provides; see the interactive menu list. + +*-v* + + Include verbose debugging messages; repeat for maximum debugging: + '-v -v'. (Further repeats are accepted but ignored.) + +*-version*, *-version* + + Output version information and exit. If '-v' is also given, the + versions of the TeX Live modules used are also reported. + + +File: tlbuild.info, Node: install-tl PROFILES, Next: install-tl ENVIRONMENT VARIABLES, Prev: install-tl OPTIONS, Up: install-tl + +A.6 PROFILES +============ + +A _profile_ file contains all the values needed to perform an +installation. After a normal installation has finished, a profile for +that exact installation is written to the file 'tlpkg/texlive.profile'. +In addition, from the text menu one can select 'P' to save the current +setup as a profile at any time. + + Such a profile file can be given as the argument to '-profile', for +example to redo the exact same installation on a different system. +Alternatively, you can use a custom profile, most easily created by +starting from a generated one and changing values, or an empty file, +which will take all the defaults. + + As mentioned above, the installer only supports selection by scheme +and collections, not individual packages, so packages cannot be +specified in profile files either. Use 'tlmgr' to work at the package +level. + + Within a profile file, each line consists of + + _variable_ [_value_] + + except for comment lines starting with '#'. The possible variable +names are listed below. Values, when present, are either '0' or '1' for +booleans, or strings (which must be specified without any quote +characters). Leading whitespace is ignored. + + If the variable 'selected_scheme' is defined and _no_ collection +variables at all are defined, then the collections required by the +specified scheme (which might change over time) are installed, without +explicitly listing them. This eases maintenance of profile files. If +any collections are specified in a profile, though, then all desired +collections must be given explicitly. + + For example, a line + + selected_scheme scheme-small + + along with definitions for the installation directories (given below +under "path options") suffices to install the "small" scheme with all +default options. The schemes are described in the 'S' menu in the text +installer, or equivalent. + + Besides 'selected_scheme', here is the list of variable names +supported in a profile: + + *collection options* (prefix 'collection-') + + Collections are specified with a variable name with the prefix +'collection-' followed by a collection name; there is no value. For +instance, 'collection-basic'. The collections are described in the 'C' +menu. + + Schemes and collections (and packages) are ultimately defined by the +files in the 'tlpkg/tlpsrc/' source directory. + + *path options* + + It is best to define all of these, even though they may not be used +in the installation, so as to avoid unintentionally getting a default +value that could cause problems later. + + TEXDIR + TEXMFCONFIG + TEXMFVAR + TEXMFHOME + TEXMFLOCAL + TEXMFSYSCONFIG + TEXMFSYSVAR + + *installer options* (prefix 'instopt_') + +'instopt_adjustpath' (default 0 on Unix, 1 on Windows) + + Adjust 'PATH' environment variable. + +'instopt_adjustrepo' (default 1) + + Set remote repository to a multiplexed CTAN mirror after + installation; see '-repository' above. + +'instopt_letter' (default 0) + + Set letter size paper as the default, instead of a4. + +'instopt_portable' (default 0) + + Install for portable use, e.g., on a USB stick. + +'instopt_write18_restricted' (default 1) + + Enable '\write18' for a restricted set of programs. + + *tlpdb options* (prefix 'tlpdbopt_') + + The definitive list is given in 'tlpkg/TeXLive/TLConfig.pm', in the +hash '%TeXLive::TLConfig::TLPDBOptions', together with explanations. +All items given there _except_ for 'tlpdbopt_location' can be specified. +Here is the current list: + + tlpdbopt_autobackup + tlpdbopt_backupdir + tlpdbopt_create_formats + tlpdbopt_desktop_integration + tlpdbopt_file_assocs + tlpdbopt_generate_updmap + tlpdbopt_install_docfiles + tlpdbopt_install_srcfiles + tlpdbopt_post_code + tlpdbopt_sys_bin + tlpdbopt_sys_info + tlpdbopt_sys_man + tlpdbopt_w32_multi_user + + *platform options* (prefix 'binary_') + + For each supported platform in TeX Live (directories under 'bin/'), +the variable 'binary_'_PLATFORM_ can be set with value 1. For example: + + binary_x86_64-linux 1 + + If no 'binary_' settings are made, the default is whatever the +current machine is running. + + In releases before 2017, many profile variables had different names +(not documented here; see the 'install-tl' source). They are accepted +and transformed to the names given above. When a profile is written, +the names above are always used. + + For more details on all of the above options, consult the TeX Live +installation manual, linked from . + + +File: tlbuild.info, Node: install-tl ENVIRONMENT VARIABLES, Next: install-tl AUTHORS AND COPYRIGHT, Prev: install-tl PROFILES, Up: install-tl + +A.7 ENVIRONMENT VARIABLES +========================= + +For ease in scripting and debugging, 'install-tl' looks for the +following environment variables. They are not of interest for normal +user installations. + +'TEXLIVE_DOWNLOADER' + +'TL_DOWNLOAD_PROGRAM' + +'TL_DOWNLOAD_ARGS' + + These override the normal choice of a download program; see the + 'tlmgr' documentation, e.g., + . + +'TEXLIVE_INSTALL_ENV_NOCHECK' + + Omit the check for environment variables containing the string + 'tex'. People developing TeX-related software are likely to have + many such variables. + +'TEXLIVE_INSTALL_NO_CONTEXT_CACHE' + + Omit creating the ConTeXt cache. This is useful for + redistributors. + +'TEXLIVE_INSTALL_NO_IMPORT' + + Omit check for installing on top of a previous installation and + then asking about importing previous settings. + +'TEXLIVE_INSTALL_NO_WELCOME' + + Omit printing the welcome message after successful installation, + e.g., when testing. + +'TEXLIVE_INSTALL_PREFIX' + +'TEXLIVE_INSTALL_TEXDIR' + +'TEXLIVE_INSTALL_TEXMFCONFIG' + +'TEXLIVE_INSTALL_TEXMFVAR' + +'TEXLIVE_INSTALL_TEXMFHOME' + +'TEXLIVE_INSTALL_TEXMFLOCAL' + +'TEXLIVE_INSTALL_TEXMFSYSCONFIG' + +'TEXLIVE_INSTALL_TEXMFSYSVAR' + + Specify the respective directories. 'TEXLIVE_INSTALL_PREFIX' + defaults to '/usr/local/texlive', while 'TEXLIVE_INSTALL_TEXDIR' + defaults to the release directory within that prefix, e.g., + '/usr/local/texlive/2016'. All the defaults can be seen by running + the installer interactively and then typing 'D' for the directory + menu. + +'NOPERLDOC' + + Don't try to run the '--help' message through 'perldoc'. + + +File: tlbuild.info, Node: install-tl AUTHORS AND COPYRIGHT, Prev: install-tl ENVIRONMENT VARIABLES, Up: install-tl + +A.8 AUTHORS AND COPYRIGHT +========================= + +This script and its documentation were written for the TeX Live +distribution () and both are licensed under the +GNU General Public License Version 2 or later. + + $Id: install-tl 54143 2020-03-06 23:51:18Z karl $ + + +File: tlbuild.info, Node: tlmgr, Next: Index, Prev: install-tl, Up: Top + +Appendix B tlmgr +**************** + +* Menu: + +* tlmgr NAME:: +* tlmgr SYNOPSIS:: +* tlmgr DESCRIPTION:: +* tlmgr EXAMPLES:: +* tlmgr OPTIONS:: +* tlmgr ACTIONS:: +* tlmgr CONFIGURATION FILE FOR TLMGR:: +* tlmgr CRYPTOGRAPHIC VERIFICATION:: +* tlmgr USER MODE:: +* tlmgr MULTIPLE REPOSITORIES:: +* tlmgr GUI FOR TLMGR:: +* tlmgr MACHINE-READABLE OUTPUT:: +* tlmgr ENVIRONMENT VARIABLES:: +* tlmgr AUTHORS AND COPYRIGHT:: + + +File: tlbuild.info, Node: tlmgr NAME, Next: tlmgr SYNOPSIS, Up: tlmgr + +B.1 NAME +======== + +tlmgr - the native TeX Live Manager + + +File: tlbuild.info, Node: tlmgr SYNOPSIS, Next: tlmgr DESCRIPTION, Prev: tlmgr NAME, Up: tlmgr + +B.2 SYNOPSIS +============ + +tlmgr [_option_...] _action_ [_option_...] [_operand_...] + + +File: tlbuild.info, Node: tlmgr DESCRIPTION, Next: tlmgr EXAMPLES, Prev: tlmgr SYNOPSIS, Up: tlmgr + +B.3 DESCRIPTION +=============== + +*tlmgr* manages an existing TeX Live installation, both packages and +configuration options. For information on initially downloading and +installing TeX Live, see . + + The most up-to-date version of this documentation (updated nightly +from the development sources) is available at +, along with procedures for updating +'tlmgr' itself and information about test versions. + + TeX Live is organized into a few top-level _schemes_, each of which +is specified as a different set of _collections_ and _packages_, where a +collection is a set of packages, and a package is what contains actual +files. Schemes typically contain a mix of collections and packages, but +each package is included in exactly one collection, no more and no less. +A TeX Live installation can be customized and managed at any level. + + See for all the TeX Live documentation +available. + + +File: tlbuild.info, Node: tlmgr EXAMPLES, Next: tlmgr OPTIONS, Prev: tlmgr DESCRIPTION, Up: tlmgr + +B.4 EXAMPLES +============ + +After successfully installing TeX Live, here are a few common operations +with 'tlmgr': + +'tlmgr option repository ctan' + +'tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet' + + Tell 'tlmgr' to use a nearby CTAN mirror for future updates; useful + if you installed TeX Live from the DVD image and want to have + continuing updates. The two commands are equivalent; 'ctan' is + just an alias for the given url. + + Caveat: 'mirror.ctan.org' resolves to many different hosts, and + they are not perfectly synchronized; we recommend updating only + daily (at most), and not more often. You can choose a particular + mirror if problems; the list of all CTAN mirrors with the status of + each is at . + +'tlmgr update --list' + + Report what would be updated without actually updating anything. + +'tlmgr update --all' + + Make your local TeX installation correspond to what is in the + package repository (typically useful when updating from CTAN). + +'tlmgr info' _what_ + + Display detailed information about a package _what_, such as the + installation status and description, of searches for _what_ in all + packages. + + For all the capabilities and details of 'tlmgr', please read the +following voluminous information. + + +File: tlbuild.info, Node: tlmgr OPTIONS, Next: tlmgr ACTIONS, Prev: tlmgr EXAMPLES, Up: tlmgr + +B.5 OPTIONS +=========== + +The following options to 'tlmgr' are global options, not specific to any +action. All options, whether global or action-specific, can be given +anywhere on the command line, and in any order. The first non-option +argument will be the main action. In all cases, '--'_option_ and +'-'_option_ are equivalent, and an '=' is optional between an option +name and its value. + +*-repository* _url|path_ + + Specify the package repository from which packages should be + installed or updated, either a local directory or network location, + as below. This overridesthe default package repository found in + the installation's TeX Live Package Database (a.k.a. the TLPDB, + which is given entirely in the file 'tlpkg/texlive.tlpdb'). + + This '--repository' option changes the location only for the + current run; to make a permanent change, use 'option repository' + (see the *note option: tlmgr option. action). + + As an example, you can choose a particular CTAN mirror with + something like this: + + -repository http://ctan.example.org/its/ctan/dir/systems/texlive/tlnet + + Of course a real hostname and its particular top-level CTAN + directory have to be specified. The list of CTAN mirrors is + available at . + + Here's an example of using a local directory: + + -repository /local/TL/repository + + For backward compatibility and convenience, '--location' and + '--repo' are accepted as aliases for this option. + + Locations can be specified as any of the following: + + '/some/local/dir' + + 'file:/some/local/dir' + + Equivalent ways of specifying a local directory. + + 'ctan' + + 'http://mirror.ctan.org/systems/texlive/tlnet' + + Pick a CTAN mirror automatically, trying for one that is both + nearby and up-to-date. The chosen mirror is used for the + entire download. The bare 'ctan' is merely an alias for the + full url. (See for more about CTAN and its + mirrors.) + + 'http://server/path/to/tlnet' + + Standard HTTP. If the (default) LWP method is used, persistent + connections are supported. TL can also use 'curl' or 'wget' + to do the downloads, or an arbitrary user-specified program, + as described in the 'tlmgr' documentation + (). + + 'https://server/path/to/tlnet' + + Again, if the (default) LWP method is used, this supports + persistent connections. Unfortunately, some versions of + 'wget' and 'curl' do not support https, and even when 'wget' + supports https, certificates may be rejected even when the + certificate is fine, due to a lack of local certificate roots. + The simplest workaround for this problem is to use http or + ftp. + + 'ftp://server/path/to/tlnet' + + If the (default) LWP method is used, persistent connections + are supported. + + 'user@machine:/path/to/tlnet' + + 'scp://user@machine/path/to/tlnet' + + 'ssh://user@machine/path/to/tlnet' + + These forms are equivalent; they all use 'scp' to transfer + files. Using 'ssh-agent' is recommended. (Info: + , + .) + + If the repository is on the network, trailing '/' characters and/or + trailing '/tlpkg' and/or '/archive' components are ignored. + +*-gui* [_action_] + + Two notable GUI front-ends for 'tlmgr', 'tlshell' and 'tlcockpit', + are started up as separate programs; see their own documentation. + + 'tlmgr' itself has a graphical interface as well as the command + line interface. You can give the option to invoke it, '--gui', + together with an action to be brought directly into the respective + screen of the GUI. For example, running + + tlmgr --gui update + + starts you directly at the update screen. If no action is given, + the GUI will be started at the main screen. See *note GUI FOR + TLMGR: tlmgr GUI FOR TLMGR. + + However, the native GUI requires Perl/TK, which is no longer + included in TeX Live's Perl distribution for Windows. You may find + 'tlshell' or 'tlcockpit' easier to work with. + +*-gui-lang* _llcode_ + + By default, the GUI tries to deduce your language from the + environment (on Windows via the registry, on Unix via + 'LC_MESSAGES'). If that fails you can select a different language + by giving this option with a language code (based on ISO 639-1). + Currently supported (but not necessarily completely translated) + are: English (en, default), Czech (cs), German (de), French (fr), + Italian (it), Japanese (ja), Dutch (nl), Polish (pl), + Brazilian Portuguese (pt_BR), Russian (ru), Slovak (sk), + Slovenian (sl), Serbian (sr), Ukrainian (uk), Vietnamese (vi), + simplified Chinese (zh_CN), and traditional Chinese (zh_TW). + + tlshell shares its message catalog with tlmgr. + +*-debug-translation* + + In GUI mode, this switch tells 'tlmgr' to report any untranslated + (or missing) messages to standard error. This can help translators + to see what remains to be done. + +*-machine-readable* + + Instead of the normal output intended for human consumption, write + (to standard output) a fixed format more suitable for machine + parsing. See the *note MACHINE-READABLE OUTPUT: tlmgr + MACHINE-READABLE OUTPUT. section below. + +*-no-execute-actions* + + Suppress the execution of the execute actions as defined in the + tlpsrc files. Documented only for completeness, as this is only + useful in debugging. + +*-package-logfile* _file_ + + 'tlmgr' logs all package actions (install, remove, update, failed + updates, failed restores) to a separate log file, by default + 'TEXMFSYSVAR/web2c/tlmgr.log'. This option allows you to specify a + different file for the log. + +*-pause* + + This option makes 'tlmgr' wait for user input before exiting. + Useful on Windows to avoid disappearing command windows. + +*-persistent-downloads* + +*-no-persistent-downloads* + + For network-based installations, this option (on by default) makes + 'tlmgr' try to set up a persistent connection (using the 'LWP' Perl + module). The idea is to open and reuse only one connection per + session between your computer and the server, instead of initiating + a new download for each package. + + If this is not possible, 'tlmgr' will fall back to using 'wget'. + To disable these persistent connections, use + '--no-persistent-downloads'. + +*-pin-file* + + Change the pinning file location from + 'TEXMFLOCAL/tlpkg/pinning.txt' (see *note Pinning: tlmgr Pinning. + below). Documented only for completeness, as this is only useful + in debugging. + +*-usermode* + + Activates user mode for this run of 'tlmgr'; see *note USER MODE: + tlmgr USER MODE. below. + +*-usertree* _dir_ + + Uses _dir_ for the tree in user mode; see *note USER MODE: tlmgr + USER MODE. below. + +*-verify-repo=[none|main|all]* + + Defines the level of verification done: If 'none' is specified, no + verification whatsoever is done. If 'main' is given and a working + GnuPG ('gpg') binary is available, all repositories are checked, + but only the main repository is required to be signed. If 'all' is + given, then all repositories need to be signed. See *note + CRYPTOGRAPHIC VERIFICATION: tlmgr CRYPTOGRAPHIC VERIFICATION. below + for details. + + The standard options for TeX Live programs are also accepted: +'--help/-h/-?', '--version', '-q' (no informational messages), '-v' +(debugging messages, can be repeated). For the details about these, see +the 'TeXLive::TLUtils' documentation. + + The '--version' option shows version information about the TeX Live +release and about the 'tlmgr' script itself. If '-v' is also given, +revision number for the loaded TeX Live Perl modules are shown, too. + + +File: tlbuild.info, Node: tlmgr ACTIONS, Next: tlmgr CONFIGURATION FILE FOR TLMGR, Prev: tlmgr OPTIONS, Up: tlmgr + +B.6 ACTIONS +=========== + +* Menu: + +* tlmgr help:: +* tlmgr version:: +* tlmgr backup:: +* tlmgr candidates _pkg_:: +* tlmgr check [_option_...] [depends|executes|files|runfiles|texmfdbs|all]:: +* tlmgr conf:: +* tlmgr dump-tlpdb [_option_...] [--json]:: +* tlmgr generate:: +* tlmgr gui:: +* tlmgr info:: +* tlmgr init-usertree:: +* tlmgr install [_option_...] _pkg_...:: +* tlmgr key:: +* tlmgr list:: +* tlmgr option:: +* tlmgr paper:: +* tlmgr path:: +* tlmgr pinning:: +* tlmgr platform:: +* tlmgr postaction:: +* tlmgr print-platform:: +* tlmgr print-platform-info:: +* tlmgr remove [_option_...] _pkg_...:: +* tlmgr repository:: +* tlmgr restore:: +* tlmgr search:: +* tlmgr shell:: +* tlmgr show:: +* tlmgr uninstall:: +* tlmgr update [_option_...] [_pkg_...]:: + + +File: tlbuild.info, Node: tlmgr help, Next: tlmgr version, Up: tlmgr ACTIONS + +B.6.1 help +---------- + +Display this help information and exit (same as '--help', and on the web +at ). Sometimes the 'perldoc' +and/or 'PAGER' programs on the system have problems, resulting in +control characters being literally output. This can't always be +detected, but you can set the 'NOPERLDOC' environment variable and +'perldoc' will not be used. + + +File: tlbuild.info, Node: tlmgr version, Next: tlmgr backup, Prev: tlmgr help, Up: tlmgr ACTIONS + +B.6.2 version +------------- + +Gives version information (same as '--version'). + + If '-v' has been given the revisions of the used modules are +reported, too. + + +File: tlbuild.info, Node: tlmgr backup, Next: tlmgr candidates _pkg_, Prev: tlmgr version, Up: tlmgr ACTIONS + +B.6.3 backup +------------ + +*backup [_option_...] -all* + +*backup [_option_...] _pkg_...* + + If the '--clean' option is not specified, this action makes a + backup of the given packages, or all packages given '--all'. These + backups are saved to the value of the '--backupdir' option, if that + is an existing and writable directory. If '--backupdir' is not + given, the 'backupdir' option setting in the TLPDB is used, if + present. If both are missing, no backups are made. (The installer + sets 'backupdir' to '.../tlpkg/backups', under the TL root + installation directory, so it is usually defined; see the *note + option: tlmgr option. description for more information.) + + If the '--clean' option is specified, backups are pruned (removed) + instead of saved. The optional integer value _N_ may be specified + to set the number of backups that will be retained when cleaning. + If 'N' is not given, the value of the 'autobackup' option is used. + If both are missing, an error is issued. For more details of + backup pruning, see the 'option' action. + + Options: + + *-backupdir* _directory_ + + Overrides the 'backupdir' option setting in the TLPDB. The + _directory_ argument is required and must specify an existing, + writable directory where backups are to be placed. + + *-all* + + If '--clean' is not specified, make a backup of all packages + in the TeX Live installation; this will take quite a lot of + space and time. If '--clean' is specified, all packages are + pruned. + + *-clean*[=_N_] + + Instead of making backups, prune the backup directory of old + backups, as explained above. The optional integer argument + _N_ overrides the 'autobackup' option set in the TLPDB. You + must use '--all' or a list of packages together with this + option, as desired. + + *-dry-run* + + Nothing is actually backed up or removed; instead, the actions + to be performed are written to the terminal. + + +File: tlbuild.info, Node: tlmgr candidates _pkg_, Next: tlmgr check [_option_...] [depends|executes|files|runfiles|texmfdbs|all], Prev: tlmgr backup, Up: tlmgr ACTIONS + +B.6.4 candidates _pkg_ +---------------------- + +Shows the available candidate repositories for package _pkg_. See *note +MULTIPLE REPOSITORIES: tlmgr MULTIPLE REPOSITORIES. below. + + +File: tlbuild.info, Node: tlmgr check [_option_...] [depends|executes|files|runfiles|texmfdbs|all], Next: tlmgr conf, Prev: tlmgr candidates _pkg_, Up: tlmgr ACTIONS + +B.6.5 check [_option_...] [depends|executes|files|runfiles|texmfdbs|all] +------------------------------------------------------------------------ + +Execute one (or all) check(s) of the consistency of the installation. +If no problems are found, there will be no output. (To get a view of +what is being done, run 'tlmgr -v check'.) + +*depends* + + Lists those packages which occur as dependencies in an installed + collection, but are themselves not installed, and those packages + which are not contained in any collection. + + If you call 'tlmgr check collections' this test will be carried out + instead since former versions for 'tlmgr' called it that way. + +*executes* + + Check that the files referred to by 'execute' directives in the TeX + Live Database are present. + +*files* + + Checks that all files listed in the local TLPDB ('texlive.tlpdb') + are actually present, and lists those missing. + +*runfiles* + + List those filenames that are occurring more than one time in the + runfiles sections, except for known duplicates. + +*texmfdbs* + + Checks related to the 'ls-R' files. If you have defined new trees, + or changed the 'TEXMF' or 'TEXMFDBS' variables, it can't hurt to + run this. It checks that: + + - all items in 'TEXMFDBS' have the '!!' prefix. + + - all items in 'TEXMFBDS' have an 'ls-R' file (if they exist at all). + + - all items in 'TEXMF' with '!!' are listed in 'TEXMFDBS'. + + - all items in 'TEXMF' with an 'ls-R' file are listed in 'TEXMFDBS'. + + Options: + +*-use-svn* + + Use the output of 'svn status' instead of listing the files; for + checking the TL development repository. (This is run nightly.) + + +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 + +B.6.6 conf +---------- + +*conf [texmf|tlmgr|updmap [-conffile _file_] [-delete] [_key_ [_value_]]]* + +*conf auxtrees [-conffile _file_] [show|add|remove] [_value_]* + + With only 'conf', show general configuration information for TeX + Live, including active configuration files, path settings, and + more. This is like running 'texconfig conf', but works on all + supported platforms. + + With one of 'conf texmf', 'conf tlmgr', or 'conf updmap', shows all + key/value pairs (i.e., all settings) as saved in 'ROOT/texmf.cnf', + the user-specific 'tlmgr' configuration file (see below), or the + first found (via 'kpsewhich') 'updmap.cfg' file, respectively. + + If _key_ is given in addition, shows the value of only that _key_ + in the respective file. If option _-delete_ is also given, the + value in the given configuration file is entirely removed (not just + commented out). + + If _value_ is given in addition, _key_ is set to _value_ in the + respective file. _No error checking is done!_ + + The 'PATH' value shown by 'conf' is as used by 'tlmgr'. The + directory in which the 'tlmgr' executable is found is automatically + prepended to the PATH value inherited from the environment. + + Here is a practical example of changing configuration values. If + the execution of (some or all) system commands via '\write18' was + left enabled during installation, you can disable it afterwards: + + tlmgr conf texmf shell_escape 0 + + The subcommand 'auxtrees' allows adding and removing arbitrary + additional texmf trees, completely under user control. 'auxtrees + show' shows the list of additional trees, 'auxtrees add' _tree_ + adds a tree to the list, and 'auxtrees remove' _tree_ removes a + tree from the list (if present). The trees should not contain an + 'ls-R' file (or files will not be found if the 'ls-R' becomes + stale). This works by manipulating the Kpathsea variable + 'TEXMFAUXTREES', in (by default) 'ROOT/texmf.cnf'. Example: + + tlmgr conf auxtrees add /quick/test/tree + tlmgr conf auxtrees remove /quick/test/tree + + In all cases the configuration file can be explicitly specified via + the option '--conffile' _file_, e.g., if you don't want to change + the system-wide configuration. + + Warning: The general facility for changing configuration values is + here, but tinkering with settings in this way is strongly + discouraged. Again, no error checking on either keys or values is + done, so any sort of breakage is possible. + + +File: tlbuild.info, Node: tlmgr dump-tlpdb [_option_...] [--json], Next: tlmgr generate, Prev: tlmgr conf, Up: tlmgr ACTIONS + +B.6.7 dump-tlpdb [_option_...] [-json] +-------------------------------------- + +Dump complete local or remote TLPDB to standard output, as-is. The +output is analogous to the '--machine-readable' output; see *note +MACHINE-READABLE OUTPUT: tlmgr MACHINE-READABLE OUTPUT. section. + + Options: + +*-local* + + Dump the local TLPDB. + +*-remote* + + Dump the remote TLPDB. + +*-json* + + Instead of dumping the actual content, the database is dumped as + JSON. For the format of JSON output see + 'tlpkg/doc/JSON-formats.txt', format definition 'TLPDB'. + + Exactly one of '--local' and '--remote' must be given. + + In either case, the first line of the output specifies the repository +location, in this format: + + "location-url" "\t" location + + where 'location-url' is the literal field name, followed by a tab, +and _location_ is the file or url to the repository. + + Line endings may be either LF or CRLF depending on the current +platform. + + +File: tlbuild.info, Node: tlmgr generate, Next: tlmgr gui, Prev: tlmgr dump-tlpdb [_option_...] [--json], Up: tlmgr ACTIONS + +B.6.8 generate +-------------- + +*generate [_option_...] language* + +*generate [_option_...] language.dat* + +*generate [_option_...] language.def* + +*generate [_option_...] language.dat.lua* + + The 'generate' action overwrites any manual changes made in the +respective files: it recreates them from scratch based on the +information of the installed packages, plus local adaptions. The TeX +Live installer and 'tlmgr' routinely call 'generate' for all of these +files. + + For managing your own fonts, please read the 'updmap --help' +information and/or . + + For managing your own formats, please read the 'fmtutil --help' +information. + + In more detail: 'generate' remakes any of the configuration files +'language.dat', 'language.def', and 'language.dat.lua' from the +information present in the local TLPDB, plus locally-maintained files. + + The locally-maintained files are 'language-local.dat', +'language-local.def', or 'language-local.dat.lua', searched for in +'TEXMFLOCAL' in the respective directories. If local additions are +present, the final file is made by starting with the main file, omitting +any entries that the local file specifies to be disabled, and finally +appending the local file. + + (Historical note: The formerly supported 'updmap-local.cfg' and +'fmtutil-local.cnf' are no longer read, since 'updmap' and 'fmtutil' now +reads and supports multiple configuration files. Thus, local additions +can and should be put into an 'updmap.cfg' of 'fmtutil.cnf' file in +'TEXMFLOCAL'. The 'generate updmap' and 'generate fmtutil' actions no +longer exist.) + + Local files specify entries to be disabled with a comment line, +namely one of these: + + %!NAME + --!NAME + + where 'language.dat' and 'language.def' use '%', and +'language.dat.lua' use '--'. In all cases, the _name_ is the respective +format name or hyphenation pattern identifier. Examples: + + %!german + --!usenglishmax + + (Of course, you're not likely to actually want to disable those +particular items. They're just examples.) + + After such a disabling line, the local file can include another entry +for the same item, if a different definition is desired. In general, +except for the special disabling lines, the local files follow the same +syntax as the master files. + + The form 'generate language' recreates all three files +'language.dat', 'language.def', and 'language.dat.lua', while the forms +with an extension recreates only that given language file. + + Options: + +*-dest* _output_file_ + + specifies the output file (defaults to the respective location in + 'TEXMFSYSVAR'). If '--dest' is given to 'generate language', it + serves as a basename onto which '.dat' will be appended for the + name of the 'language.dat' output file, '.def' will be appended to + the value for the name of the 'language.def' output file, and + '.dat.lua' to the name of the 'language.dat.lua' file. (This is + just to avoid overwriting; if you want a specific name for each + output file, we recommend invoking 'tlmgr' twice.) + +*-localcfg* _local_conf_file_ + + specifies the (optional) local additions (defaults to the + respective location in 'TEXMFLOCAL'). + +*-rebuild-sys* + + tells 'tlmgr' to run necessary programs after config files have + been regenerated. These are: 'fmtutil-sys --all' after 'generate + fmtutil', 'fmtutil-sys --byhyphen .../language.dat' after 'generate + language.dat', and 'fmtutil-sys --byhyphen .../language.def' after + 'generate language.def'. + + These subsequent calls cause the newly-generated files to actually + take effect. This is not done by default since those calls are + lengthy processes and one might want to made several related + changes in succession before invoking these programs. + + The respective locations are as follows: + + tex/generic/config/language.dat (and language-local.dat) + tex/generic/config/language.def (and language-local.def) + tex/generic/config/language.dat.lua (and language-local.dat.lua) + + +File: tlbuild.info, Node: tlmgr gui, Next: tlmgr info, Prev: tlmgr generate, Up: tlmgr ACTIONS + +B.6.9 gui +--------- + +Start the graphical user interface. See *GUI* below. + + +File: tlbuild.info, Node: tlmgr info, Next: tlmgr init-usertree, Prev: tlmgr gui, Up: tlmgr ACTIONS + +B.6.10 info +----------- + +*info [_option_...] _pkg_...* + +*info [_option_...] collections* + +*info [_option_...] schemes* + + With no argument, lists all packages available at the package + repository, prefixing those already installed with 'i'. + + With the single word 'collections' or 'schemes' as the argument, + lists the request type instead of all packages. + + With any other arguments, display information about _pkg_: the + name, category, short and long description, sizes, installation + status, and TeX Live revision number. If _pkg_ is not locally + installed, searches in the remote installation source. + + For normal packages (not collections or schemes), the sizes of the + four groups of files (run/src/doc/bin files) are shown separately. + For collections, the cumulative size is shown, including all + directly-dependent packages (but not dependent collections). For + schemes, the cumulative size is also shown, including all + directly-dependent collections and packages. + + If _pkg_ is not found locally or remotely, the search action is + used and lists matching packages and files. + + It also displays information taken from the TeX Catalogue, namely + the package version, date, and license. Consider these, especially + the package version, as approximations only, due to timing skew of + the updates of the different pieces. By contrast, the 'revision' + value comes directly from TL and is reliable. + + The former actions 'show' and 'list' are merged into this action, + but are still supported for backward compatibility. + + Options: + + *-list* + + If the option '--list' is given with a package, the list of + contained files is also shown, including those for + platform-specific dependencies. When given with schemes and + collections, '--list' outputs their dependencies in a similar + way. + + *-only-installed* + + If this option is given, the installation source will not be + used; only locally installed packages, collections, or schemes + are listed. + + *-only-remote* + + Only list packages from the remote repository. Useful when + checking what is available in a remote repository using 'tlmgr + --repo ... --only-remote info'. Note that '--only-installed' + and '--only-remote' cannot both be specified. + + *-data 'item1,item2,...'* + + If the option '--data' is given, its argument must be a comma + separated list of field names from: 'name', 'category', + 'localrev', 'remoterev', 'shortdesc', 'longdesc', 'installed', + 'size', 'relocatable', 'depends', 'cat-version', 'cat-date', + or 'cat-license'. In this case the requested packages' + information is listed in CSV format one package per line, and + the column information is given by the 'itemN'. The 'depends' + column contains the name of all dependencies separated by ':'. + + *-json* + + In case '--json' is specified, the output is a JSON encoded + array where each array element is the JSON representation of a + single 'TLPOBJ' but with additional information. For details + see 'tlpkg/doc/JSON-formats.txt', format definition: + 'TLPOBJINFO'. If both '--json' and '--data' are given, + '--json' takes precedence. + + +File: tlbuild.info, Node: tlmgr init-usertree, Next: tlmgr install [_option_...] _pkg_..., Prev: tlmgr info, Up: tlmgr ACTIONS + +B.6.11 init-usertree +-------------------- + +Sets up a texmf tree for so-called user mode management, either the +default user tree ('TEXMFHOME'), or one specified on the command line +with '--usertree'. See *note USER MODE: tlmgr USER MODE. below. + + +File: tlbuild.info, Node: tlmgr install [_option_...] _pkg_..., Next: tlmgr key, Prev: tlmgr init-usertree, Up: tlmgr ACTIONS + +B.6.12 install [_option_...] _pkg_... +------------------------------------- + +Install each _pkg_ given on the command line, if it is not already +installed. It does not touch existing packages; see the 'update' action +for how to get the latest version of a package. + + By default this also installs all packages on which the given _pkg_s +are dependent. Options: + +*-dry-run* + + Nothing is actually installed; instead, the actions to be performed + are written to the terminal. + +*-file* + + Instead of fetching a package from the installation repository, use + the package files given on the command line. These files must be + standard TeX Live package files (with contained tlpobj file). + +*-force* + + If updates to 'tlmgr' itself (or other parts of the basic + infrastructure) are present, 'tlmgr' will bail out and not perform + the installation unless this option is given. Not recommended. + +*-no-depends* + + Do not install dependencies. (By default, installing a package + ensures that all dependencies of this package are fulfilled.) + +*-no-depends-at-all* + + Normally, when you install a package which ships binary files the + respective binary package will also be installed. That is, for a + package 'foo', the package 'foo.i386-linux' will also be installed + on an 'i386-linux' system. This option suppresses this behavior, + and also implies '--no-depends'. Don't use it unless you are sure + of what you are doing. + +*-reinstall* + + Reinstall a package (including dependencies for collections) even + if it already seems to be installed (i.e, is present in the TLPDB). + This is useful to recover from accidental removal of files in the + hierarchy. + + When re-installing, only dependencies on normal packages are + followed (i.e., not those of category Scheme or Collection). + +*-with-doc* + +*-with-src* + + While not recommended, the 'install-tl' program provides an option + to omit installation of all documentation and/or source files. (By + default, everything is installed.) After such an installation, you + may find that you want the documentation or source files for a + given package after all. You can get them by using these options + in conjunction with '--reinstall', as in (using the 'fontspec' + package as the example): + + tlmgr install --reinstall --with-doc --with-src fontspec + + This action does not automatically add new symlinks in system +directories; you need to run 'tlmgr path add' (*note path: tlmgr path.) +yourself if you are using this feature and want new symlinks added. + + +File: tlbuild.info, Node: tlmgr key, Next: tlmgr list, Prev: tlmgr install [_option_...] _pkg_..., Up: tlmgr ACTIONS + +B.6.13 key +---------- + +*key list* + +*key add _file_* + +*key remove _keyid_* + + The action 'key' allows listing, adding and removing additional GPG + keys to the set of trusted keys, that is, those that are used to + verify the TeX Live databases. + + With the 'list' argument, 'key' lists all keys. + + The 'add' argument requires another argument, either a filename or + '-' for stdin, from which the key is added. The key is added to + the local keyring 'GNUPGHOME/repository-keys.gpg', which is + normally 'tlpkg/gpg/repository-keys.gpg'. + + The 'remove' argument requires a key id and removes the requested + id from the local keyring. + + +File: tlbuild.info, Node: tlmgr list, Next: tlmgr option, Prev: tlmgr key, Up: tlmgr ACTIONS + +B.6.14 list +----------- + +Synonym for *note info: tlmgr info. + + +File: tlbuild.info, Node: tlmgr option, Next: tlmgr paper, Prev: tlmgr list, Up: tlmgr ACTIONS + +B.6.15 option +------------- + +*option [-json] [show]* + +*option [-json] showall|help* + +*option _key_ [_value_]* + + The first form, 'show', shows the global TeX Live settings currently +saved in the TLPDB with a short description and the 'key' used for +changing it in parentheses. + + The second form, 'showall', is similar, but also shows options which +can be defined but are not currently set to any value ('help' is a +synonym). + + Both 'show...' forms take an option '--json', which dumps the option +information in JSON format. In this case, both forms dump the same +data. For the format of the JSON output see +'tlpkg/doc/JSON-formats.txt', format definition 'TLOPTION'. + + In the third form, with _key_, if _value_ is not given, the setting +for _key_ is displayed. If _value_ is present, _key_ is set to _value_. + + Possible values for _key_ are (run 'tlmgr option showall' for the +definitive list): + + repository (default package repository), + formats (generate formats at installation or update time), + postcode (run postinst code blobs) + docfiles (install documentation files), + srcfiles (install source files), + backupdir (default directory for backups), + autobackup (number of backups to keep). + sys_bin (directory to which executables are linked by the path action) + sys_man (directory to which man pages are linked by the path action) + sys_info (directory to which Info files are linked by the path action) + desktop_integration (Windows-only: create Start menu shortcuts) + fileassocs (Windows-only: change file associations) + multiuser (Windows-only: install for all users) + + One common use of 'option' is to permanently change the installation +to get further updates from the Internet, after originally installing +from DVD. To do this, you can run + + tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet + + The 'install-tl' documentation has more information about the +possible values for 'repository'. (For backward compatibility, +'location' can be used as a synonym for 'repository'.) + + If 'formats' is set (this is the default), then formats are +regenerated when either the engine or the format files have changed. +Disable this only when you know how and want to regenerate formats +yourself whenever needed (which is often, in practice). + + The 'postcode' option controls execution of per-package +postinstallation action code. It is set by default, and again disabling +is not likely to be of interest except to developers doing debugging. + + The 'docfiles' and 'srcfiles' options control the installation of +their respective file groups (documentation, sources; grouping is +approximate) per package. By default both are enabled (1). Either or +both can be disabled (set to 0) if disk space is limited or for minimal +testing installations, etc. When disabled, the respective files are not +downloaded at all. + + The options 'autobackup' and 'backupdir' determine the defaults for +the actions 'update', 'backup' and 'restore'. These three actions need +a directory in which to read or write the backups. If '--backupdir' is +not specified on the command line, the 'backupdir' option value is used +(if set). The TL installer sets 'backupdir' to '.../tlpkg/backups', +under the TL root installation directory. + + The 'autobackup' option (de)activates automatic generation of +backups. Its value is an integer. If the 'autobackup' value is '-1', +no backups are removed. If 'autobackup' is 0 or more, it specifies the +number of backups to keep. Thus, backups are disabled if the value is +0. In the '--clean' mode of the 'backup' action this option also +specifies the number to be kept. The default value is 1, so that +backups are made, but only one backup is kept. + + To setup 'autobackup' to '-1' on the command line, use: + + tlmgr option -- autobackup -1 + + The '--' avoids having the '-1' treated as an option. (The '--' +stops parsing for options at the point where it appears; this is a +general feature across most Unix programs.) + + The 'sys_bin', 'sys_man', and 'sys_info' options are used on Unix +systems to control the generation of links for executables, Info files +and man pages. See the 'path' action for details. + + The last three options affect behavior on Windows installations. If +'desktop_integration' is set, then some packages will install items in a +sub-folder of the Start menu for 'tlmgr gui', documentation, etc. If +'fileassocs' is set, Windows file associations are made (see also the +'postaction' action). Finally, if 'multiuser' is set, then adaptions to +the registry and the menus are done for all users on the system instead +of only the current user. All three options are on by default. + + +File: tlbuild.info, Node: tlmgr paper, Next: tlmgr path, Prev: tlmgr option, Up: tlmgr ACTIONS + +B.6.16 paper +------------ + +*paper [a4|letter]* + +*<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [_papersize_|-list]*> + +*paper -json* + + With no arguments ('tlmgr paper'), shows the default paper size +setting for all known programs. + + With one argument (e.g., 'tlmgr paper a4'), sets the default for all +known programs to that paper size. + + With a program given as the first argument and no paper size +specified (e.g., 'tlmgr dvips paper'), shows the default paper size for +that program. + + With a program given as the first argument and a paper size as the +last argument (e.g., 'tlmgr dvips paper a4'), set the default for that +program to that paper size. + + With a program given as the first argument and '--list' given as the +last argument (e.g., 'tlmgr dvips paper --list'), shows all valid paper +sizes for that program. The first size shown is the default. + + If '--json' is specified without other options, the paper setup is +dumped in JSON format. For the format of JSON output see +'tlpkg/doc/JSON-formats.txt', format definition 'TLPAPER'. + + Incidentally, this syntax of having a specific program name before +the 'paper' keyword is unusual. It is inherited from the longstanding +'texconfig' script, which supports other configuration settings for some +programs, notably 'dvips'. 'tlmgr' does not support those extra +settings. + + +File: tlbuild.info, Node: tlmgr path, Next: tlmgr pinning, Prev: tlmgr paper, Up: tlmgr ACTIONS + +B.6.17 path +----------- + +*path [-w32mode=user|admin] add* + +*path [-w32mode=user|admin] remove* + + On Unix, adds or removes symlinks for executables, man pages, and + info pages in the system directories specified by the respective + options (see the *note option: tlmgr option. description above). + Does not change any initialization files, either system or + personal. Furthermore, any executables added or removed by future + updates are not taken care of automatically; this command must be + rerun as needed. + + On Windows, the registry part where the binary directory is added + or removed is determined in the following way: + + If the user has admin rights, and the option '--w32mode' is not + given, the setting _w32_multi_user_ determines the location (i.e., + if it is on then the system path, otherwise the user path is + changed). + + If the user has admin rights, and the option '--w32mode' is given, + this option determines the path to be adjusted. + + If the user does not have admin rights, and the option '--w32mode' + is not given, and the setting _w32_multi_user_ is off, the user + path is changed, while if the setting _w32_multi_user_ is on, a + warning is issued that the caller does not have enough privileges. + + If the user does not have admin rights, and the option '--w32mode' + is given, it must be 'user' and the user path will be adjusted. If + a user without admin rights uses the option '--w32mode admin' a + warning is issued that the caller does not have enough privileges. + + +File: tlbuild.info, Node: tlmgr pinning, Next: tlmgr platform, Prev: tlmgr path, Up: tlmgr ACTIONS + +B.6.18 pinning +-------------- + +The 'pinning' action manages the pinning file, see *note Pinning: tlmgr +Pinning. below. + +'pinning show' + + Shows the current pinning data. + +'pinning add' _repo_ _pkgglob_... + + Pins the packages matching the _pkgglob_(s) to the repository + _repo_. + +'pinning remove' _repo_ _pkgglob_... + + Any packages recorded in the pinning file matching the s + for the given repository _repo_ are removed. + +'pinning remove _repo_ --all' + + Remove all pinning data for repository _repo_. + + +File: tlbuild.info, Node: tlmgr platform, Next: tlmgr postaction, Prev: tlmgr pinning, Up: tlmgr ACTIONS + +B.6.19 platform +--------------- + +*platform list|add|remove _platform_...* + +*platform set _platform_* + +*platform set auto* + + 'platform list' lists the TeX Live names of all the platforms + (a.k.a. architectures), ('i386-linux', ...) available at the + package repository. + + 'platform add' _platform_... adds the executables for each given + platform _platform_ to the installation from the repository. + + 'platform remove' _platform_... removes the executables for each + given platform _platform_ from the installation, but keeps the + currently running platform in any case. + + 'platform set' _platform_ switches TeX Live to always use the given + platform instead of auto detection. + + 'platform set auto' switches TeX Live to auto detection mode for + platform. + + Platform detection is needed to select the proper 'xz' and 'wget' + binaries that are shipped with TeX Live. + + 'arch' is a synonym for 'platform'. + + Options: + + *-dry-run* + + Nothing is actually installed; instead, the actions to be + performed are written to the terminal. + + +File: tlbuild.info, Node: tlmgr postaction, Next: tlmgr print-platform, Prev: tlmgr platform, Up: tlmgr ACTIONS + +B.6.20 postaction +----------------- + +*postaction [_option_...] install [shortcut|fileassoc|script] [_pkg_...]* + +*postaction [_option_...] remove [shortcut|fileassoc|script] [_pkg_...]* + + Carry out the postaction 'shortcut', 'fileassoc', or 'script' given + as the second required argument in install or remove mode (which is + the first required argument), for either the packages given on the + command line, or for all if '--all' is given. + + Options: + + *-w32mode=[user|admin]* + + If the option '--w32mode' is given the value 'user', all + actions will only be carried out in the user-accessible parts + of the registry/filesystem, while the value 'admin' selects + the system-wide parts of the registry for the file + associations. If you do not have enough permissions, using + '--w32mode=admin' will not succeed. + + *-fileassocmode=[1|2]* + + '--fileassocmode' specifies the action for file associations. + If it is set to 1 (the default), only new associations are + added; if it is set to 2, all associations are set to the TeX + Live programs. (See also 'option fileassocs'.) + + *-all* + + Carry out the postactions for all packages + + +File: tlbuild.info, Node: tlmgr print-platform, Next: tlmgr print-platform-info, Prev: tlmgr postaction, Up: tlmgr ACTIONS + +B.6.21 print-platform +--------------------- + +Print the TeX Live identifier for the detected platform +(hardware/operating system) combination to standard output, and exit. +'--print-arch' is a synonym. + + +File: tlbuild.info, Node: tlmgr print-platform-info, Next: tlmgr remove [_option_...] _pkg_..., Prev: tlmgr print-platform, Up: tlmgr ACTIONS + +B.6.22 print-platform-info +-------------------------- + +Print the TeX Live platform identifier, TL platform long name, and +original output from guess. + + +File: tlbuild.info, Node: tlmgr remove [_option_...] _pkg_..., Next: tlmgr repository, Prev: tlmgr print-platform-info, Up: tlmgr ACTIONS + +B.6.23 remove [_option_...] _pkg_... +------------------------------------ + +Remove each _pkg_ specified. Removing a collection removes all package +dependencies (unless '--no-depends' is specified), but not any +collection dependencies of that collection. However, when removing a +package, dependencies are never removed. Options: + +*-all* + + Uninstalls all of TeX Live, asking for confirmation unless + '--force' is also specified. + +*-backup* + +*-backupdir* _directory_ + + These options behave just as with the *note update: (update)tlmgr + update [_option_...] [...]. action (q.v.), except they apply to + making backups of packages before they are removed. The default is + to make such a backup, that is, to save a copy of packages before + removal. + + The *note restore: tlmgr restore. action explains how to restore + from a backup. + +*-no-depends* + + Do not remove dependent packages. + +*-no-depends-at-all* + + See above under *note install: tlmgr install [_option_...] _pkg_... + (and beware). + +*-force* + + By default, removal of a package or collection that is a dependency + of another collection or scheme is not allowed. With this option, + the package will be removed unconditionally. Use with care. + + A package that has been removed using the '--force' option because + it is still listed in an installed collection or scheme will not be + updated, and will be mentioned as 'forcibly removed' in the output + of 'tlmgr update --list'. + +*-dry-run* + + Nothing is actually removed; instead, the actions to be performed + are written to the terminal. + + This action does not automatically remove symlinks to executables +from system directories; you need to run 'tlmgr path remove' (*note +path: tlmgr path.) yourself if you are using this feature and want stale +symlinks removed. + + +File: tlbuild.info, Node: tlmgr repository, Next: tlmgr restore, Prev: tlmgr remove [_option_...] _pkg_..., Up: tlmgr ACTIONS + +B.6.24 repository +----------------- + +*repository list* + +*repository list _path|url|tag_* + +*repository add _path_ [_tag_]* + +*repository remove _path|tag_* + +*repository set _path_[#_tag_] [_path_[#_tag_] ...]* + +*repository status* + + This action manages the list of repositories. See *note + (MULTIPLE_REPOSITORIES):: below for detailed explanations. + + The first form, 'repository list', lists all configured + repositories and the respective tags if set. If a path, url, or + tag is given after the 'list' keyword, it is interpreted as the + source from which to initialize a TL database and lists the + contained packages. This can also be an otherwise-unused + repository, either local or remote. If the option + '--with-platforms' is specified in addition, for each package the + available platforms (if any) are also listed. + + The form 'repository add' adds a repository (optionally attaching a + tag) to the list of repositories, while 'repository remove' removes + a repository, either by full path/url, or by tag. + + The form 'repository set' sets the list of available repositories + to the items given on the command line, overwriting previous + settings. + + The form 'repository status' reports the verification status of the + loaded repositories with the format of one repository per line with + fields separated by a single space: + + The tag (which can be the same as the url); + + = the url; + + = iff machine-readable output is specified, the verification + code (a number); + + = a textual description of the verification status, as the + last field extending to the end of line. + + That is, in normal (not machine-readable) output, the third field + (numeric verification status) is not present. + + In all cases, one of the repositories must be tagged as 'main'; + otherwise, all operations will fail! + + +File: tlbuild.info, Node: tlmgr restore, Next: tlmgr search, Prev: tlmgr repository, Up: tlmgr ACTIONS + +B.6.25 restore +-------------- + +*restore [_option_...] _pkg_ [_rev_]* + +*restore [_option_...] -all* + + Restore a package from a previously-made backup. + + If '--all' is given, try to restore the latest revision of all + package backups found in the backup directory. + + Otherwise, if neither _pkg_ nor _rev_ are given, list the available + backup revisions for all packages. With _pkg_ given but no _rev_, + list all available backup revisions of _pkg_. + + When listing available packages, 'tlmgr' shows the revision, and in + parenthesis the creation time if available (in format yyyy-mm-dd + hh:mm). + + If (and only if) both _pkg_ and a valid revision number _rev_ are + specified, try to restore the package from the specified backup. + + Options: + + *-all* + + Try to restore the latest revision of all package backups + found in the backup directory. Additional non-option + arguments (like _pkg_) are not allowed. + + *-backupdir* _directory_ + + Specify the directory where the backups are to be found. If + not given it will be taken from the configuration setting in + the TLPDB. + + *-dry-run* + + Nothing is actually restored; instead, the actions to be + performed are written to the terminal. + + *-force* + + Don't ask questions. + + *-json* + + When listing backups, the option '--json' turn on JSON output. + The format is an array of JSON objects ('name', 'rev', + 'date'). For details see 'tlpkg/doc/JSON-formats.txt', format + definition: 'TLBACKUPS'. If both '--json' and '--data' are + given, '--json' takes precedence. + + +File: tlbuild.info, Node: tlmgr search, Next: tlmgr shell, Prev: tlmgr restore, Up: tlmgr ACTIONS + +B.6.26 search +------------- + +*search [_option_...] _what_* + +*search [_option_...] -file _what_* + +*search [_option_...] -all _what_* + + By default, search the names, short descriptions, and long + descriptions of all locally installed packages for the argument + _what_, interpreted as a (Perl) regular expression. + + Options: + + *-file* + + List all filenames containing _what_. + + *-all* + + Search everything: package names, descriptions and filenames. + + *-global* + + Search the TeX Live Database of the installation medium, + instead of the local installation. + + *-word* + + Restrict the search of package names and descriptions (but not + filenames) to match only full words. For example, searching + for 'table' with this option will not output packages + containing the word 'tables' (unless they also contain the + word 'table' on its own). + + +File: tlbuild.info, Node: tlmgr shell, Next: tlmgr show, Prev: tlmgr search, Up: tlmgr ACTIONS + +B.6.27 shell +------------ + +Starts an interactive mode, where tlmgr prompts for commands. This can +be used directly, or for scripting. The first line of output is +'protocol' _n_, where _n_ is an unsigned number identifying the protocol +version (currently 1). + + In general, tlmgr actions that can be given on the command line +translate to commands in this shell mode. For example, you can say +'update --list' to see what would be updated. The TLPDB is loaded the +first time it is needed (not at the beginning), and used for the rest of +the session. + + Besides these actions, a few commands are specific to shell mode: + +protocol + + Print 'protocol _n_', the current protocol version. + +help + + Print pointers to this documentation. + +version + + Print tlmgr version information. + +quit, end, bye, byebye, EOF + + Exit. + +restart + + Restart 'tlmgr shell' with the original command line; most useful + when developing 'tlmgr'. + +load [local|remote] + + Explicitly load the local or remote, respectively, TLPDB. + +save + + Save the local TLPDB, presumably after other operations have + changed it. + +get [_var_] =item set [_var_ [_val_]] + + Get the value of _var_, or set it to _val_. Possible _var_ names: + 'debug-translation', 'machine-readable', 'no-execute-actions', + 'require-verification', 'verify-downloads', 'repository', and + 'prompt'. All except 'repository' and 'prompt' are booleans, + taking values 0 and 1, and behave like the corresponding command + line option. The 'repository' variable takes a string, and sets + the remote repository location. The 'prompt' variable takes a + string, and sets the current default prompt. + + If _var_ or then _val_ is not specified, it is prompted for. + + +File: tlbuild.info, Node: tlmgr show, Next: tlmgr uninstall, Prev: tlmgr shell, Up: tlmgr ACTIONS + +B.6.28 show +----------- + +Synonym for *note info: tlmgr info. + + +File: tlbuild.info, Node: tlmgr uninstall, Next: tlmgr update [_option_...] [_pkg_...], Prev: tlmgr show, Up: tlmgr ACTIONS + +B.6.29 uninstall +---------------- + +Synonym for *note remove: tlmgr remove [_option_...] _pkg_.... + + +File: tlbuild.info, Node: tlmgr update [_option_...] [_pkg_...], Prev: tlmgr uninstall, Up: tlmgr ACTIONS + +B.6.30 update [_option_...] [_pkg_...] +-------------------------------------- + +Updates the packages given as arguments to the latest version available +at the installation source. Either '--all' or at least one _pkg_ name +must be specified. Options: + +*-all* + + Update all installed packages except for 'tlmgr' itself. If + updates to 'tlmgr' itself are present, this gives an error, unless + also the option '--force' or '--self' is given. (See below.) + + In addition to updating the installed packages, during the update + of a collection the local installation is (by default) synchronized + to the status of the collection on the server, for both additions + and removals. + + This means that if a package has been removed on the server (and + thus has also been removed from the respective collection), 'tlmgr' + will remove the package in the local installation. This is called + "auto-remove" and is announced as such when using the option + '--list'. This auto-removal can be suppressed using the option + '--no-auto-remove' (not recommended, see option description). + + Analogously, if a package has been added to a collection on the + server that is also installed locally, it will be added to the + local installation. This is called "auto-install" and is announced + as such when using the option '--list'. This auto-installation can + be suppressed using the option '--no-auto-install' (also not + recommended). + + An exception to the collection dependency checks (including the + auto-installation of packages just mentioned) are those that have + been "forcibly removed" by you, that is, you called 'tlmgr remove + --force' on them. (See the 'remove' action documentation.) To + reinstall any such forcibly removed packages use + '--reinstall-forcibly-removed'. + + To reiterate: automatic removals and additions are entirely + determined by comparison of collections. Thus, if you manually + install an individual package 'foo' which is later removed from the + server, 'tlmgr' will not notice and will not remove it locally. + (It has to be this way, without major rearchitecture work, because + the tlpdb does not record the repository from which packages come + from.) + + If you want to exclude some packages from the current update run + (e.g., due to a slow link), see the '--exclude' option below. + +*-self* + + Update 'tlmgr' itself (that is, the infrastructure packages) if + updates to it are present. On Windows this includes updates to the + private Perl interpreter shipped inside TeX Live. + + If this option is given together with either '--all' or a list of + packages, then 'tlmgr' will be updated first and, if this update + succeeds, the new version will be restarted to complete the rest of + the updates. + + In short: + + tlmgr update --self # update infrastructure only + tlmgr update --self --all # update infrastructure and all packages + tlmgr update --force --all # update all packages but *not* infrastructure + # ... this last at your own risk, not recommended! + +*-dry-run* + + Nothing is actually installed; instead, the actions to be performed + are written to the terminal. This is a more detailed report than + '--list'. + +*-list* [_pkg_] + + Concisely list the packages which would be updated, newly + installed, or removed, without actually changing anything. If + '--all' is also given, all available updates are listed. If + '--self' is given, but not '--all', only updates to the critical + packages (tlmgr, texlive infrastructure, perl on Windows, etc.) + are listed. If neither '--all' nor '--self' is given, and in + addition no _pkg_ is given, then '--all' is assumed (thus, 'tlmgr + update --list' is the same as 'tlmgr update --list --all'). If + neither '--all' nor '--self' is given, but specific package names + are given, those packages are checked for updates. + +*-exclude* _pkg_ + + Exclude _pkg_ from the update process. If this option is given + more than once, its arguments accumulate. + + An argument _pkg_ excludes both the package _pkg_ itself and all + its related platform-specific packages _pkg.ARCH_. For example, + + tlmgr update --all --exclude a2ping + + will not update 'a2ping', 'a2ping.i386-linux', or any other + 'a2ping.'_ARCH_ package. + + If this option specifies a package that would otherwise be a + candidate for auto-installation, auto-removal, or reinstallation of + a forcibly removed package, 'tlmgr' quits with an error message. + Excludes are not supported in these circumstances. + + This option can also be set permanently in the tlmgr config file + with the key 'update-exclude'. + +*-no-auto-remove* [_pkg_...] + + By default, 'tlmgr' tries to remove packages in an existing + collection which have disappeared on the server, as described above + under '--all'. This option prevents such removals, either for all + packages (with '--all'), or for just the given _pkg_ names. This + can lead to an inconsistent TeX installation, since packages are + not infrequently renamed or replaced by their authors. Therefore + this is not recommended. + +*-no-auto-install* [_pkg_...] + + Under normal circumstances 'tlmgr' will install packages which are + new on the server, as described above under '--all'. This option + prevents any such automatic installation, either for all packages + (with '--all'), or the given _pkg_ names. + + Furthermore, after the 'tlmgr' run using this has finished, the + packages that would have been auto-installed _will be considered as + forcibly removed_. So, if 'foobar' is the only new package on the + server, then + + tlmgr update --all --no-auto-install + + is equivalent to + + tlmgr update --all + tlmgr remove --force foobar + + Again, since packages are sometimes renamed or replaced, using this + option is not recommended. + +*-reinstall-forcibly-removed* + + Under normal circumstances 'tlmgr' will not install packages that + have been forcibly removed by the user; that is, removed with + 'remove --force', or whose installation was prohibited by + '--no-auto-install' during an earlier update. + + This option makes 'tlmgr' ignore the forcible removals and + re-install all such packages. This can be used to completely + synchronize an installation with the server's idea of what is + available: + + tlmgr update --reinstall-forcibly-removed --all + +*-backup* + +*-backupdir* _directory_ + + These two options control the creation of backups of packages + _before_ updating; that is, backing up packages as currently + installed. If neither option is given, no backup will made. If + '--backupdir' is given and specifies a writable directory then a + backup will be made in that location. If only '--backup' is given, + then a backup will be made to the directory previously set via the + *note option: tlmgr option. action (see below). If both are given + then a backup will be made to the specified _directory_. + + You can also set options via the *note option: tlmgr option. action + to automatically make backups for all packages, and/or keep only a + certain number of backups. + + 'tlmgr' always makes a temporary backup when updating packages, in + case of download or other failure during an update. In contrast, + the purpose of this '--backup' option is to save a persistent + backup in case the actual _content_ of the update causes problems, + e.g., introduces an TeX incompatibility. + + The *note restore: tlmgr restore. action explains how to restore + from a backup. + +*-no-depends* + + If you call for updating a package normally all depending packages + will also be checked for updates and updated if necessary. This + switch suppresses this behavior. + +*-no-depends-at-all* + + See above under *note install: tlmgr install [_option_...] _pkg_... + (and beware). + +*-force* + + Force update of normal packages, without updating 'tlmgr' itself + (unless the '--self' option is also given). Not recommended. + + Also, 'update --list' is still performed regardless of this option. + + If the package on the server is older than the package already +installed (e.g., if the selected mirror is out of date), 'tlmgr' does +not downgrade. Also, packages for uninstalled platforms are not +installed. + + 'tlmgr' saves a copy of the 'texlive.tlpdb' file used for an update +with a suffix representing the repository url, as in +'tlpkg/texlive.tlpdb.'_long-hash-string_. These can be useful for +fallback information, but if you don't like them accumulating (e.g., +'mirror.ctan.org' resolves to many different hosts, each resulting in a +possibly different hash), it's harmless to delete them. + + This action does not automatically add or remove new symlinks in +system directories; you need to run 'tlmgr' *note path: tlmgr path. +yourself if you are using this feature and want new symlinks added. + + +File: tlbuild.info, Node: tlmgr CONFIGURATION FILE FOR TLMGR, Next: tlmgr CRYPTOGRAPHIC VERIFICATION, Prev: tlmgr ACTIONS, Up: tlmgr + +B.7 CONFIGURATION FILE FOR TLMGR +================================ + +'tlmgr' reads two configuration files: one is system-wide, in +'TEXMFSYSCONFIG/tlmgr/config', and the other is user-specific, in +'TEXMFCONFIG/tlmgr/config'. The user-specific one is the default for +the 'conf tlmgr' action. (Run 'kpsewhich -var-value=TEXMFSYSCONFIG' or +'... TEXMFCONFIG ...' to see the actual directory names.) + + A few defaults corresponding to command-line options can be set in +these configuration files. In addition, the system-wide file can +contain a directive to restrict the allowed actions. + + In these config files, empty lines and lines starting with # are +ignored. All other lines must look like: + + key = value + + where the spaces are optional but the '=' is required. + + The allowed keys are: + +'auto-remove', value 0 or 1 (default 1), same as command-line option. + +'gui-expertmode', value 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings. + +'gui-lang' _llcode_, with a language code value as with the command-line option. + +'no-checksums', value 0 or 1 (default 0, see below). + +'persistent-downloads', value 0 or 1 (default 1), same as command-line option. + +'require-verification', value 0 or 1 (default 0), same as command-line option. + +'update-exclude', value: comma-separated list of packages (no space allowed). Same as the command line option '--exclude' for the action 'update'. + +'verify-downloads', value 0 or 1 (default 1), same as command-line option. + + The system-wide config file can contain one additional key: + +'allowed-actions' _action1_ [,_action_,...] The value is a comma-separated list 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 the '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. + + The 'no-checksums' key needs more explanation. By default, package +checksums computed and stored on the server (in the TLPDB) are compared +to checksums computed locally after downloading. 'no-checksums' +disables this process. + + The checksum algorithm is SHA-512. Your system must have one of +(looked for in this order) the Perl 'Digest::SHA' module, the 'openssl' +program (), the 'sha512sum' program (from GNU +Coreutils, ), or finally the +'shasum' program (just to support old Macs). If none of these are +available, a warning is issued and 'tlmgr' proceeds without checking +checksums. (Incidentally, other SHA implementations, such as the pure +Perl and pure Lua modules, are much too slow to be usable in our +context.) 'no-checksums' avoids the warning. + + +File: tlbuild.info, Node: tlmgr CRYPTOGRAPHIC VERIFICATION, Next: tlmgr USER MODE, Prev: tlmgr CONFIGURATION FILE FOR TLMGR, Up: tlmgr + +B.8 CRYPTOGRAPHIC VERIFICATION +============================== + +'tlmgr' and 'install-tl' perform cryptographic verification if possible. +If verification is performed and successful, the programs report +'(verified)' after loading the TLPDB; otherwise, they report '(not +verified)'. But either way, by default the installation and/or updates +proceed normally. + + If a program named 'gpg' is available (that is, found in 'PATH'), by +default cryptographic signatures will be checked: we require the main +repository be signed, but not any additional repositories. If 'gpg' is +not available, by default signatures are not checked and no verification +is carried out, but 'tlmgr' still proceeds normally. + + The behavior of the verification can be controlled by the command +line and config file option 'verify-repo' which takes one of the +following values: 'none', 'main', or 'all'. With 'none', no +verification whatsoever is attempted. With 'main' (the default) +verification is required only for the main repository, and only if 'gpg' +is available; though attempted for all, missing signatures of subsidiary +repositories will not result in an error. Finally, in the case of +'all', 'gpg' must be available and all repositories need to be signed. + + In all cases, if a signature is checked and fails to verify, an error +is raised. + + Cryptographic verification requires checksum checking (described just +above) to succeed, and a working GnuPG ('gpg') program (see below for +search method). Then, unless cryptographic verification has been +disabled, a signature file ('texlive.tlpdb.*.asc') of the checksum file +is downloaded and the signature verified. The signature is created by +the TeX Live Distribution GPG key 0x0D5E5D9106BAB6BC, which in turn is +signed by Karl Berry's key 0x0716748A30D155AD and Norbert Preining's key +0x6CACA448860CDC13. All of these keys are obtainable from the standard +key servers. + + Additional trusted keys can be added using the 'key' action. + +* Menu: + +* tlmgr Configuration of GnuPG invocation:: + + +File: tlbuild.info, Node: tlmgr Configuration of GnuPG invocation, Up: tlmgr CRYPTOGRAPHIC VERIFICATION + +B.8.1 Configuration of GnuPG invocation +--------------------------------------- + +The executable used for GnuPG is searched as follows: If the environment +variable 'TL_GNUPG' is set, it is tested and used; otherwise 'gpg' is +checked; finally 'gpg2' is checked. + + Further adaptation of the 'gpg' invocation can be made using the two +environment variables 'TL_GNUPGHOME', which is passed to 'gpg' as the +value for '--homedir', and 'TL_GNUPGARGS', which replaces the default +options '--no-secmem-warning --no-permission-warning'. + + +File: tlbuild.info, Node: tlmgr USER MODE, Next: tlmgr MULTIPLE REPOSITORIES, Prev: tlmgr CRYPTOGRAPHIC VERIFICATION, Up: tlmgr + +B.9 USER MODE +============= + +'tlmgr' provides a restricted way, called "user mode", to manage +arbitrary texmf trees in the same way as the main installation. For +example, this allows people without write permissions on the +installation location to update/install packages into a tree of their +own. + + 'tlmgr' is switched into user mode with the command line option +'--usermode'. It does not switch automatically, nor is there any +configuration file setting for it. Thus, this option has to be +explicitly given every time user mode is to be activated. + + This mode of 'tlmgr' works on a user tree, by default the value of +the 'TEXMFHOME' variable. This can be overridden with the command line +option '--usertree'. In the following when we speak of the user tree we +mean either 'TEXMFHOME' or the one given on the command line. + + Not all actions are allowed in user mode; 'tlmgr' will warn you and +not carry out any problematic actions. Currently not supported (and +probably will never be) is the 'platform' action. The 'gui' action is +currently not supported, but may be in a future release. + + Some 'tlmgr' actions don't need any write permissions and thus work +the same in user mode and normal mode. Currently these are: 'check', +'help', 'list', 'print-platform', 'print-platform-info', 'search', +'show', 'version'. + + On the other hand, most of the actions dealing with package +management do need write permissions, and thus behave differently in +user mode, as described below: 'install', 'update', 'remove', 'option', +'paper', 'generate', 'backup', 'restore', 'uninstall', 'symlinks'. + + Before using 'tlmgr' in user mode, you have to set up the user tree +with the 'init-usertree' action. This creates _usertree_'/web2c' and +_usertree_'/tlpkg/tlpobj', and a minimal +_usertree_'/tlpkg/texlive.tlpdb'. At that point, you can tell 'tlmgr' +to do the (supported) actions by adding the '--usermode' command line +option. + + In user mode the file _usertree_'/tlpkg/texlive.tlpdb' contains only +the packages that have been installed into the user tree using 'tlmgr', +plus additional options from the "virtual" package +'00texlive.installation' (similar to the main installation's +'texlive.tlpdb'). + + All actions on packages in user mode can only be carried out on +packages that are known as 'relocatable'. This excludes all packages +containing executables and a few other core packages. Of the 2500 or so +packages currently in TeX Live the vast majority are relocatable and can +be installed into a user tree. + + Description of changes of actions in user mode: + +* Menu: + +* tlmgr User mode install:: +* tlmgr User mode backup, restore, remove, update:: +* tlmgr User mode generate, option, paper:: + + +File: tlbuild.info, Node: tlmgr User mode install, Next: tlmgr User mode backup, restore, remove, update, Up: tlmgr USER MODE + +B.9.1 User mode install +----------------------- + +In user mode, the 'install' action checks that the package and all +dependencies are all either relocated or already installed in the system +installation. If this is the case, it unpacks all containers to be +installed into the user tree (to repeat, that's either 'TEXMFHOME' or +the value of '--usertree') and add the respective packages to the user +tree's 'texlive.tlpdb' (creating it if need be). + + Currently installing a collection in user mode installs all dependent +packages, but in contrast to normal mode, does _not_ install dependent +collections. For example, in normal mode 'tlmgr install +collection-context' would install 'collection-basic' and other +collections, while in user mode, _only_ the packages mentioned in +'collection-context' are installed. + + If a package shipping map files is installed in user mode, a backup +of the user's 'updmap.cfg' in 'USERTREE/web2c/' is made, and then this +file regenerated from the list of installed packages. + + +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 + +B.9.2 User mode backup, restore, remove, update +----------------------------------------------- + +In user mode, these actions check that all packages to be acted on are +installed in the user tree before proceeding; otherwise, they behave +just as in normal mode. + + +File: tlbuild.info, Node: tlmgr User mode generate, option, paper, Prev: tlmgr User mode backup, restore, remove, update, Up: tlmgr USER MODE + +B.9.3 User mode generate, option, paper +--------------------------------------- + +In user mode, these actions operate only on the user tree's +configuration files and/or 'texlive.tlpdb'. creates configuration files +in user tree + + +File: tlbuild.info, Node: tlmgr MULTIPLE REPOSITORIES, Next: tlmgr GUI FOR TLMGR, Prev: tlmgr USER MODE, Up: tlmgr + +B.10 MULTIPLE REPOSITORIES +========================== + +The main TeX Live repository contains a vast array of packages. +Nevertheless, additional local repositories can be useful to provide +locally-installed resources, such as proprietary fonts and house styles. +Also, alternative package repositories distribute packages that cannot +or should not be included in TeX Live, for whatever reason. + + The simplest and most reliable method is to temporarily set the +installation source to any repository (with the '-repository' or 'option +repository' command line options), and perform your operations. + + When you are using multiple repositories over a sustained length of +time, however, explicitly switching between them becomes inconvenient. +Thus, it's possible to tell 'tlmgr' about additional repositories you +want to use. The basic command is 'tlmgr repository add'. The rest of +this section explains further. + + When using multiple repositories, one of them has to be set as the +main repository, which distributes most of the installed packages. When +you switch from a single repository installation to a multiple +repository installation, the previous sole repository will be set as the +main repository. + + By default, even if multiple repositories are configured, packages +are _still_ _only_ installed from the main repository. Thus, simply +adding a second repository does not actually enable installation of +anything from there. You also have to specify which packages should be +taken from the new repository, by specifying so-called "pinning" rules, +described next. + +* Menu: + +* tlmgr Pinning:: + + +File: tlbuild.info, Node: tlmgr Pinning, Up: tlmgr MULTIPLE REPOSITORIES + +B.10.1 Pinning +-------------- + +When a package 'foo' is pinned to a repository, a package 'foo' in any +other repository, even if it has a higher revision number, will not be +considered an installable candidate. + + As mentioned above, by default everything is pinned to the main +repository. Let's now go through an example of setting up a second +repository and enabling updates of a package from it. + + First, check that we have support for multiple repositories, and have +only one enabled (as is the case by default): + + $ tlmgr repository list + List of repositories (with tags if set): + /var/www/norbert/tlnet + + Ok. Let's add the 'tlcontrib' repository (this is a real repository +hosted at ) with the tag 'tlcontrib': + + $ tlmgr repository add http://contrib.texlive.info/current tlcontrib + + Check the repository list again: + + $ tlmgr repository list + List of repositories (with tags if set): + http://contrib.texlive.info/current (tlcontrib) + /var/www/norbert/tlnet (main) + + Now we specify a pinning entry to get the package 'classico' from +'tlcontrib': + + $ tlmgr pinning add tlcontrib classico + + Check that we can find 'classico': + + $ tlmgr show classico + package: classico + ... + shortdesc: URW Classico fonts + ... + + - install 'classico': + + $ tlmgr install classico + tlmgr: package repositories: + ... + [1/1, ??:??/??:??] install: classico @tlcontrib [737k] + + In the output here you can see that the 'classico' package has been +installed from the 'tlcontrib' repository ('@tlcontrib'). + + Finally, 'tlmgr pinning' also supports removing certain or all +packages from a given repository: + + $ tlmgr pinning remove tlcontrib classico # remove just classico + $ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib + + A summary of 'tlmgr pinning' actions is given above. + + +File: tlbuild.info, Node: tlmgr GUI FOR TLMGR, Next: tlmgr MACHINE-READABLE OUTPUT, Prev: tlmgr MULTIPLE REPOSITORIES, Up: tlmgr + +B.11 GUI FOR TLMGR +================== + +The graphical user interface for 'tlmgr' requires Perl/Tk +. For Unix-based +systems Perl/Tk (as well as Perl of course) has to be installed outside +of TL. has a list of +invocations for some distros. For Windows the necessary modules are no +longer shipped within TeX Live, so you'll have to have an external Perl +available that includes them. + + We are talking here about the GUI built into tlmgr itself, not about +the other tlmgr GUIs, which are: tlshell (Tcl/Tk-based), tlcockpit +(Java-based) and, only on Macs, TeX Live Utility. These are invoked as +separate programs. + + The GUI mode of tlmgr is started with the invocation 'tlmgr gui'; +assuming Tk is loadable, the graphical user interface will be shown. +The main window contains a menu bar, the main display, and a status area +where messages normally shown on the console are displayed. + + Within the main display there are three main parts: the 'Display +configuration' area, the list of packages, and the action buttons. + + Also, at the top right the currently loaded repository is shown; this +also acts as a button and when clicked will try to load the default +repository. To load a different repository, see the 'tlmgr' menu item. + + Finally, the status area at the bottom of the window gives additional +information about what is going on. + +* Menu: + +* tlmgr Main display:: +* tlmgr Menu bar:: +* tlmgr GUI options:: + + +File: tlbuild.info, Node: tlmgr Main display, Next: tlmgr Menu bar, Up: tlmgr GUI FOR TLMGR + +B.11.1 Main display +------------------- + +* Menu: + +* tlmgr Display configuration area:: +* tlmgr Package list area:: +* tlmgr Main display action buttons:: + + +File: tlbuild.info, Node: tlmgr Display configuration area, Next: tlmgr Package list area, Up: tlmgr Main display + +B.11.1.1 Display configuration area +................................... + +The first part of the main display allows you to specify (filter) which +packages are shown. By default, all are shown. Changes here are +reflected right away. + +Status + + Select whether to show all packages (the default), only those + installed, only those _not_ installed, or only those with update + available. + +Category + + Select which categories are shown: packages, collections, and/or + schemes. These are briefly explained in the *note DESCRIPTION: + tlmgr DESCRIPTION. section above. + +Match + + Select packages matching for a specific pattern. By default, this + searches both descriptions and filenames. You can also select a + subset for searching. + +Selection + + Select packages to those selected, those not selected, or all. + Here, "selected" means that the checkbox in the beginning of the + line of a package is ticked. + +Display configuration buttons + + To the right there are three buttons: select all packages, select + none (a.k.a. deselect all), and reset all these filters to the + defaults, i.e., show all available. + + +File: tlbuild.info, Node: tlmgr Package list area, Next: tlmgr Main display action buttons, Prev: tlmgr Display configuration area, Up: tlmgr Main display + +B.11.1.2 Package list area +.......................... + +The second are of the main display lists all installed packages. If a +repository is loaded, those that are available but not installed are +also listed. + + Double clicking on a package line pops up an informational window +with further details: the long description, included files, etc. + + Each line of the package list consists of the following items: + +a checkbox + + Used to select particular packages; some of the action buttons (see + below) work only on the selected packages. + +package name + + The name (identifier) of the package as given in the database. + +local revision (and version) + + If the package is installed the TeX Live revision number for the + installed package will be shown. If there is a catalogue version + given in the database for this package, it will be shown in + parentheses. However, the catalogue version, unlike the TL + revision, is not guaranteed to reflect what is actually installed. + +remote revision (and version) + + If a repository has been loaded the revision of the package in the + repository (if present) is shown. As with the local column, if a + catalogue version is provided it will be displayed. And also as + with the local column, the catalogue version may be stale. + +short description + + The short description of the package. + + +File: tlbuild.info, Node: tlmgr Main display action buttons, Prev: tlmgr Package list area, Up: tlmgr Main display + +B.11.1.3 Main display action buttons +.................................... + +Below the list of packages are several buttons: + +Update all installed + + This calls 'tlmgr update --all', i.e., tries to update all + available packages. Below this button is a toggle to allow + reinstallation of previously removed packages as part of this + action. + + The other four buttons only work on the selected packages, i.e., + those where the checkbox at the beginning of the package line is + ticked. + +Update + + Update only the selected packages. + +Install + + Install the selected packages; acts like 'tlmgr install', i.e., + also installs dependencies. Thus, installing a collection installs + all its constituent packages. + +Remove + + Removes the selected packages; acts like 'tlmgr remove', i.e., it + will also remove dependencies of collections (but not dependencies + of normal packages). + +Backup + + Makes a backup of the selected packages; acts like 'tlmgr backup'. + This action needs the option 'backupdir' set (see 'Options -' + General>). + + +File: tlbuild.info, Node: tlmgr Menu bar, Next: tlmgr GUI options, Prev: tlmgr Main display, Up: tlmgr GUI FOR TLMGR + +B.11.2 Menu bar +--------------- + +The following entries can be found in the menu bar: + +'tlmgr' menu + + The items here load various repositories: the default as specified + in the TeX Live database, the default network repository, the + repository specified on the command line (if any), and an + arbitrarily manually-entered one. Also has the so-necessary 'quit' + operation. + +'Options menu' + + Provides access to several groups of options: 'Paper' + (configuration of default paper sizes), 'Platforms' (only on Unix, + configuration of the supported/installed platforms), 'GUI Language' + (select language used in the GUI interface), and 'General' + (everything else). + + Several toggles are also here. The first is 'Expert options', + which is set by default. If you turn this off, the next time you + start the GUI a simplified screen will be shown that display only + the most important functionality. This setting is saved in the + configuration file of 'tlmgr'; see *note CONFIGURATION FILE FOR + TLMGR: tlmgr CONFIGURATION FILE FOR TLMGR. for details. + + The other toggles are all off by default: for debugging output, to + disable the automatic installation of new packages, and to disable + the automatic removal of packages deleted from the server. Playing + with the choices of what is or isn't installed may lead to an + inconsistent TeX Live installation; e.g., when a package is + renamed. + +'Actions menu' + + Provides access to several actions: update the filename database + (aka 'ls-R', 'mktexlsr', 'texhash'), rebuild all formats + ('fmtutil-sys --all'), update the font map database ('updmap-sys'), + restore from a backup of a package, and use of symbolic links in + system directories (not on Windows). + + The final action is to remove the entire TeX Live installation + (also not on Windows). + +'Help menu' + + Provides access to the TeX Live manual (also on the web at + ) and the usual "About" box. + + +File: tlbuild.info, Node: tlmgr GUI options, Prev: tlmgr Menu bar, Up: tlmgr GUI FOR TLMGR + +B.11.3 GUI options +------------------ + +Some generic Perl/Tk options can be specified with 'tlmgr gui' to +control the display: + +'-background' _color_ + + Set background color. + +'-font "' _fontname_ _fontsize_ '"' + + Set font, e.g., 'tlmgr gui -font "helvetica 18"'. The argument to + '-font' must be quoted, i.e., passed as a single string. + +'-foreground' _color_ + + Set foreground color. + +'-geometry' _geomspec_ + + Set the X geometry, e.g., 'tlmgr gui -geometry 1024x512-0+0' + creates the window of (approximately) the given size in the + upper-right corner of the display. + +'-xrm' _xresource_ + + Pass the arbitrary X resource string _xresource_. + + A few other obscure options are recognized but not mentioned here. +See the Perl/Tk documentation () for +the complete list, and any X documentation for general information. + + +File: tlbuild.info, Node: tlmgr MACHINE-READABLE OUTPUT, Next: tlmgr ENVIRONMENT VARIABLES, Prev: tlmgr GUI FOR TLMGR, Up: tlmgr + +B.12 MACHINE-READABLE OUTPUT +============================ + +With the '--machine-readable' option, 'tlmgr' writes to stdout in the +fixed line-oriented format described here, and the usual informational +messages for human consumption are written to stderr (normally they are +written to stdout). The idea is that a program can get all the +information it needs by reading stdout. + + Currently this option only applies to the *note update: tlmgr update +[_option_...] [_pkg_...], *note install: tlmgr install [_option_...] +_pkg_..., and *note option: tlmgr option. actions. + +* Menu: + +* tlmgr Machine-readable 'update' and 'install' output:: +* tlmgr Machine-readable 'option' output:: + + +File: tlbuild.info, Node: tlmgr Machine-readable 'update' and 'install' output, Next: tlmgr Machine-readable 'option' output, Up: tlmgr MACHINE-READABLE OUTPUT + +B.12.1 Machine-readable 'update' and 'install' output +----------------------------------------------------- + +The output format is as follows: + + fieldname "\t" value + ... + "end-of-header" + pkgname status localrev serverrev size runtime esttot + ... + "end-of-updates" + other output from post actions, not in machine readable form + + The header section currently has two fields: 'location-url' (the +repository source from which updates are being drawn), and 'total-bytes' +(the total number of bytes to be downloaded). + + The _localrev_ and _serverrev_ fields for each package are the +revision numbers in the local installation and server repository, +respectively. The _size_ field is the number of bytes to be downloaded, +i.e., the size of the compressed tar file for a network installation, +not the unpacked size. The runtime and esttot fields are only present +for updated and auto-install packages, and contain the currently passed +time since start of installation/updates and the estimated total time. + + Line endings may be either LF or CRLF depending on the current +platform. + +'location-url' _location_ + + The _location_ may be a url (including 'file:///foo/bar/...'), or a + directory name ('/foo/bar'). It is the package repository from + which the new package information was drawn. + +'total-bytes' _count_ + + The _count_ is simply a decimal number, the sum of the sizes of all + the packages that need updating or installing (which are listed + subsequently). + + Then comes a line with only the literal string 'end-of-header'. + + Each following line until a line with literal string 'end-of-updates' +reports on one package. The fields on each line are separated by a tab. +Here are the fields. + +_pkgname_ + + The TeX Live package identifier, with a possible platform suffix + for executables. For instance, 'pdftex' and 'pdftex.i386-linux' + are given as two separate packages, one on each line. + +_status_ + + The status of the package update. One character, as follows: + + 'd' + + The package was removed on the server. + + 'f' + + The package was removed in the local installation, even though + a collection depended on it. (E.g., the user ran 'tlmgr + remove --force'.) + + 'u' + + Normal update is needed. + + 'r' + + Reversed non-update: the locally-installed version is newer + than the version on the server. + + 'a' + + Automatically-determined need for installation, the package is + new on the server and is (most probably) part of an installed + collection. + + 'i' + + Package will be installed and isn't present in the local + installation (action install). + + 'I' + + Package is already present but will be reinstalled (action + install). + +_localrev_ + + The revision number of the installed package, or '-' if it is not + present locally. + +_serverrev_ + + The revision number of the package on the server, or '-' if it is + not present on the server. + +_size_ + + The size in bytes of the package on the server. The sum of all the + package sizes is given in the 'total-bytes' header field mentioned + above. + +_runtime_ + + The run time since start of installations or updates. + +_esttot_ + + The estimated total time. + + +File: tlbuild.info, Node: tlmgr Machine-readable 'option' output, Prev: tlmgr Machine-readable 'update' and 'install' output, Up: tlmgr MACHINE-READABLE OUTPUT + +B.12.2 Machine-readable 'option' output +--------------------------------------- + +The output format is as follows: + + key "\t" value + + If a value is not saved in the database the string '(not set)' is +shown. + + If you are developing a program that uses this output, and find that +changes would be helpful, do not hesitate to write the mailing list. + + +File: tlbuild.info, Node: tlmgr ENVIRONMENT VARIABLES, Next: tlmgr AUTHORS AND COPYRIGHT, Prev: tlmgr MACHINE-READABLE OUTPUT, Up: tlmgr + +B.13 ENVIRONMENT VARIABLES +========================== + +'tlmgr' uses many of the standard TeX environment variables, as reported +by, e.g., 'tlmgr conf' (*note conf: tlmgr conf.). + + In addition, for ease in scripting and debugging, 'tlmgr' looks for +the following environment variables. These are not of interest for +normal user installations. + +'TEXLIVE_COMPRESSOR' + + This variable allows selecting a different compressor program for + backups and intermediate rollback containers. The order of + selection is: + + 1. If the environment variable 'TEXLIVE_COMPRESSOR' is defined, + use it; abort if it doesn't work. Possible values: 'lz4', + 'gzip', 'xz'. The necessary options are added internally. + + 2. If lz4 is available (either from the system or TL) and + working, use that. + + 3. If gzip is available (from the system) and working, use that. + + 4. If xz is available (either from the system or TL) and working, + use that. + + lz4 and gzip are faster in creating tlmgr's local backups, hence + they are preferred. The unconditional use of xz for the tlnet + containers is unaffected, to minimize download sizes. + +'TEXLIVE_DOWNLOADER' + +'TL_DOWNLOAD_PROGRAM' + +'TL_DOWNLOAD_ARGS' + + These options allow selecting different download programs then the + ones automatically selected by the installer. The order of + selection is: + + 1. If the environment variable 'TEXLIVE_DOWNLOADER' is defined, + use it; abort if the specified program doesn't work. Possible + values: 'lwp', 'curl', 'wget'. The necessary options are + added internally. + + 2. If the environment variable 'TL_DOWNLOAD_PROGRAM' is defined + (can be any value), use it together with 'TL_DOWNLOAD_ARGS'; + abort if it doesn't work. + + 3. If LWP is available and working, use that (by far the most + efficient method, as it supports persistent downloads). + + 4. If curl is available (from the system) and working, use that. + + 5. If wget is available (either from the system or TL) and + working, use that. + + TL provides 'wget' binaries for platforms where necessary, so some + download method should always be available. + +'TEXLIVE_PREFER_OWN' + + By default, compression and download programs provided by the + system, i.e., found along 'PATH' are preferred over those shipped + with TeX Live. + + This can create problems with systems that are too old, and so can + be overridden by setting the environment variable + 'TEXLIVE_PREFER_OWN' to 1. In this case, executables shipped with + TL will be preferred. + + Extra compression/download programs not provided by TL, such as + gzip, lwp, and curl, are still checked for on the system and used + if available, per the above. 'TEXLIVE_PREFER_OWN' only applies + when the program being checked for is shipped with TL, namely the + lz4 and xz compressors and wget downloader. + + Exception: on Windows, the 'tar.exe' shipped with TL is always + used, regardless of any setting. + + +File: tlbuild.info, Node: tlmgr AUTHORS AND COPYRIGHT, Prev: tlmgr ENVIRONMENT VARIABLES, Up: tlmgr + +B.14 AUTHORS AND COPYRIGHT +========================== + +This script and its documentation were written for the TeX Live +distribution () and both are licensed under the +GNU General Public License Version 2 or later. + + $Id: tlmgr.pl 54118 2020-03-05 22:27:22Z karl $ + + +File: tlbuild.info, Node: Index, Prev: tlmgr, Up: Top + +Index +***** + +[index] +* Menu: + +* --bindir configure option: '--prefix' '--bindir' .... + (line 6) +* --bindir configure option <1>: '--enable-multiplatform'. + (line 6) +* --build=HOST: Cross configuring. (line 6) +* --disable-all-packages: Build one package. (line 6) +* --disable-all-pkgs: '--disable-all-pkgs'. + (line 6) +* --disable-bibtex8: Configure options for 'texk/bibtex-x'. + (line 9) +* --disable-bibtexu: Configure options for 'texk/bibtex-x'. + (line 12) +* --disable-dump-share: Configure options for 'texk/web2c'. + (line 27) +* --disable-dvipdfmx: Configure options for 'texk/dvipdfm-x'. + (line 12) +* --disable-etex-synctex: Configure options for 'texk/web2c'. + (line 59) +* --disable-ipc: Configure options for 'texk/web2c'. + (line 31) +* --disable-largefile: '--disable-largefile'. + (line 6) +* --disable-linked-scripts: Configure options for 'texk/texlive'. + (line 6) +* --disable-mf-nowin: Configure options for 'texk/web2c'. + (line 34) +* --disable-missing: '--disable-missing'. (line 6) +* --disable-native-texlive-build: '--disable-native-texlive-build'. + (line 6) +* --disable-PROG: '--enable-PROG' '--disable-PROG'. + (line 6) +* --disable-synctex: Configure options for 'texk/web2c'. + (line 64) +* --disable-tex: Configure options for 'texk/web2c'. + (line 37) +* --disable-web-progs: Configure options for 'texk/web2c'. + (line 41) +* --disable-xdvipdfmx: Configure options for 'texk/dvipdfm-x'. + (line 15) +* --enable-*win for Metafont window support: Configure options for 'texk/web2c'. + (line 55) +* --enable-auto-core: Configure options for 'texk/web2c'. + (line 45) +* --enable-compiler-warnings=LEVEL: '--enable-compiler-warnings='LEVEL. + (line 6) +* --enable-cxx-runtime-hack: Macros for compilers. + (line 29) +* --enable-etex: Configure options for 'texk/web2c'. + (line 37) +* --enable-libtool-hack: Configure options for 'texk/web2c'. + (line 50) +* --enable-maintainer-mode: Build system tools. (line 28) +* --enable-maintainer-mode <1>: '--enable-maintainer-mode'. + (line 6) +* --enable-missing to ignore dependencies: Build one package. (line 71) +* --enable-mktextfm-default: 'kpathsea' library. (line 18) +* --enable-multiplatform: '--enable-multiplatform'. + (line 6) +* --enable-PROG: '--enable-PROG' '--disable-PROG'. + (line 6) +* --enable-shared: '--enable-shared'. (line 6) +* --enable-silent-rules: '--enable-silent-rules'. + (line 6) +* --enable-tex-synctex: Configure options for 'texk/web2c'. + (line 59) +* --enable-texlive-build: '--disable-native-texlive-build'. + (line 15) +* --enable-xi2-scrolling: Configure options for 'texk/xdvik'. + (line 13) +* --enable-xindy-docs: Configure options for 'utils/xindy'. + (line 10) +* --enable-xindy-rules: Configure options for 'utils/xindy'. + (line 6) +* --host=HOST: Cross configuring. (line 6) +* --libdir configure option: '--enable-multiplatform'. + (line 6) +* --no-clean Build option: Build problems. (line 6) +* --prefix configure option: '--prefix' '--bindir' .... + (line 6) +* --with-banner-add=STR: Configure options for 'texk/web2c'. + (line 6) +* --with-clisp-runtime=FILENAME: Configure options for 'utils/xindy'. + (line 14) +* --with-editor=CMD: Configure options for 'texk/web2c'. + (line 11) +* --with-fontconfig-includes=DIR: Configure options for 'texk/web2c'. + (line 16) +* --with-fontconfig-libdir=DIR: Configure options for 'texk/web2c'. + (line 16) +* --with-gs=FILENAME: Configure options for 'texk/xdvik'. + (line 6) +* --with-LIB-includes=DIR, -libdir: Library-specific configure options. + (line 16) +* --with-libgs-includes, -libdir: Configure options for 'texk/dvisvgm'. + (line 17) +* --with-system-kpathsea: 'kpathsea' library. (line 13) +* --with-system-LIB: Adding a new generic library module. + (line 34) +* --with-system-LIB <1>: Library-specific configure options. + (line 9) +* --with-system-libgs: Configure options for 'texk/dvisvgm'. + (line 6) +* --with-xdvi-x-toolkit: 'xdvik' package. (line 21) +* --with-xdvi-x-toolkit=KIT: Configure options for 'texk/xdvik'. + (line 9) +* --without-libgs: Configure options for 'texk/dvisvgm'. + (line 12) +* --without-ln-s: '--without-ln-s'. (line 6) +* --without-x: '--without-x'. (line 6) +* -C configure option: Build in parallel. (line 11) +* -j make option: Build in parallel. (line 6) +* ac/withenable.ac: Adding a new program module. + (line 42) +* adapting TeX Live for distros: Distro builds. (line 54) +* adding a new generic library: Adding a new generic library module. + (line 6) +* adding a new program: Adding a new program module. + (line 6) +* adding a new TeX-specific library: Adding a new TeX-specific library module. + (line 6) +* adding to TeX Live: Extending TeX Live. (line 6) +* 'am/' top-level directory: Top-level directories. + (line 14) +* ANSI C: Declarations and definitions. + (line 6) +* 'ApplicationServices' Mac framework, required by 'xetex': Prerequisites. + (line 31) +* asymptote: Linked scripts. (line 23) +* asymptote <1>: 'asymptote'. (line 6) +* Autoconf: Overview of build system. + (line 6) +* autoconf macros: Autoconf macros. (line 6) +* Automake: Overview of build system. + (line 6) +* autoreconf, for new program: Adding a new program module. + (line 76) +* biber: Linked scripts. (line 23) +* bibtex-x: Configure options for 'texk/bibtex-x'. + (line 6) +* bibtex8: Configure options for 'texk/bibtex-x'. + (line 6) +* bibtexu: Configure options for 'texk/bibtex-x'. + (line 6) +* BSD distro: Distro builds. (line 6) +* build directory, required: Building. (line 17) +* build iteration: Build iteration. (line 6) +* build on demand: Build one package. (line 6) +* build one engine: Build one engine. (line 6) +* build one package: Build one package. (line 6) +* build problems: Build problems. (line 6) +* Build script: Building. (line 6) +* build system, design of: Overview of build system. + (line 6) +* 'build-aux/' top-level directory: Top-level directories. + (line 30) +* BUILDCC, BUILDCFLAGS, ...: Cross configuring. (line 42) +* building: Building. (line 6) +* building a distribution: Build distribution. (line 6) +* building in parallel: Build in parallel. (line 6) +* C++11, removing dependent sources: Build one package. (line 64) +* C++11, required: Prerequisites. (line 15) +* C, ANSI, required: Declarations and definitions. + (line 6) +* C99, avoided: Declarations and definitions. + (line 6) +* cache file, for 'configure': Build in parallel. (line 11) +* cache for 'configure': Build in parallel. (line 6) +* callexe.c: Macros for Windows. (line 32) +* CC: Variables for configure. + (line 10) +* CC=C-COMPILER: Build one package. (line 78) +* CC_BUILD: Cross problems. (line 13) +* ChangeLog: Adding a new program module. + (line 73) +* chktex: Declarations and definitions. + (line 18) +* clisp: Variables for configure. + (line 18) +* CLISP: Variables for configure. + (line 17) +* CLISP <1>: Configure options for 'utils/xindy'. + (line 14) +* 'clisp', required by 'xindy': Prerequisites. (line 35) +* 'Cocoa' Mac framework, required by 'xetex': Prerequisites. (line 31) +* coding conventions: Coding conventions. (line 6) +* compilers, C and C++11: Prerequisites. (line 6) +* config.guess, config.sub, ...: Top-level directories. + (line 30) +* 'configure' options: Configure options. (line 6) +* 'configure' options, for 'bibtex-x': Configure options for 'texk/bibtex-x'. + (line 6) +* 'configure' options, for 'dvipdfm-x': Configure options for 'texk/dvipdfm-x'. + (line 6) +* 'configure' options, for 'dvisvgm': Configure options for 'texk/dvisvgm'. + (line 6) +* 'configure' options, for 'kpathsea': Configure options for 'kpathsea'. + (line 6) +* 'configure' options, for 'texk/texlive': Configure options for 'texk/texlive'. + (line 6) +* 'configure' options, for 'web2c': Configure options for 'texk/web2c'. + (line 6) +* 'configure' options, for 'xdvik': Configure options for 'texk/xdvik'. + (line 6) +* 'configure' options, for 'xindy': Configure options for 'utils/xindy'. + (line 6) +* 'configure' options, global: Global configure options. + (line 6) +* 'configure' options, library-specific: Library-specific configure options. + (line 6) +* 'configure' options, program-specific: Program-specific configure options. + (line 6) +* 'configure' variables: Variables for configure. + (line 6) +* configure.ac: Adding a new program module. + (line 45) +* configuring, for cross compilation: Cross configuring. (line 6) +* 'const': Const. (line 6) +* continuous integration: Continuous integration. + (line 6) +* conventions, coding: Coding conventions. (line 6) +* CPPFLAGS: Variables for configure. + (line 12) +* cross compilation: Cross compilation. (line 6) +* cross compilation configuring: Cross configuring. (line 6) +* cross compilation problems: Cross problems. (line 6) +* cross compilation, with host binary: 'xdvik' package. (line 14) +* ctangle: Cross problems. (line 26) +* CXX: Variables for configure. + (line 11) +* CXX=C++-COMPILER: Build one package. (line 78) +* declarations and definitions, in source code: Declarations and definitions. + (line 6) +* declarations before statements, avoiding: Declarations and definitions. + (line 6) +* dependencies, with several output files: Build in parallel. (line 6) +* DESTDIR: '--prefix' '--bindir' .... + (line 9) +* directories, for installation: Installation directories. + (line 6) +* directories, top-level: Top-level directories. + (line 6) +* discards qualifiers warning: Const. (line 30) +* 'dist' and 'distcheck' targets for 'make': Build distribution. + (line 6) +* distribution tarball, making: Build distribution. (line 6) +* distro, building for: Distro builds. (line 6) +* dvipdfm-x: Configure options for 'texk/dvipdfm-x'. + (line 6) +* dvipdfmx: Configure options for 'texk/dvipdfm-x'. + (line 6) +* dvisvgm: Configure options for 'texk/dvisvgm'. + (line 6) +* engine, adding new: Adding a new program module. + (line 104) +* engine, building one: Build one engine. (line 6) +* environment variables, for 'configure': Configure options. (line 16) +* exec_prefix: '--enable-multiplatform'. + (line 6) +* extending TeX Live: Extending TeX Live. (line 6) +* 'extern' functions: Declarations and definitions. + (line 41) +* failure to build: Build problems. (line 6) +* flags, macros for library and header: Macros for library and header flags. + (line 6) +* 'fontconfig' library, required by 'xetex': Prerequisites. (line 31) +* FreeType: Prerequisites. (line 11) +* 'freetype' cross compiling: Cross problems. (line 13) +* freetype library: 'freetype' library. (line 6) +* freetype-config: 'freetype' library. (line 13) +* freetype-config <1>: Variables for configure. + (line 24) +* FT2_CONFIG: Variables for configure. + (line 21) +* gcc, default compilers: Build one package. (line 78) +* general setup macros: General setup macros. + (line 6) +* generic library module, adding: Adding a new generic library module. + (line 6) +* Ghostscript location for Xdvik: Configure options for 'texk/xdvik'. + (line 6) +* git-svn: Transfer from Subversion to Github. + (line 6) +* global 'configure' options: Global configure options. + (line 6) +* 'gmake', required: Prerequisites. (line 11) +* GNU 'make', required: Prerequisites. (line 11) +* GNU tools, needed for building: Build system tools. (line 6) +* GNU/Linux distro: Distro builds. (line 6) +* Gnulib, used for common files: Top-level directories. + (line 30) +* ICU cross compiling: Cross problems. (line 20) +* ICU libraries: Variables for configure. + (line 24) +* icu-config: Variables for configure. + (line 24) +* ICU_CONFIG: Variables for configure. + (line 22) +* infrastructure, tools needed for: Build system tools. (line 6) +* 'inst/' top-level directory: Top-level directories. + (line 39) +* install-tl, TeX Live installer: Installing. (line 8) +* installation directories: Installation directories. + (line 6) +* installing: Installing. (line 6) +* interprocess communication: Configure options for 'texk/web2c'. + (line 31) +* introduction: Introduction. (line 6) +* iteration through sources, by 'configure' and 'make': Build iteration. + (line 6) +* kpathsea library: 'kpathsea' library. (line 6) +* kpathsea.ac: 'kpathsea' library. (line 18) +* kpse-libpng-flags.m4: 'png' library. (line 46) +* kpse-pkgs.m4: Overview of build system. + (line 30) +* kpse-zlib-flags.m4: 'zlib' library. (line 6) +* kpsewhich: Variables for configure. + (line 30) +* KPSEWHICH: Variables for configure. + (line 29) +* KPSE_ADD_FLAGS: Macros for library and header flags. + (line 20) +* KPSE_ALL_SYSTEM_FLAGS: Adding a new generic library module. + (line 34) +* KPSE_BASIC: General setup macros. + (line 8) +* KPSE_CHECK_LATEX: Macros for programs. (line 8) +* KPSE_CHECK_PDFLATEX: Macros for programs. (line 15) +* KPSE_CHECK_PERL: Macros for programs. (line 18) +* KPSE_CHECK_WIN32: Macros for Windows. (line 9) +* KPSE_COMMON: General setup macros. + (line 16) +* KPSE_COMPILER_VISIBILITY: Macros for compilers. + (line 18) +* KPSE_COMPILER_WARNINGS: Macros for compilers. + (line 8) +* KPSE_COND_MINGW32: Macros for Windows. (line 19) +* KPSE_COND_WIN32: Macros for Windows. (line 15) +* KPSE_COND_WIN32_WRAP: Macros for Windows. (line 24) +* kpse_cv_cxx_hack: Macros for compilers. + (line 33) +* kpse_cv_have_win32: Macros for Windows. (line 10) +* kpse_cv_visibility_c[xx]flags: Macros for compilers. + (line 25) +* kpse_cv_warning_cflags: Macros for compilers. + (line 15) +* KPSE_CXX_HACK: Macros for compilers. + (line 28) +* KPSE_ENABLE_PROG: Adding a new program module. + (line 14) +* KPSE_LARGEFILE: Macros for libraries. + (line 8) +* KPSE_LIBPNG_FLAGS: Macros for library and header flags. + (line 10) +* KPSE_LIBPNG_FLAGS <1>: 'png' library. (line 46) +* kpse_libs_pkgs: Adding a new generic library module. + (line 6) +* KPSE_LIB_FLAGS: Macros for library and header flags. + (line 6) +* KPSE_LIB_FLAGS <1>: Adding a new generic library module. + (line 26) +* KPSE_LIB_SYSTEM_FLAGS: Adding a new generic library module. + (line 34) +* KPSE_PROG_LEX: Macros for programs. (line 21) +* KPSE_RESTORE_FLAGS: Macros for library and header flags. + (line 24) +* kpse_texk_pkgs: Adding a new program module. + (line 6) +* kpse_texlibs_pkgs: Adding a new TeX-specific library module. + (line 11) +* KPSE_TRY_LIB: 'png' library. (line 18) +* KPSE_TRY_LIB <1>: Adding a new generic library module. + (line 20) +* KPSE_TRY_LIBXX: 'png' library. (line 31) +* KPSE_TRY_LIBXX <1>: Adding a new generic library module. + (line 20) +* kpse_utils_pkgs: Adding a new program module. + (line 10) +* KPSE_WIN32_CALL: Macros for Windows. (line 31) +* KPSE_WITH_LIB: Adding a new generic library module. + (line 11) +* KPSE_WITH_TEXLIB: Adding a new TeX-specific library module. + (line 14) +* large file support: '--disable-largefile'. + (line 6) +* LATEX: Variables for configure. + (line 40) +* layout of sources: Layout and infrastructure. + (line 6) +* LFS (large file support): '--disable-largefile'. + (line 6) +* libexpat, dependency of 'libfontconfig': Configure options for 'texk/web2c'. + (line 50) +* libfontconfig, hack for avoiding linking dependencies: Configure options for 'texk/web2c'. + (line 50) +* libfreetype: Variables for configure. + (line 24) +* 'libfreetype', and 'const': Const. (line 21) +* libpng library: 'png' library. (line 6) +* library module, generic, adding: Adding a new generic library module. + (line 6) +* library module, TeX-specific, adding: Adding a new TeX-specific library module. + (line 6) +* library modules: Library modules. (line 6) +* library-specific 'configure' options: Library-specific configure options. + (line 6) +* 'libsigsegv', required by 'xindy': Prerequisites. (line 35) +* libstc++, statically linking: Macros for compilers. + (line 29) +* Libtool: Overview of build system. + (line 6) +* libtool, hack for avoiding excessive linking: Configure options for 'texk/web2c'. + (line 50) +* libXt: Configure options for 'texk/web2c'. + (line 22) +* linked scripts: Linked scripts. (line 6) +* linking C++ libraries statically: Macros for compilers. + (line 29) +* lisp.run, lisp.exe: Configure options for 'utils/xindy'. + (line 14) +* LittleEndian architectures: Configure options for 'texk/web2c'. + (line 27) +* 'm4/' top-level directory: Top-level directories. + (line 14) +* macros, for compilers: Macros for compilers. + (line 6) +* macros, for libraries: Macros for libraries. + (line 6) +* macros, for library and header flags: Macros for library and header flags. + (line 6) +* macros, for programs: Macros for programs. (line 6) +* macros, for Windows: Macros for Windows. (line 6) +* macros, general setup: General setup macros. + (line 6) +* MAKE: Variables for configure. + (line 33) +* make -t: Build system tools. (line 43) +* 'make' rules, verbose vs. silent: '--enable-silent-rules'. + (line 6) +* Makefile.am: Adding a new program module. + (line 46) +* mf-nowin: Configure options for 'texk/web2c'. + (line 34) +* 'mingw32': Cross configuring. (line 27) +* MINGW32, Automake conditional: Macros for Windows. (line 20) +* mktex.ac: 'kpathsea' library. (line 18) +* mktextfm: 'kpathsea' library. (line 18) +* modules, for libraries: Library modules. (line 6) +* modules, for programs: Program modules. (line 6) +* motif: Configure options for 'texk/xdvik'. + (line 9) +* native cross compilation: Cross compilation. (line 10) +* NEWPROG-SRC, original source subdirectory: Adding a new program module. + (line 33) +* OBJCXX=OBJC-COMPILER: Build one package. (line 78) +* one engine, building: Build one engine. (line 6) +* one package, building: Build one package. (line 6) +* OpenGL, required for Asymptote: 'asymptote'. (line 6) +* operating system distribution, building for: Distro builds. (line 6) +* otangle: Cross problems. (line 26) +* overall build process: Building. (line 6) +* parallel build: Build in parallel. (line 6) +* paths, for installation: Installation directories. + (line 6) +* PDF files, size of: '--disable-largefile'. + (line 11) +* PDFLATEX: Variables for configure. + (line 41) +* PERL: Variables for configure. + (line 39) +* 'perl', required by 'web2c', etc.: Prerequisites. (line 23) +* PKG_CONFIG: Variables for configure. + (line 23) +* plain.tex, not in source tree: Installing. (line 8) +* png library: 'png' library. (line 6) +* PostScript files, size of: '--disable-largefile'. + (line 11) +* Preining, Norbert: Distro builds. (line 54) +* preloaded binaries: Configure options for 'texk/web2c'. + (line 45) +* prerequisites for building: Prerequisites. (line 6) +* problems with build: Build problems. (line 6) +* program module, adding: Adding a new program module. + (line 6) +* program modules: Program modules. (line 6) +* program-specific 'configure' options: Program-specific configure options. + (line 6) +* proxy build system: 'png' library. (line 36) +* reautoconf: Build system tools. (line 28) +* reautoconf, for new program: Adding a new program module. + (line 89) +* requirements for building: Prerequisites. (line 6) +* runscript.exe: Macros for Windows. (line 25) +* scripts, linked and not maintained: Linked scripts. (line 6) +* scrolling, smooth: Configure options for 'texk/xdvik'. + (line 13) +* SED: Variables for configure. + (line 34) +* setup macros, general: General setup macros. + (line 6) +* shared libraries, using vs. avoiding: Distro builds. (line 11) +* size of PDF and PS files: '--disable-largefile'. + (line 11) +* size of source tree: Build one package. (line 53) +* source code declarations: Declarations and definitions. + (line 6) +* source directory building, not supported: Building. (line 17) +* source tree: Layout and infrastructure. + (line 6) +* squeeze: Cross problems. (line 13) +* squeeze/configure.ac: 'xdvik' package. (line 14) +* 'static' functions: Declarations and definitions. + (line 35) +* static linking for C++: Macros for compilers. + (line 29) +* stpcpy: Declarations and definitions. + (line 18) +* Subversion repository: Build system tools. (line 38) +* support files, separate from build: Installing. (line 8) +* symlinks, used for scripts: Linked scripts. (line 6) +* synctex: Configure options for 'texk/web2c'. + (line 59) +* synctex <1>: Configure options for 'texk/web2c'. + (line 64) +* system distribution, building for: Distro builds. (line 6) +* t1utils package: 't1utils' package. (line 6) +* tangle: Cross problems. (line 26) +* tests, running: Overview of build system. + (line 6) +* TeX-specific library module, adding: Adding a new TeX-specific library module. + (line 6) +* texlive.tlpdb, TeX Live database: Installing. (line 8) +* tie: Cross problems. (line 26) +* timestamps, in repository: Build system tools. (line 38) +* TLpatches/patch-...: Adding a new program module. + (line 68) +* TLpatches/TL-Changes: Adding a new program module. + (line 64) +* tools, for building: Build system tools. (line 6) +* top-level directories: Top-level directories. + (line 6) +* touching files to avoid rerunning: Build system tools. (line 43) +* Travis-CI: Continuous integration. + (line 6) +* travis.yml: CI testing on Travis-CI. + (line 6) +* type cast from const, avoiding: Const. (line 38) +* use-commit-times, Subversion: Build system tools. (line 38) +* variable declarations, in source code: Declarations and definitions. + (line 52) +* variables for 'configure': Variables for configure. + (line 6) +* warning, discards qualifiers: Const. (line 30) +* WARNING_C[XX]FLAGS: Macros for compilers. + (line 9) +* web2c program: Cross problems. (line 13) +* web2c.ac: Configure options for 'texk/web2c'. + (line 37) +* wget: Linked scripts. (line 23) +* WIN32, Automake conditional: Macros for Windows. (line 16) +* WIN32_WRAP, Automake conditional: Macros for Windows. (line 25) +* Windows, invoking scripts on: Linked scripts. (line 6) +* Windows, macros for: Macros for Windows. (line 6) +* withenable.ac, for new modules: Adding a new program module. + (line 14) +* 'Work/' top-level directory: Top-level directories. + (line 39) +* wrapper binary for scripts on Windows: Linked scripts. (line 6) +* wrapper build system: 'freetype' library. (line 6) +* X toolkit: Configure options for 'texk/web2c'. + (line 22) +* X11 development, required by X clients: Prerequisites. (line 27) +* X11 headers, and 'const': Const. (line 21) +* xasy: 'asymptote'. (line 6) +* xaw: Configure options for 'texk/xdvik'. + (line 9) +* xdvik: 'xdvik' package. (line 6) +* xdvik <1>: Configure options for 'texk/xdvik'. + (line 6) +* xdvipdfmx: Configure options for 'texk/dvipdfm-x'. + (line 6) +* xindy: Linked scripts. (line 23) +* xindy <1>: 'xindy' package. (line 6) +* xindy <2>: Configure options for 'utils/xindy'. + (line 6) +* 'xindy' cross compiling requires 'clisp': Cross problems. (line 33) +* XInput: Configure options for 'texk/xdvik'. + (line 13) +* Xlib: Configure options for 'texk/web2c'. + (line 22) +* xz: Linked scripts. (line 23) +* zlib library: 'zlib' library. (line 6) + + + +Tag Table: +Node: Top1208 +Node: Introduction2118 +Node: Overview of build system3946 +Node: Prerequisites5997 +Node: Building8593 +Node: Build iteration9979 +Node: Build problems11020 +Node: Build in parallel11474 +Node: Build distribution12078 +Node: Build one package12726 +Node: Build one engine16373 +Node: Cross compilation17887 +Node: Cross configuring19167 +Node: Cross problems20844 +Node: Installing22506 +Node: Installation directories23526 +Node: Linked scripts25344 +Node: Distro builds26835 +Node: Layout and infrastructure29211 +Node: Build system tools30042 +Node: Top-level directories32259 +Node: Autoconf macros34495 +Node: General setup macros35257 +Node: Macros for programs36132 +Node: Macros for compilers36933 +Node: Macros for libraries38341 +Node: Macros for library and header flags38767 +Node: Macros for Windows40678 +Node: Library modules42265 +Node: 'png' library42762 +Node: 'zlib' library45114 +Node: 'freetype' library45635 +Node: 'kpathsea' library46337 +Node: Program modules47720 +Node: 't1utils' package48156 +Node: 'xindy' package48705 +Node: 'xdvik' package49825 +Node: 'asymptote'50890 +Node: Extending TeX Live51390 +Node: Adding a new program module52173 +Node: Adding a new generic library module57306 +Node: Adding a new TeX-specific library module59535 +Node: Configure options60233 +Node: Global configure options61614 +Node: '--disable-native-texlive-build'62182 +Node: '--prefix' '--bindir' ...63150 +Node: '--disable-largefile'63698 +Node: '--disable-missing'64248 +Node: '--enable-compiler-warnings='LEVEL64655 +Node: '--enable-cxx-runtime-hack'65317 +Node: '--enable-maintainer-mode'65743 +Node: '--enable-multiplatform'66278 +Node: '--enable-shared'66857 +Node: '--enable-silent-rules'67234 +Node: '--without-ln-s'67692 +Node: '--without-x'68045 +Node: Program-specific configure options68237 +Node: '--enable-PROG' '--disable-PROG'68900 +Node: '--disable-all-pkgs'69179 +Node: Configure options for 'texk/web2c'69970 +Node: Configure options for 'texk/bibtex-x'72514 +Node: Configure options for 'texk/dvipdfm-x'73063 +Node: Configure options for 'texk/dvisvgm'73845 +Node: Configure options for 'texk/texlive'74732 +Node: Configure options for 'texk/xdvik'75159 +Node: Configure options for 'utils/xindy'75786 +Node: Library-specific configure options76680 +Node: Configure options for 'kpathsea'77643 +Node: Variables for configure78351 +Node: Coding conventions79777 +Node: Declarations and definitions80492 +Node: Const82666 +Node: Continuous integration84530 +Node: Transfer from Subversion to Github85194 +Node: Automatic update of the Git mirror87356 +Node: CI testing on Travis-CI87938 +Node: Releases on Github88647 +Node: install-tl89087 +Node: install-tl NAME89456 +Node: install-tl SYNOPSIS89614 +Node: install-tl DESCRIPTION89872 +Node: install-tl REFERENCES90932 +Node: install-tl OPTIONS91456 +Ref: install-tl *-gui* [[=]_module_]91797 +Ref: install-tl 'text'92005 +Ref: install-tl 'tcl'92125 +Ref: install-tl 'wizard'92467 +Ref: install-tl 'expert'92600 +Ref: install-tl 'perltk'92722 +Ref: install-tl *-no-gui*93268 +Ref: install-tl *-lang* _llcode_93358 +Ref: install-tl *-repository* _url|path_94114 +Ref: install-tl *-select-repository*95002 +Ref: install-tl *-all-options*95438 +Ref: install-tl *-custom-bin* _path_95693 +Ref: install-tl *-debug-translation*96527 +Ref: install-tl *-force-platform* _platform_96746 +Ref: install-tl *-help*, *--help*, *-?*96990 +Ref: install-tl *-in-place*97403 +Ref: install-tl *-init-from-profile* _profile_file_97948 +Ref: install-tl *-logfile* _file_98217 +Ref: install-tl *-no-cls*98568 +Ref: install-tl *-no-persistent-downloads*98716 +Ref: install-tl *-persistent-downloads*98741 +Ref: install-tl *-no-verify-downloads*99359 +Ref: install-tl *-non-admin*99722 +Ref: install-tl *-portable*99815 +Ref: install-tl *-print-platform*99954 +Ref: install-tl *-profile* _profile_file_100152 +Ref: install-tl *-q*100373 +Ref: install-tl *-scheme* _scheme_100435 +Ref: install-tl *-v*100909 +Ref: install-tl *-version*, *--version*101064 +Node: install-tl PROFILES101198 +Ref: install-tl 'instopt_adjustpath' (default 0 on Unix, 1 on Windows)104064 +Ref: install-tl 'instopt_adjustrepo' (default 1)104140 +Ref: install-tl 'instopt_letter' (default 0)104277 +Ref: install-tl 'instopt_portable' (default 0)104368 +Ref: install-tl 'instopt_write18_restricted' (default 1)104464 +Node: install-tl ENVIRONMENT VARIABLES105803 +Ref: install-tl 'TEXLIVE_DOWNLOADER'106181 +Ref: install-tl 'TL_DOWNLOAD_PROGRAM'106204 +Ref: install-tl 'TL_DOWNLOAD_ARGS'106224 +Ref: install-tl 'TEXLIVE_INSTALL_ENV_NOCHECK'106428 +Ref: install-tl 'TEXLIVE_INSTALL_NO_CONTEXT_CACHE'106630 +Ref: install-tl 'TEXLIVE_INSTALL_NO_IMPORT'106739 +Ref: install-tl 'TEXLIVE_INSTALL_NO_WELCOME'106891 +Ref: install-tl 'TEXLIVE_INSTALL_PREFIX'107013 +Ref: install-tl 'TEXLIVE_INSTALL_TEXDIR'107039 +Ref: install-tl 'TEXLIVE_INSTALL_TEXMFCONFIG'107070 +Ref: install-tl 'TEXLIVE_INSTALL_TEXMFVAR'107098 +Ref: install-tl 'TEXLIVE_INSTALL_TEXMFHOME'107127 +Ref: install-tl 'TEXLIVE_INSTALL_TEXMFLOCAL'107157 +Ref: install-tl 'TEXLIVE_INSTALL_TEXMFSYSCONFIG'107191 +Ref: install-tl 'TEXLIVE_INSTALL_TEXMFSYSVAR'107222 +Ref: install-tl 'NOPERLDOC'107593 +Node: install-tl AUTHORS AND COPYRIGHT107657 +Node: tlmgr108070 +Node: tlmgr NAME108555 +Node: tlmgr SYNOPSIS108687 +Node: tlmgr DESCRIPTION108877 +Node: tlmgr EXAMPLES109976 +Ref: tlmgr 'tlmgr option repository ctan'110227 +Ref: tlmgr 'tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet'110299 +Ref: tlmgr 'tlmgr update --list'110904 +Ref: tlmgr 'tlmgr update --all'110997 +Ref: tlmgr 'tlmgr info' _what_111154 +Node: tlmgr OPTIONS111416 +Ref: tlmgr *--repository* _url|path_111936 +Ref: tlmgr '/some/local/dir'113122 +Ref: tlmgr 'file:/some/local/dir'113151 +Ref: tlmgr 'ctan'113224 +Ref: tlmgr 'http://mirror.ctan.org/systems/texlive/tlnet'113277 +Ref: tlmgr 'http://server/path/to/tlnet'113618 +Ref: tlmgr 'https://server/path/to/tlnet'113999 +Ref: tlmgr 'ftp://server/path/to/tlnet'114467 +Ref: tlmgr 'user@machine:/path/to/tlnet'114599 +Ref: tlmgr 'scp://user@machine/path/to/tlnet'114640 +Ref: tlmgr 'ssh://user@machine/path/to/tlnet'114681 +Ref: tlmgr *--gui* [_action_]115074 +Ref: tlmgr *--gui-lang* _llcode_115887 +Ref: tlmgr *--debug-translation*116623 +Ref: tlmgr *--machine-readable*116826 +Ref: tlmgr *--no-execute-actions*117094 +Ref: tlmgr *--package-logfile* _file_117287 +Ref: tlmgr *--pause*117541 +Ref: tlmgr *--persistent-downloads*117696 +Ref: tlmgr *--no-persistent-downloads*117724 +Ref: tlmgr *--pin-file*118218 +Ref: tlmgr *--usermode*118436 +Ref: tlmgr *--usertree* _dir_118556 +Ref: tlmgr *--verify-repo=[none|main|all]*118682 +Node: tlmgr ACTIONS119581 +Node: tlmgr help120442 +Node: tlmgr version120919 +Node: tlmgr backup121182 +Ref: tlmgr *backup [_option_...] --all*121353 +Ref: tlmgr *backup [_option_...] _pkg_...*121386 +Ref: tlmgr *--backupdir* _directory_122452 +Ref: tlmgr *--all*122669 +Ref: tlmgr *--clean*[=_N_]122921 +Ref: tlmgr *--dry-run*123248 +Node: tlmgr candidates _pkg_123378 +Node: tlmgr check [_option_...] [depends|executes|files|runfiles|texmfdbs|all]123733 +Ref: tlmgr *depends*124247 +Ref: tlmgr *executes*124589 +Ref: tlmgr *files*124704 +Ref: tlmgr *runfiles*124840 +Ref: tlmgr *texmfdbs*124977 +Ref: tlmgr - all items in 'TEXMFDBS' have the '!!' prefix.125207 +Ref: tlmgr - all items in 'TEXMFBDS' have an 'ls-R' file (if they exist at all).125283 +Ref: tlmgr - all items in 'TEXMF' with '!!' are listed in 'TEXMFDBS'.125348 +Ref: tlmgr - all items in 'TEXMF' with an 'ls-R' file are listed in 'TEXMFDBS'.125423 +Ref: tlmgr *--use-svn*125448 +Node: tlmgr conf125589 +Ref: tlmgr *conf [texmf|tlmgr|updmap [--conffile _file_] [--delete] [_key_ [_value_]]]*125877 +Ref: tlmgr *conf auxtrees [--conffile _file_] [show|add|remove] [_value_]*125941 +Node: tlmgr dump-tlpdb [_option_...] [--json]128356 +Ref: tlmgr *--local*128789 +Ref: tlmgr *--remote*128828 +Ref: tlmgr *--json*128866 +Node: tlmgr generate129437 +Ref: tlmgr *generate [_option_...] language*129633 +Ref: tlmgr *generate [_option_...] language.dat*129672 +Ref: tlmgr *generate [_option_...] language.def*129711 +Ref: tlmgr *generate [_option_...] language.dat.lua*129754 +Ref: tlmgr *--dest* _output_file_132081 +Ref: tlmgr *--localcfg* _local_conf_file_132657 +Ref: tlmgr *--rebuild-sys*132780 +Node: tlmgr gui133595 +Node: tlmgr info133773 +Ref: tlmgr *info [_option_...] _pkg_...*133935 +Ref: tlmgr *info [_option_...] collections*133969 +Ref: tlmgr *info [_option_...] schemes*133999 +Ref: tlmgr *--list*135529 +Ref: tlmgr *--only-installed*135843 +Ref: tlmgr *--only-remote*136031 +Ref: tlmgr *--data 'item1,item2,...'*136335 +Ref: tlmgr *--json* 1136916 +Node: tlmgr init-usertree137299 +Node: tlmgr install [_option_...] _pkg_...137680 +Ref: tlmgr *--dry-run* 1138188 +Ref: tlmgr *--file*138305 +Ref: tlmgr *--force*138527 +Ref: tlmgr *--no-depends*138747 +Ref: tlmgr *--no-depends-at-all*138906 +Ref: tlmgr *--reinstall*139306 +Ref: tlmgr *--with-doc*139684 +Ref: tlmgr *--with-src*139697 +Node: tlmgr key140425 +Ref: tlmgr *key list*140583 +Ref: tlmgr *key add _file_*140601 +Ref: tlmgr *key remove _keyid_*140623 +Node: tlmgr list141217 +Node: tlmgr option141379 +Ref: tlmgr *option [--json] [show]*141534 +Ref: tlmgr *option [--json] showall|help*141565 +Ref: tlmgr *option _key_ [_value_]*141591 +Node: tlmgr paper146169 +Ref: tlmgr *paper [a4|letter]*146318 +Ref: tlmgr *<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [_papersize_|--list]*>146394 +Ref: tlmgr *paper --json*146409 +Node: tlmgr path147624 +Ref: tlmgr *path [--w32mode=user|admin] add*147785 +Ref: tlmgr *path [--w32mode=user|admin] remove*147822 +Node: tlmgr pinning149307 +Ref: tlmgr 'pinning show'149548 +Ref: tlmgr 'pinning add' _repo_ _pkgglob_...149621 +Ref: tlmgr 'pinning remove' _repo_ _pkgglob_...149740 +Ref: tlmgr 'pinning remove _repo_ --all'149893 +Node: tlmgr platform149947 +Ref: tlmgr *platform list|add|remove _platform_...*150133 +Ref: tlmgr *platform set _platform_*150160 +Ref: tlmgr *platform set auto*150181 +Ref: tlmgr *--dry-run* 2151058 +Node: tlmgr postaction151177 +Ref: tlmgr *postaction [_option_...] install [shortcut|fileassoc|script] [_pkg_...]*151407 +Ref: tlmgr *postaction [_option_...] remove [shortcut|fileassoc|script] [_pkg_...]*151481 +Ref: tlmgr *--w32mode=[user|admin]*151796 +Ref: tlmgr *--fileassocmode=[1|2]*152212 +Ref: tlmgr *--all* 1152497 +Node: tlmgr print-platform152552 +Node: tlmgr print-platform-info152883 +Node: tlmgr remove [_option_...] _pkg_...153183 +Ref: tlmgr *--all* 2153667 +Ref: tlmgr *--backup*153777 +Ref: tlmgr *--backupdir* _directory_ 1153803 +Ref: tlmgr *--no-depends* 1154208 +Ref: tlmgr *--no-depends-at-all* 1154270 +Ref: tlmgr *--force* 1154373 +Ref: tlmgr *--dry-run* 3154846 +Node: tlmgr repository155182 +Ref: tlmgr *repository list*155370 +Ref: tlmgr *repository list _path|url|tag_*155404 +Ref: tlmgr *repository add _path_ [_tag_]*155437 +Ref: tlmgr *repository remove _path|tag_*155469 +Ref: tlmgr *repository set _path_[#_tag_] [_path_[#_tag_] ...]*155523 +Ref: tlmgr *repository status*155544 +Ref: tlmgr The tag (which can be the same as the url);156771 +Node: tlmgr restore157249 +Ref: tlmgr *restore [_option_...] _pkg_ [_rev_]*157428 +Ref: tlmgr *restore [_option_...] --all*157458 +Ref: tlmgr *--all* 3158158 +Ref: tlmgr *--backupdir* _directory_ 2158372 +Ref: tlmgr *--dry-run* 4158553 +Ref: tlmgr *--force* 2158685 +Ref: tlmgr *--json* 2158731 +Node: tlmgr search159058 +Ref: tlmgr *search [_option_...] _what_*159222 +Ref: tlmgr *search [_option_...] --file _what_*159259 +Ref: tlmgr *search [_option_...] --all _what_*159295 +Ref: tlmgr *--file* 1159515 +Ref: tlmgr *--all* 4159577 +Ref: tlmgr *--global*159666 +Ref: tlmgr *--word*159793 +Node: tlmgr shell160108 +Ref: tlmgr protocol160843 +Ref: tlmgr help 1160907 +Ref: tlmgr version 1160960 +Ref: tlmgr quit, end, bye, byebye, EOF161028 +Ref: tlmgr restart161049 +Ref: tlmgr load [local|remote]161172 +Ref: tlmgr save161242 +Ref: tlmgr get [_var_] =item set [_var_ [_val_]]161365 +Node: tlmgr show161966 +Node: tlmgr uninstall162133 +Node: tlmgr update [_option_...] [_pkg_...]162363 +Ref: tlmgr *--all* 5162734 +Ref: tlmgr *--self*164913 +Ref: tlmgr *--dry-run* 5165677 +Ref: tlmgr *--list* [_pkg_]165854 +Ref: tlmgr *--exclude* _pkg_166543 +Ref: tlmgr *--no-auto-remove* [_pkg_...]167343 +Ref: tlmgr *--no-auto-install* [_pkg_...]167827 +Ref: tlmgr *--reinstall-forcibly-removed*168589 +Ref: tlmgr *--backup* 1169124 +Ref: tlmgr *--backupdir* _directory_ 3169150 +Ref: tlmgr *--no-depends* 2170316 +Ref: tlmgr *--no-depends-at-all* 2170519 +Ref: tlmgr *--force* 3170622 +Node: tlmgr CONFIGURATION FILE FOR TLMGR171642 +Ref: tlmgr 'auto-remove', value 0 or 1 (default 1), same as command-line option.172649 +Ref: tlmgr 'gui-expertmode', value 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings.172786 +Ref: tlmgr 'gui-lang' _llcode_, with a language code value as with the command-line option.172868 +Ref: tlmgr 'no-checksums', value 0 or 1 (default 0, see below).172922 +Ref: tlmgr 'persistent-downloads', value 0 or 1 (default 1), same as command-line option.173002 +Ref: tlmgr 'require-verification', value 0 or 1 (default 0), same as command-line option.173082 +Ref: tlmgr 'update-exclude', value: comma-separated list of packages (no space allowed). Same as the command line option '--exclude' for the action 'update'.173230 +Ref: tlmgr 'verify-downloads', value 0 or 1 (default 1), same as command-line option.173306 +Ref: tlmgr 'allowed-actions' _action1_ [,_action_,...] The value is a comma-separated list of 'tlmgr' actions which are allowed to be executed when 'tlmgr' is invoked in system mode (that is, without '--usermode').173575 +Node: tlmgr CRYPTOGRAPHIC VERIFICATION174663 +Node: tlmgr Configuration of GnuPG invocation176836 +Node: tlmgr USER MODE177474 +Node: tlmgr User mode install180320 +Node: tlmgr User mode backup, restore, remove, update181464 +Node: tlmgr User mode generate, option, paper181906 +Node: tlmgr MULTIPLE REPOSITORIES182282 +Node: tlmgr Pinning184011 +Node: tlmgr GUI FOR TLMGR185934 +Node: tlmgr Main display187583 +Node: tlmgr Display configuration area187835 +Ref: tlmgr Status188196 +Ref: tlmgr Category188360 +Ref: tlmgr Match188546 +Ref: tlmgr Selection188727 +Ref: tlmgr Display configuration buttons188931 +Node: tlmgr Package list area189114 +Ref: tlmgr a checkbox189698 +Ref: tlmgr package name189834 +Ref: tlmgr local revision (and version)189933 +Ref: tlmgr remote revision (and version)190308 +Ref: tlmgr short description190605 +Node: tlmgr Main display action buttons190650 +Ref: tlmgr Update all installed190916 +Ref: tlmgr Update191288 +Ref: tlmgr Install191338 +Ref: tlmgr Remove191524 +Ref: tlmgr Backup191702 +Node: tlmgr Menu bar191859 +Ref: tlmgr 'tlmgr' menu192082 +Ref: tlmgr 'Options menu'192390 +Ref: tlmgr 'Actions menu'193473 +Ref: tlmgr 'Help menu'193901 +Node: tlmgr GUI options194035 +Ref: tlmgr '-background' _color_194281 +Ref: tlmgr '-font "' _fontname_ _fontsize_ '"'194346 +Ref: tlmgr '-foreground' _color_194504 +Ref: tlmgr '-geometry' _geomspec_194556 +Ref: tlmgr '-xrm' _xresource_194748 +Node: tlmgr MACHINE-READABLE OUTPUT195017 +Node: tlmgr Machine-readable 'update' and 'install' output195833 +Ref: tlmgr 'location-url' _location_197115 +Ref: tlmgr 'total-bytes' _count_197331 +Ref: tlmgr _pkgname_197741 +Ref: tlmgr _status_197951 +Ref: tlmgr 'd'198029 +Ref: tlmgr 'f'198089 +Ref: tlmgr 'u'198268 +Ref: tlmgr 'r'198314 +Ref: tlmgr 'a'198437 +Ref: tlmgr 'i'198615 +Ref: tlmgr 'I'198734 +Ref: tlmgr _localrev_198836 +Ref: tlmgr _serverrev_198943 +Ref: tlmgr _size_199055 +Ref: tlmgr _runtime_199224 +Ref: tlmgr _esttot_199294 +Node: tlmgr Machine-readable 'option' output199327 +Node: tlmgr ENVIRONMENT VARIABLES199845 +Ref: tlmgr 'TEXLIVE_COMPRESSOR'200356 +Ref: tlmgr 'TEXLIVE_DOWNLOADER'201204 +Ref: tlmgr 'TL_DOWNLOAD_PROGRAM'201227 +Ref: tlmgr 'TL_DOWNLOAD_ARGS'201247 +Ref: tlmgr 'TEXLIVE_PREFER_OWN'202273 +Node: tlmgr AUTHORS AND COPYRIGHT203097 +Node: Index203495 + +End Tag Table diff --git a/Build/source/doc/tlbuild.texi b/Build/source/doc/tlbuild.texi new file mode 100644 index 00000000000..a6e235fb8f3 --- /dev/null +++ b/Build/source/doc/tlbuild.texi @@ -0,0 +1,2689 @@ +\input texinfo +@setfilename tlbuild.info + +@set version 2021 +@set month-year February 2021 + +@set mytitle Building @TeX{} Live (@value{version}) +@settitle @value{mytitle} + +@macro TL +@TeX{}@tie{}Live +@end macro + +@copying +This file documents the @TL{} build system and more. + +@noindent +Copyright @copyright{} 2016--2021 Karl Berry.@* +Copyright @copyright{} 2013--2015 Karl Berry & Peter Breitenlohner. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the @TeX{} Users Group. +@end copying + +@c Put everything in one index (arbitrarily chosen to be the concept index). +@syncodeindex fn cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex tp cp +@syncodeindex vr cp + +@dircategory TeX +@direntry +* TLbuild: (tlbuild). TeX Live configuration and development. +@end direntry + +@dircategory Individual utilities +@direntry +* install-tl:: Installing TeX Live. +* tlmgr:: Managing TeX Live. +@end direntry + +@titlepage +@title @value{mytitle} +@subtitle @value{version} release +@subtitle @value{month-year} +@author Peter Breitenlohner +@author Karl Berry +@author @url{https://tug.org/texlive} + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@shortcontents +@contents + +@ifnottex +@node Top +@top @value{mytitle} + +For an overview of this manual, @pxref{Introduction}. + +@menu +* Introduction:: About this manual. +* Overview of build system:: The @TL{} build system. +* Prerequisites:: Requirements for building @TL{}. +* Building:: The overall build process. +* Installing:: How and where installation happens (or not). +* Layout and infrastructure:: Autoconf macros, etc., in detail. +* Configure options:: List of all configure options. +* Coding conventions:: Conventions to follow. +* Continuous integration:: Automated build testing. +* install-tl:: The @TL{} installer. +* tlmgr:: The native @TL{} package manager. +* Index:: General index. +@end menu +@end ifnottex + + +@node Introduction +@chapter Introduction + +@cindex introduction + +This manual (dated @value{month-year}) corresponds to the @TL{} +@value{version} release. + +This manual is aimed at system installers and programmers, and focuses +on how to configure, build, and develop the @TL{} (TL) sources. It is +also available as plain text files in the source tree: +@file{source/README.*}. + +The main @file{source/README} file in the TL source tree provides +maximally-terse information for doing a build, and portability +information for different systems, along with +@file{source/doc/README.solaris}. + +For information on acquiring the TL sources, see +@url{https://tug.org/texlive/svn}. The canonical source repository +uses Subversion, and we have no plans to change this. + +This manual does not duplicate the information found in other TL +documentation resources, such as: + +@itemize +@item The @TL{} web pages: @url{https://tug.org/texlive}. + +@item The web page describing how to build the binaries which +are distributed with @TL{}: @url{https://tug.org/texlive/build.html}. + +@item The @TL{} user manual: @url{https://tug.org/texlive/doc.html}, or +run @code{texdoc texlive}. + +@item Other @TeX{}-related Texinfo manuals (@pxref{,,,web2c, Web2c}, +@ref{,,,kpathsea, Kpathsea}, etc.): +@url{https://tug.org/texinfohtml/}, or check the @samp{TeX} category in +the GNU Info system. + +@item Package documentation: +@url{https://tug.org/texlive/Contents/live/doc.html}, or the +@file{doc.html} file at the top level of the installed TL. + +@end itemize + +As an exception, the full documentation for @code{install-tl} and +@code{tlmgr} is included here as appendices, simply because it is easy +to do so. The same text is available online (linked from +@url{https://tug.org/texlive/doc.html}, or by invoking the program +with @samp{--help} (or look at the end of the source). + + +@c The first word of the chapter/section title here is used to +@c construct the README.* filenames, so choose well. (Or hack the script.) + +@node Overview of build system +@chapter Overview of build system + +@cindex build system, design of + +@cindex Autoconf +@cindex Automake +@cindex Libtool +@cindex tests, running +The @TL{} build system was redesigned in 2009 to consistently use +Autoconf, Automake, and Libtool. Thus, running@*@ @ @ @code{configure +&& make && make check && make install}@*or the essentially-equivalent +top-level @code{Build} script suffices to build and install the TL +programs. The @code{make check} clause performs various tests of the +generated programs---not strictly required but strongly recommended. +Running @code{configure --help} will display a comprehensive list of +all @code{configure} options. + +The main components of the TL build system are: + +@table @file +@item libs/@var{lib} +Generic libraries. + +@item texk/@var{lib} +@TeX{}-specific libraries in subdirectories, notably +@var{lib}=@code{kpathsea}. (The other one is @file{texk/ptexenc}.) + +@item texk/@var{prog} +@TeX{}-specific programs (that use Kpathsea). + +@item utils/@var{prog} +Other programs (that don't use Kpathsea). + +@end table + +@pindex kpse-pkgs.m4 +The primary design goal of the build system is modularity. Each +program and library module (or package) specifies its own requirements +and properties, such as required libraries, whether an installed +(system) version of a library can be used, @code{configure} options to +be seen at the top level, and more. An explicit list of all available +modules is kept in a single central place: @file{m4/kpse-pkgs.m4}. + +A second, related goal is to configure and build each library before +configuring any other (program or library) module which uses that +library. This allows checking for properties and features of a +library built as part of the TL tree in much the same way as for a +system version of that library. + +All generic libraries and several programs are maintained +independently. The corresponding modules use (most of) the +distributed source tree and document any modifications of that source. + +All this is for the sake of simplifying both upgrading of modules and +integrating new modules into the TL build system. (Despite all +efforts, neither task is easy.) + + +@node Prerequisites +@chapter Prerequisites + +@cindex prerequisites for building +@cindex requirements for building + +@cindex compilers, C and C++11 +Overall, building the @TL{} programs, when using all libraries from +the TL source tree, requires C and C++11 compilers and GNU +@code{make}. If @code{make} from your @code{PATH} is not GNU make, +you can set the @code{MAKE} environment variable to whatever is necessary. + +@cindex GNU @code{make}, required +@cindex @code{gmake}, required +@cindex FreeType +GNU @code{make} is required only because of some third-party +libraries, notably FreeType; all the TL-maintained directories (and +Automake/Autoconf output in general) work with any reasonable +@code{make}. + +@cindex C++11, required +A C++11 compiler is similarly required because of the third-party +library ICU; the program @code{dvisvgm} also requires C++11. It is +possible to build everything else with older compilers, but you have +to remove the C++11-dependent sources. @xref{Build one package}. + +A few programs in the tree have additional requirements: + +@table @file +@item web2c +@cindex @code{perl}, required by @code{web2c}, etc. +requires @code{perl} for some tests run by @code{make check}. + +@item xdvik +@itemx xpdfopen +@cindex X11 development, required by X clients +require X11 headers and libraries, typically in ``development'' packages +that are not installed by default. + +@item xetex +@cindex @code{fontconfig} library, required by @code{xetex} +@cindex @code{ApplicationServices} Mac framework, required by @code{xetex} +@cindex @code{Cocoa} Mac framework, required by @code{xetex} +requires @file{fontconfig} (again both headers and library), or, for +MacOSX only, the @code{ApplicationServices} and @code{Cocoa} +frameworks. + +@item xindy +@cindex @code{clisp}, required by @code{xindy} +@cindex @code{libsigsegv}, required by @code{xindy} +requires GNU @code{clisp}, @code{libsigsegv}, and @code{libiconv}; +additionally, to build the rules and/or documentation: @code{perl}, +@code{latex}, @code{pdflatex}. + +@end table + +@noindent Lacking the required tools, building these +programs must avoided, e.g.,@* +@code{configure --without-x --disable-xetex --disable-xindy} + +Modifying source files induces more requirements, as one might expect: + +@itemize +@item +Modification of any @code{.y} or @code{.l} source files requires +@file{bison} or @file{flex} to update the corresponding C sources. + +@item +Modification of the sources for @code{.info} files requires +@code{makeinfo}. + +@item +Modification of any part of the build system (M4 macros, +@file{configure.ac}, @file{Makefile.am}, or their fragments) requires +GNU M4, GNU Autoconf, GNU Automake, and GNU Libtool to update the +generated files. Furthermore, to reliably reproduce the build files, +the original GNU releases of these tools must be used, not any distro +packaging of them. @xref{Build system tools}, for more discussion. + +@end itemize + +If you haven't modified any source files, and infrastructure tools +such as @code{autoconf} or @code{makeinfo} are still being run, check +your timestamps---notably, @code{use-commit-times} must be set to +@code{yes} in your Subversion configuration (@pxref{Build system +tools}). Barring buggy commits, no infrastructure tools are needed to +do a normal build. + + +@node Building +@chapter Building + +@cindex building +@cindex overall build process + +@pindex Build @r{script} +The top-level @file{Build} script is intended to simplify building the +binaries distributed with @TL{} itself---we call this the ``native'' +TL build. It runs @code{configure && make world}, which builds +everything in a subdirectory of the main source tree (default +@file{Work/}), installs everything in another subdirectory (default +@file{inst/}), and finally runs @code{make check}. The exact +directory and command names can be specified via environment variables +and a few leading options. All remaining arguments (assignments or +options) are passed to the @file{configure} script. Please take a +look at the @file{./Build} source file for more information; it is a +straightforward shell script. + +@cindex source directory building, not supported +@cindex build directory, required +An alternative, and the one we will mainly discuss here, is to run +@code{configure} and @code{make} in a suitable empty subdirectory. +Building in the source directory itself is not supported (sorry). + +@menu +* Build iteration:: What @code{configure} and @code{make} do in TL. +* Build problems:: If the build fails. +* Build in parallel:: Simultaneous @code{make} processes. +* Build distribution:: Making a distribution tarball. +* Build one package:: Example of working on just one program. +* Build one engine:: Example of building just one @TeX{} engine. +* Cross compilation:: Building on host X for target Y. +@end menu + + +@node Build iteration +@section Build iteration + +@cindex build iteration +@cindex iteration through sources, by @code{configure} and @code{make} + +Running the top-level @file{configure} script configures the top level +and the subdirectories @file{libs}, @file{utils}, and @file{texk}. +Running @code{make} at the top level first iterates over the +@TeX{}-specific libraries, and then runs @code{make} in @file{libs}, +@file{utils}, and @file{texk} to iterate over the generic libraries, +utility programs, and @TeX{}-specific programs, respectively. These +iterations consist of two steps: + +@enumerate +@item +For each library or program module not yet configured, run +@code{configure}, adding the configure option @code{--disable-build} +if the module need not be built, otherwise running @code{make all}. + +@item +For each library or program module that must be built, run +@code{make} for the selected target(s): @code{default} or +@code{all} to (re-)build, @code{check} to run tests, @code{install}, +etc. + +@end enumerate + +Running the top-level @code{make} a second time iterates again over +all the library and program modules, and finds (should find) nothing +to be done. + + +@node Build problems +@section Build problems + +@cindex build problems +@cindex problems with build +@cindex failure to build +@vindex --no-clean Build @r{option} +If configuring or building a module fails, you should first try to +find and fix the problem. Failing that, a possible workaround is to +remove the subdirectory for that module from the build tree (so +@code{configure} won't try to run there, and finally rerun the top +level @code{make} (or @file{./Build} @code{--no-clean}). + + +@node Build in parallel +@section Build in parallel + +@cindex building in parallel +@cindex parallel build +@cindex cache for @code{configure} + +@cindex dependencies, with several output files +@vindex -j make @r{option} +The TL build system carefully formulates dependencies as well as +@code{make} rules when a tool (such as @code{tangle}, @code{ctangle}, +and @code{convert}) creates several output files. This allows for +parallel builds (@code{make -j @var{n}} with @math{@var{n}>1} or even +@code{make -j}) that can considerably speed up the TL build. + +@cindex cache file, for @code{configure} +@vindex -C configure @r{option} +Incidentally, a noticeable speed-up can be independently gained by +using a configure cache file, i.e., specifying the @code{configure} +option @code{-C} (recommended). + + +@node Build distribution +@section Build distribution + +@cindex building a distribution +@cindex distribution tarball, making + +@cindex @code{dist} and @code{distcheck} targets for @code{make} +Running @code{make dist} at the top level creates a tarball +@file{tex-live-@var{yyyy}-@var{mm}-@var{dd}.tar.xz} from the TL source +tree. Running @code{make distcheck} also verifies that this tarball +suffices to build and install all of TL. + +This is useful for checking consistency of the source tree and +Makefiles, but the result is not a complete or even usable @TeX{} +system, since all the support files are lacking; @pxref{Installing}. +We do not actually distribute any such tarball, and have no plans to +do so. + + +@node Build one package +@section Build one package + +@cindex build one package +@cindex one package, building + +@vindex --disable-all-packages +@cindex build on demand +To build one package, the basic idea is to use the @code{configure} +option @code{--disable-all-pkgs} (@pxref{@code{--disable-all-pkgs}}). +Then all program and library modules are configured but none are made. +However, the @file{Makefile}s still contain all build rules and +dependencies and can be invoked to build an individual program or +library, first building any required libraries. + +Here is an example from start to finish for working on +@code{dvipdfm-x}. (Unfortunately, this does not suffice for building +the @TeX{} engines; see the next section.) + +@example +mkdir mydir && cd mydir # new working directory + +# Get sources (@url{https://tug.org/texlive/svn}), e.g.: +rsync -a --delete --exclude=.svn --exclude=Work \ + tug.org::tldevsrc/Build/source/ . + +# Create build directory: +mkdir Work && cd Work + +# Do the configure: +../configure --disable-all-pkgs --enable-dvipdfm-x \ + -C CFLAGS=-g CXXFLAGS=-g >&outc || echo fail + +# Do the make: +make >&outm || echo fail + +# Test: +cd texk/dvipdfm-x +make check +@end example + +Then you can modify source files in @file{mydir/texk/dvipdfm-x} and +rerun @code{make} in @file{mydir/Work/texk/dvipdfm-x} to rebuild; that +build directory is where the binary ends up and where you can run a +debugger, etc. + +The second line of the @code{configure} invocation shows examples of +extra things you likely want to specify if you intend to hack the +sources (and not just build binaries): the @code{-C} speeds +@code{configure} by enabling a cache file, and the @code{CFLAGS} and +@code{CXXFLAGS} settings eliminate compiler optimization for debugging +purposes. + +Of course, you need to actually look at the output and check that +things are working. There are many @code{configure} options you can +tweak as desired; check the output from @code{configure --help}. It +is also a good idea to run @code{make check} after making any changes, +to ensure that whatever tests have been written still pass. + +@cindex size of source tree +Finally, the above retrieves the entire TL source tree (several +hundred megabytes). It is natural to ask if this is really necessary. +Strictly speaking, the answer is no, but it is vastly more convenient +to do so. If you cut down the source tree, you must also give +additional @code{configure} flags to individually disable using system +versions of libraries, or the intricacies of the dependencies (such as +@code{teckit} requiring @code{zlib}) will have undesired side effects. +For an example of this approach, see the @code{build-pdftex.sh} script +in the @code{pdftex} development source (details at +@url{http://pdftex.org}), which is indeed such a cut-down TL source +tree. + +@cindex C++11, removing dependent sources +Some libraries and programs require C++11. If you want to build with +an older compiler lacking such support, you need to (re)move those +source directories; specifying @code{--disable} for them does not +suffice, unfortunately. Specifically, before running @code{configure}: + +@example +rm -rf libs/icu libs/graphite2 texk/dvisvgm +@end example + +@vindex --enable-missing @r{to ignore dependencies} +Also, even with @code{--disable-all-pkgs}, dependencies are (currently) +checked. For instance, if a (non-MacOSX) system does not have +@code{fontconfig}, Xe@TeX{} cannot be built (@pxref{Prerequisites}), +and @code{configure} will terminate even with @code{--disable-xetex}. +To proceed without such dependencies, specify @code{--enable-missing} +also. (Patches to improve this would be most welcome.) + +@vindex CC=@var{c-compiler} +@vindex CXX=@var{c++-compiler} +@vindex OBJCXX=@var{objc-compiler} +@pindex gcc@r{, default compilers} +By default, the @code{gcc} compilers will be used if present; +otherwise, individual packages may use something different. You can +explicitly specify the compilers to be used with the environment +variables @code{CC}, @code{CXX}, and @code{OBJCXX}. + + +@node Build one engine +@section Build one engine + +@cindex build one engine +@cindex one engine, building +@cindex engine, building one + +Unfortunately, there is one common case where the steps in the +preceding section to build one package (@pxref{Build one package}) do +not suffice: wanting to build one, or a subset, of the @TeX{} engines +(or other Web2c programs). + +The simplest way to do this is to disable everything and then +explicitly specify what to make. For example, to build only the +original @TeX{}: + +@example +cd Work # top build directory +../configure --without-x --disable-shared --disable-all-pkgs \ + --enable-tex --disable-synctex -C CFLAGS=-g CXXFLAGS=-g +make +cd texk/web2c # cd engine build directory +make tex # must specify target +@end example + +The first @code{make} run will configure everything, and even build +the libraries, even though the packages are disabled. +The source tree can be cut down to just what is needed for the given +engine (the separate pdf@TeX{} and Lua@TeX{} source repositories do +this, for example), but see caveats in previous section. + +If you want to debug an X-related program or shared library setup, or +other variants, change the @code{configure} options +accordingly. Either @code{../Build} or @code{../configure} can be run. + +Then it is necessary to again specify the target engine (@code{tex}, +in the above) in the @code{make}. + +All this is somewhat unfortunate. We hope to improve the situation in +the future. Patches are welcome. + +@node Cross compilation +@section Cross compilation + +@cindex cross compilation +In a cross compilation a @dfn{build} system is used to create +binaries to be executed on a @dfn{host} system with different +hardware and/or operating system. + +@cindex native cross compilation +In simple cases, the build system can execute binaries for the host +system. This typically occurs for bi-arch systems where, e.g., +@code{i386-linux} binaries can run on @code{x86_64-linux} systems and +@code{win32} binaries can run on @code{win64} systems. Although +sometimes called ``native cross'', technically this is not cross +compilation at all. In most such cases it suffices to specify +suitable compiler flags. It might be useful to add the configure +option @code{--build=@var{host}} to get the correct canonical host +name, but note that this should @emph{not} be @code{--host=@var{host}} +(@pxref{Hosts and Cross-Compilation,,, autoconf, GNU Autoconf}). + +In order to build, e.g., 32-bit binaries with @command{clang} on a 64-bit +MacOSX system one could use: + +@example +TL_BUILD_ENV="CC='clang -arch i386' \ + CXX='clang++ -arch i386' \ + OBJCXX='clang++ -arch i386'" \ + ./Build --build=i386-apple-darwin +@end example + +@menu +* Cross configuring:: Configuring for cross compilation. +* Cross problems:: Cross compilation problems. +@end menu + +@node Cross configuring +@subsection Cross configuring + +@cindex cross compilation configuring +@cindex configuring, for cross compilation + +@vindex --host=@var{host} +@vindex --build=@var{host} +In a standard cross compilation, binaries for the host system cannot +execute on the build system and it is necessary to specify the +configure options @code{--host=@var{host}} and +@code{--build=@var{build}} with two different values. + +Building binaries requires suitable ``cross'' tools, e.g., compiler, +linker, and archiver, and perhaps a ``cross'' version of +@code{pkg-config} and similar to locate host system libraries. +Autoconf expects that these cross tools are given by their usual +variables or found under their usual name prefixed with +@code{@var{host}-}. Here a list of such tools and corresponding +variables: + +@example +@code{ar} AR +@code{freetype-config} FT2_CONFIG +@code{g++} CXX +@code{gcc} CC +@code{icu-config} ICU_CONFIG +@code{objdump} OBJDUMP +@code{pkg-config} PKG_CONFIG +@code{ranlib} RANLIB +@code{strip} STRIP +@end example + +@cindex @code{mingw32} +@noindent In order to, e.g., build @code{mingw32} binaries on +@code{x86_64-linux} with a cross compiler found as +@file{i386-pc-mingw32-gcc} one would specify + +@example +--host=i386-pc-mingw32 --build=x86_64-linux-gnu +@end example + +@noindent or perhaps + +@example +--host=mingw32 --build=x86_64-linux CC=i386-pc-mingw32-gcc +@end example + +@noindent but this latter, especially, might require adding @code{CXX} and others. + +Configure arguments such as @code{CFLAGS=@dots{}} refer to the cross +compiler. If necessary, you can specify compilers and flags for the +few auxiliary C and C++ programs required for the build process as +configure arguments + +@vindex BUILDCC@r{,} BUILDCFLAGS@r{, @dots{}} +@example +BUILDCC=@dots{} +BUILDCPPFLAGS=@dots{} +BUILDCFLAGS=@dots{} +BUILDCXX=@dots{} +BUILDCXXFLAGS=@dots{} +BUILDLDFLAGS=@dots{} +@end example + +@node Cross problems +@subsection Cross problems + +@cindex cross compilation problems + +The fact that binaries for the host system cannot be executed on the +build system causes some problems. + +One problem is that configure tests using @code{AC_RUN_IFELSE} can +compile and link the test program but cannot execute it. Such tests +should be avoided if possible and otherwise must supply a pessimistic +test result. + +@pindex squeeze +@pindex web2c @r{program} +@cindex @code{freetype} cross compiling +@vindex CC_BUILD +Another problem arises if the build process must execute some +(auxiliary or installable) programs. Auxiliary programs can be placed +into a subdirectory that is configured natively as is done for +@file{texk/web2c/web2c}, @file{texk/dvipsk/squeeze}, and +@file{texk/xdvik/squeeze}. The module @file{libs/freetype2} uses the +value of @code{CC_BUILD}, @file{@var{build}-gcc}, @file{gcc}, or +@file{cc} as the compiler for the auxiliary program. + +@cindex ICU cross compiling +The situation for installable programs needed by the build process is +somewhat different. A rather expensive possibility, chosen for the ICU +libraries in module @file{libs/icu}, is to first compile natively for +the build system and in a second step to use these (uninstalled) +programs during the cross compilation. + +@pindex tangle +@pindex ctangle +@pindex otangle +@pindex tie +This approach would also be possible for the tools such as +@file{tangle} used in the module @file{texk/web2c} to build the WEB +programs, but that would require first building a native +@code{kpathsea} library. To avoid this complication, cross +compilation of programs written in (C)WEB requires sufficiently recent +installed versions of @file{tangle}, @file{ctangle}, @file{otangle}, +and @file{tie}. + +@cindex @code{xindy} cross compiling requires @code{clisp} +Building @code{xindy} requires running the host system @code{clisp} +binary, thus cross compilation is painful, but possible. + + +@node Installing +@chapter Installing + +@cindex installing +This section discusses the results of @code{make install} in the +source tree. + +@cindex support files, separate from build +@pindex texlive.tlpdb@r{, @TL{} database} +@pindex install-tl@r{, @TL{} installer} +@pindex plain.tex@r{, not in source tree} +The main consideration is that @code{make install} is not enough to +make a usable @TeX{} installation. Beyond the compiled binaries, +(thousands of) support files are needed; just as a first example, +@file{plain.tex} is not in the source tree. + +These support files are maintained completely independently and are +not present in the TL source tree. The best basis for dealing with them +is the @TL{} (plain text) database in +@file{Master/tlpkg/texlive.tlpdb}, and/or the @TL{} installer, +@code{install-tl}. More information is under @file{Master/tlpkg} and +at @url{https://tug.org/texlive/distro.html}. + +@menu +* Installation directories:: The prefix, @code{bindir}, etc., directories. +* Linked scripts:: Scripts not maintained in the sources. +* Distro builds:: Configuring and building for OS distributions. +@end menu + + +@node Installation directories +@section Installation directories + +@cindex installation directories +@cindex directories, for installation +@cindex paths, for installation + +Running @code{make install} (or @code{make install-strip}) installs +executables in @code{@var{bindir}}, libraries in @code{@var{libdir}}, +headers in @code{@var{includedir}}, general data (including ``linked +scripts'', @pxref{Linked scripts}) in +@code{@var{datarootdir}/texmf-dist}, man pages in @code{@var{mandir}}, +and Info files in @code{@var{infodir}}. + +The values of these directories are determined by @code{configure} +and can be specified explicitly as options such as +@code{--prefix=@var{prefix}} or @code{--bindir=@var{bindir}}; +otherwise, they are given by their usual Autoconf defaults: + +@example +@var{prefix} /usr/local +@var{exec_prefix} @var{prefix} +@var{bindir} @var{exec_prefix}/bin +@var{libdir} @var{exec_prefix}/lib +@var{includedir} @var{prefix}/include +@var{datarootdir} @var{prefix}/share +@var{mandir} @var{datarootdir}/man +@var{infodir} @var{datarootdir}/info +@end example + +@noindent except possibly modified as follows: + +@itemize @bullet +@item +If the option @code{--enable-multiplatform} is given, +@code{/@var{platform}} (i.e., the canonical platform name) is appended +to @code{@var{bindir}} and @code{@var{libdir}}. This is implied for a +native TL build. + +@item +@raggedright +In a native TL build, @code{@var{datarootdir}} is set to +@code{@var{prefix}}, @code{@var{infodir}} is set to +@code{@var{prefix}/texmf-dist/doc/info}, and @code{@var{mandir}} to +@code{@var{prefix}/texmf-dist/doc/man}, corresponding to the +directories used in the TL distribution. +@end raggedright + +@end itemize + +@noindent The top-level @file{configure} script displays all these +installation paths. + +For the native TL build, the @code{Build} script leaves the binaries +in @file{./inst/bin/@var{std-system-triplet}}. The new binaries are +not directly usable from that location; they need to be copied to +@file{Master/bin/@var{tl-platform}}. The other files and directories +that end up in @file{./inst/} are ignored. + + +@node Linked scripts +@section Linked scripts + +@cindex linked scripts +@cindex scripts, linked and not maintained + +@cindex symlinks, used for scripts +@cindex wrapper binary for scripts on Windows +@cindex Windows, invoking scripts on +Quite a few executables are architecture-independent shell, Perl, or +other interpreted scripts, rather than compiled binaries. A few are +maintained as part of the TL source tree, but most are maintained +elsewhere with copies under @file{texk/texlive/linked_scripts}. + +These so-called @dfn{linked scripts} are installed under +@code{@var{datarootdir}/texmf-dist/scripts}; for Unix-like systems a +symbolic link is made in @code{@var{bindir}}. For example, a symlink +points from @code{@var{bindir}/ps2eps} to +@code{@var{datarootdir}/texmf-dist/scripts/ps2eps/ps2eps.pl}. For +Windows, a standard wrapper binary (copied to, e.g., +@code{@var{bindir}/ps2eps.exe}) serves the same purpose. The source +for the wrapper is in @file{texk/texlive/w32_wrapper}. + +One reason for this is to avoid having many copies of the same +script; a more important reason is that it guarantees the scripts will +stay in sync across the different supported operating systems. + +@pindex asymptote +@pindex biber +@pindex xindy +@pindex xz +@pindex wget +Most important of all, we want the @code{@var{bindir}} resulting from +the build to be as close as possible to what is in the TL +distribution. At present, there are a few exceptions---Asymptote, +Biber, Xindy---and each one creates considerable extra work. We don't +want to add more. (See @url{https://tug.org/texlive/build.html} for +information about building those exceptions, as well as the @code{xz} +and @code{wget} programs that are used in the TL infrastructure.) + + +@node Distro builds +@section Distro builds + +@cindex distro, building for +@cindex operating system distribution, building for +@cindex system distribution, building for + +@cindex GNU/Linux distro +@cindex BSD distro +Although they use the same code base, building for the native TL +distribution as shipped by the @TeX{} user groups is typically quite +different from a ``distro'' build needed by, e.g., a full GNU/Linux or +BSD operating system distribution. + +@cindex shared libraries, using vs.@: avoiding +The native TL distribution uses shared libraries only when absolutely +necessary (@file{libc}, @file{libm}, X11 libraries, and +@file{libfontconfig}). In contrast, a distro typically wants to use +as many shared libraries as possible from elsewhere on the system, +including @TeX{}-specific libraries such as @file{libkpathsea} (even +though Kpathsea has never officially been released as a shared +library). In addition, the installation paths will, in general, be +completely different. + +Here are the @code{configure} options that distro builds are likely to +find most relevant: + +@table @code +@item --disable-native-texlive-build +This must be specified to avoid interference from the many tweaks we +do for the native TL build. + +@item --with-banner-add=/@var{SomeDistro} +This isn't technically required, but is strongly recommended, so your +build and your distro can be distinguished from others. + +@item --enable-shared +Build shared versions of the @TeX{}-specific libraries (uses +@code{libtool}). + +@item --disable-static +Do not build the static versions of the @TeX{}-specific libraries. + +@item --with-system-@var{lib} +Look for and use a system version of the library @var{lib}. +@code{configure --help} will give you the list of possibilities. + +@item --with-@var{lib}-includes=@var{dir} +@itemx --with-@var{lib}-libdir=@var{dir} +If needed, allows you to specify where the headers/code are for the +given library @var{lib}. + +@item --prefix=/usr +@itemx --prefix=/opt/TeXLive +Or whatever your convention is. The default is @file{/usr/local} and +you shouldn't install there for a distro. + +@item --libdir=\$@{exec_prefix@}/lib64 +May be needed for 64-bit bi-architecture (GNU/Linux) systems. + +@end table + +@cindex Preining, Norbert +@cindex adapting @TL{} for distros +You will need to take care of the support files mentioned above +(@pxref{Installing}), and many other issues, such as font maps, +languages, and formats, independently of the build. Norbert Preining +has written a detailed article on adapting TL for distros: +@url{https://tug.org/TUGboat/tb34-3/tb108preining-distro.pdf}. (If the +article needs updating in the future, perhaps we will merge it into +this document.) + + +@node Layout and infrastructure +@chapter Layout and infrastructure + +@cindex layout of sources +@cindex source tree + +The @TL{} source tree is the subtree rooted at @file{Build/source} of +the complete TL distribution and contains the sources for all executables +distributed by TL, as well as @code{configure} scripts and @code{make} +rules to build and install them together with some of their support +files. + +@menu +* Build system tools:: Modifying infrastructure files. +* Top-level directories:: libs texk utils; am auxdir build-aux m4; doc extra. +* Autoconf macros:: TL-specific Autoconf macros. +* Library modules:: Handling libraries, with examples. +* Program modules:: Handling programs, with examples. +* Extending @TL{}:: Adding a new module. +@end menu + + +@node Build system tools +@section Build system tools + +@cindex tools, for building +@cindex GNU tools, needed for building +@cindex infrastructure, tools needed for + +As mentioned above (@pxref{Prerequisites}), a normal build has few +requirements. On the other hand, if you want to modify the @TL{} +infrastructure sources, such as @file{configure.ac} or +@file{Makefile.am} files, you will need to have several additional +tools installed. + +In general, the TL build system uses the latest released versions of +the GNU build tools, installed directly from the original GNU releases +(e.g., by building them with @code{configure --prefix=/usr/local/gnu} +and having @env{PATH} start with @file{/usr/local/gnu/bin}). We have +found that trying to use the versions of these tools packaged for +distros causes many extra hassles, so don't do that, tempting as it +may be. + +Currently the versions we use are: + +@display +@include build-tools.txt +@end display + +@pindex reautoconf +@vindex --enable-maintainer-mode +These versions should be used to update the generated files (e.g., +@file{configure} or @file{Makefile.in}) in all or parts of the TL tree +after their dependencies have been changed. This can be done +explicitly with the top-level @code{reautoconf} script or implicitly +by using the configure option @code{--enable-maintainer-mode}. + +It has often turned out that the bison and flex versions are not +critical; however, the autotools versions are. If you don't have the +given versions, get them before modifying the build infrastructure. + +@cindex Subversion repository +@cindex timestamps, in repository +@vindex use-commit-times@r{, Subversion} +The files in the Subversion repository (see +@url{https://tug.org/texlive/svn}) are all up to date (barring +bugs). For this to be reflected by their timestamps in your checkout, +be sure to set @file{use-commit-times=yes} in +@file{~/.subversion/config} or the equivalent. + +@cindex touching files to avoid rerunning +@pindex make -t +If timestamps are wrong, you may also be able to avoid unnecessary +runs of @code{bison}, @code{flex}, or @code{makeinfo} with +@code{touch} of the generated (@file{.c}, @file{.h}, or @file{.info}) +files. With @code{--enable-maintainer-mode} it may also be necessary +to @code{touch} first @file{aclocal.m4}, then @file{configure} and +@file{config.h.in} (or @file{c-auto.in}), and finally all +@file{Makefile.in} files. + + +@node Top-level directories +@section Top-level directories + +@cindex directories, top-level +@cindex top-level directories + +Here is a brief description of the top-level directories in the @TL{} +source tree. + +As mentioned at the beginning of @pxref{Overview of build +system}, the main source directories are @file{texk/} +(@TeX{}-specific programs and libraries), @file{utils/} (additional +programs), and @file{libs/} (generic libraries). + +@cindex @file{am/} top-level directory +@cindex @file{m4/} top-level directory +In addition, the top-level directories @file{am/} and @file{m4/} +contain @file{Makefile.am} fragments and Autoconf macros, +respectively, used in many places. Specifically, the file +@file{m4/kpse-pkgs.m4} contains lists of all program and library +modules; missing modules are silently ignored. (This helps in +creating cut-down source trees.) + +Each module contributes fragments (in separate files) defining its +capabilities and requirements to the @file{configure.ac} scripts at +the top-level and in the subdirectories @file{libs}, @file{utils}, and +@file{texk}. The fragments from program modules supply +@code{configure} options to disable or enable building them; those +from library modules specify if an installed (system) version of that +library can be used. This ultimately determines which modules need to +be built---although all modules must be configured for the benefit of +@file{make} targets such as @code{dist} or @code{distcheck}. + +@cindex @file{build-aux/} top-level directory +@pindex config.guess@r{,} config.sub, @dots{} +@cindex Gnulib, used for common files +The top-level @file{build-aux/} directory contains the common files +@file{compile}, @file{config.guess}, @file{config.sub}, +@file{depcomp}, etc.@ used by most packages. These are taken from the +GNU Gnulib sources (@url{https://www.gnu.org/software/gnulib}), which +in turn synchronizes with any ultimate upstream repository. There are +independent copies of some of these in a few other places, e.g., +@file{libs/freetype2/freetype-*/builds/unix/}. The @code{reautoconf} +script does not touch those, but a TL cron job keeps them in sync +(nightly). + +@cindex @file{Work/} top-level directory +@cindex @file{inst/} top-level directory +When the top-level @file{./Build} script is used to build TL, two more +two more top-level directories appear: @file{Work/} for the build tree, +and @file{inst/} for the install tree (from @code{make install}). +These names (and everything else about @file{Build}'s operation) can +be changed by setting environment variables before running it; see the +script source. + + +@node Autoconf macros +@section Autoconf macros + +@cindex autoconf macros + +@c Texinfo macro: @ovar(ARG) +@c ARG is the name of an optional argument; this is used for +@c documentation of macro arguments (@defmac lines). Plain +@c brackets are treated specially and appear more distinct. +@macro ovar{varname} +[@var{\varname\}] +@end macro + +@c @dvar(ARG, DEFAULT) +@c ------------------- +@c The ARG is an optional argument, defaulting to DEFAULT. To be used +@c for macro arguments in their documentation (@defmac). +@c @macro xxdvar{varname, default} +@c @r{[}@var{\varname\} = @samp{\default\}@r{]} +@c @end macro + +Here we describe a few of the Autoconf macros used in several +modules---many more are defined in the sources; see the top-level +@code{m4/} directory. These general macros are supplemented by +module-specific macros in directories such as @file{texk/dvipng/m4/}; +some of those are described in following sections (@pxref{Library +modules} and @ref{Program modules}). + +@menu +* Setup: General setup macros. +* Programs: Macros for programs. +* Compilers: Macros for compilers. +* Libraries: Macros for libraries. +* Flags: Macros for library and header flags. +* Windows: Macros for Windows. +@end menu + +@node General setup macros +@subsection General setup macros + +@cindex general setup macros +@cindex setup macros, general +@cindex macros, general setup +The TL sources use two general setup macros: + +@defmac KPSE_BASIC (@var{name}, @ovar{more-options}) +Initialize the basic TL infrastructure for module @var{name}:@*@ @ @ +@code{AM_INIT_AUTOMAKE([foreign @var{more-options}])}@*@ @ @ +@code{AM_MAINTAINER_MODE}@*@ @ @ @code{KPSE_COMPILER_WARNINGS}@* +and make sure the C compiler understands function prototypes. This is +used for all generic library and program modules. +@end defmac + +@defmac KPSE_COMMON (@var{name}, @ovar{more-options}) +Like @code{KPSE_BASIC} but add:@*@ @ @ @code{LT_PREREQ([2.2.6])}@*@ @ +@ @code{LT_INIT([win32-dll])}@*@ @ @ @code{AC_SYS_LARGEFILE}@*@ @ @ +@code{AC_FUNC_FSEEKO}@*along with checks for frequently used functions, +headers, types, and structures. This is used for @TeX{}-specific +modules. +@end defmac + + +@node Macros for programs +@subsection Macros for programs + +@cindex macros, for programs +Macros for program checks: + +@defmac KPSE_CHECK_LATEX +Set @code{LATEX} to the first of @code{latex}, @code{elatex}, or +@code{lambda} which exists in @code{PATH}, or to @code{no} if none of +them exists. Call @code{AC_SUBST} for @code{LATEX}. The result of +this test can be overridden by setting the @code{LATEX} environment +variable or the cache variable @code{ac_cv_prog_LATEX}. +@end defmac + +@defmac KPSE_CHECK_PDFLATEX +Check for @code{pdflatex} in @code{PATH} and set @code{PDFLATEX}. +@end defmac + +@defmac KPSE_CHECK_PERL +Check for @code{perl} or @code{perl5} in @code{PATH} and set +@code{PERL}. +@end defmac + +@defmac KPSE_PROG_LEX +Call @code{AC_PROG_LEX} and add the flag @code{-l} for @code{flex}. +@end defmac + + +@node Macros for compilers +@subsection Macros for compilers + +@cindex macros, for compilers + +Macros for compiler-related checks: + +@defmac KPSE_COMPILER_WARNINGS +@vindex WARNING_C[XX]FLAGS +When using the (Objective) C/C++ compiler, set +@code{WARNING_[OBJ]C[XX]FLAGS} to suitable warning flags (depending on +the value given to or implied for @code{--enable-compiler-warnings}). +Call @code{AC_SUBST} for them. At present this assumes GNU compiler +warning options, but could be extended to others if necessary. + +@vindex kpse_cv_warning_cflags +This macro caches its results in the @code{kpse_cv_warning_cflags}, +@dots{} variables. +@end defmac + +@defmac KPSE_COMPILER_VISIBILITY +When using the C or C++ compiler, try to set +@code{VISIBILITY_C[XX]FLAGS} to flags to hide external symbols. Call +@code{AC_SUBST} for this variable. At present this only tests for +the compiler option @code{-fvisibility=hidden}, but could be +extended if necessary. + +@vindex kpse_cv_visibility_c[xx]flags +This macro caches its results in the @code{kpse_cv_visibility_cflags} +or @code{kpse_cv_visibility_cxxflags} variable. +@end defmac + +@defmac KPSE_CXX_HACK +@cindex static linking for C++ +@cindex linking C++ libraries statically +@vindex --enable-cxx-runtime-hack +@pindex libstc++@r{, statically linking} +Provide the configure option @code{--enable-cxx-runtime-hack}. If +enabled and when using @code{g++}, try to statically link with +@file{libstdc++}, notably improving portability of the resulting +binary. + +@vindex kpse_cv_cxx_hack +This macro caches its result in the @code{kpse_cv_cxx_hack} variable. +@end defmac + + +@node Macros for libraries +@subsection Macros for libraries + +@cindex macros, for libraries +One macro for a library check: + +@defmac KPSE_LARGEFILE (@var{variable}, @ovar{extra-define}) +Call @code{AC_SYS_LARGEFILE} and @code{AC_FUNC_FSEEKO} and append +suitable @code{-D} flags (optionally including +@code{-D@var{extra-define}}) to @var{variable}. +@end defmac + + +@node Macros for library and header flags +@subsection Macros for library and header flags + +@cindex macros, for library and header flags +@cindex flags, macros for library and header +@vindex KPSE_@var{LIB}_FLAGS +Each library module @file{libs/@var{lib}} or @file{texk/@var{lib}} is +supplemented by a macro @code{KPSE_@var{LIB}_FLAGS} (all uppercase) +that provides make variables for that library. E.g., for +@file{libs/libpng}: + +@defmac KPSE_LIBPNG_FLAGS +Provide the configure option @code{--with-system-libpng}. Set and +@code{AC_SUBST} @code{make} variables for modules using this library (either +an installed version or from the @TL{} tree): + +@multitable {@code{LIBPNG_INCLUDES}} {for the @code{make} rules to rebuild the library.} +@item @code{LIBPNG_INCLUDES} +@tab for use in @code{CPPFLAGS}, +@item @code{LIBPNG_LIBS} +@tab for use in @code{LDADD}, +@item @code{LIBPNG_DEPEND} +@tab for use as a Makefile dependency, +@item @code{LIBPNG_RULE} +@tab for the @code{make} rules to rebuild the library. +@end multitable +@end defmac + +@defmac KPSE_ADD_FLAGS (@var{name}) +Temporarily extend @code{CPPFLAGS} and @code{LIBS} with the values required +for the library module @code{@var{name}}. +@end defmac + +@defmac KPSE_RESTORE_FLAGS +Restore @code{CPPFLAGS} and @code{LIBS} to their original values. +@end defmac + +As an example, the @file{configure.ac} file for a hypothetical program +@file{utils/foo} using @file{libpng}, and hence @file{zlib}, would +contain +@example +KPSE_ZLIB_FLAGS +KPSE_LIBPNG_FLAGS +@end example + +@noindent and its @file{Makefile.am} would be along these lines: +@example +bin_PROGRAMS = foo +AM_CPPFLAGS = $@{LIBPNG_INCLUDES@} $@{ZLIB_INCLUDES@} +foo_LDADD = $@{LIBPNG_LIBS@} $@{ZLIB_LIBS@} +foo_DEPENDENCIES = $@{ZLIB_DEPEND@} $@{LIBPNG_DEPEND@} +## Rebuild libz +@@ZLIB_RULE@@ +## Rebuild libpng +@@LIBPNG_RULE@@ +@end example + +If it were necessary to examine whether certain @file{zlib} or +@file{libpng} features were available, @file{configure.ac} should be +continued this way: +@example +KPSE_ADD_FLAGS([zlib]) +@dots{} # @r{tests for @file{zlib} features, if any} +KPSE_ADD_FLAGS([libpng]) +@dots{} # @r{tests for @file{libpng} features} +KPSE_RESTORE_FLAGS # @r{restore @code{CPPFLAGS} and @code{LIBS}} +@end example + + +@node Macros for Windows +@subsection Macros for Windows + +@cindex macros, for Windows +@cindex Windows, macros for +Windows differs in several aspects from Unix-like systems, many of +them due to the lack of symbolic links. + +@defmac KPSE_CHECK_WIN32 +@vindex kpse_cv_have_win32 +Check if compiling for a Windows system. The result is either +@code{no} for Unix-like systems (including Cygwin), @code{mingw32} for +Windows with GCC, or @code{native} for Windows with MSVC. The result +is cached in the @code{kpse_cv_have_win32} variable. +@end defmac + +@defmac KPSE_COND_WIN32 +@vindex WIN32@r{, Automake conditional} +Call @code{KPSE_CHECK_WIN32} and define the Automake conditional +@code{WIN32} (@code{true} if the value of @code{kpse_cv_have_win32} is +not @code{no}). +@end defmac + +@defmac KPSE_COND_MINGW32 +@vindex MINGW32@r{, Automake conditional} +Call @code{KPSE_COND_WIN32} and define the Automake conditional +@code{MINGW32} (@code{true} if the value of @code{kpse_cv_have_win32} is +@code{mingw32}). +@end defmac + +@defmac KPSE_COND_WIN32_WRAP +@vindex WIN32_WRAP@r{, Automake conditional} +@pindex runscript.exe +Call @code{KPSE_COND_WIN32} and define the Automake conditional +@code{WIN32_WRAP} (@code{true} if the standard Windows wrapper +(@file{texk/texlive/w32_wrapper/runscript.exe}) exists. This wrapper +is used on Windows instead of symlinks for the ``linked scripts'' +(@pxref{Linked scripts}). +@end defmac + +@defmac KPSE_WIN32_CALL +@pindex callexe.c +Call @code{KPSE_COND_WIN32} and check if the file +@file{texk/texlive/w32_wrapper/callexe.c} exists; if it does, create a +symlink in the build tree. Compiling @file{callexe.c} with +@code{-DEXEPROG='"@var{foo}.exe"'} and installing @file{callexe.exe} +as @code{@var{bar}.exe} is used on Windows instead of a symlink +@code{@var{bar}->@var{foo}} for Unix-like systems. +@end defmac + + +@node Library modules +@section Library modules + +@cindex library modules +@cindex modules, for libraries +Here we discuss some specifics for a few of the libraries in TL, both +for the details themselves, and as a way of illuminating the general +structure and variation. + +@menu +* @code{png} library:: @file{libs/libpng} +* @code{zlib} library:: @file{libs/zlib} +* @code{freetype} library:: @file{libs/freetype2} +* @code{kpathsea} library:: @file{texk/kpathsea} +@end menu + +@node @code{png} library +@subsection The @code{png} library in @file{libs/libpng} + +@pindex png @r{library} +@pindex libpng @r{library} +The ``generic'' @code{png} library uses the source tree in the +subdirectory @file{libpng-src/}, with all modifications for TL +recorded in @file{TLpatches/*}. The @file{configure.ac} fragment +@file{ac/withenable.ac} contains + +@example +KPSE_WITH_LIB([libpng], [zlib]) +@end example + +@noindent to specify the module name and indicate the dependency on +@code{zlib}. A third literal argument `@code{tree}' would specify that +the library from the @TL{} tree cannot be replaced by a system +version. That not being the case here, a second fragment +@file{ac/libpng.ac} contains + +@findex KPSE_TRY_LIB +@example +KPSE_TRY_LIB([libpng], + [#include ], + [png_structp png; png_voidp io; png_rw_ptr fn; +png_set_read_fn(png, io, fn);]) +@end example + +@noindent thus providing the simple C code + +@example +#include +int main () +@{ png_structp png; png_voidp io; png_rw_ptr fn; + png_set_read_fn(png, io, fn); + return 0; @} +@end example + +@findex KPSE_TRY_LIBXX +@noindent which Autoconf uses to verify the usability of a system +version with C code. The analogous macro @code{KPSE_TRY_LIBXX} would +check using C++. These fragments are included by the +@file{configure.ac} at the top level of TL +(@code{Build/source/configure.ac}). + +@cindex proxy build system +For this library, like many other modules, a proxy build system for TL +is used, consisting of our own @file{configure.ac}, +@file{Makefile.am}, @file{include/Makefile.am}; the distributed build +system is not used. (Consequently, a few generated files and +auxiliary scripts are removed from the distributed source tree.) + +The public headers @file{png.h}, @file{pngconf.h}, and +@file{pnglibconf.h} are ``installed'' (as symlinks) under +@file{include/} in the build tree exactly as they are for a system +version under, e.g., @file{/usr/include/}. + +@pindex kpse-libpng-flags.m4 +@vindex KPSE_LIBPNG_FLAGS +The module is supplemented by the file @file{m4/kpse-libpng-flags.m4} +that defines the M4 macro @code{KPSE_LIBPNG_FLAGS} used by all modules +depending on this library in their @file{configure.ac} to generate the +@code{make} variables @code{LIBPNG_INCLUDES} for use in +@code{CPPFLAGS}, @code{LIBPNG_LIBS} for use in @code{LDADD}, +@code{LIBPNG_DEPEND} for use as dependencies, and @code{LIBPNG_RULE} +for the @code{make} rules to rebuild the library. + +@file{m4/kpse-libpng-flags.m4} also supplies the configure option +@code{--with-system-libpng}, which then uses @code{pkg-config} to +determine the flags required for the system library. + + +@node @code{zlib} library +@subsection The @code{zlib} library in @file{libs/zlib} + +@pindex zlib @r{library} + +@pindex kpse-zlib-flags.m4 +This generic library is very much analogous to @code{libpng}, but +without the dependency on any other library. The file +@file{m4/kpse-zlib-flags.m4} supplies the configure option +@code{--with-system-zlib}, as well as @code{--with-zlib-includes} and +@code{--with-zlib-libdir} to specify non-standard locations of the +@code{zlib} headers and/or library. + + +@node @code{freetype} library +@subsection The @code{freetype} library in @file{libs/freetype2} + +@pindex freetype @r{library} +@cindex wrapper build system + +This module uses a wrapper build system. In contrast to the proxy +build described earlier, the wrapper build has an almost trivial +@file{configure.ac} and a @file{Makefile.am} which invokes the +@code{configure} and @code{make} in the distributed source, followed +by @code{make install} with the TL build tree as destination. In +other words, this actually uses the build system provided by upstream +(possibly patched). + +@pindex freetype-config +The flags required for the system library are obtained through +@code{freetype-config}. + + +@node @code{kpathsea} library +@subsection The @code{kpathsea} library in @file{texk/kpathsea} + +@pindex kpathsea @r{library} + +This is one of the @TeX{}-specific libraries that are maintained as +part of @TL{} (@pxref{,,, kpathsea, Kpathsea +@r{(@url{tug.org/kpathsea})}}); the other is @code{ptexenc}. These +@TeX{} libraries are Libtool libraries (static and/or shared) and are +installed by @code{make install} together with the programs. They +are, however, not part of the TL DVD as distributed by @TeX{} user +groups, and have never been officially released for standalone use. + +@pindex --with-system-kpathsea +It is possible, and probably useful for distro builds (@pxref{Distro +builds}), to specify the configure option +@code{--with-system-kpathsea} in order to use a system version of the +library. Programs outside the TL tree should use @code{pkg-config} +for the required flags. + +@pindex kpathsea.ac +@pindex mktex.ac +@vindex --enable-mktextfm-default +@pindex mktextfm +In addition to @file{kpathsea/ac/withenable.ac} and +@file{kpathsea/ac/kpathsea.ac} here there is a third fragment +@file{kpathsea.ac/mktex.ac}, included by both @file{withenable.ac} and +@file{configure.ac}, which supplies configure options such as +@code{--enable-mktextfm-default}. These determine the compile time +default of whether or not to run @code{mktextfm} (and similar) to +generate a missing @file{.tfm} (or whatever) file. In any case, +however, the command line options @code{-mktex=tfm} or +@code{-no-mktex=tfm} for the @TeX{}-like engines override this +default. + + +@node Program modules +@section Program modules + +@cindex program modules +@cindex modules, for programs +As with libraries (@pxref{Library modules}), here we discuss the +details for a few of the programs in TL. + +@menu +* @code{t1utils} package:: @file{utils/t1utils} +* @code{xindy} package:: @file{utils/xindy} +* @code{xdvik} package:: @file{texk/xdvik} +* @code{asymptote}:: @file{utils/asymptote} +@end menu + + +@node @code{t1utils} package +@subsection The @code{t1utils} package in @file{utils/t1utils} + +@pindex t1utils @r{package} + +Here we use the distributed source tree @file{t1utils-src} with +modifications documented in @file{TLpatches/*} and a proxy build +system consisting of @file{configure.ac} and @file{Makefile.am}. The +fragment @file{ac/withenable.ac} contains + +@example +KPSE_ENABLE_PROG([t1utils]) +@end example + +@noindent specifying the module name without any dependencies, and +supplies the configure option @code{--disable-t1utils}. + + +@node @code{xindy} package +@subsection The @code{xindy} package in @file{utils/xindy} + +@pindex xindy + +This module uses the distributed source tree @file{xindy-src/} with +modifications documented in @file{TLpatches/*}, and a wrapper +@file{configure.ac} and @file{Makefile.am} that descends into +@file{xindy-src}. + +The @code{xindy} build requires a @file{make} that supports a +@code{VPATH} build, can handle all targets, and do not refer to +@code{$@{top_srcdir@}} or @code{$@{top_builddir@}}. The fragment +@code{xindy/ac/withenable.ac} contains + +@example +KPSE_ENABLE_PROG([xindy], , [disable]) +m4_include(kpse_TL[utils/xindy/ac/xindy.ac]) +m4_include(kpse_TL[utils/xindy/ac/clisp.ac]) +@end example + +@noindent where @code{disable} in the third argument indicates that +@code{xindy} is only built if explicitly enabled by the user with +@code{configure --enable-xindy} (the need for @code{clisp} makes it +too painful to enable by default). + +The additional fragments @file{ac/xindy.ac} and @file{ac/clisp.ac} +specify more @code{configure} options to be seen at the top level, +with @file{ac/xindy.ac} also included by @file{configure.ac}. + + +@node @code{xdvik} package +@subsection The @code{xdvik} package in @file{texk/xdvik} + +@pindex xdvik + +This package is maintained as part of the @TL{} tree with sources in +its own directory (@file{texk/xdvik/}). The fragment +@code{xdvik/ac/withenable.ac} contains + +@example +dnl extra_dirs = texk/xdvik/squeeze +KPSE_ENABLE_PROG([xdvik], [kpathsea freetype2], [x]) +m4_include(kpse_TL[texk/xdvik/ac/xdvik.ac]) +@end example + +@pindex squeeze/configure.ac +@cindex cross compilation, with host binary +@noindent thus specifying dependencies on the @code{kpathsea}, +@code{freetype}, and X11 libraries. The M4 comment (following +@code{dnl}) signals the subsidiary @file{squeeze/configure.ac}. This +is needed because the main executable @file{xdvi-bin} (to be installed +as, e.g., @file{xdvi-xaw}) is for the @code{host} system whereas the +auxiliary program @file{squeeze/squeeze} has to run on the +@code{build} system; in a cross compilation, these differ. + +@vindex --with-xdvi-x-toolkit +The additional fragment @code{ac/xdvik.ac} is also included by +@file{configure.ac} and supplies the configure option +@code{--with-xdvi-x-toolkit} also seen at the top level. + + +@node @code{asymptote} +@subsection The subdirectory @file{utils/asymptote} + +@pindex asymptote +@pindex xasy + +@cindex OpenGL, required for Asymptote +This subdirectory contains the sources for @file{asy} and @file{xasy} +but due to its complexity and prerequisites (e.g., OpenGL) it is +not part of the TL build system. These programs must be built and +installed independently, but are included on the TL DVD together with +their support files. See @url{https://tug.org/build.html#asymptote}. + + +@node Extending @TL{} +@section Extending @TL{} + +@cindex extending @TL{} +@cindex adding to @TL{} + +This section outlines the basic process for adding new packages to the +TL build system. + +In any case, a new package directory @file{foo} should contain the +original sources, modified only with changes necessary for TL, in +@file{foo/foo-src}. The changes should be documented in +@file{foo/TLpatches/*}, and also be submitted upstream whenever +reasonable. In addition, @file{foo/} will need the usual Automake +build-related files (@file{configure.ac}, @file{Makefile.am}, etc. +Please maintain @file{foo/ChangeLog} for all TL changes. + +@menu +* Adding a new program module:: +* Adding a new generic library module:: +* Adding a new @TeX{}-specific library module:: +@end menu + + +@node Adding a new program module +@subsection Adding a new program module + +@cindex adding a new program +@cindex program module, adding + +@vindex kpse_texk_pkgs +A @TeX{}-specific program module in a subdirectory +@file{texk/@var{prog}} may use the @TeX{}-specific libraries and is +included by adding its name @file{@var{prog}} to the M4 list +@code{kpse_texk_pkgs} defined in @file{m4/kpse-pkgs.m4}. + +@vindex kpse_utils_pkgs +A generic program module in a subdirectory @file{utils/@var{prog}} +must not use the @TeX{}-specific libraries and is included by adding +its name @file{@var{prog}} to the M4 list @code{kpse_utils_pkgs} in +@file{m4/kpse-pkgs.m4}. + +@pindex withenable.ac@r{, for new modules} +@findex KPSE_ENABLE_PROG +In either case, the subdirectory @file{texk/@var{prog}} or +@file{utils/@var{prog}} must provide a fragment +@file{ac/withenable.ac} that contains the M4 macro +@code{KPSE_ENABLE_PROG} defined in @file{m4/kpse-setup.m4} with +@code{@var{prog}} as the mandatory first argument and three optional +arguments: + +@enumerate +@item a list of required libraries from the TL tree; + +@item a list of options: @code{disable} if this module is not to be +built without the configure option @code{--enable-@var{prog}}, +@code{native} if cross compilation is not possible, @code{x} if the +program requires X11 libraries; + +@item a comment added to the help text for the @code{configure} +option @code{--enable-@var{prog}} or @code{--disable-@var{prog}}. +@end enumerate + +If the module requires specific @code{configure} options to be seen at +the top level, they should be defined in an additional fragment +@file{ac/@var{prog}.ac} included from @file{ac/withenable.ac} and +@file{configure.ac}. + +@cindex @var{newprog-src}, original source subdirectory +Usually, the new program is maintained somewhere outside of @TL{}. In +that case, as above, we put the upstream sources into a subdirectory +@file{@var{prog}-src} (e.g., @file{utils/newprog/newprog-src}). We do +not typically run @code{configure} in this original @code{...-src} +directory, but only in our own directory; but we do compile using the +source files in @code{...-src}. + +So, to summarize the files that must (usually) be created inside a new +TL source directory (@file{texk/newprog} or @file{utils/newprog}): + +@ftable @file +@item ac/withenable.ac +The @code{KPSE_ENABLE_PROG} call just explained. + +@item configure.ac +@itemx Makefile.am +By merging the contents of the original @file{configure.ac} (if +provided) and a comparable program already in TL. In the above +example, one line that will be needed in @file{configure.ac} (can be +added before the @code{AC_CONFIG_FILES} at the end) is: + +@example +AC_SUBST([NEWPROG_TREE], [newprog-src]) +@end example + +@noindent and then use @code{@@NEWPROG_TREE@@} in +@code{Makefile.am} where needed. + +In general, there is no magic recipe for this part of the job. It's +necessary to think about what needs to be done in the original vs.@: +in @TL{}. It's useful to look at the setup for the most comparable +programs already in TL that you can find. It's also useful to grep the +entire @file{Build/source} tree for whatever you can think of to +investigate how something is done. Most of the TL-specific macros are +defined in @file{Build/source/m4/*}. + +@item TLpatches/TL-Changes +First actions taken after getting the original source tree; typically +removal of derived or unused common files. + +@item TLpatches/patch-... +If any changes are needed to the original sources, record the patches +here so they can be applied next time. Also, send them upstream so +that we don't have to maintain them forever. + +@item ChangeLog +Record all TL-specific changes, now and in the future. + +@end ftable + +@pindex autoreconf@r{, for new program} +After populating the new TL source directory (@file{.../newprog/}, in +the above), run GNU @code{autoreconf} there (@pxref{Build system +tools}). Once that works, if you are the one who's eventually going +to commit the new package, @code{svn add} the necessary files, +including the generated @file{Makefile.in aclocal.m4 configure}, and +@code{svn:ignore} the Automake cache @file{autom4te.cache}. (This is +so people checking out the TL source tree do not have to run any +autotools, but can simply run @code{configure}.) + +To reiterate: do not fail to commit the generated @file{configure} and +other files. The m4 code in @file{kpse-pkgs.m4} uses the existence of +@file{configure} to determine whether to descend into (and configure) +a given subdirectory. + +@pindex reautoconf@r{, for new program} +Then, run the TL tool @code{reautoconf} in the top-level TL +@code{Build/source/} directory, to incorporate the new program into +the build tree. It is good to then rebuild the whole tree (e.g., using +TL's @file{Build/Build} script) to get all the necessary files generated. + +It will probably fail. So then you need to keep at it until the +program compiles and tests successfully. The most efficient way is to +rerun @code{autoreconf} as needed in the new source directory +(@code{Build/source/.../newprog}), then @code{make} in the +corresponding build directory (@code{Build/work/.../newprog}), then +@code{make check}, etc. In the end, also make sure that the whole tree +builds from scratch. + +After final success, don't forget to commit. (Or email the TL +maintainers with the patch.) + +@cindex engine, adding new +Caveat: adding a new @TeX{} engine is not completely different, but +it's not all that similar, either. In that case, the work is done +inside a new subdirectory of @file{texk/web2c/}. Many things are +common to all the engines, other things need to be copied and possibly +modified for each one, yet others are unique to each. No general +recipe is possible. + + +@node Adding a new generic library module +@subsection Adding a new generic library module + +@cindex adding a new generic library +@cindex generic library module, adding +@cindex library module, generic, adding + +@vindex kpse_libs_pkgs +A generic library module in a subdirectory @file{libs/@var{lib}} must +not depend on @TeX{}-specific libraries, by definition. It is +included by adding its name @file{@var{lib}} to the M4 macro +@code{kpse_libs_pkgs} in @file{m4/kpse-pkgs.m4}---before any other +libraries from the @TL{} tree on which it depends. + +@findex KPSE_WITH_LIB +As with program modules, the subdirectory @file{libs/@var{lib}} must +contain the sources and build system for the library (and any +installable support programs) and a fragment @file{ac/withenable.ac} +that contains the M4 macro @code{KPSE_WITH_LIB} defined in +@file{m4/kpse-setup.m4} with @code{@var{lib}} as the mandatory first +argument and two optional arguments: a list of required libraries from +the TL tree, and a list of options: for libraries, currently there is +only one---specify @code{tree} if this library cannot be replaced by a +system version. + +@findex KPSE_TRY_LIB +@findex KPSE_TRY_LIBXX +If a system version can be used, a second fragment +@file{ac/@var{lib}.ac} is needed, containing the M4 macro +@code{KPSE_TRY_LIB} (or @code{KPSE_TRY_LIBXX}) with @code{@var{lib}} +as the mandatory first argument and two additional arguments for the +Autoconf macro @code{AC_LANG_PROGRAM} used to compile and link a small +C (or C++) program as sanity check for using the system library. + +@vindex KPSE_@var{LIB}_FLAGS +In addition a file @file{m4/kpse-@var{lib}-flags} (at the top level) +must define the M4 macro @code{KPSE_@var{LIB}_FLAGS} (all uppercase) +setting up the @code{make} variables @code{@var{LIB}_INCLUDES}, +@code{@var{LIB}_LIBS}, @code{@var{LIB}_DEPEND}, and +@code{@var{LIB}_RULE} with the values required for @code{CPPFLAGS}, +@code{LDADD}, dependencies, and a (multi-line) @code{make} rule to +rebuild the library when necessary. All of that is needed for the +library from the TL tree and, if supported, for a system version. + +@vindex --with-system-@var{lib} +@vindex KPSE_@var{LIB}_SYSTEM_FLAGS +@vindex KPSE_ALL_SYSTEM_FLAGS +If a system library is allowed, @code{KPSE_@var{LIB}_FLAGS} also +provides the configure option @code{--with-system-@var{lib}} and uses +the additional M4 macro @code{KPSE_@var{LIB}_SYSTEM_FLAGS} to generate +the @code{make} variables for a system library. In addition, the +definition of the M4 macro @code{KPSE_ALL_SYSTEM_FLAGS} in +@file{m4/kpse-pkgs.m4} must be extended by the line:@*@ @ @ +@code{AC_REQUIRE([KPSE_@var{LIB}_SYSTEM_FLAGS])} + + +@node Adding a new @TeX{}-specific library module +@subsection Adding a new @TeX{}-specific library module + +@cindex adding a new @TeX{}-specific library +@cindex @TeX{}-specific library module, adding +@cindex library module, @TeX{}-specific, adding + +A @TeX{}-specific library module in a subdirectory +@file{texk/@var{lib}} may depend on other @TeX{}-specific libraries +but must not depend on any generic library from the TL tree. It is +included in the same general ways as a generic library (see the +previous section), with these modifications: + +@itemize @bullet +@item +@vindex kpse_texlibs_pkgs +The library name @code{@var{lib}} is added to the M4 macro +@code{kpse_texlibs_pkgs}, which is also in @file{m4/kpse-pkgs.m4}. + +@item +@findex KPSE_WITH_TEXLIB +The fragment @code{ac/withenable.ac} must use @code{KPSE_WITH_TEXLIB}. +@end itemize + + +@node Configure options +@chapter Configure options + +@cindex @code{configure} options + +Corresponding to the large number of program and library modules there +are a large number @code{configure} options, most of which are +described here. The command@*@ @ @ @code{configure --help}@*at the +top level gives an exhaustive list of all global options and a few +important module-specific ones, whereas, e.g.,@*@ @ @ +@code{texk/lcdf-typetools/configure --help}@* also displays the +@code{lcdf-typetools} specific options, which are not shown at the +top level. + +@cindex environment variables, for @code{configure} +The help text also mentions several influential environment variables, +but for @TL{} it is better to specify them as assignments on the +command line. + +The @file{./Build} script used to make the binaries shipped with @TL{} +invokes the top-level @code{configure} with a few additional options +(@pxref{Building}). The defaults discussed below are those for the +actual @code{configure} script; invoking @code{configure} via +@file{./Build} yields different results. + +Defaults for most options are set at the top level and propagated +explicitly to all subdirectories. Options specified on the command +line are checked for consistency but never modified. + +@menu +* Global configure options:: +* Program-specific configure options:: +* Library-specific configure options:: +* Variables for configure:: +@end menu + + +@node Global configure options +@section Global configure options + +@cindex global @code{configure} options +@cindex @code{configure} options, global +Here are the global configure options. + +@menu +* @code{--disable-native-texlive-build}:: +* @code{--prefix} @code{--bindir} @dots{}:: +* @code{--disable-largefile}:: +* @code{--disable-missing}:: +* @code{--enable-compiler-warnings=}@var{level}:: +* @code{--enable-cxx-runtime-hack}:: +* @code{--enable-maintainer-mode}:: +* @code{--enable-multiplatform}:: +* @code{--enable-shared}:: +* @code{--enable-silent-rules}:: +* @code{--without-ln-s}:: +* @code{--without-x}:: +@end menu + + +@node @code{--disable-native-texlive-build} +@subsection @code{--disable-native-texlive-build} + +@vindex --disable-native-texlive-build +If enabled (the default), build for a TL binary distribution as +shipped by the @TeX{} user groups. This requires GNU @code{make} and +implies @code{--enable-multiplatform} and +@code{--enable-cxx-runtime-hack} (unless they are explicitly disabled), +and enforces @code{--disable-shared}. + +If building TL for a GNU/Linux or other distribution, this should be +disabled and system versions of most libraries should be used +(@pxref{Distro builds}). + +@vindex --enable-texlive-build +A related option, @code{--enable-texlive-build}, is automatically +passed to all subdirectories (and cannot be disabled). Subdirectories +that can also be built independently from the TL tree (such as +@file{utils/xindy} and @file{texk/dvipng}) but cooperate with TL can +use this option to enable TL-specific adaptations, such as +installation paths. + + +@node @code{--prefix} @code{--bindir} @dots{} +@subsection @code{--prefix}, @code{--bindir}, @dots{} + +@vindex --prefix configure @r{option} +@vindex --bindir configure @r{option} +These standard Autoconf options specify various installation +directories as usual. For the complete list, @pxref{Installation +directories}. + +@vindex DESTDIR +Also as usual, all values are prefixed by the value of @code{DESTDIR}, +if set, on the @code{make} command line (@pxref{Staged Installs, , +Installation in a temporary location, automake, GNU Automake}). + + +@node @code{--disable-largefile} +@subsection @code{--disable-largefile} + +@vindex --disable-largefile +@cindex large file support +@cindex LFS (large file support) +Omit large file support (LFS), which is needed on most 32-bit Unix +systems for files with 2GB or more. Regardless of this option, the +size of @code{DVI} and @code{GF} files must always be @math{<2}GB, due +to the file format specifications. + +@cindex size of PDF and PS files +@cindex PDF files, size of +@cindex PostScript files, size of +With LFS, there is no fixed limit on the size of PDF files created by +@file{pdftex} or PostScript files created by @file{dvips}. + + +@node @code{--disable-missing} +@subsection @code{--disable-missing} + +@vindex --disable-missing +Immediately terminate the build process if a requested program or feature +must be disabled, e.g., due to missing libraries. This can help when +figuring out a specific (sub)set of modules to enable. + + +@node @code{--enable-compiler-warnings=}@var{level} +@subsection @code{--enable-compiler-warnings=}@var{level} + +@vindex --enable-compiler-warnings=@var{level} +Enable various levels of compiler warnings for C, C++, and/or +Objective@tie{}C: the @var{level} value can be one of: @code{no min +yes max all}. The default is @code{yes} in @code{maintainer-mode} +(see below) and @code{min} otherwise. This option defines the +variables @code{WARNING_[OBJ]C[XX]FLAGS}, but these variables are not +consistently used in all library and program modules. At present, +these warning flags assume options from the GNU compilers. + + +@node @code{--enable-cxx-runtime-hack} +@subsection @code{--enable-cxx-runtime-hack} + +If enabled (as it is for the native TL build), when using @code{g++}, +try to statically link with @code{libstdc++}, thus improving +portability of the resulting binary. @xref{Macros for compilers}. + + +@node @code{--enable-maintainer-mode} +@subsection @code{--enable-maintainer-mode} + +@vindex --enable-maintainer-mode +Enable @file{make} rules and dependencies not useful (and sometimes +confusing) to the casual user. This requires current versions of the +GNU build tools (@pxref{Build system tools}), as it automatically +rebuilds infrastructure files as needed. @xref{maintainer-mode,, +@code{missing} and @code{AM_MAINTAINER_MODE}, automake, GNU Automake}. + + +@node @code{--enable-multiplatform} +@subsection @code{--enable-multiplatform} + +@vindex --enable-multiplatform +@vindex exec_prefix +@vindex --bindir configure @r{option} +@vindex --libdir configure @r{option} +If enabled (as it is for the native TL build) and +@code{--bindir=@var{dir}} or @code{--libdir=@var{dir}} are not +specified, install executables and libraries in per-platform +subdirectories of @file{@var{eprefix}/bin} and +@file{@var{eprefix}/lib} where @var{eprefix} is the value given or +implied for @code{exec_prefix}. In any case, the values for +@code{bindir} and @code{libdir} are automatically propagated to all +subdirectories. + + +@node @code{--enable-shared} +@subsection @code{--enable-shared} + +@vindex --enable-shared +Build shared versions of the @TeX{}-specific libraries such as +@file{libkpathsea}. This is not allowed for a native TL build (i.e., +@code{--disable-native-texlive-build} must also be specified). + + +@node @code{--enable-silent-rules} +@subsection @code{--enable-silent-rules} + +@vindex --enable-silent-rules +@cindex @code{make} rules, verbose vs.@: silent +Enable the use of less verbose build rules. When using GNU +@code{make} (or any @code{make} implementation supporting nested +variable expansions), you can specify @code{V=1} on the @code{make} +command line to get more verbosity, or @code{V=0} to get less, +regardless of this option. + + +@node @code{--without-ln-s} +@subsection @code{--without-ln-s} + +@vindex --without-ln-s +Required when using a system without a working @code{ln -s} to build +binaries for a Unix-like system. However, @code{make install} will +not create anything useful, and might fail. + + +@node @code{--without-x} +@subsection @code{--without-x} + +@vindex --without-x +Disable all programs using the X Window System. + + +@node Program-specific configure options +@section Program-specific configure options + +@cindex program-specific @code{configure} options +@cindex @code{configure} options, program-specific +Here are (some of) the program-specific @code{configure} options. + +@menu +* @code{--enable-@var{prog}} @code{--disable-@var{prog}}:: +* @code{--disable-all-pkgs}:: +* Configure options for @file{texk/web2c}:: +* Configure options for @file{texk/bibtex-x}:: +* Configure options for @file{texk/dvipdfm-x}:: +* Configure options for @file{texk/dvisvgm}:: +* Configure options for @file{texk/texlive}:: +* Configure options for @file{texk/xdvik}:: +* Configure options for @file{utils/xindy}:: +@end menu + + +@node @code{--enable-@var{prog}} @code{--disable-@var{prog}} +@subsection @code{--enable-@var{prog}}, @code{--disable-@var{prog}} + +@vindex --enable-@var{prog} +@vindex --disable-@var{prog} +Do or do not build and install the program(s) of module @code{@var{prog}}. + + +@node @code{--disable-all-pkgs} +@subsection @code{--disable-all-pkgs} + +@vindex --disable-all-pkgs +Do not build any program modules by default---only those explicitly +enabled. This is useful when one wants to work on only a single +program, which is specified with an additional @code{--enable} option, +e.g., @code{--enable-dvipdfm-x}. It's still simplest to check out and +configure the whole source tree, but at least only the program you are +interested in, and its dependencies, are built. @xref{Build one package}. + +Without this option, all modules are built except those that are +explicitly disabled or specify @code{disable} in their +@file{ac/withenable.ac} fragment. + + +@node Configure options for @file{texk/web2c} +@subsection Configure options for @file{texk/web2c} + +@cindex @code{configure} options, for @code{web2c} + +@vindex --with-banner-add=@var{str} +@noindent @code{--with-banner-add=@var{str}}@*Add @code{@var{str}} to the +default version string (which is `@code{TeX Live @var{year}}' or +`@code{Web2C @var{year}}') appended to banner lines. This is ignored +for a native TL build, but distro builds should specify, e.g., +@code{/@var{SomeDistro}}. + +@vindex --with-editor=@var{cmd} +@noindent @code{--with-editor=@var{cmd}}@*Specify the command +@code{@var{cmd}} to invoke from the @code{e} option of @TeX{} and friends, +replacing the default @code{vi +%d '%s'} for Unix or @code{texworks +--position=%d "%s"} for Windows. + +@vindex --with-fontconfig-includes=@var{dir} +@vindex --with-fontconfig-libdir=@var{dir} +@noindent @code{--with-fontconfig-includes=@var{dir}}, +@code{--with-fontconfig-libdir=@var{dir}}@*Building Xe@TeX{} on +non-Mac systems requires the @code{fontconfig} library headers and +code. If one or both of these options are given, the required flags +are derived from them; otherwise, they are determined via +@file{pkg-config} (if present). + +@cindex X toolkit +@pindex libXt +@pindex Xlib +@noindent @code{--with-mf-x-toolkit}@*Use the X toolkit (@file{libXt}) for +Metafont (the default is to use the lowest-level @file{Xlib} support; +it seems this has the best chance of working across X installations +nowadays). + +@vindex --disable-dump-share +@cindex LittleEndian architectures +@noindent @code{--disable-dump-share}@*Make the @code{fmt}/@code{base} +dump files architecture dependent (somewhat faster on LittleEndian +architectures). + +@vindex --disable-ipc +@cindex interprocess communication +@noindent @code{--disable-ipc}@*Disable @TeX{}'s @code{--ipc} option. + +@vindex --disable-mf-nowin +@pindex mf-nowin +@noindent @code{--disable-mf-nowin}@*Do not build a separate +non-graphically-capable Metafont (@file{mf-nowin}). + +@vindex --disable-tex +@vindex --enable-etex +@pindex web2c.ac +@noindent @code{--disable-tex}, @code{--enable-etex}, @dots{}@*Do not or +do build the various @TeX{}, Metafont, and MetaPost engines (defaults are +defined in the fragment @file{texk/web2c/ac/web2c.ac}). + +@vindex --disable-web-progs +@noindent @code{--disable-web-progs}@*Do not build the original WEB programs +@file{bibtex}, @dots{}, @file{weave}. Useful if, e.g., you only want +to (re)build some engines. + +@vindex --enable-auto-core +@cindex preloaded binaries +@noindent @code{--enable-auto-core}@*This option causes @TeX{} and Metafont +to produce a core dump when a particular hacky filename is +encountered, for use in creating preloaded binaries. This is rarely +done nowadays. + +@vindex --enable-libtool-hack +@pindex libtool@r{, hack for avoiding excessive linking} +@pindex libfontconfig@r{, hack for avoiding linking dependencies} +@pindex libexpat@r{, dependency of @code{libfontconfig}} +@noindent @code{--enable-libtool-hack}@* +If enabled (which is the default for all platforms), prevents +@code{libtool} from linking explicitly with dependencies of +@file{libfontconfig} such as @file{libexpat}. + +@vindex --enable-*win @r{for Metafont window support} +@noindent @code{--enable-*win}@*Include various types of non-X window +support for Metafont (EPSF output, @code{mftalk}, old graphics +terminals, @dots{}). + +@vindex --enable-tex-synctex +@vindex --disable-etex-synctex +@cindex synctex +@noindent @code{--enable-tex-synctex}, @code{--disable-etex-synctex}, +@dots{}@*Build the @TeX{} engines with or without @code{SyncTeX} +support; ignored for a native @TL{} build. Defaults are defined in +@file{texk/web2c/ac/web2c.ac}. + +@vindex --disable-synctex +@cindex synctex +@noindent @code{--disable-synctex} +@*Do not build the @code{SyncTeX} library and tool. + + +@node Configure options for @file{texk/bibtex-x} +@subsection Configure options for @file{texk/bibtex-x} + +@cindex @code{configure} options, for @code{bibtex-x} +@pindex bibtex8 +@pindex bibtexu +@pindex bibtex-x +The programs @code{bibtex8} and @code{bibtexu} have been merged into the +module @code{bibtex-x} (extended Bib@TeX{}). + +@vindex --disable-bibtex8 +@noindent @code{--disable-bibtex8}@*Do not build the @file{bibtex8} program. + +@vindex --disable-bibtexu +@noindent @code{--disable-bibtexu}@*Do not build the @file{bibtexu} program +(building @file{bibtexu} requires @code{ICU} libraries). + + +@node Configure options for @file{texk/dvipdfm-x} +@subsection Configure options for @file{texk/dvipdfm-x} + +@cindex @code{configure} options, for @code{dvipdfm-x} +@pindex dvipdfm-x +@pindex dvipdfmx +@pindex xdvipdfmx + +The former modules @code{dvipdfmx} (extended DVI to PDF converter) and +@code{xdvipdfmx} (the same, as used by Xe@TeX{}) have been merged into +@code{dvipdfm-x} at the source level. Two separate binaries are still +created by default. In addition, @file{dvipdfm} is created as a +symlink to @file{dvipdfmx}, with backward-compatible (very slightly +different) behavior. + +@vindex --disable-dvipdfmx +@noindent @code{--disable-dvipdfmx}@*Do not build the @file{dvipdfmx} +program or make the @file{dvipdfm} symlink. + +@vindex --disable-xdvipdfmx +@noindent @code{--disable-xdvipdfmx}@*Do not build the @file{xdvipdfmx} +program. + + +@node Configure options for @file{texk/dvisvgm} +@subsection Configure options for @file{texk/dvisvgm} + +@cindex @code{configure} options, for @file{dvisvgm} +@pindex dvisvgm + +@vindex --with-system-libgs +@noindent @code{--with-system-libgs}@*Build @file{dvisvgm} using installed +Ghostscript (@code{gs}) headers and library (not allowed for a native +TL build). The default is to load the @code{gs} library at runtime if +possible, else to disable support for PostScript specials. + +@vindex --without-libgs +@noindent @code{--without-libgs}@*Build @file{dvisvgm} without PostScript +support at all. Because the dynamic loading just mentioned defeats all +attempts at static linking, the result can crash due to library +incompatibilities, e.g., on CentOS 5. + +@vindex --with-libgs-includes@r{,} -libdir +@noindent @code{--with-libgs-includes=@var{dir}}, +@code{--with-libgs-libdir=@var{dir}}@*Specify non-standard locations +of the Ghostscript headers and library. + + +@node Configure options for @file{texk/texlive} +@subsection Configure options for @file{texk/texlive} + +@cindex @code{configure} options, for @file{texk/texlive} +@vindex --disable-linked-scripts +@noindent @code{--disable-linked-scripts}@*Do not install the ``linked +scripts'' (@pxref{Linked scripts}), except for the TL scripts required +to run @code{texlinks}. + + +@node Configure options for @file{texk/xdvik} +@subsection Configure options for @file{texk/xdvik} + +@cindex @code{configure} options, for @file{xdvik} +@pindex xdvik + +@vindex --with-gs=@var{filename} +@cindex Ghostscript location for Xdvik +@noindent @code{--with-gs=@var{filename}}@*Hardwire the location of Ghostscript +(@file{gs}) as called by Xdvik. + +@vindex --with-xdvi-x-toolkit=@var{kit} +@pindex motif +@pindex xaw +@noindent @code{--with-xdvi-x-toolkit=@var{kit}}@*Use toolkit +@code{@var{kit}} for @file{xdvik}, one of: @code{motif xaw xaw3d +neXtaw}. The default is @code{motif} if available, else @code{xaw}. + +@vindex --enable-xi2-scrolling +@pindex XInput +@pindex scrolling, smooth +@noindent @code{--enable-xi2-scrolling}@*Use XInput 2.1 ``smooth scrolling'' +if available (default: yes, except for a native TL build). + + +@node Configure options for @file{utils/xindy} +@subsection Configure options for @file{utils/xindy} + +@cindex @code{configure} options, for @file{xindy} +@pindex xindy + +@vindex --enable-xindy-rules +@noindent @code{--enable-xindy-rules}@*Build and install @code{xindy} rules +(default: yes, except for a native TL build). + +@vindex --enable-xindy-docs +@noindent @code{--enable-xindy-docs}@*Build and install @code{xindy} +documentation (default: yes, except for a native TL build). + +@vindex --with-clisp-runtime=@var{filename} +@pindex lisp.run@r{,} lisp.exe +@cindex CLISP +@noindent @code{--with-clisp-runtime=@var{filename}}@*Specifies the +full path for the Clisp runtime file (@file{lisp.run} or +@file{lisp.exe}) to be installed. When specified as @code{default} +(the default for a native TL build) the path is determined by the +Clisp executable; the value @code{system} (not allowed for a native TL +build, but the default otherwise) indicates that @file{xindy} will use +the installed version of @file{clisp} (which must be identical to the +one used to build @file{xindy}). + + +@node Library-specific configure options +@section Library-specific configure options + +@cindex library-specific @code{configure} options +@cindex @code{configure} options, library-specific +Here are (some of) the library-specific @code{configure} options, +starting with this generic one: + +@vindex --with-system-@var{lib} +@noindent @code{--with-system-@var{lib}} + +Use an installed (system) version of the library @code{@var{lib}}; +this option exists for most libraries, but is not allowed for a native +TL build. Using a system version implies also using the system +versions of all libraries that @var{lib} depends on. + +@vindex --with-@var{lib}-includes=@var{dir}@r{,} -libdir +For many libraries @code{--with-@var{lib}-includes=@var{dir}} and +@code{--with-@var{lib}-libdir=@var{dir}} can specify non-standard +search locations; others use @file{pkg-config} or similar to determine +the required flags. + +The top-level @file{configure} script performs a consistency check for all +required system libraries and bails out if tests fail. + +@menu +* Configure options for @code{kpathsea}:: +@end menu + +@node Configure options for @code{kpathsea} +@subsection Configure options for @code{kpathsea} + +@cindex @code{configure} options, for @code{kpathsea} + +@noindent @code{--enable-@var{cmd}-default}, +@code{--disable-@var{cmd}-default}@*Determine the compile time default +for whether or not to run @var{cmd}, which is one of: +@table @code +@item mkocp +(Omega compiled translation process file) +@item mkofm +(Omega font metrics file) +@item mktexfmt +(format/base dump file) +@item mktexmf +(Metafont source) +@item mktexpk +(PK bitmap font) +@item mktextex +(@TeX{} source) +@item mktextfm +(TFM file) +@end table + +@noindent to generate the specified type of file dynamically. +The default can be overridden by the user in any case +(@pxref{@code{kpathsea} library}). + +@node Variables for configure +@section Variables for configure + +@cindex variables for @code{configure} +@cindex @code{configure} variables + +The values for these variables can be specified as @code{configure} +arguments of the form @code{@var{VAR}=@var{value}}. They can also be +defined in the environment, but that might not work for cross +compilations. + +@vtable @code +@item CC +@itemx CXX +@itemx CPPFLAGS +And plenty more. As usual with Autoconf, these variables specify the +name (or full path) of compilers, preprocessor flags, and similar. +@xref{Preset Output Variables,,, autoconf, GNU Autoconf}. + +@item CLISP +@pindex clisp +Name (or full path) of the @file{clisp} executable, used to build +@code{xindy}. + +@item FT2_CONFIG +@itemx ICU_CONFIG +@itemx PKG_CONFIG +@pindex freetype-config +@pindex icu-config +@pindex libfreetype +@cindex ICU libraries +These specify the name (or path) for the @file{freetype-config}, +@file{icu-config}, and @file{pkg-config} commands used to determine the +flags required for system versions of @file{libfreetype}, the ICU +libraries, and other libraries, respectively. + +@item KPSEWHICH +@pindex kpsewhich +Name (or path) of an installed @file{kpsewhich} binary, used by +@code{make check} to determine the location of, e.g., +@file{cmbx10.tfm}. + +@item MAKE +@itemx SED +And more. Name (or path) of the @code{make}, @code{sed}, and similar +programs; used at the top level and propagated to all subdirectories. + +@item PERL +@itemx LATEX +@itemx PDFLATEX +Name (or full path) for the @file{perl}, @file{latex}, and @file{pdflatex} +commands used, e.g., to build the @code{xindy} documentation. + +@end vtable + + +@node Coding conventions +@chapter Coding conventions + +@cindex coding conventions +@cindex conventions, coding + +Ideally, building all of @TL{} with +@code{--enable-compiler-warnings=max} should produce no (GCC) compiler +warnings at all. In spite of considerable efforts into that direction +we are still far from that goal and there are reasons that we may +never fully reach it. Below are some rules about declarations of +functions or variables and the use of @code{const}. These rules +should be applied to the code maintained in the @TL{} tree and for +other packages whose maintainers are willing to accept patches. + +@menu +* Declarations and definitions:: +* Const:: +@end menu + + +@node Declarations and definitions +@section Declarations and definitions + +@cindex declarations and definitions, in source code +@cindex source code declarations +@cindex ANSI C +@cindex declarations before statements, avoiding +@cindex C, ANSI, required +@cindex C99, avoided + +@subsubheading C standards + +The @TL{} build system no longer supports pre-ANSI C compilers. Thus +all function prototypes and definitions must conform to the ANSI C +standard (including @code{void} in the declaration of C functions with +no parameters). On the other hand, TL is built for a wide variety of +systems, not all of which support the C99 standard. Therefore using +C99 features should be avoided if that can easily be done. In +particular, C code must not contain declarations after statements or +C++-style comments. + +@pindex chktex +@findex stpcpy +If some C99 (or later) constructs must be used, the module should +verify that they are available and otherwise provide an alternative. +For example, the module @file{texk/chktex} uses the C99 function +@code{stpcpy()} that may or may not be available on a particular +system. It uses @code{AC_CHECK_DECLS([stpcpy])} in +@file{configure.ac} to test this, and provides a perhaps +less efficient alternative (in the file @file{Utility.h}): + +@example +#if !(defined HAVE_DECL_STPCPY && HAVE_DECL_STPCPY) +static inline char *stpcpy(char *dest, const char *src) +@{ + return strcpy(dest, src) + strlen(src); +@} +#endif +@end example + +@subsubheading Static functions + +@cindex @code{static} functions +Functions used in only one file should be declared @code{static}; they +require no prototype except in forward declarations. + +@subsubheading Extern functions + +@cindex @code{extern} functions +Functions not declared @code{static}, usually because they are used in +several files, require an (@code{extern}) prototype in exactly one +header file, which is included in the file defining the function and +in all files using that function---this is the only way to guarantee +consistency between definition and use. There should be no +@code{extern} declarations sprinkled throughout the C code (with or +without comments as to where that function is defined). + +@subsubheading Variable declarations + +@cindex variable declarations, in source code +The declaration of global variables follows analogous rules: they are +either declared @code{static} if used in only one file or declared +@code{extern} in exactly one header and instantiated in exactly one +file. + +@node Const +@section Const + +@cindex @code{const} + +The @code{const} feature of C is valuable, but easy to mis-use. + +@subsubheading Function parameters + +Ideally, a function parameter not modified by the function should be +declared as @code{const}. This is important in particular for strings +(@code{char*}) because the actual arguments are often string literals. +It is perfectly legitimate and safe to use a type @code{char*} value +for a type @code{const char*} variable (in an assignment, as +initializer, as function argument, or as return value). It is equally +safe to use a type @code{char**} value for a type @code{const +char*const*} variable, but not for a type @code{const char**} variable +since that might cause modification of a quantity supposed to be +constant. + +@cindex X11 headers, and @code{const} +@cindex @code{libfreetype}, and @code{const} +Getting all @code{const} qualifiers right can get quite involved but +can almost always be done. There are only a couple notable +exceptions: the X11 headers are full of declarations that ought to use +@code{const} but do not; at one time, @file{libfreetype} also did not +fully specify @code{const}, but this has not been checked recently. + +@subsubheading What must be avoided with @code{const} + +@cindex warning, discards qualifiers +@cindex discards qualifiers warning +The GCC compiler warnings ``assignment discards qualifiers@dots{}'' +and analogous warnings for ``initialization'', ``passing arg'', or +``return'' must be strenuously avoided in our own code. The only +exception is when they are caused by X11 declarations or other third +party code. + +@subsubheading What should be avoided with @code{const} + +@cindex type cast from const, avoiding +A type cast, e.g., from @code{const char*} to @code{char*} does not +solve any problems; depending on warning options, it may only hide +them. Therefore such casts should be avoided whenever possible and +otherwise must be carefully analyzed to make sure that they cannot +cause the modification of quantities supposed to be constant. + + +@node Continuous integration +@chapter Continuous integration + +@cindex continuous integration +@cindex Travis-CI + +The @TL{} sources are subjected to continuous integration testing on +Travis-CI (@url{https://travis-ci.org/TeX-Live/texlive-source}) via a +git-svn mirror of the sources that is pushed to Github +(@url{https://github.com/TeX-Live/texlive-source}). The git-svn mirror +is updated (currently) at 30 minute intervals, and only the last +commit pushed is tested on Travis-CI. + +@menu +* Transfer from Subversion to Github:: +* Automatic update of the Git mirror:: +* CI testing on Travis-CI:: +* Releases on Github:: +@end menu + + +@node Transfer from Subversion to Github +@section Transfer from Subversion to Github + +@pindex git-svn +The git-svn program (@url{https://git-scm.com/docs/git-svn}) is used +to check out the subtree @code{Build/source} of the canonical +Subversion repository. The author index file used is not maintained +in either Git or Subversion but can be provided on request. + +@c TODO what should we do here with the author index file? It contains a +@c mapping from subversion names to name/email as shown in git. + +The initial checkout was done by invoking +@example +git svn --authors-file usermap clone \ + svn://@var{user}@@tug.org/texlive/trunk/Build/source +@end example + +@noindent where the @code{usermap} file maps Subversion user names to +name and emails of the authors. Anonymous checkout is also possible: +@example +git svn --authors-file usermap clone \ + svn://tug.org/texlive/trunk/Build/source +@end example + +In the following, we will use @emph{admin} to refer to a user who has +read/write access to the @TL{} subversion repository, and is also an +administrator of the `@code{TeX-Live}' team at Github. The above +initial checkout has been carried out by @emph{admin} on the server +@code{texlive.info}. + +On Github, a new git repository named @code{texlive-source} was +created by @emph{admin} within the @code{TeX-Live} ``organization'' +(@url{https://github.com/TeX-Live}). The remote was added to the +checkout with @code{git remote add origin +git@@github.com:TeX-Live/texlive-source.git}. + +To automate the update on Github, a new ssh key was generated and +added to the @code{texlive-source} repository on Github as deployment +key. Thus, pushes using this key can only go to the +@code{texlive-source} repository and not anywhere else. + +The usage of @code{git-svn} requires a strict discipline to keep a +linear history in the master branch. Since we are aiming at a pure +mirror facility on Github, we have decided to further restrict the +@code{master} branch of the @code{texlive-source} repository on Github +to changes by @emph{admin}. + +This setup allows other developers to branch off @code{master} and +push their branches to the Github repository, but all updates need to +come from the local @code{master} (not the one on Github) to +Subversion, back to @code{master} on @code{texlive.info}, and from +there to Github. + +@node Automatic update of the Git mirror +@section Automatic update of the Git mirror + +@emph{admin} has installed a cron job on @code{texlive.info} running +every 30 minute which essentially runs @code{git svn rebase} and +@code{git push} in the @code{master} branch of the checkout. The first +command fetches the changes from the Subversion repository and updates +the @code{master} branch with them, and the second pushes changes (if +any) to Github. + +@node CI testing on Travis-CI +@section CI testing on Travis-CI + +@pindex travis.yml +The @code{source} tree of @TL{} contains a top-level file +@code{.travis.yml} which controls the automatic testing on +Travis-CI. @emph{admin} has registered with Travis-CI and allowed +access to the Github's @code{TeX-Live} organization's +@code{texlive-source} repository. The default settings are to build +the last commit of each push. No further action is necessary on +Travis-CI. + +If changes have been pushed via the cron job above, Travis-CI will +automatically checkout the last pushed commit and try building it. + +@node Releases on Github +@section Releases on Github + +Given a git checkout of @code{texlive-source}: + +@example +git pull +git tag build-svnNNNN +git push --tags +@end example + +@noindent and the result will appear at +@url{https://github.com/TeX-Live/texlive-source/releases}. +Releases can also be made manually from that web page (see +@code{tl-update-bindir} for hints). + +@c made from pod doc. +@include tlbuild-incl/install-tl.texi +@include tlbuild-incl/tlmgr.texi + +@node Index +@unnumbered Index + +@printindex cp + +@bye -- cgit v1.2.3