path: root/Build/source/README.config

Copyright (C) 2009 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 2009 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 dialog, pdfopen, etc.) as well as
library packages, i.e., subdirectories texk/kpathsea/ 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.

Note, however, that 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; thus, invoking configure via ./Build yields different results.

Options explicitly specified on the command will never be modified.


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

1.1. --disable-native-texlive-build
-----------------------------------
If enabled (by 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'.

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

A related option '--enable-texlive-build' is automatically passed to all
subdirectories (and can not be disabled).  Programs that could also be built
independent from the TL tree (such as utils/xindy/ or texk/dvipng/) 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 libstc++,
somewhat improving portability.

1.4. --enable-shared
---------------------
Build a shared Kpathsea library (not allowed for a TeX Live native build).

1.5. --disable-largefile
------------------------
Omit support for large files (>=2GB).

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

1.7. --enable-compiler-warnings=[no|min|yes|max]
------------------------------------------------
Enable various degrees of compiler warnings for C and C++.  The default is
'yes' in maintainer-mode and 'min' otherwise.  This options defines
additional CFLAGS or CXXFLAGS, but these flags are not yet used by all
library and program packages (actually only by a few of them).  Using these
compiler warnings should help to resolve portability problems.

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

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

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-tex-banner=STR
Specify the version string STR appended to banner lines, replacing the
default `Web2C YYYY'; the string STR must contain the current Web2C
version, that is, the YYYY.

The Build script for a TL native build currently specifies
`--with-tex-banner="TeX Live 2009"', whereas a distro build should alter
this to, e.g., `--with-tex-banner="TeX Live 2009/Debian"'.

2.3.1. --with-editor=CMD
Specify the command CMD to invoke from the `e' option, replacing the default
`vi +%d %s'.

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

2.3.4. --disable-dump-share
Make the fmt/base/mem 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-mf, --disable-mp
Do or do not build the various TeX, METAFONT, and MetaPost engines.

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

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

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

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

2.3.11. --disable-omfonts
Build the Web2C versions of the omega font utilies (ofm2opl, opl2ofm,
ovf2ovp, and ovp2ovf) instead of the C version, omfonts.  The web
versions are needed in Japanese environments; the C versions fix some
(unknown) bugs.  We hope the situation will be resolved.

2.4. Configure options for texk/xdvik/
--------------------------------------
2.4.1. --with-gs=PATH
Hardwire the location of GhostScript (gs).

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


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

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

For many libraries there are in addition '--with-LIB-includes=DIR' and
'--with-LIB-libdir=DIR' to indicate that the library is installed in an
unusual location.

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

3.2. Configure options for libfontconfig
----------------------------------------
Building XeTeX and xdvipdfmx on non-Mac systems requires libfontconfig.

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 libfreetype
---------------------------------------------
The flags for a system freetype library are determined via freetype-config.

3.4. Configure options for libpoppler
-------------------------------------
3.4.1. --with-system-xpdf
Use libpoppler instead of xpdf (and pkg-config to obtain the required flags).


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. PKG_CONFIG=/path/to/pkg-config
-----------------------------------
For fontconfig and system xpdf (poppler) libraries.

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

4.4. PERL=/path/to/perl
-------------------------
To build xindy rules and docs.

4.5. LATEX=/path/to/latex
-------------------------
To build xindy rules.

4.6. PDFLATEX=/path/to/pdflatex
-------------------------------
To build xindy docs.

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


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