rename and update README* files, now generated from tlbuild.texi

git-svn-id: svn://tug.org/texlive/trunk@33605 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 141 insertions, 0 deletions

diff --git a/Build/source/README.3installing b/Build/source/README.3installing
new file mode 100644
index 00000000000..c65ebde5d9d
--- /dev/null
+++ b/Build/source/README.3installing
@@ -0,0 +1,141 @@
+(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 this is not enough to make a usable
+TeX installation.  Beyond the binaries that are built from the sources,
+(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 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 <http://tug.org/texlive/distro.html>.
+
+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 explictly 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-PLATFORM-NAME'.  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 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 (e.g., 'BINDIR/ps2eps.exe') serves the same
+purpose.  (The source for the wrapper is in 'texk/texlive/w32_wrapper'.)
+
+   One reason for all this is to avoid having many copies of the same
+script, but more importantly this allows invoking the same script on all
+operating systems.  Furthermore, we want the 'BINDIR' resulting from the
+build to be exactly what is in the TL distribution; any deviations cause
+considerable extra work.
+
+5.3 Distro builds
+=================
+
+Although they use the same code base, building for the native TL
+distribution as shipped by the TL 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').
+However, 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, but we digress).  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'
+     Use system versions for as many libraries LIB as possible.
+     '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:
+<http://tug.org/TUGboat/tb34-3/tb108preining-distro.pdf>.  (If it needs
+updating at some point, perhaps we will merge it into this document.)
+