source/README.3installing

   1 (This file was generated by makeinfo and splitinfo.gawk.)
   2 (Released under the old-style GNU documentation license;
   3  see sources or other output files for full text.)
   4
   5 5 Installing
   6 ************
   7
   8 This section discusses the results of 'make install' in the source tree.
   9
  10    The main consideration is that 'make install' is not enough to make a
  11 usable TeX installation.  Beyond the compiled binaries, (thousands of)
  12 support files are needed; just as a first example 'plain.tex' is not in
  13 the source tree.
  14
  15    These support files are maintained completely independently and are
  16 not present in the source tree.  The best basis for dealing with them is
  17 the TeX Live (plain text) database in 'Master/tlpkg/texlive.tlpdb',
  18 and/or the TeX Live installer, 'install-tl'.  More information is under
  19 'Master/tlpkg' and at <http://tug.org/texlive/distro.html>.
  20
  21 5.1 Installation directories
  22 ============================
  23
  24 Running 'make install' (or 'make install-strip') installs executables in
  25 'BINDIR', libraries in 'LIBDIR', headers in 'INCLUDEDIR', general data
  26 (including "linked scripts", *note Linked scripts::) in
  27 'DATAROOTDIR/texmf-dist', man pages in 'MANDIR', and Info files in
  28 'INFODIR'.
  29
  30    The values of these directories are determined by 'configure' and can
  31 be specified explictly as options such as '--prefix=PREFIX' or
  32 '--bindir=BINDIR'; otherwise, they are given by their usual Autoconf
  33 defaults:
  34
  35      PREFIX                  /usr/local
  36      EXEC_PREFIX             PREFIX
  37      BINDIR                  EXEC_PREFIX/bin
  38      LIBDIR                  EXEC_PREFIX/lib
  39      INCLUDEDIR              PREFIX/include
  40      DATAROOTDIR             PREFIX/share
  41      MANDIR                  DATAROOTDIR/man
  42      INFODIR                 DATAROOTDIR/info
  43
  44 ... except possibly modified as follows:
  45
  46    * If the option '--enable-multiplatform' is given, '/PLATFORM' (i.e.,
  47      the canonical platform name) is appended to 'BINDIR' and 'LIBDIR'.
  48      This is implied for a native TL build.
  49
  50    * In a native TL build, 'DATAROOTDIR' is set to 'PREFIX', 'INFODIR'
  51      is set to 'PREFIX/texmf-dist/doc/info', and 'MANDIR' to
  52      'PREFIX/texmf-dist/doc/man', corresponding to the directories used
  53      in the TL distribution.
  54
  55 The top-level 'configure' script displays all these installation paths.
  56
  57    For the native TL build, the 'Build' script leaves the binaries in
  58 './inst/bin/STD-PLATFORM-NAME'.  The new binaries are not directly
  59 usable from that location; they need to be copied to
  60 'Master/bin/TL-PLATFORM'.  The other files and directories that end up
  61 in './inst/' are ignored.
  62
  63 5.2 Linked scripts
  64 ==================
  65
  66 Quite a few executables are architecture-independent shell, Perl, or
  67 other interpreted scripts, rather than compiled binaries.  A few are
  68 maintained as part of the TL source tree, but most are maintained
  69 elsewhere with copies under 'texk/texlive/linked_scripts'.
  70
  71    These so-called "linked scripts" are installed under
  72 'DATAROOTDIR/texmf-dist/scripts'; for Unix-like systems a symbolic link
  73 is made in 'BINDIR'.  For example, a symlink points from 'BINDIR/ps2eps'
  74 to 'DATAROOTDIR/texmf-dist/scripts/ps2eps/ps2eps.pl'.  For Windows, a
  75 standard wrapper binary (e.g., 'BINDIR/ps2eps.exe') serves the same
  76 purpose.  (The source for the wrapper is in 'texk/texlive/w32_wrapper'.)
  77
  78    One reason for this is to avoid having many copies of the same
  79 script; a more important reason is that it guarantees the scripts will
  80 stay in sync across the different supported operating systems.
  81
  82    Most important of all, we want the 'BINDIR' resulting from the build
  83 to be as close as possible to what is in the TL distribution.  At
  84 present, there are a few exceptions--Asymptote, Biber, Xindy--and each
  85 one creates considerable extra work.  We don't want to add more.  (See
  86 <http://tug.org/texlive/build.html> for information about building those
  87 exceptions, as well as the 'xz' and 'wget' programs that are used in the
  88 TL infrastructure.)
  89
  90 5.3 Distro builds
  91 =================
  92
  93 Although they use the same code base, building for the native TL
  94 distribution as shipped by the TeX user groups is typically quite
  95 different from a "distro" build needed by, e.g., a full GNU/Linux or BSD
  96 operating system distribution.
  97
  98    The native TL distribution uses shared libraries only when absolutely
  99 necessary ('libc', 'libm', X11 libraries, and 'libfontconfig').
 100 However, a distro typically wants to use as many shared libraries as
 101 possible from elsewhere on the system, including TeX-specific libraries
 102 such as 'libkpathsea' (even though Kpathsea has never officially been
 103 released as a shared library, but we digress).  In addition, the
 104 installation paths will, in general, be completely different.
 105
 106    Here are the 'configure' options that distro builds are likely to
 107 find most relevant:
 108
 109 '--disable-native-texlive-build'
 110      This must be specified to avoid interference from the many tweaks
 111      we do for the native TL build.
 112
 113 '--with-banner-add=/SOMEDISTRO'
 114      This isn't technically required, but is strongly recommended, so
 115      your build and your distro can be distinguished from others.
 116
 117 '--enable-shared'
 118      Build shared versions of the TeX-specific libraries (uses
 119      'libtool').
 120
 121 '--disable-static'
 122      Do not build the static versions of the TeX-specific libraries.
 123
 124 '--with-system-LIB'
 125      Use system versions for as many libraries LIB as possible.
 126      'configure --help' will give you the list of possibilities.
 127
 128 '--with-LIB-includes=DIR'
 129 '--with-LIB-libdir=DIR'
 130      If needed, allows you to specify where the headers/code are for the
 131      given library LIB.
 132
 133 '--prefix=/usr'
 134 '--prefix=/opt/TeXLive'
 135      Or whatever your convention is.  The default is '/usr/local' and
 136      you shouldn't install there for a distro.
 137
 138 '--libdir=\${exec_prefix}/lib64'
 139      May be needed for 64-bit bi-architecture (GNU/Linux) systems.
 140
 141    You will need to take care of the support files mentioned above
 142 (*note Installing::), and many other issues, such as font maps,
 143 languages, and formats, independently of the build.  Norbert Preining
 144 has written a detailed article on adapting TL for distros:
 145 <http://tug.org/TUGboat/tb34-3/tb108preining-distro.pdf>.  (If the
 146 article needs updating in the future, perhaps we will merge it into this
 147 document.)
 148