@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 trouble, @pxref{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: @pxref{unixtex.ftp}.

This section explains what to do if you wish to take the defaults for
everything (installing under @file{/usr/local}), 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.

@enumerate
@item
Be sure you have enough disk space: approximately 8 megabytes for the
compressed archives, 15MB for sources, 45MB for compilation, 40MB for
the (initial) installed system (including library files).  @xref{Disk
space}.

@item
Retrieve these two 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/texmflib.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

@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}.

@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}/MakeTeXls-R
@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,
@pxref{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{MakeTeXPK} (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{MakeTeXPK} assumes @file{/usr/local/share/texmf/fonts}
is globally writable.  If you need a different arrangement, 
@pxref{MakeTeX configuration}.

@xref{MakeTeX scripts}.

@item
@cindex fonts, being created
@pindex MakeTeXPK @r{, initial runs}
@cindex tests, simple
For some simple tests, try @samp{tex story \\bye} and @samp{latex
simple}.  Then run @file{xdvi story} or @file{dvips simple} 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::        
* MakeTeX 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{texmflib}; the individual
distributions don't enter into it.  Sizes are in megabytes.  All numbers
are approximate.

@multitable {distribution} {.tar.gz} {unpacked} {compiled} {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  3.8 @tab 14.1 @tab 43.1 @tab 23.5
@item texmflib @tab  3.8 @tab 15.0 @tab    - @tab 15.0
@item (totals) @tab  7.6 @tab 29.1 @tab 43.1 @tab 38.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.cnf.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.cnf.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{MakeTeXnames.cnf}, either
before or after installation, to control various aspects of
@code{MakeTeXPK} and friends.  @xref{MakeTeX configuration}.

You do not need to edit @file{texmf.cnf.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.cnf.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.cnf.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.cnf.in} before installation, or the installed
@file{texmf.cnf}, and remove the @samp{$MAKETEX_MODE}.

@xref{MakeTeX script arguments}, for how this interacts with @code{MakeTeXPK}.

@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.cnf.in
@flindex texmf.cnf@r{, generated}
@file{texmf.sed} (together with a little extra magic---see
@file{kpathsea/Makefile}) is applied to @file{texmf.cnf.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.h.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.h.in}.  It also creates a @file{Makefile} from
the corresponding @file{Makefile.in}, doing @samp{@@@var{var}@@} and
@samp{ac_include} substitutions).

@flindex CONFIGURE
@flindex kpathsea/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{MakeTeXPK} by default
with the option @samp{--disable-maketexpk}.
@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}}

If you have Bash, the GNU shell, use it if @code{sh} runs into trouble
(@pxref{Top,,,features,Bash Features}).

Most Bourne shell variants other than Bash cannot handle
@code{configure} scripts as generated by GNU Autoconf (@pxref{Top,
Introduction,, autoconf, Autoconf}).  Specifically:
@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}
The Korn shell may be installed as @file{/bin/sh} on AIX.
@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}
Ash is sometimes installed as @file{/bin/sh} on NetBSD, FreeBSD, and
Linux systems.  @file{/bin/bash} should be available.

