diff options
Diffstat (limited to 'Build/source/texk/kpathsea/doc/install.texi')
-rw-r--r-- | Build/source/texk/kpathsea/doc/install.texi | 1239 |
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. |