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, 443 insertions, 0 deletions

diff --git a/Build/source/README.5configure b/Build/source/README.5configure
new file mode 100644
index 00000000000..f94b0ae674d
--- /dev/null
+++ b/Build/source/README.5configure
@@ -0,0 +1,443 @@
+(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.)
+
+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
+by the top-level '--help'.
+
+   The help text also mentions several influential environment
+variables, but for TeX Live it is better to specify them as assigments
+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' may yield
+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.
+
+7.1 Global configure options
+============================
+
+Here are the 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 would be used (*note
+Distro builds::).  This may fail without GNU 'make', but will be tried
+regardless.
+
+   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') can use this option, e.g., to choose TL-specific
+installation paths.
+
+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.).
+
+7.1.3 '--disable-largefile'
+---------------------------
+
+Omit large file support (LFS), needed on most 32-bit Unix systems for
+files with 2GB or more.  Regardless of this, 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'.  The size of PDF images
+included by 'pdftex' must, however, be <4GB when using 'xpdf' and <2GB
+when using older versions of 'poppler' (even on 64-bit systems with
+LFS), whereas 'poppler' versions 0.23 and later impose no such limit.
+
+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.
+
+7.1.5 '--enable-compiler-warnings='LEVEL
+----------------------------------------
+
+Enable various levels of compiler warnings for (Objective) C and 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 'WARNING_[OBJ]C[XX]FLAGS' but these flags are not used in all
+library and program modules.  Using them should help to resolve
+portability problems.
+
+   At present, these warning flags are only defined for the GNU
+compilers but flags for other compilers could be added when needed.
+
+7.1.6 '--enable-cxx-runtime-hack'
+---------------------------------
+
+If enabled (as it is for the native TL build) and when using 'g++', try
+to statically link with 'libstdc++', somewhat improving portability of
+the resulting binary.  *Note Macros for compilers::.
+
+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.
+
+7.1.8 '--enable-multiplatform'
+------------------------------
+
+If enabled, 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'.  This can be overridden by
+explicitly '--bindir=DIR' or '--libdir=DIR'.  In any case, the values
+for 'bindir' and 'libdir' are automatically propagated to all
+subdirectories.
+
+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).
+
+7.1.10 '--enable-silent-rules'
+------------------------------
+
+Enable the use of less verbose build rules.  When using GNU 'make' (or
+another '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.
+
+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 even fail.
+
+7.1.12 '--without-x'
+--------------------
+
+Disable all programs using the X Window System.
+
+7.2 Program-specific configure options
+======================================
+
+Here are (some of) the program-specific 'configure' options.
+
+7.2.1 '--enable-PROG', '--disable-PROG'
+---------------------------------------
+
+Do or do not build and install the program(s) of the module 'PROG'.
+
+7.2.2 '--disable-all-pkgs'
+--------------------------
+
+Do not build any program modules by default--only those explicitly
+enabled.  Without this option, all modules are built except those that
+are explicitly disabled or specify 'disable' in their 'ac/withenable.ac'
+fragment.
+
+7.2.3 Configure options for 'texk/web2c'
+----------------------------------------
+
+'--with-banner-add=STR'
+Add 'STR' to the default version string ('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-like
+engines, 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-omfonts'
+Build the WEB versions of the Omega font utilities 'ofm2opl', 'opl2ofm',
+'ovf2ovp', and 'ovp2ovf' instead of the C version 'omfonts'.  The WEB
+and C versions should be roughly equivalent.
+
+'--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 core 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 other window support for Metafont (EPSF output,
+'mftalk', old 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 again defined in
+'texk/web2c/ac/web2c.ac'.
+
+7.2.4 Configure options for 'texk/bibtex-x'
+-------------------------------------------
+
+The former programs 'bibtex8' and 'bibtexu' have been merged into the
+module 'bibtex-x' (extended BibTeX).
+
+'--disable-bibtex8'
+Do not build the 'bibtex8' program.
+
+   -disable-bibtexu '--disable-bibtexu'
+Do not build the 'bibtexu' program (building 'bibtexu' requires 'ICU'
+libraries).
+
+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'.
+
+'--disable-dvipdfmx'
+Do not build the 'dvipdfmx' program.
+
+'--disable-xdvipdfmx'
+Do not build the 'xdvipdfmx' program (building 'xdvipdfmx' requires the
+'freetype' library).
+
+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, or otherwise disable support for
+PostScript specials.
+
+'--without-libgs'
+Build 'dvisvgm' without PostScript support at all.  Because the dynamic
+loading just mention 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.
+
+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'.
+
+7.2.8 Configure options for 'texk/xdvik'
+----------------------------------------
+
+'--with-gs=FILENAME'
+Hardwire the location of Ghostscript ('gs').
+
+'--with-xdvi-x-toolkit=KIT'
+Use toolkit 'KIT' for 'xdvik', one of: 'motif xaw xaw3d neXtaw'.  The
+default is 'motif' if available, else 'xaw'.
+
+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
+for a non-native one) indicates that 'xindy' will use the installed
+version of 'clisp' (which must be identical to the one used to build
+'xindy').
+
+'--with-recode'
+Use 'recode' instead of 'iconv' to build the 'xindy' rules and
+documentation, required for some systems where 'iconv' is missing or
+broken.
+
+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 (if any) that LIB depends on.
+
+   For many libraries '--with-LIB-includes=DIR' and
+'--with-LIB-libdir=DIR' to 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.
+
+7.3.1 Configure options for 'kpathsea'
+--------------------------------------
+
+'--enable-CMD-default', '--disable-CMD-default'
+Determine the compile time default whether or not to run CMD, 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.
+
+7.3.2 Configure options for system 'poppler'
+--------------------------------------------
+
+Building LuaTeX and XeTeX requires 'poppler', either from the TL tree or
+system headers and library.  Building pdfTeX requires either 'xpdf' from
+the TeX Live tree or system 'poppler' headers and library.
+
+'--with-system-poppler'
+Use a system version (0.18 or newer) of 'poppler' for LuaTeX and XeTeX,
+and use 'pkg-config' to obtain the required flags.
+
+'--with-system-xpdf'
+Use a system version (0.12 or better) of 'poppler' (and 'pkg-config')
+for pdfTeX instead of 'xpdf' from the TL tree.  *Note
+'--disable-largefile'::.
+
+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: (GNU 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,
+     or many other libraries.
+
+'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.
+
+'TL_PLATFORM'
+     The utility program 'biber' consists of many Perl modules bundled
+     into an executable by the 'Par::Packer' mechanism.  Therefore it is
+     not feasible to build 'biber' as part of TL.
+
+     However, in order for 'make install' to create all executables in
+     'bindir', the 'biber' module in TL contains pre-made binaries (by
+     'biber' contributors, released on the original 'biber' site) for
+     the platforms for which they are available.  TL merely checks if an
+     executable is present for the current platform, and if so, installs
+     it.
+
+     The complication is hidden in the phrase "current platform".  TL
+     has its own ideas about platform names, and the mapping from the
+     canonical system name determined by 'config.guess' or 'config.sub'
+     to the TL platform name is not trivial.  So, a value given for
+     'TL_PLATFORM' is used as the TL platform name.  Otherwise, the
+     build uses copies of the Perl modules 'TeXLive/TLUtils.pm' and
+     'TeXLive/TLConfig.pm', to avoid duplicating the platform-detection
+     logic.
+