@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 @pxref{Invoking configure,, Running @code{configure} scripts,
autoconf, Autoconf} (a copy is in the file @file{kpathsea/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; @pxref{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-maketexmf-default
@itemx --without-maketexpk-default
@itemx --without-maketextfm-default
@itemx --with-maketextex-default
Enable or disable the dynamic generation programs.  @xref{MakeTeX
configuration}.

@item --enable-shared
Build Kpathsea as a shared library, and link against it.  Also build the
usual static library.  @xref{Shared library}.

@item --disable-static
Build only the shared library.
@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-toolkit
@end example

@item
@cindex @TeX{} hierarchy, one
Putting the binaries, @TeX{} files, GNU info files, etc.@: into a single
@TeX{} hierarchy, say @var{texmf}, requires overriding defaults in both
@code{configure} and @code{make}:
@example
configure --prefix=@var{texmf} --datadir=@var{texmf}
make texmf=@var{texmf}
@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}.  (Unfortunately, making this happen by default
is very difficult, because of interactions with an existing installed
shared library.)

Currently, shared library support is implemented only on SunOS 4
(Solaris 1) and SunOS 5 (Solaris 2).  If you're interested and willing
in adding support for other systems, please see the @samp{configure}
mode in the @file{klibtool} script, especially the host-specific case
statement around line 250.


@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}/MakeTeXls-R
@end example
@noindent @xref{Filename database}.

Although the @code{MakeTeX@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 MakeTeX scripts
@subsection @file{MakeTeX} scripts

@cindex @file{MakeTeX} scripts
@cindex scripts for file creation

@cindex font set, infinite
@cindex dynamic creation of files
@cindex Sauter fonts, and dynamic source creation
@cindex DC 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{MakeTeX configuration}).  This is most useful for
fonts (bitmaps, TFM's, and arbitrarily-sizable Metafont sources such as
the Sauter and DC fonts), since any given document can use fonts never
before referenced.  Trying to build all fonts in advance is therefore
impractical, if not impossible.

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
* MakeTeX configuration::
* MakeTeX script names::
* MakeTeX script arguments::
@end menu


@node MakeTeX configuration
@subsubsection @file{MakeTeX} configuration

@cindex @file{MakeTeX} script configuration
@cindex configuration of @file{MakeTeX} scripts
@cindex enabling @file{MakeTeX} scripts
@cindex disabling @file{MakeTeX} scripts

The following file types can run an external program to create missing
files: @file{pk}, @file{tfm}, @file{mf}, @file{tex}; the scripts are
named @file{MakeTeXPK}, @file{MakeTeXTFM}, @file{MakeTeXMF}, and
@file{MakeTeXTeX}.

In the absence of @code{configure} options specifying otherwise,
everything but @file{MakeTeXTeX} will be enabled by default. The
@code{configure} options to change the defaults are:

@cindex @code{configure} options for @file{MakeTeX} scripts
@opindex --without-maketexmf-default
@opindex --without-maketexpk-default
@opindex --without-maketextfm-default
@opindex --with-maketextex-default
@example
--without-maketexmf-default
--without-maketexpk-default
--without-maketextfm-default
--with-maketextex-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{MAKETEXPK} (@pxref{MakeTeX script arguments}).

@flindex MakeTeX.site
@cindex site overrides for @code{MakeTeX@dots{}}
As distributed, all the scripts source a file
@file{texmf/web2c/MakeTeX.site} if it exists, so you can override
various defaults.  See @file{MakeTeXcommon}, for instance, which defines
the default mode, resolution, directory permissions, some special
directory names, etc.  If you prefer not to change the distributed
scripts, you can simply create @file{MakeTeX.site} with the appropriate
definitions (you do not need to create it if you have nothing to put in
it).  @file{MakeTeX.site} has no special syntax; it's an arbitrary
Bourne shell script.  The distribution contains a sample
@file{MakeTeX.site} for you to copy and modify as you please (it is not
installed anywhere).

@flindex MakeTeXnames.cnf
@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{MakeTeX.site}, as just mentioned;

@item
by editing the file @file{MakeTeXnames.cnf}, either before @samp{make
install} (in the source hierarchy) or after (in the installed
hierarchy);

@item
or in the environment.
@end itemize

By default, @code{MakeTeXPK} installs fonts into the standard @TeX{}
directory structure (@pxref{TeX directory structure,, @TeX{} directory
structure}).  It uses aliases and directory names from the Fontname
distribution (@pxref{Top,, Introduction, fontname, Fontname}). Most of
the options here change that.

@vtable @samp
@item appendonlydir
@cindex directories, making append-only
@flindex MakeTeXmkdir
Tell @code{MakeTeXmkdir} to create directories append-only, i.e., set
their sticky bit (@pxref{Mode Structure,,, fileutils, GNU File
Utilities}).

@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}.

@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 strip
@cindex supplier directory, omitting
@cindex typeface directory, omitting
Omit the font supplier and typeface name directory levels.

@item varfonts
@flindex /var/tex/fonts
@vindex VARTEXFONTS
@cindex Linux File System Standard
Put @code{MakeTeXPK}-generated fonts under the directory named
by @code{VARTEXFONTS}; the default value in @file{kpathsea/texmf.cnf.in}
is @file{/var/tex/fonts}, as recommended by the @cite{Linux File System
Standard} (but unless @samp{varfonts} is enabled, nothing cares about
that value).

@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.
@end vtable


@node MakeTeX script names
@subsubsection @file{MakeTeX} script names

@cindex @file{MakeTeX} script names
@cindex names for @file{MakeTeX} scripts

