From ea58320b10f549a61236be100fc97925aea6b489 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 21 Apr 2014 22:45:37 +0000 Subject: rename and update README* files, now generated from tlbuild.texi git-svn-id: svn://tug.org/texlive/trunk@33605 c570f23f-e606-0410-a88d-b1316a301751 --- Build/source/README.5configure | 443 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 443 insertions(+) create mode 100644 Build/source/README.5configure (limited to 'Build/source/README.5configure') 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. + -- cgit v1.2.3