path: root/Build/source/README.config

Copyright (C) 2009-2013 Peter Breitenlohner <tex-live@tug.org>
You may freely use, modify and/or distribute this file.

	Configure options for the TeX Live (TL) build system
	====================================================

The TL build system contains a collection of program packages, i.e.,
subdirectories texk/PROG/ (where `PROG' is web2c, afm2pl, bibtex8, etc.) and
utils/UTIL/ (where `UTIL' is biber, xpdfopen, etc.) as well as library
packages, i.e., subdirectories texk/kpathsea/, texk/ptexenc/, and libs/LIB/
(where `LIB' is zlib, libpng, t1lib, etc.) for most of the libraries
required by the program packages.  Correspondingly there are plenty of
configure options, most of which are described below.

See 'configure --help' (at the top-level) for an exhaustive list of all
global options and a few important package specific ones or run, e.g.,
'texk/lcdf-typetools/configure --help' to also see lcdf-typetools
specific options not shown at the top level.

The ./Build script used to make the binaries shipped with TeX Live
invokes the top-level configure with a few additional options.  Any
defaults discussed below are those for the base configure script;
invoking configure via ./Build may yield different results.

Defaults for most options are set at the top-level and then propagated
explicitly to all subdirectories.

Options specified on the command line will never be modified.


1. Global configure options
===========================

1.1. --disable-native-texlive-build
-----------------------------------
If enabled (as default), build for a TeX Live binary distribution as
shipped by the user groups; this implies '--enable-multiplatform' and
'--enable-cxx-runtime-hack' unless they are explicitly disabled and
enforces '--disable-shared'.  This also requires GNU make.

If building TL for a GNU/Linux or other distribution, this would be
disabled and system versions of most libraries would be used (see below).
This may require GNU make, but will also try without it.

The default installation directories are quite different when this option is
enabled or disabled.

A related option '--enable-texlive-build' is automatically passed to all
subdirectories (and can not be disabled).  Programs that could also be built
independently from the TL tree (such as utils/xindy/ or texk/dvipng/) can
use this option, e.g., to choose TL specific installation directories.

1.2. --enable-multiplatform
---------------------------
If enabled, install executables and libraries in platform dependent
subdirectories of EPREFIX/bin and EPREFIX/lib (unless '--bindir=DIR' or
'--libdir=DIR' is specified), where EPREFIX is the exec-prefix.  This
option automatically propagates the values for bindir and libdir to all
subdirectories to be configured, and thus need not be used explicitly in
any program or library package.

1.3. --enable-cxx-runtime-hack
------------------------------
If enabled and when using g++, try to statically link with libstdc++,
somewhat improving portability.

1.4. --enable-libtool-hack
--------------------------
If enabled prevents libtool from linking explicitly with dependency_libs.
At present this is enabled by default for all systems.

1.5. --enable-shared
---------------------
Build shared Kpathsea and Ptexenc libraries (not allowed for a native TeX
Live build).

1.6. --disable-largefile
------------------------
Omit large file support (LFS), needed for files >=2GB on most 32-bit Unix
systems.  The size of DVI and GF files must always be <2GB.  With LFS there
should be no limit on the size of PDF files created by pdfTeX or PS files
created by dvips.  The size of PDF images included by pdfTeX must, however,
be <4GB when using xpdf and <2GB when using poppler (even on 64-bit systems
with LFS).

1.7. --without-x
----------------
Do not use the X Window System.

1.8. --enable-compiler-warnings=[no|min|yes|max|all]
----------------------------------------------------
Enable various degrees of compiler warnings for (Objective) C and C++.  The
default is 'yes' in maintainer-mode and 'min' otherwise.  This option
defines WARNING_[OBJ]C[XX]FLAGS but these flags are not yet used by all
library and program packages.  Using them should help to resolve portability
problems.

At the moment these warning flags are only defined for the GNU compilers
but flags for other compilers could be added when needed.

1.9. --disable-missing
----------------------
Immediately terminate the build process if a requested program or feature
must be disabled, e.g., due to missing libraries.

1.10. --enable-silent-rules
---------------------------
Enable the use of less verbose build rules.  When using GNU make or another
'make' implementation that supports nested variable expansions you can
always specify 'V=1' on the make command line to get more respectively 'V=0'
to get less verbosity.

1.11. --without-ln-s
--------------------
Required to build for a Unix-like system without working 'ln -s'.  But note
that 'make install' will not create anything useful and might even fail.

2. Configure options for program packages
=========================================

2.1. --disable-PROG and --disable-UTIL
--------------------------------------
Do not build and install the program(s) of the package `PROG' or `UTIL'.

2.2. --disable-all-pkgs
-----------------------
Do not build any program packages, except those explicitly enabled.
Without this option, all packages are built except those explicitly
disabled and except for utils/xindy/ (which is disabled by default due to
its requirement for clisp et al.).

2.3. Configure options for texk/web2c/
--------------------------------------
2.3.1. --with-banner-add=STR
Add STR to the default version string ('TeX Live YEAR' or 'Web2C YEAR')
appended to banner lines.  The Build script for a native TL build doesn't
use this option, but distro builds should specify this as, e.g.,
'/SomeDistro'.

2.3.2. --with-editor=CMD
Specify the command CMD to invoke from the `e' option, replacing the default
`vi +%d '%s'' for Unix or `texworks --position=%d "%s"' for Windows.

2.3.3. --enable-auto-core
This option causes TeX & MF to produce a core dump when a particular
hacky filename is encountered.

2.3.4. --disable-dump-share
Make the fmt/base dump files architecture dependent (somewhat faster on
little-endian architectures).

2.3.5. --disable-ipc
If enabled (by default) allow TeX's '--ipc' option.

2.3.6. --disable-tex, --enable-etex, --disable-aleph, --disable-pdftex,
       --disable-luatex, --disable-xetex, --disable-ptex, --disable-eptex,
       --disable-uptex, --disable-euptex, --disable-mf, --disable-mp
Do or do not build the various TeX, METAFONT, and MetaPost engines
(defaults for the TeX engines are defined in texk/web2c/ac/web2c.ac).

2.3.7. --enable-tex-synctex, --disable-etex-synctex,
       --disable-ptex-synctex, --disable-eptex-synctex
       --disable-uptex-synctex, --disable-euptex-synctex
       --disable-pdftex-synctex, --disable-xetex-synctex
Build the various TeX engines with or without SyncTeX support (ignored for a
native TeX Live build, defaults are defined in texk/web2c/ac/web2c.ac).

2.3.8. --with-mf-x-toolkit
Use the X toolkit (libXt) for METAFONT (default is yes).

2.3.9. --enable-*win
Include various types of other window support for METAFONT.

2.3.10. --disable-mf-nowin
Do not build a separate non-graphically-capable METAFONT.

2.3.11. --disable-web-progs
Do not build the WEB programs bibtex ... weave, e.g., if you just
want to rebuild some engines.

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

2.4. Configure options for texk/bibtex-x/
-----------------------------------------
2.4.1. --disable-bibtex8
Do not build the bibtex8 program.

2.4.2. --disable-bibtexu
Do not build the bibtexu program.

The former packages bibtex8 and bibtexu have been merged into bibtex-x
(extended BibTeX).  Building bibtexu requires icu libraries.

2.5. Configure options for texk/dvisvgm/
----------------------------------------
2.5.1. --with-system-libgs
Build dvisvgm with installed gs headers and library (not allowed for a
native TeX Live build).  The default is to load the gs library at runtime,
or otherwise disable support for PostScript specials.

2.5.2. --with-libgs-includes=DIR, --with-libgs-libdir=DIR
Non standard search locations for libgs.

2.6. Configure options for texk/xdvik/
--------------------------------------
2.6.1. --with-gs=PATH
Hardwire the location of Ghostscript (gs).

2.6.2. --with-xdvi-x-toolkit=KIT
Use toolkit KIT (motif/xaw/xaw3d/neXtaw) for xdvi, default: Motif if
available, else Xaw.

2.7. Configure options for utils/xindy/
---------------------------------------
2.7.1. --enable-xindy-rules
Build and install xindy rules (default: yes, except for a native TeX Live
build).

2.7.2. --enable-xindy-docs
Build and install xindy documentation (default: yes, except for a native TeX
Live build).

2.7.3. --with-clisp-runtime=PATH
Specifies the full PATH of the CLISP runtime (lisp.run or lisp.exe) to be
installed.  When specified as `default' (the default for a native TeX Live
build) the path is determined by the CLISP executable; the value `system'
(not allowed for a native TeX Live build, but the default for a non-native
one) indicates that xindy will use the installed version of clisp (that must
be identical to the one used to build xindy).

2.7.4. --with-recode
Use `recode' instead of `iconv' to build the xindy rules and documentation,
required for some systems where iconv is missing or broken.

3. Configure options for libraries
==================================

3.1. --with-system-LIB
----------------------
Use an installed (system) version of the library `LIB'; this option exists
for most libraries (not allowed for a native TeX Live build).

For many libraries there are in addition '--with-LIB-includes=DIR' and
'--with-LIB-libdir=DIR' to indicate non standard search locations.

The top-level configure script performs a consistency check for all required
system libraries and bails out early if some of these tests fail.

3.2. Configure options for fontconfig
-------------------------------------
Building XeTeX and xdvipdfmx on non-Mac systems requires fontconfig headers
and library.

3.2.1. --with-fontconfig-includes=DIR, --with-fontconfig-libdir=DIR
If one or both of these options are given, the flags are derived from them. 
Otherwise, the flags are determined via pkg-config (if present).

3.3. Configure options for system freetype2 (libfreetype)
---------------------------------------------------------
The flags for a system freetype2 library are determined via freetype-config.

3.4. Configure options for xpdf and poppler
-------------------------------------------
Building LuaTeX and XeTeX requires poppler either from the TL tree or
installed (system) headers and library; pdfTeX requires either xpdf from the
TL tree or installed poppler headers and library.

3.4.1. --with-system-poppler
Use an installed (system) version >=0.12 of poppler for LuaTeX and XeTeX
(and pkg-config to obtain the required flags).

3.4.2. --with-system-xpdf
Use an installed (system) version >=0.12 of poppler instead of xpdf for
pdfTeX (and pkg-config to obtain the required flags).

See information at --disable-largefile for a minor deficiency resulting
from using poppler instead of TL's xpdf library.

4. Interesting and/or important VAR=value configure arguments
=============================================================
Used instead of searching for programs in PATH.

4.1. FT2_CONFIG=/path/to/freetype-config
----------------------------------------
For system freetype2 library.

4.2. ICU_CONFIG=/path/to/icu-config
-----------------------------------
For system icu libraries.

4.3. PKG_CONFIG=/path/to/pkg-config
-----------------------------------
For most system libraries.

You need a pkg-config executable when compiling the cairo included in
TL, but it doesn't need to do anything.  A symlink to, e.g., /bin/false
is sufficient.

4.4. CLISP=/path/to/clisp
-------------------------
For xindy.

4.5. PERL=/path/to/perl, LATEX=/path/to/latex, PDFLATEX=/path/to/pdflatex
-------------------------------------------------------------------------
To build xindy docs.

4.6. PERL=/path/to/perl or TL_PLATFORM=TeX_Live_platform_name
-------------------------------------------------------------
Set the TeX Live platform name for biber.

4.7. KPSEWHICH=/path/to/kpsewhich
---------------------------------
For `make check'.

4.8. MAKE=/path/to/GNU_make, SED=/path/to/GNU_sed
-------------------------------------------------
For the top-level.


Happy building.  Please use the tlbuild list for questions or
discussion: http://lists.tug.org/tlbuild.