summaryrefslogtreecommitdiff
path: root/Build/source/texk/kpathsea/doc/install.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/kpathsea/doc/install.texi')
-rw-r--r--Build/source/texk/kpathsea/doc/install.texi1239
1 files changed, 1239 insertions, 0 deletions
diff --git a/Build/source/texk/kpathsea/doc/install.texi b/Build/source/texk/kpathsea/doc/install.texi
new file mode 100644
index 00000000000..67e82a8acd1
--- /dev/null
+++ b/Build/source/texk/kpathsea/doc/install.texi
@@ -0,0 +1,1239 @@
+@ifclear version
+@defcodeindex cm
+@defcodeindex fl
+@defcodeindex op
+@end ifclear
+
+@node Installation
+@chapter Installation
+
+@cindex installation
+@cindex configuration
+@cindex compilation
+
+@ifset version
+(A copy of this chapter is in the distribution file @file{kpathsea/INSTALL}.)
+@end ifset
+
+The procedure for Kpathsea (and Web2c, etc.) configuration and
+installation follows. If you encounter trouble, see @ref{Common
+problems}, a copy of which is in the file @file{kpathsea/BUGS}.
+
+@menu
+* Simple installation:: If you just want to do it.
+* Custom installation:: If you want to change things around.
+* Security:: Who can write what files, etc.
+* TeX directory structure:: Managing the horde of TeX input files.
+* unixtex.ftp:: Getting software via FTP, on CD-ROM, or on tape.
+* Reporting bugs:: Where and how to report bugs.
+@end menu
+
+
+@node Simple installation
+@section Simple installation
+
+@cindex simple installation
+@cindex installation, simple
+
+@cindex precompiled executables, instead of installation
+@cindex installation, getting executables instead of
+Installing @TeX{} and friends for the first time can be a daunting
+experience. Thus, you may prefer to skip this whole thing and just get
+precompiled executables: see @ref{unixtex.ftp}.
+
+This section explains what to do if you wish to take the defaults for
+everything, and generally to install in the simplest possible way. Most
+steps here refer to corresponding subsection in the next section which
+explains how to override defaults and generally gives more details.
+
+By default everything will be installed under @file{/usr/local} and the
+following discussion assumes this. However, if you already have @TeX{}
+installed, its location is used to derive the directory under which
+everything is to be installed.
+
+@enumerate
+@item
+Be sure you have enough disk space: approximately 8 megabytes for the
+compressed archives, 15MB for sources, 50MB for compilation, 40MB for
+the (initial) installed system (including library files). @xref{Disk
+space}.
+
+@item
+Retrieve these distribution archives:
+@table @url
+@item ftp://ftp.tug.org/tex/texk.tar.gz
+These are the sources, which you will be compiling.
+
+@item ftp://ftp.tug.org/tex/texklib.tar.gz
+This is a basic set of input files. You should unpack it in the
+directory @file{/usr/local/share}; doing so will create a @file{texmf}
+subdirectory there.
+@end table
+
+These archives are mirrored on the CTAN hosts, in the
+@file{systems/web2c} directory.
+
+@noindent @xref{Kpathsea application distributions}.
+
+@item
+When using the default search paths, there is no need to edit any
+distribution files. @xref{Changing search paths}.
+
+@item
+At the top level of the distribution, run @samp{sh configure}. (If you
+have the GNU Bash shell installed, run @samp{bash configure}.)
+@xref{Running configure}.
+
+@item
+@samp{make}. @xref{Running make}. If you are using a BSD 4.4 system
+such as FreeBSD or NetBSD, you may have to use GNU make (often installed
+in @file{/usr/local/bin}), not the BSD make.
+
+@item
+@samp{make install}. @xref{Installing files}.
+
+@item
+@samp{make distclean}. @xref{Cleaning up}.
+
+@item
+Set up a cron job to rebuild the filename database that makes searching
+faster. This line will rebuild it every midnight:
+@example
+0 0 * * * cd /usr/local/share/texmf && @var{/bindir}/mktexlsr
+@end example
+@xref{Filename database generation}, and @ref{Filename database}.
+
+@item
+@cindex printer configuration files
+@cindex PostScript fonts, additional
+@cindex color printers, configuring
+If you're installing Dvips, you also need to set up configuration files
+for your printers and make any additional PostScript fonts available.
+@xref{Installation,,, dvips, Dvips}. If you have any color printers,
+see @ref{Color device configuration,,, dvips, Dvips}.
+
+@item
+The first time you run a DVI driver, a bunch of PK fonts will be built
+by Metafont via @code{mktexpk} (and added to the filename database).
+This will take some time. Don't be alarmed; they will created only this
+first time (unless something is wrong with your path definitions).
+
+By default, @code{mktexpk} will create these fonts in a hierarchy
+under @file{/var/tmp/texfonts}; it simply assumes that @file{/var/tmp}
+exists and is globally writable. If you need a different arrangement,
+see @ref{mktex configuration}.
+
+@xref{mktex scripts}.
+
+@item
+@cindex fonts, being created
+@pindex mktexpk @r{, initial runs}
+@cindex tests, simple
+For some simple tests, try @samp{tex story \\bye} and @samp{latex
+sample2e}. Then run @file{xdvi story} or @file{dvips sample2e} on the
+resulting DVI files to preview/print the documents. @xref{Installation
+testing}.
+@end enumerate
+
+
+@node Custom installation
+@section Custom installation
+
+@cindex custom installation
+@cindex installation, customized
+
+Most sites need to modify the default installation procedure in some
+way, perhaps merely changing the prefix from @samp{/usr/local}, perhaps
+adding extra compiler or loader options to work around @code{configure}
+bugs. This section explains how to override default choices. For
+additional distribution-specific information:
+@itemize @bullet
+@item @file{dviljk/INSTALL}.
+@item @xref{Installation,,,dvips,Dvips}.
+@item @xref{Installation,,,web2c,Web2c}.
+@item @file{xdvik/INSTALL}.
+@end itemize
+
+@cindex non-Unix operating systems
+@cindex Amiga support
+@cindex DOS support
+@cindex OS/2 support
+@cindex VMS support
+These instructions are for Unix systems. Other operating-system
+specific distributions have their own instructions. The code base
+itself supports Amiga, DOS, OS/2, and VMS.
+
+
+Following are the same steps as in the previous section (which describes
+the simplest installation), but with much more detail.
+
+@menu
+* Disk space::
+* Kpathsea application distributions::
+* Changing search paths::
+* Running configure::
+* Running make::
+* Installing files::
+* Cleaning up::
+* Filename database generation::
+* mktex scripts::
+* Installation testing::
+@end menu
+
+
+@node Disk space
+@subsection Disk space
+
+@cindex disk space, needed
+@cindex total disk space
+@cindex size of distribution archives
+Here is a table showing the disk space needed for each distribution
+(described in the next section). The `(totals)' line reflects the
+@samp{texk} source distribution and @samp{texklib}; the individual
+distributions don't enter into it. Sizes are in megabytes. All numbers
+are approximate.
+
+@multitable {distribution} {.tar.gz} {unpacked} {compiled} {installed}
+@item Distribution @tab .tar.gz @tab Unpacked @tab Compiled @tab Installed
+@item dviljk @tab .9 @tab 3.8 @tab
+@item dvipsk @tab .9 @tab 3.2 @tab
+@item xdvik @tab .7 @tab 2.5 @tab
+@item web2c @tab 1.3 @tab 5.0 @tab
+@item web @tab 1.9 @tab 6.5 @tab - @tab -
+@item texk @tab 7.5 @tab 32.1 @tab 95.3 @tab 33.5
+@item texklib @tab 6.3 @tab 15.0 @tab - @tab 15.0
+@item (totals) @tab 14.6 @tab 47.1 @tab 95.3 @tab 48.5
+@end multitable
+
+
+@node Kpathsea application distributions
+@subsection Kpathsea application distributions
+
+@cindex distributions, compiling simultaneously
+@cindex version number, of Kpathsea
+@cindex Kpathsea version number
+
+@cindex distributions, not compiling
+@cindex NeXT, lacking X11
+@cindex X11, lacking on NeXT
+The archive @url{ftp://ftp.tug.org/tex/texk.tar.gz} contains all of the
+Kpathsea applications I maintain, and the library itself. For example,
+since NeXT does not generally support X11, you'd probably want to skip
+@samp{xdvik} (or simply remove it after unpacking @file{texk.tar.gz}.
+If you are not interested in all of them, you can also retrieve them
+separately:
+
+@cindex DVI drivers
+@table @file
+@item dviljk.tar.gz
+@cindex PCL driver
+@cindex LaserJet drive
+DVI to PCL, for LaserJet printers.
+
+@item dvipsk.tar.gz
+@cindex PDF generation
+@cindex PostScript driver
+DVI to PostScript, for previewers, printers, or PDF generation.
+
+@item web2c.tar.gz
+The software needed to compile @TeX{} and friends.
+
+@item web.tar.gz
+The original WEB source files, also used in compilation.
+
+@item xdvik.tar.gz
+@cindex X11 previewer
+DVI previewing under the X window system.
+
+@end table
+
+@cindex Babel
+@cindex non-English typesetting
+If you want to use the Babel La@TeX{} package for support of non-English
+typesetting, you may need to retrieve additional files. See the file
+@file{install.txt} in the Babel distribution.
+
+
+@node Changing search paths
+@subsection Changing search paths
+
+@cindex search paths, changing default
+@cindex paths, changing default
+@flindex texmf.in@r{, editing}
+If the search paths for your installation differ from the standard
+@TeX{} directory structure (@pxref{Top,, Introduction, tds, A Directory
+Structure for @TeX{} files}), edit the file @file{kpathsea/texmf.in}
+as desired, before running @code{configure}. For example, if you have
+all your fonts or macros in one big directory.
+
+You may also wish to edit the file @file{mktex.cnf}, either before or
+after installation, to control various aspects of @code{mktexpk} and
+friends. @xref{mktex configuration}.
+
+You do not need to edit @file{texmf.in} to change the default
+top-level or other installation @emph{directories} (only the paths).
+You can and should do that when you run @code{configure} (next step).
+
+You also do not need to edit @file{texmf.in} if you are willing to
+rely on @file{texmf.cnf} at runtime to define the paths, and let the
+compile-time default paths be incorrect. Usually there is no harm in
+doing this.
+
+The section below explains default generation in more detail.
+
+@menu
+* Default path features::
+* Default path generation::
+@end menu
+
+
+@node Default path features
+@subsubsection Default path features
+
+@cindex default path features
+@cindex features, of default paths
+
+The purpose of having all the different files described in the section
+above is to avoid having the same information in more than one place. If
+you change the installation directories or top-level prefix at
+@code{configure}-time, those changes will propagate through the whole
+sequence. And if you change the default paths in @file{texmf.in},
+those changes are propagated to the compile-time defaults.
+
+The Make definitions are all repeated in several @t{Makefile}'s; but
+changing the top-level @file{Makefile} should suffice, as it passes down
+all the variable definitions, thus overriding the submakes. (The
+definitions are repeated so you can run Make in the subdirectories, if
+you should have occasion to.)
+
+@vindex MAKETEX_MODE
+@cindex paths, device name included in
+By default, the bitmap font paths end with @samp{/$MAKETEX_MODE}, thus
+including the device name (usually a Metafont mode name such as
+@samp{ljfour}). This distinguishes two different devices with the same
+resolution---a write/white from a write/black 300@dmn{dpi} printer, for
+example.
+
+@findex kpse_init_prog@r{, and @code{MAKETEX_MODE}}
+@flindex proginit.c
+However, since most sites don't have this complication, Kpathsea
+(specifically, the @code{kpse_init_prog} function in
+@file{kpathsea/proginit.c}) has a special case: if the mode has not been
+explicitly set by the user (or in a configuration file), it sets
+@code{MAKETEX_MODE} to @code{/}. This makes the default PK path, for
+example, expand into @code{@dots{}/pk//}, so fonts will be found even if
+there is no subdirectory for the mode (if you arranged things that way
+because your site has only one printer, for example) or if the program
+is mode-independent (e.g., @code{pktype}).
+
+To make the paths independent of the mode, simply edit
+@file{texmf.in} before installation, or the installed
+@file{texmf.cnf}, and remove the @samp{$MAKETEX_MODE}.
+
+@xref{mktex script arguments}, for how this interacts with @code{mktexpk}.
+
+@flindex HIER
+@flindex kpathsea/HIER
+@xref{TeX directory structure,, @TeX{} directory structure}, for a
+description of the default arrangement of the input files that comprise
+the @TeX{} system. The file @file{kpathsea/HIER} is a copy of that
+section.
+
+
+@node Default path generation
+@subsubsection Default path generation
+
+@cindex default paths, changing
+@cindex paths, changing default
+@cindex installation, changing default directories
+@cindex directories, changing default installation
+
+This section describes how the default paths are constructed.
+
+You may wish to ignore the whole mess and simply edit @file{texmf.cnf}
+after it is installed, perhaps even copying it into place beforehand so
+you can complete the installation, if it seems necessary.
+
+@cindex default paths, how they're made
+To summarize the chain of events that go into defining the default paths:
+
+@enumerate
+@item
+@samp{configure} creates a @file{Makefile} from each @file{Makefile.in}.
+
+@item
+@flindex texmf.sed
+When Make runs in the @file{kpathsea} directory, it creates a file
+@file{texmf.sed} that substitutes the Make value of @code{$(var)} for a
+string @code{@@var@@}. The variables in question are the one that
+define the installation directories.
+
+@item
+@flindex texmf.in
+@flindex texmf.cnf@r{, generated}
+@file{texmf.sed} (together with a little extra magic---see
+@file{kpathsea/Makefile}) is applied to @file{texmf.in} to generate
+@file{texmf.cnf}. This is the file that will eventually be installed
+and used.
+
+@item
+@flindex paths.h
+The definitions in @file{texmf.cnf} are recast as C @code{#define}'s in
+@file{paths.h}. These values will be the compile-time defaults; they
+are not used at runtime unless no @file{texmf.cnf} file can be found.
+
+(That's a lie: the compile-time defaults are what any extra @t{:}'s in
+@file{texmf.cnf} expand into; but the paths as distributed have no extra
+@t{:}'s, and there's no particular reason for them to.)
+@end enumerate
+
+
+@node Running configure
+@subsection Running @code{configure}
+
+@flindex configure@r{, running}
+@flindex c-auto.in
+@flindex Makefile.in
+@findex ac_include@r{, Autoconf extension}
+@cindex @@@var{var}@@ substitutions
+@cindex system dependencies
+Run @code{sh configure @var{options}} (in the top-level directory, the
+one containing @file{kpathsea/}), possibly using a shell other than
+@code{sh} (@pxref{configure shells}).
+
+@code{configure} adapts the source distribution to the present system
+via @code{#define}'s in @file{*/c-auto.h}, which are created from the
+corresponding @file{c-auto.in}. It also creates a @file{Makefile} from
+the corresponding @file{Makefile.in}, doing @samp{@@@var{var}@@} and
+@samp{ac_include} substitutions).
+
+@flindex README.CONFIGURE
+@flindex kpathsea/README.CONFIGURE
+@code{configure} is the best place to control the configuration,
+compilation, and installed location of the software, either via
+command-line options, or by setting environment variables before
+invoking it. For example, you can disable @code{mktexpk} by default
+with the option @samp{--disable-mktexpk}.
+@xref{configure options}.
+
+@menu
+* configure shells::
+* configure options::
+* configure environment::
+* configure scenarios::
+* Shared library::
+@end menu
+
+
+@node configure shells
+@subsubsection @code{configure} shells
+
+@cindex shells and @code{configure}
+@pindex bash@r{, recommended for running @code{configure}}
+
+Considerable effort has gone into trying to ensure that the
+@code{configure} scripts can be run by most Bourne shell variants.
+If @code{sh} runs into trouble, your best bet is to use Bash, the GNU
+Bourne-again shell (@pxref{Top,,,bash,Bash Reference Manual}).
+
+Bourne shell variants for which problems have been reported in the past
+are:
+@table @code
+@item ksh
+@pindex ksh@r{, losing with @code{configure}}
+@pindex bsh@r{, ok with @code{configure}}
+@cindex Korn shell@r{, losing with @code{configure}}
+@cindex AIX shells and @code{configure}
+Old versions of the Korn shell may fail to handle the scripts. The Korn
+shell may be installed as @file{/bin/sh} on AIX, in which case
+@file{/bin/bsh} may serve instead.
+
+@item ash
+@pindex ash@r{, losing with @code{configure}}
+@cindex NetBSD shells and @code{configure}
+@cindex FreeBSD shells and @code{configure}
+@cindex Linux shells and @code{configure}
+Old versions of ash are unable to handle the scripts. Ash is sometimes
+installed as @file{/bin/sh} on NetBSD, FreeBSD, and Linux systems.
+@file{/bin/bash} should be available for those systems, but might not be
+part of a default installation.
+
+@item @r{Ultrix} /bin/sh
+@cindex DEC shells and @code{configure}
+@cindex Ultrix shells and @code{configure}
+@pindex sh5@r{, ok with @code{configure}}
+@file{/bin/sh} under Ultrix is a DEC-grown shell that is notably
+deficient in many ways. @file{/bin/sh5} may be necessary.
+@end table
+
+
+@node configure options
+@subsubsection @code{configure} options
+
+@cindex @code{configure} options
+
+For a complete list of all @code{configure} options, run @samp{configure
+--help} or see @ref{Invoking configure,, Running @code{configure} scripts,
+autoconf, Autoconf}, (a copy is in the file @file{kpathsea/README.CONFIGURE}).
+The generic options are listed first in the @samp{--help} output, and
+the package-specific options come last. The environment variables
+@code{configure} pays attention to are listed below.
+
+Options particularly likely to be useful are @samp{--prefix},
+@samp{--datadir}, and the like; see @ref{configure scenarios}.
+
+@opindex --with @r{options}
+@opindex --enable @r{options}
+@cindex configuration of optional features
+@cindex options to @code{configure}
+This section gives pointers to descriptions of the @samp{--with} and
+@samp{--enable} options to @code{configure} that Kpathsea-using programs
+accept.
+
+@table @samp
+@item --without-mktexmf-default
+@itemx --without-mktexpk-default
+@itemx --without-mktextfm-default
+@itemx --with-mktextex-default
+Enable or disable the dynamic generation programs. @xref{mktex
+configuration}.
+
+@item --enable-shared
+@opindex --enable-shared
+Build Kpathsea as a shared library, and link against it. Also build the
+usual static library. @xref{Shared library}.
+
+@item --disable-static
+@opindex --disable-static
+Build only the shared library. Implies @samp{--enable-shared}.
+
+@item --enable-maintainer-mode
+@opindex --enable-maintainer-mode
+Enables make targets that are useful for the maintainer and likely to be
+a pain for anyone else; the makefiles created when this option is
+enabled may not work at all for you. You have been warned.
+@end table
+
+@node configure environment
+@subsubsection @code{configure} environment
+
+@code{configure} uses the value of the following environment variables in
+determining your system's characteristics, and substitutes for them in
+@t{Makefile}'s:
+
+@vtable @samp
+@item CC
+@pindex gcc@r{, compiling with}
+@pindex cc@r{, compiling with}
+The compiler to use: default is @code{gcc} if it's installed, otherwise
+@code{cc}.
+
+@item CFLAGS
+@cindex compiler options, specifying
+Options to give the compiler: default is @samp{-g -O2} for @code{gcc},
+@samp{-g} otherwise. @code{CFLAGS} comes after any other options. You
+may need to include @code{-w} here if your compilations commonly have
+useless warnings (e.g., @code{NULL redefined}), or @code{configure} may
+fail to detect the presence of header files (it takes the messages on
+standard error to mean the header file doesn't exist).
+
+@item CPPFLAGS
+@cindex configuration compiler options
+Options to pass to the compiler preprocessor; this matters most for
+configuration, not the actual source compilation. The @code{configure}
+script often does only preprocessing (e.g., to check for the existence
+of @t{#include} files), and @code{CFLAGS} is not used for this. You may
+need to set this to something like
+@samp{-I/usr/local/include/wwwhatever} if you have the libwww library
+installed for hyper-xdvik (see @file{xdvik/INSTALL}).
+
+@item DEFS
+@cindex preprocessor options
+Additional preprocessor options, but not used by @code{configure}.
+Provided for enabling or disabling program features, as documented in
+the various program-specific installation instructions. @code{DEFS}
+comes before any compiler options included by the distribution
+@file{Makefile}s or by @code{configure}.
+
+@item LDFLAGS
+@cindex loader options
+Additional options to give to the loader. @code{LDFLAGS} comes before
+any other linker options.
+
+@item LIBS
+@cindex libraries, specifying additional
+Additional libraries to link with.
+@end vtable
+
+
+@node configure scenarios
+@subsubsection @code{configure} scenarios
+
+Here are some common installation scenarios:
+
+@itemize @bullet
+@item
+Including X support in Metafont. This is disabled by default, since
+many sites have no use for it, and it's a leading cause of configuration
+problems.
+@example
+configure --with-x
+@end example
+
+@item
+@cindex @TeX{} hierarchy, one
+Putting the binaries, @TeX{} files, GNU info files, etc.@: into a single
+@TeX{} hierarchy, say @file{/here/texmf}, requires overriding defaults in
+@code{configure}:
+@example
+configure --prefix=/here/texmf --datadir=/here
+@end example
+
+@item
+@cindex multiple architectures, compiling on
+@cindex architectures, compiling multiple
+@cindex symbolic link trees, for multiple architectures
+@opindex --srcdir@r{, for building multiple architectures}
+@pindex lndir @r{for building symlink trees}
+You can compile on multiple architectures simultaneously either by
+building symbolic link trees with the @code{lndir} script from the X11
+distribution, or with the @samp{--srcdir} option:
+@example
+configure --srcdir=@var{srcdir}
+@end example
+
+@item
+@cindex multiple architectures, directories for
+If you are installing binaries for multiple architectures into a single
+hierarchy, you will probably want to override the default @file{bin} and
+@file{lib} directories, something like this:
+@example
+configure --prefix=@var{texmf} --datadir=@var{texmf} \
+ --bindir=@var{texmf}/@var{arch}/bin --libdir=@var{texmf}/@var{arch}/lib
+make texmf=@var{texmf}
+@end example
+@pindex depot
+@cindex automounter, and configuration
+@noindent (Unless you make provisions for architecture-specific files in
+other ways, e.g., with Depot or an automounter.)
+
+@item
+@opindex -O@r{, compiling with}
+@opindex -g@r{, compiling without}
+@cindex optimization, enabling
+@cindex debugging with @samp{-g}, disabling
+To compile with optimization (to compile without debugging, remove the
+@samp{-g}):
+@example
+env CFLAGS="-g -O" sh configure @dots{}
+@end example
+@noindent For a potential problem if you optimize, see @ref{TeX or
+Metafont failing,, @TeX{} or Metafont failing}.
+@end itemize
+
+
+@node Shared library
+@subsubsection Shared library
+
+@cindex shared library, making
+
+@opindex --enable-shared
+You can compile Kpathsea as a shared library on a few systems, by
+specifying the option @samp{--enable-shared} when you run
+@samp{configure}.
+
+@cindex code sharing
+The main advantage in doing this is that the executables can then share
+the code, thus decreasing memory and disk space requirements.
+
+On some systems, you can record the location of shared libraries in a
+binary, usually by giving certain options to the linker. Then
+individual users do not need to set their system's environment variable
+(e.g., @code{LD_LIBRARY_PATH}) to find shared libraries. If you want to
+do this, you will need to add the necessary options to @code{LDFLAGS}
+yourself; for example, on Solaris, include something like
+@samp{-R$@{prefix@}/lib}, on IRIX or Linux, use
+@samp{-rpath$@{prefix@}/lib}. (Unfortunately, making this happen by
+default is very difficult, because of interactions with an existing
+installed shared library.)
+
+
+@node Running make
+@subsection Running @code{make}
+
+@pindex make@r{, running}
+
+@flindex texmf.cnf@r{, creating}
+@flindex paths.h@r{, creating}
+@code{make} (still in the top-level directory). This also creates the
+@file{texmf.cnf} and @file{paths.h} files that define the default search
+paths, and (by default) the @samp{plain} and @samp{latex} @TeX{} formats.
+
+@cindex fallback resolutions, overriding
+You can override directory names and other values at @code{make}-time.
+@file{make/paths.make} lists the variables most commonly reset. For
+example, @samp{make default_texsizes=600} changes the list of fallback
+resolutions.
+
+You can also override each of @code{configure}'s environment variables
+(@pxref{configure environment}). The Make variables have the same names.
+
+Finally, you can supply additional options via the following variables.
+(@code{configure} does not use these.)
+
+@vtable @samp
+@item XCPPFLAGS
+@itemx XDEFS
+@cindex preprocessor options, additional
+Preprocessor options.
+
+@item XCFLAGS
+@cindex compiler options, additional
+Compiler options.
+
+@item XLDFLAGS
+@cindex loader options, initial
+Loader options (included at beginning of link commands).
+
+@item XLOADLIBES
+@cindex loader options, final
+More loader options (included at end of link commands).
+
+@item XMAKEARGS
+@cindex Make arguments, additional
+Additional Make arguments passed to all sub-@code{make}'s. You may need
+to include assignments to the other variables here via @code{XMAKEARGS};
+for example: @samp{make XMAKEARGS="CFLAGS=-O XDEFS=-DA4"}.
+@end vtable
+
+@cindex compiler, changing
+@cindex libraries, changing
+It's generally a bad idea to use a different compiler (@samp{CC}) or
+libraries (@code{LIBS}) for compilation than you did for configuration,
+since the values @code{configure} determined may then be incorrect.
+
+@cindex universe, BSD vs.@: system V
+@cindex BSD universe
+@cindex system V universe
+@cindex Solaris BSD compatibility, not
+@flindex libucb@r{, avoiding}
+@flindex ucbinclude@r{, avoiding}
+Adding compiler options to change the ``universe'' you are using
+(typically BSD vs.@: system V) is generally a cause of trouble. It's
+best to use the native environment, whatever that is; @code{configure}
+and the software usually adapt best to that. In particular, under
+Solaris 2.x, you should not use the BSD-compatibility library
+(@file{libucb}) or include files (@file{ucbinclude}).
+
+@cindex Babel
+If you want to use the Babel La@TeX{} package for support of non-English
+typesetting, you need to modify some files before making the La@TeX{}
+format. See the file @file{install.txt} in the Babel distribution.
+
+
+@node Installing files
+@subsection Installing files
+
+@cindex installing files
+
+The basic command is the usual @code{make install}. For security
+issues, @pxref{Security}.
+
+The first time you install any manual in the GNU Info system, you should
+add a line (you choose where) to the file @file{dir} in your
+@samp{$(infodir)} directory. Sample text for this is given near the top
+of the Texinfo source files (@file{kpathsea/kpathsea.texi},
+@file{dvipsk/dvips.texi}, and @file{web2c/doc/web2c.texi}).
+If you have a recent version of the GNU Texinfo distribution installed
+(@url{ftp://prep.ai.mit.edu/pub/gnu/texinfo-3.9.tar.gz} or later), this
+should happen automatically.
+
+On the offchance that this is your first Info installation, the
+@file{dir} file I use is included in the distribution as
+@file{etc/dir-example}.
+
+@cindex multiple architectures, installing on
+@cindex architecture-(in)dependent files, installing only
+@cindex installation, architecture-(in)dependent files only
+You may wish to use one of the following targets, especially if you are
+installing on multiple architectures:
+@itemize @bullet
+@item
+@findex install-exec @r{Make target}
+@code{make install-exec} to install in architecture-dependent
+directories, i.e., ones that depend on the @code{$(exec_prefix)} Make
+variable. This includes links to binaries, libraries, etc., not just
+``executables''.
+
+@item
+@findex install-data @r{Make target}
+@code{make install-data} to install in architecture-independent
+directories, such as documentation, configuration files, pool files, etc.
+@end itemize
+
+@cindex AFS
+@cindex Andrew File System, installing with
+@flindex /afs/@dots{} @r{, installing into}
+If you use the Andrew File System, the normal path (e.g.,
+@var{prefix}/bin) only gets you to a read-only copy of the files, and
+you must specify a different path for installation. The best way to do this
+is by setting the @samp{prefix} variable on the @code{make} command
+line. The sequence becomes something like this:
+@example
+configure --prefix=/whatever
+make
+make install prefix=/afs/.@var{system.name}/system/1.3/@@sys/whatever
+@end example
+@flindex ls-R @r{and AFS}
+@cindex relative filenames in @file{ls-R}
+@noindent With AFS, you will definitely want to use relative filenames in
+@file{ls-R} (@pxref{Filename database}), not absolute filenames. This
+is done by default, but check anyway.
+
+
+@node Cleaning up
+@subsection Cleaning up
+
+@findex distclean @r{Make target}
+The basic command is @code{make distclean}. This removes all files
+created by the build.
+
+Alternatively,
+@itemize @bullet
+@item
+@findex mostlyclean @r{Make target}
+@code{make mostlyclean} if you intend to compile on another
+architecture. For Web2C, since the generated C files are portable,
+they are not removed. If the @code{lex} vs.@: @code{flex} situation
+is going to be different on the next machine, @code{rm
+web2c/lex.yy.c}.
+
+@item
+@findex clean @r{Make target}
+@code{make clean} to remove files created by compiling, but leave
+configuration files and Makefiles.
+
+@item
+@findex maintainer-clean @r{Make target}
+@code{make maintainer-clean} to remove everything that the Makefiles can
+rebuild. This is more than @samp{distclean} removes, and you should
+only use it if you are thoroughly conversant with (and have the necessary
+versions of) Autoconf.
+
+@item
+@findex extraclean @r{Make target}
+@code{make extraclean} to remove other junk, e.g., core files, log
+files, patch rejects. This is independent of the other @samp{clean}
+targets.
+@end itemize
+
+
+@node Filename database generation
+@subsection Filename database generation
+
+@cindex filename database generation
+@cindex generation of filename database
+
+You will probably want to set up a @code{cron} entry on the appropriate
+machine(s) to rebuild the filename database nightly or so, as in:
+@example
+0 0 * * * cd @var{texmf} && @var{/bindir}/mktexlsr
+@end example
+@noindent @xref{Filename database}.
+
+Although the @code{mktex@dots{}} scripts make every effort to add
+newly-created files on the fly, it can't hurt to make sure you get a
+fresh version every so often.
+
+
+@node mktex scripts
+@subsection @file{mktex} scripts
+
+@cindex @file{mktex} scripts
+@cindex scripts for file creation
+
+@cindex font set, infinite
+@cindex dynamic creation of files
+@cindex Sauter fonts, and dynamic source creation
+@cindex EC fonts, and dynamic source creation
+If Kpathsea cannot otherwise find a file, for some file types it is
+configured by default to invoke an external program to create it
+dynamically (@pxref{mktex configuration}). These are collectively
+known as @dfn{@code{mktex} scripts}, since most of them are named
+@code{mktex...}.
+
+For example, this is useful for fonts (bitmaps, TFM's, and
+arbitrarily-sizable Metafont sources such as the Sauter and EC fonts),
+since any given document can use fonts never before referenced.
+Building all fonts in advance is therefore impractical, if not
+impossible.
+
+It is also useful for the @TeX{} @samp{.fmt} (and Metafont
+@samp{.base} and Metapost @samp{.mem} files, @pxref{Memory
+dumps,,,Web2c,web2c}), where pre-generating every format consumes a
+lot of both time and space.
+
+The script is passed the name of the file to create and possibly other
+arguments, as explained below. It must echo the full pathname of the
+file it created (and nothing else) to standard output; it can write
+diagnostics to standard error.
+
+@menu
+* config: mktex configuration.
+* names: mktex script names.
+* args: mktex script arguments.
+@end menu
+
+
+@node mktex configuration
+@subsubsection @file{mktex} configuration
+
+@cindex @file{mktex} script configuration
+@cindex configuration of @file{mktex} scripts
+@cindex enabling @file{mktex} scripts
+@cindex disabling @file{mktex} scripts
+
+The list of file types and program names that can run an external
+program to create missing files is listed in the next section. In the
+absence of @code{configure} options specifying otherwise, everything
+but @file{mktextex} will be enabled by default. The @code{configure}
+options to change the defaults are:
+
+@cindex @code{configure} options for @file{mktex} scripts
+@opindex --without-mktexfmt-default
+@opindex --without-mktexmf-default
+@opindex --without-mktexocp-default
+@opindex --without-mktexofm-default
+@opindex --without-mktexpk-default
+@opindex --without-mktextfm-default
+@opindex --with-mktextex-default
+@example
+--without-mktexfmt-default
+--without-mktexmf-default
+--without-mktexocp-default
+--without-mktexofm-default
+--without-mktexpk-default
+--without-mktextfm-default
+--with-mktextex-default
+@end example
+
+The @code{configure} setting is overridden if the environment variable
+or configuration file value named for the script is set; e.g.,
+@file{MKTEXPK} (@pxref{mktex script arguments}).
+
+@flindex fmtutils.cnf
+@code{mktexfmt} reads a file @file{fmtutil.cnf}, typically located in
+@file{texmf/web2c/} to glean its configuration information. The rest
+of the files and features in this section are primarily intended for
+the font generation scripts.
+
+@flindex mktex.cnf
+@flindex mktex.opt
+@cindex site overrides for @code{mktex@dots{}}
+As distributed, all the scripts source a file
+@file{texmf/web2c/mktex.cnf} if it exists, so you can override various
+defaults.
+See @file{mktex.opt}, for instance, which defines the default mode,
+resolution, some special directory names, etc. If you prefer not to
+change the distributed scripts, you can simply create @file{mktex.cnf}
+with the appropriate definitions (you do not need to create it if you
+have nothing to put in it). @file{mktex.cnf} has no special syntax;
+it's an arbitrary Bourne shell script. The distribution contains a
+sample @file{mktex.cnf} for you to copy and modify as you please (it
+is not installed anywhere).
+
+@flindex mktex.opt
+@vindex MT_FEATURES
+In addition, you can configure a number of features with the
+@code{MT_FEATURES} variable, which you can define:
+
+@itemize @bullet
+@item
+in @file{mktex.opt}, as just mentioned;
+
+@item
+by editing the file @file{mktex.opt}, either before @samp{make
+install} (in the source hierarchy) or after (in the installed
+hierarchy);
+
+@item
+or in the environment.
+@end itemize
+
+If none of the options below are enabled, @code{mktexpk},
+@code{mktextfm}, and @code{mktexmf} follow the following procedure to
+decide where fonts should be installed. Find the tree where the font's
+sources are, and test the permissions of the @samp{fonts} directory of
+that tree to determine whether it is writable. If it is, put the files
+in the tree in appropriate locations. If it isn't writable, see whether
+the tree is a system tree (named in @code{SYSTEXMF}). If so, the
+@code{VARTEXFONTS} tree is used. In all other cases the working
+directory is used.
+
+The @samp{appendonlydir} option is enabled by default.
+
+@vtable @samp
+@item appendonlydir
+@cindex directories, making append-only
+@flindex mktexdir
+Tell @code{mktexdir} to create directories append-only, i.e., set
+their sticky bit (@pxref{Mode Structure,,, coreutils, GNU Core
+Utilities}). This feature is silently ignored on non-Unix platforms
+(e.g. Windows/NT and MS-DOS) which don't support similar functionality.
+This feature is enabled by default.
+
+@item dosnames
+@cindex 8.3 filenames, using
+@cindex DOS compatible names
+@flindex dpi@var{nnn} directories
+Use 8.3 names; e.g., @file{dpi600/cmr10.pk} instead of
+@file{cmr10.600pk}. Note that this feature only affects filenames that
+would otherwise clash with other TeX-related filenames; @file{mktex}
+scripts do nothing about filenames which exceed the 8+3 MS-DOS limits
+but remain unique when truncated (by the OS) to these limits, and nether
+do the scripts care about possible clashes with files which aren't
+related with TeX. For example, @file{cmr10.600pk} would clash with
+@file{cmr10.600gf} and is therefore changed when @samp{dosnames} is in
+effect, but @file{mf.pool} and @file{mp.base} don't clash with any
+TeX-related files and are therefore unchanged.
+
+This feature is turned on by default on MS-DOS. If you do not wish
+@samp{dosnames} to be set on an MS-DOS platform, you need to set the
+@code{MT_FEATURES} environment variable to a value that doesn't include
+@samp{dosnames}. You can also change the default setting by editing
+@file{mktex.opt}, but only if you use the @file{mktex} shell scripts;
+the emulation programs don't consult @file{mktex.opt}.
+
+@item fontmaps
+@cindex fontmaps
+@cindex fontname
+Instead of deriving the location of a font in the destination tree from
+the location of the sources, the aliases and directory names from the
+Fontname distribution are used. (@pxref{Top,, Introduction, fontname,
+Fontname}).
+
+@item nomfdrivers
+@cindex metafont driver files
+Let mktexpk and mktextfm create metafont driver files in a temporary
+directory. These will be used for just one metafont run and not
+installed permanently.
+
+@item nomode
+@cindex mode directory, omitting
+Omit the directory level for the mode name; this is fine as long as
+you generate fonts for only one mode.
+
+@item stripsupplier
+@cindex supplier directory, omitting
+Omit the font supplier name directory level.
+
+@item striptypeface
+@cindex typeface directory, omitting
+Omit the font typeface name directory level.
+
+@item strip
+@cindex supplier directory, omitting
+@cindex typeface directory, omitting
+Omit the font supplier and typeface name directory levels. This feature
+is deprecated in favour of @samp{stripsupplier} and @samp{striptypeface}.
+
+@item varfonts
+@flindex /var/tmp/texfonts
+@vindex VARTEXFONTS
+@cindex Linux File System Standard
+When this option is enabled, fonts that would otherwise be written in
+system texmf tree go to the @code{VARTEXFONTS} tree instead. The
+default value in @file{kpathsea/Makefile.in} is
+@file{/var/tmp/texfonts}. The @cite{Linux File System Standard}
+recommends @file{/var/tex/fonts}.
+
+@vindex USE_VARTEXFONTS
+The @samp{varfonts} setting in @code{MT_FEATURES} is overridden by the
+@code{USE_VARTEXFONTS} environment variable: if set to @samp{1}, the
+feature is enabled, and if set to @samp{0}, the feature is disabled.
+
+@item texmfvar
+@vindex TEXMFVAR
+Force generated files that would go into a system tree (as defined by
+@code{SYSTEXMF}) into @code{TEXMFVAR}. Starting with te@TeX{}-3.0, the
+variable @code{TEXMFVAR} is always set. The @samp{varfonts} feature takes
+precedence if also set.
+
+@vindex USE_TEXMFVAR
+The @samp{texmfvar} setting in @code{MT_FEATURES} is overridden by the
+@code{USE_TEXMFVAR} environment variable: if set to @samp{1}, the
+feature is enabled, and if set to @samp{0}, the feature is disabled.
+@end vtable
+
+
+@node mktex script names
+@subsubsection @file{mktex} script names
+
+@cindex @file{mktex} script names
+@cindex names for @file{mktex} scripts
+
+The following table shows the default name of the script for each
+of the file types which support runtime generation.
+
+@table @file
+@item mktexfmt
+@pindex mktexfmt
+@pindex fmtutil
+(@samp{.fmt}, @samp{.base}, @samp{.mem}) @TeX{}/Metafont/MetaPost
+formats. This script is also named @command{fmtutil}, and reads
+@file{fmtutil.cnf} for configuration information.
+
+@item mktexmf
+@pindex mktexmf
+(@samp{.mf}) Metafont input files.
+
+@item mkocp
+@pindex mkocp
+(@samp{.ocp}) Omega compiled process files.
+
+@item mkofm
+@pindex mkofm
+(@samp{.ofm}) Omega font metric files.
+
+@item mktexpk
+@pindex mktexpk
+(@samp{pk}) Glyph fonts.
+
+@item mktextex
+@pindex mktextex
+(@samp{.tex}) @TeX{} input files (disabled by default).
+
+@item mktextfm
+@pindex mktextfm
+(@samp{.tfm}) TFM files.
+@end table
+
+@vindex DVIPSMAKEPK
+@vindex XDVIMAKEPK
+@vindex DVILJMAKEPK
+@noindent These names can be overridden by an environment variable specific
+to the program---for example, @code{DVIPSMAKEPK} for Dvipsk.
+
+@comment next two paragraphs are repeated in dvips.texi
+@flindex missfont.log
+@cindex failed @code{mktex@dots{}} script invocation
+If a @code{mktex@dots{}} script fails, the invocation is appended to a
+file @file{missfont.log} (by default) in the current directory. You can
+then execute the log file to create the missing files after fixing the
+problem.
+
+@vindex TEXMFOUTPUT
+@vindex MISSFONT_LOG
+If the current directory is not writable and the environment variable or
+configuration file value @code{TEXMFOUTPUT} is set, its value is
+used. Otherwise, nothing is written. The name @samp{missfont.log} is
+overridden by the @code{MISSFONT_LOG} environment variable or
+configuration file value.
+
+
+@node mktex script arguments
+@subsubsection @file{mktex} script arguments
+
+@cindex arguments to @file{mktex}
+
+The first argument to a @file{mktex} script is always the name
+of the file to be created.
+
+In the default @file{mktexpk} implementation, additional arguments may
+also be passed:
+
+@table @samp
+@item --dpi @var{num}
+Sets the resolution of the generated font to @var{num}.
+@item --mfmode @var{name}
+Sets the Metafont mode to @var{name}.
+@item --bdpi @var{num}
+Sets the the ``base dpi'' for the font. This must match the mode being
+used.
+@item --mag @var{string}
+A ``magstep'' string suitable for the Metafont @code{mag} variable.
+This must match the combination of @var{bdpi} and @var{dpi} being used.
+@item --destdir @var{string}
+A directory name. If the directory is absolute, it is used as-is.
+Otherwise, it is appended to the root destination directory set in the
+script.
+@end table
+
+
+@node Installation testing
+@subsection Installation testing
+
+@cindex testing, post-installation
+@cindex installation testing
+
+Besides the tests listed in @ref{Simple installation}, you can try
+running @samp{make check}. This includes the torture tests (trip, trap,
+and mptrap) that come with Web2c (@pxref{Triptrap,,, web2c, Web2c}).
+
+
+@node Security
+@section Security
+
+@cindex security considerations
+
+None of the programs in the @TeX{} system require any special system
+privileges, so there's no first-level security concern of people gaining
+illegitimate root access.
+
+@cindex trojan horse attack
+@flindex .rhosts@r{, writable by @TeX{}}
+A @TeX{} document, however, can write to arbitrary files, e.g.,
+@file{~/.rhosts}, and thus an unwitting user who runs @TeX{} on a random
+document is vulnerable to a trojan horse attack. This loophole is
+closed by default, but you can be permissive if you so desire in
+@file{texmf.cnf}. @xref{tex invocation,,, web2c, Web2c}. MetaPost has
+the same issue.
+
+Dvips, Xdvi, and @TeX{} can also execute shell commands under some
+circumstances. To disable this, see the @samp{-R} option in @ref{Option
+details,,, dvips, Dvips}, the xdvi man page, and @ref{tex
+invocation,,, web2c, Web2c}, respectively.
+
+@cindex local cache of fonts
+@cindex cache of fonts, local
+Another security issue arises because it's very useful---almost
+necessary---to make arbitrary fonts on user demand with @code{mktexpk}
+and friends. Where do these files get installed? By default, the
+@code{mktexpk} distributed with Kpathsea assumes a world-writable
+@file{/var/tmp} directory; this is a simple and convenient approach, but
+it may not suit your situation because it means that a local cache of
+fonts is created on every machine.
+
+@cindex globally writable directories
+To avoid this duplication, many people consider a shared, globally
+writable font tree desirable, in spite of the potential security
+problems. To do this you should change the value of @code{VARTEXFONTS}
+in @file{texmf.cnf} to refer to some globally known directory.
+@xref{mktex configuration}.
+
+@cindex append-only directories and @code{mktexpk}
+The first restriction you can apply is to make newly-created directories
+under @file{texmf} be append-only with an option in @file{mktex.cnf}.
+@xref{mktex configuration}.
+
+@cindex group-writable directories
+@cindex setgid scripts
+Another approach is to establish a group (or user) for @TeX{} files,
+make the @file{texmf} tree writable only to that group (or user), and
+make @code{mktexpk} et al.@: setgid to that group (or setuid to that
+user). Then users must invoke the scripts to install things. (If
+you're worried about the inevitable security holes in scripts, then you
+could write a C wrapper to exec the script.)
+
+@cindex file permissions
+@cindex permissions, file
+The @file{mktex@dots{}} scripts install files with the same read and
+write permissions as the directory they are installed in. The
+executable, sgid, suid, and sticky bits are always cleared.
+
+@cindex directory permissions
+@cindex permissions, directory
+Any directories created by the @file{mktex@dots{}} scripts have the
+same permissions as their parent directory, unless the
+@code{appendonlydir} feature is used, in which case the sticky bit is
+always set.