fix getsup (HH)

[luatex.git] / source / README.5configure

(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
at the top-level.

   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' or 'luatex' must, however, be <2GB when using
'poppler' version 0.22 or before (even on 64-bit systems with LFS).

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 and '--bindir=DIR' or '--libdir=DIR' are not specified,
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'.  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.  This is useful when one wants to work on only a single
program, which is specified with an additional '--enable' option, e.g.,
'--enable-dvipdfm-x'.  It's still simplest to check out and configure
the whole source tree, but at least only the program you are interested
in, and its dependencies, are built.  The 'configure' will generally
take less than a minute with everything disabled.  (It is a good idea to
run 'make check' after doing this, and after making any changes, to
ensure that whatever tests have been written still pass.)

   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-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'.

'--disable-synctex'
Do not build the 'SyncTeX' library and tool.

7.2.4 Configure options for 'texk/bibtex-x'
-------------------------------------------

The programs 'bibtex8' and 'bibtexu' have been merged into the module
'bibtex-x' (extended BibTeX).

'--disable-bibtex8'
Do not build the 'bibtex8' program.

'--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' at the source level.  Two separate binaries are still
created by default.  In addition, 'dvipdfm' is created as a symlink to
'dvipdfmx', with backward-compatible (very slightly different) behavior.

'--disable-dvipdfmx'
Do not build the 'dvipdfmx' program with the 'dvipdfm' symlink.

'--disable-xdvipdfmx'
Do not build the 'xdvipdfmx' program.

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 mentioned 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'.

'--enable-xi2-scrolling'
Use XInput 2.1 "smooth scrolling" if available.  (default: yes, except
for a native TL build).

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').

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' can 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 (or LuaJITTeX) 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 (or
LuaJITTeX) 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.