README.3installing

(This file was generated by makeinfo and splitinfo.gawk.)
(Released under the old-style GNU documentation license;
 see sources or other output files for full text.)

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 <https://tug.org/texlive/distro.html> and
<https://tug.org/texlive/build.html#deploy>.

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", see 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.

5.2 Linked scripts
==================

Quite a few of the executables in TeX Live 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 independently in their own packages, 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/fmtutil' to 'DATAROOTDIR/texmf-dist/scripts/texlive/fmtutil.pl'.
The symlink is relative, so the installation root can be anywhere.

   For Windows, we cannot portably use symlinks, so a standard wrapper
binary (copied to, e.g., 'BINDIR/fmtutil.exe') serves the same purpose
(the source for the wrapper is in 'texk/texlive/windows_wrapper').

   One reason for all 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 'make
install' in the TL source tree to be as close as possible to what's in
thej 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
<https://tug.org/texlive/build.html> for information about building
those exceptions, as well as the 'xz' and 'wget' programs that are used
in the TL infrastructure.)

   As part of the 'make install' in the 'linked_scripts' directory, a
file 'scripts-targets.lst' is created to record all the links that are
created this way, so that distros and others can reproduce them.  The
file has one line per link.  The first word is the target of the link
(e.g., 'texmf-dist/scripts/texlive/fmtutil.pl'), and the second word is
the name of the link to be placed in the bindir (e.g., 'fmtutil').
Determining the relative link target (how many '../'s) is left to the
users of this file, since it varies among distributions.  It can be
assumed there is no whitespace in these filenames.

   A few links are within bindir; in that case, the first word of the
line is just a base name, e.g., the file 'fmtutil mktexfmt' means that
doing the equivalent of 'ln -s fmtutil mktexfmt' in the bindir.

   Be aware that although extensions are usually stripped (as with
'fmtutil'), there are exceptions, such as 'memoize-extract.pl' and
'listings-ext.sh'.

   The 'scripts-targets.lst' file started being created as of the
TeX Live 2025 release.  Historically, another file 'scripts.lst' has
been (and still is) created, containing only the link targets, and using
a Bourne shell syntax.

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 (see
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:
<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.)