@flindex tex-make.c
@vindex kpse_make_specs
The following table shows the default name of the script for each
possible file types.  (The source is the variable @code{kpse_make_specs}
in @file{kpathsea/tex-make.c}.)

@table @file
@item MakeTeXPK
@pindex MakeTeXPK
Glyph fonts.

@item MakeTeXTeX
@pindex MakeTeXTeX
@TeX{} input files.

@item MakeTeXMF
@pindex MakeTeXMF
Metafont input files.

@item MakeTeXTFM
@pindex MakeTeXTFM
TFM files.
@end table

@vindex DVIPSMAKEPK
@vindex XDVIMAKEPK
@vindex DVILJMAKEPK
@noindent These names are 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{MakeTeX@dots{}} script invocation
If a @code{MakeTeX@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 MakeTeX script arguments
@subsubsection @file{MakeTeX} script arguments

@cindex arguments to @file{MakeTeX}

The first argument to a @file{MakeTeX} script is always the name
of the file to be created.

In the default @file{MakeTeXPK} implementation, from three to five
additional arguments may also passed, via environment variables:

@enumerate
@item
@vindex KPATHSEA_DPI
The resolution to make the font at (@code{KPATHSEA_DPI}).

@item
@vindex MAKETEX_BASE_DPI
@cindex base dpi
The ``base dpi'' the program is operating at (@code{MAKETEX_BASE_DPI}),
i.e., the assumed resolution of the output device.

@item
@vindex MAKETEX_MAG
@vindex mag @r{Metafont variable}
@cindex magstep for @code{MakeTeXPK}
A ``magstep'' string suitable for the Metafont @code{mag} variable
(@code{MAKETEX_MAG}).

@item
@vindex MAKETEX_MODE
@vindex mode @r{Metafont variable}
@cindex Metafont mode name for @code{MakeTeXPK}
Optionally, a Metafont mode name to assign to the Metafont @code{mode}
variable (@code{MAKETEX_MODE}).  Otherwise, (the default)
@code{MakeTeXPK} guesses the mode from the resolution.  @xref{TeX
directory structure,, @TeX{} directory structure}.

@item
@vindex mtp_destdir
@cindex destination directory for @code{MakeTeXPK}
Optionally, 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 (from environment variables @code{DESTDIR} or
@code{MTP_DESTDIR} or a compile-time default). If this argument is not
supplied, the mode name is appended to the root destination directory.
@end enumerate

@noindent Kpathsea sets @code{KPATHSEA_DPI} appropriately for each
attempt at building a font.  It's up to the program using Kpathsea to
set the others. (@xref{Calling sequence}.)

@vindex MAKETEXPK @r{environment variable}
@cindex specification for @code{MakeTeXPK}
You can change the specification for the arguments passed to the
external script by setting the environment variable named as the script
name, but all capitals---@code{MAKETEXPK}, for example.  If you've
changed the script name by setting (say) @code{DVIPSMAKEPK} to
@samp{foo}, then the spec is taken from the environment variable
@code{FOO}.

The spec can contain any variable references, to the above variables or
any others.  As an example, the default spec for @code{MakeTeXPK} is:
@example
$KPATHSEA_DPI $MAKETEX_BASE_DPI $MAKETEX_MAG $MAKETEX_MODE
@end example

@noindent The convention of passing the name of the file to be created
as the first argument cannot be changed.


@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{Torture tests,,, 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 globally writable directories
Another security issue arises because it's very useful---almost
necessary---to make arbitrary fonts on user demand with @code{MakeTeXPK}
and friends.  Where do these files get installed?  By default, the
@code{MakeTeXPK} distributed with Kpathsea assumes a globally writable
@file{texmf} tree; this is the simplest and most convenient approach,
but it may not suit your situation.

@cindex append-only directories and @code{MakeTeXPK}
The first restriction you can apply is to make newly-created directories
under @file{texmf} be append-only with an option in
@file{MakeTeXnames.cnf}.  @xref{MakeTeX 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{MakeTeXPK} 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 local cache of fonts
@cindex cache of fonts, loca
Finally, using a central writable @file{texmf} tree may be completely
impossible, because it's on an NFS filesystem that you cannot export
read/write, or AFS is in use, or simply because ``it's policy''.  Then
you must resort to each user's machine having its own local directory of
dynamically-created fonts; again, @file{MakeTeXnames.cnf} has an option
to do this, and again, @pxref{MakeTeX configuration}.
