tentative fix for issue 3 (ex 53)

[mplib] / src / texk / kpathsea / install.texi

@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}).  This is most 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.  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
* mktex configuration::
* mktex script names::
* 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 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{mktexpk}, @file{mktextfm}, @file{mktexmf}, and
@file{mktextex}.

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-mktexmf-default
@opindex --without-mktexpk-default
@opindex --without-mktextfm-default
@opindex --with-mktextex-default
@example
--without-mktexmf-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 mktex.cnf
@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

@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 mktexpk
@pindex mktexpk
Glyph fonts.

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

@item mktexmf
@pindex mktexmf
Metafont input files.

@item mktextfm
@pindex mktextfm
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{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

@c  The feature mentioned here doesn't seem to be implemented.
@c  Worse, the variable name clashed with the "switch" used to select
@c  whether a mktex program is run at all.  However, a dearth of
@c  complains suggests that no-one was using it anyway.
@c
@c @vindex MKTEXPK @r{environment variable}
@c @cindex specification for @code{mktexpk}
@c You can change the specification for the arguments passed to the
@c external script by setting the environment variable named as the script
@c name, but all capitals---@code{MKTEXPK}, for example.  If you've
@c changed the script name by setting (say) @code{DVIPSMAKEPK} to
@c @samp{foo}, then the spec is taken from the environment variable
@c @code{FOO}.
@c
@c The spec can contain any variable references, to the above variables or
@c any others.  As an example, the default spec for @code{mktexpk} is:
@c @example
@c $KPATHSEA_DPI $MAKETEX_BASE_DPI $MAKETEX_MAG $MAKETEX_MODE
@c @end example
@c
@c @noindent The convention of passing the name of the file to be created
@c 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{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.