This manual documents how to install and use the Kpathsea library for filename lookup. It corresponds to version 3.5.6, released in January 2007.
This manual corresponds to version 3.5.6 of the Kpathsea library, released in January 2007.
The library's fundamental purpose is to return a filename from a list of directories specified by the user, similar to what shells do when looking up program names to execute.
The following software, all of which we maintain, uses this library:
Other software that we do not maintain also uses it.
We are still actively maintaining the library (and probably always will be, despite our hopes). If you have comments or suggestions, please send them to us (see Reporting bugs).
We distribute the library under the GNU Library General Public License (LGPL). In short, this means if you write a program using the library, you must (offer to) distribute the source to the library, along with any changes you have made, and allow anyone to modify the library source and distribute their modifications. It does not mean you have to distribute the source to your program, although we hope you will. See the files GPL and LGPL for the text of the GNU licenses.
If you know enough about TeX to be reading this manual, then you (or your institution) should consider joining the TeX Users Group (if you're already a member, great!). TUG produces the periodical TUGboat, sponsors an annual meeting and publishes the proceedings, and arranges courses on TeX for all levels of users throughout the world. Anyway, here is the address:
TeX Users Group
P.O. Box 2311
Portland OR 97208-2311
USA
phone: +1 503 223-9994
fax: +1 503 223-3960
email: tug@tug.org
(This section is for those people who are curious about how the library came about.) (If you like to read historical accounts of software, we urge you to seek out the GNU Autoconf manual and the “Errors of TeX” paper by Don Knuth, published in Software—Practice and Experience 19(7), July 1989.)
[Karl writes.] My first ChangeLog entry for Web2c seems to be February
1990, but I may have done some work before then. In any case, Tim
Morgan and I were jointly maintaining it for a time. (I should mention
here that Tim had made Web2c into a real distribution long before I had
ever used it or even heard of it, and Tom Rokicki did the original
implementation. I was using pxp and pc on VAX 11/750's
and the hot new Sun 2 machines.)
It must have been later in 1990 and 1991 that I started working on TeX for the Impatient. Dvips, Xdvi, Web2c, and the GNU fontutils (which I was also writing at the time) all used different environment variables, and, more importantly, had different bugs in their path searching. This became extremely painful, as I was stressing everything to the limit working on the book. I also desperately wanted to implement subdirectory searching, since I couldn't stand putting everything in one big directory, and also couldn't stand having to explicitly specify cm, pandora, ... in a path.
In the first incarnation, I just hacked separately on each program—that was the original subdirectory searching code in both Xdvi and Dvips, though I think Paul Vojta has completely rewritten Xdvi's support by now. That is, I tried to go with the flow in each program, rather than changing the program's calling sequences to conform to common routines.
Then, as bugs inevitably appeared, I found I was fixing the same thing three times (Web2c and fontutils were always sharing code, since I maintained those—there was no Dvipsk or Xdvik or Dviljk at this point). After a while, I finally started sharing source files. They weren't yet a library, though. I just kept things up to date with shell scripts. (I was developing on a 386 running ISC 2.2 at the time, and so didn't have symbolic links. An awful experience.)
The ChangeLogs for Xdvik and Dvipsk record initial releases of those distributions in May and June 1992. I think it was because I was tired of the different configuration strategies of each program, not so much because of the path searching. (Autoconf was being developed by David MacKenzie and others, and I was adapting it to TeX and friends.)
I started to make a separate library that other programs could link with on my birthday in April 1993, according to the ChangeLog. I don't remember exactly why I finally took the time to make it a separate library; a conversation with david zuhn that initiated it. Just seemed like it was time.
Dviljk got started in March 1994 after I bought a Laserjet 4. (Kpathsea work got suspended while Norm Walsh and I, with Gustaf Neumann's help, implemented a way for TeX to get at all those neat builtin LJ4 fonts ... such a treat to have something to typeset in besides Palatino!)
By spring of 1995, I had implemented just about all the path-searching features in Kpathsea that I plan to, driven beyond my initial goals by Thomas Esser and others. I then started to integrate Web2c with Kpathsea. After the release of a stable Web2c, I hope to be able to stop development, and turn most of my attention back to making fonts for GNU. (Always assuming Micros**t hasn't completely obliterated Unix by then, or that software patents haven't stopped software development by anybody smaller than a company with a million-dollar-a-year legal budget. Which is actually what I think is likely to happen, but that's another story...)
[Olaf writes.] At the end of 1997, UNIX is still alive and kicking, individuals still develop software, and Web2c development still continues. Karl had been looking for some time for someone to take up part of the burden, and I volunteered.
(A copy of this chapter is in the distribution file kpathsea/INSTALL.)
The procedure for Kpathsea (and Web2c, etc.) configuration and installation follows. If you encounter trouble, see Common problems, a copy of which is in the file kpathsea/BUGS.
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 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 /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.
These archives are mirrored on the CTAN hosts, in the systems/web2c directory.
0 0 * * * cd /usr/local/share/texmf && /bindir/mktexlsr
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, mktexpk will create these fonts in a hierarchy
under /var/tmp/texfonts; it simply assumes that /var/tmp
exists and is globally writable. If you need a different arrangement,
see mktex configuration.
See mktex scripts.
Most sites need to modify the default installation procedure in some
way, perhaps merely changing the prefix from `/usr/local', perhaps
adding extra compiler or loader options to work around configure
bugs. This section explains how to override default choices. For
additional distribution-specific information:
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.
Here is a table showing the disk space needed for each distribution (described in the next section). The `(totals)' line reflects the `texk' source distribution and `texklib'; the individual distributions don't enter into it. Sizes are in megabytes. All numbers are approximate.
| Distribution | .tar.gz | Unpacked | Compiled | Installed
|
| dviljk | .9 | 3.8 |
| |
| dvipsk | .9 | 3.2 |
| |
| xdvik | .7 | 2.5 |
| |
| web2c | 1.3 | 5.0 |
| |
| web | 1.9 | 6.5 | - | -
|
| texk | 7.5 | 32.1 | 95.3 | 33.5
|
| texklib | 6.3 | 15.0 | - | 15.0
|
| (totals) | 14.6 | 47.1 | 95.3 | 48.5
|
The archive 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 `xdvik' (or simply remove it after unpacking texk.tar.gz. If you are not interested in all of them, you can also retrieve them separately:
If you want to use the Babel LaTeX package for support of non-English typesetting, you may need to retrieve additional files. See the file install.txt in the Babel distribution.
If the search paths for your installation differ from the standard
TeX directory structure (see Introduction), edit the file kpathsea/texmf.in
as desired, before running configure. For example, if you have
all your fonts or macros in one big directory.
You may also wish to edit the file mktex.cnf, either before or
after installation, to control various aspects of mktexpk and
friends. See mktex configuration.
You do not need to edit texmf.in to change the default
top-level or other installation directories (only the paths).
You can and should do that when you run configure (next step).
You also do not need to edit texmf.in if you are willing to rely on 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.
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
configure-time, those changes will propagate through the whole
sequence. And if you change the default paths in texmf.in,
those changes are propagated to the compile-time defaults.
The Make definitions are all repeated in several Makefile's; but changing the top-level 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.)
By default, the bitmap font paths end with `/$MAKETEX_MODE', thus including the device name (usually a Metafont mode name such as `ljfour'). This distinguishes two different devices with the same resolution—a write/white from a write/black 300dpi printer, for example.
However, since most sites don't have this complication, Kpathsea
(specifically, the kpse_init_prog function in
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
MAKETEX_MODE to /. This makes the default PK path, for
example, expand into .../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., pktype).
To make the paths independent of the mode, simply edit texmf.in before installation, or the installed texmf.cnf, and remove the `$MAKETEX_MODE'.
See mktex script arguments, for how this interacts with mktexpk.
See TeX directory structure, for a description of the default arrangement of the input files that comprise the TeX system. The file kpathsea/HIER is a copy of that section.
This section describes how the default paths are constructed.
You may wish to ignore the whole mess and simply edit texmf.cnf after it is installed, perhaps even copying it into place beforehand so you can complete the installation, if it seems necessary.
To summarize the chain of events that go into defining the default paths:
$(var) for a
string @var@. The variables in question are the one that
define the installation directories.
#define's in
paths.h. These values will be the compile-time defaults; they
are not used at runtime unless no texmf.cnf file can be found.
(That's a lie: the compile-time defaults are what any extra :'s in texmf.cnf expand into; but the paths as distributed have no extra :'s, and there's no particular reason for them to.)
configureRun sh configure options (in the top-level directory, the
one containing kpathsea/), possibly using a shell other than
sh (see configure shells).
configure adapts the source distribution to the present system
via #define's in */c-auto.h, which are created from the
corresponding c-auto.in. It also creates a Makefile from
the corresponding Makefile.in, doing `@var@' and
`ac_include' substitutions).
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 mktexpk by default
with the option `--disable-mktexpk'.
See configure options.
configure shells
Considerable effort has gone into trying to ensure that the
configure scripts can be run by most Bourne shell variants.
If sh runs into trouble, your best bet is to use Bash, the GNU
Bourne-again shell (see Top).
Bourne shell variants for which problems have been reported in the past are:
kshash /bin/shconfigure options
For a complete list of all configure options, run `configure
--help' or see Running configure scripts, (a copy is in the file kpathsea/README.CONFIGURE).
The generic options are listed first in the `--help' output, and
the package-specific options come last. The environment variables
configure pays attention to are listed below.
Options particularly likely to be useful are `--prefix', `--datadir', and the like; see configure scenarios.
This section gives pointers to descriptions of the `--with' and
`--enable' options to configure that Kpathsea-using programs
accept.
configure environmentconfigure uses the value of the following environment variables in
determining your system's characteristics, and substitutes for them in
Makefile's:
gcc if it's installed, otherwise
cc.
gcc,
`-g' otherwise. CFLAGS comes after any other options. You
may need to include -w here if your compilations commonly have
useless warnings (e.g., NULL redefined), or 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).
configure
script often does only preprocessing (e.g., to check for the existence
of #include files), and CFLAGS is not used for this. You may
need to set this to something like
`-I/usr/local/include/wwwhatever' if you have the libwww library
installed for hyper-xdvik (see xdvik/INSTALL).
configure.
Provided for enabling or disabling program features, as documented in
the various program-specific installation instructions. DEFS
comes before any compiler options included by the distribution
Makefiles or by configure.
LDFLAGS comes before
any other linker options.
configure scenariosHere are some common installation scenarios:
configure --with-x
configure:
configure --prefix=/here/texmf --datadir=/here
lndir script from the X11
distribution, or with the `--srcdir' option:
configure --srcdir=srcdir
configure --prefix=texmf --datadir=texmf \
--bindir=texmf/arch/bin --libdir=texmf/arch/lib
make texmf=texmf
(Unless you make provisions for architecture-specific files in other ways, e.g., with Depot or an automounter.)
env CFLAGS="-g -O" sh configure ...
For a potential problem if you optimize, see TeX or Metafont failing.
You can compile Kpathsea as a shared library on a few systems, by specifying the option `--enable-shared' when you run `configure'.
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., LD_LIBRARY_PATH) to find shared libraries. If you want to
do this, you will need to add the necessary options to LDFLAGS
yourself; for example, on Solaris, include something like
`-R${prefix}/lib', on IRIX or Linux, use
`-rpath${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 Linux, SunOS 4 (Solaris 1), SunOS 5 (Solaris 2), IRIX 5, and IRIX 6. If you're interested and willing in adding support for other systems, please see the `configure' mode in the klibtool script, especially the host-specific case statement around line 250.
make
make (still in the top-level directory). This also creates the
texmf.cnf and paths.h files that define the default search
paths, and (by default) the `plain' and `latex' TeX formats.
You can override directory names and other values at make-time.
make/paths.make lists the variables most commonly reset. For
example, `make default_texsizes=600' changes the list of fallback
resolutions.
You can also override each of configure's environment variables
(see configure environment). The Make variables have the same names.
Finally, you can supply additional options via the following variables.
(configure does not use these.)
make's. You may need
to include assignments to the other variables here via XMAKEARGS;
for example: `make XMAKEARGS="CFLAGS=-O XDEFS=-DA4"'.
It's generally a bad idea to use a different compiler (`CC') or
libraries (LIBS) for compilation than you did for configuration,
since the values configure determined may then be incorrect.
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; configure
and the software usually adapt best to that. In particular, under
Solaris 2.x, you should not use the BSD-compatibility library
(libucb) or include files (ucbinclude).
If you want to use the Babel LaTeX package for support of non-English typesetting, you need to modify some files before making the LaTeX format. See the file install.txt in the Babel distribution.
The basic command is the usual make install. For security
issues, see Security.
The first time you install any manual in the GNU Info system, you should add a line (you choose where) to the file dir in your `$(infodir)' directory. Sample text for this is given near the top of the Texinfo source files (kpathsea/kpathsea.texi, dvipsk/dvips.texi, and web2c/doc/web2c.texi). If you have a recent version of the GNU Texinfo distribution installed (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 dir file I use is included in the distribution as etc/dir-example.
You may wish to use one of the following targets, especially if you are installing on multiple architectures:
make install-exec to install in architecture-dependent
directories, i.e., ones that depend on the $(exec_prefix) Make
variable. This includes links to binaries, libraries, etc., not just
“executables”.
make install-data to install in architecture-independent
directories, such as documentation, configuration files, pool files, etc.
If you use the Andrew File System, the normal path (e.g.,
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 `prefix' variable on the make command
line. The sequence becomes something like this:
configure --prefix=/whatever
make
make install prefix=/afs/.system.name/system/1.3/@sys/whatever
With AFS, you will definitely want to use relative filenames in ls-R (see Filename database), not absolute filenames. This is done by default, but check anyway.
The basic command is make distclean. This removes all files
created by the build.
Alternatively,
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 lex vs. flex situation
is going to be different on the next machine, rm
web2c/lex.yy.c.
make clean to remove files created by compiling, but leave
configuration files and Makefiles.
make maintainer-clean to remove everything that the Makefiles can
rebuild. This is more than `distclean' removes, and you should
only use it if you are thoroughly conversant with (and have the necessary
versions of) Autoconf.
make extraclean to remove other junk, e.g., core files, log
files, patch rejects. This is independent of the other `clean'
targets.
You will probably want to set up a cron entry on the appropriate
machine(s) to rebuild the filename database nightly or so, as in:
0 0 * * * cd texmf && /bindir/mktexlsr
See Filename database.
Although the mktex... 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.
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 (see 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.
The following file types can run an external program to create missing files: pk, tfm, mf, tex; the scripts are named mktexpk, mktextfm, mktexmf, and mktextex.
In the absence of configure options specifying otherwise,
everything but mktextex will be enabled by default. The
configure options to change the defaults are:
--without-mktexmf-default
--without-mktexpk-default
--without-mktextfm-default
--with-mktextex-default
The configure setting is overridden if the environment variable
or configuration file value named for the script is set; e.g.,
MKTEXPK (see mktex script arguments).
As distributed, all the scripts source a file texmf/web2c/mktex.cnf if it exists, so you can override various defaults. See 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 mktex.cnf with the appropriate definitions (you do not need to create it if you have nothing to put in it). mktex.cnf has no special syntax; it's an arbitrary Bourne shell script. The distribution contains a sample mktex.cnf for you to copy and modify as you please (it is not installed anywhere).
In addition, you can configure a number of features with the
MT_FEATURES variable, which you can define:
If none of the options below are enabled, mktexpk,
mktextfm, and 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 `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 SYSTEXMF). If so, the
VARTEXFONTS tree is used. In all other cases the working
directory is used.
The `appendonlydir' option is enabled by default.
mktexdir to create directories append-only, i.e., set
their sticky bit (see Mode Structure). 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.
This feature is turned on by default on MS-DOS. If you do not wish
`dosnames' to be set on an MS-DOS platform, you need to set the
MT_FEATURES environment variable to a value that doesn't include
`dosnames'. You can also change the default setting by editing
mktex.opt, but only if you use the mktex shell scripts;
the emulation programs don't consult mktex.opt.
VARTEXFONTS tree instead. The
default value in kpathsea/Makefile.in is
/var/tmp/texfonts. The Linux File System Standard
recommends /var/tex/fonts.
The `varfonts' setting in MT_FEATURES is overridden by the
USE_VARTEXFONTS environment variable: if set to `1', the
feature is enabled, and if set to `0', the feature is disabled.
SYSTEXMF) into TEXMFVAR. Starting with teTeX-3.0, the
variable TEXMFVAR is always set. The `varfonts' feature takes
precedence if also set.
The `texmfvar' setting in MT_FEATURES is overridden by the
USE_TEXMFVAR environment variable: if set to `1', the
feature is enabled, and if set to `0', the feature is disabled.
The following table shows the default name of the script for each
possible file types. (The source is the variable kpse_make_specs
in kpathsea/tex-make.c.)
These names are overridden by an environment variable specific
to the program—for example, DVIPSMAKEPK for Dvipsk.
If a mktex... script fails, the invocation is appended to a
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.
If the current directory is not writable and the environment variable or
configuration file value TEXMFOUTPUT is set, its value is
used. Otherwise, nothing is written. The name `missfont.log' is
overridden by the MISSFONT_LOG environment variable or
configuration file value.
The first argument to a mktex script is always the name of the file to be created.
In the default mktexpk implementation, additional arguments may also be passed:
mag variable.
This must match the combination of bdpi and dpi being used.
Besides the tests listed in Simple installation, you can try running `make check'. This includes the torture tests (trip, trap, and mptrap) that come with Web2c (see Triptrap).
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.
A TeX document, however, can write to arbitrary files, e.g., ~/.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 texmf.cnf. See tex invocation. MetaPost has the same issue.
Dvips, Xdvi, and TeX can also execute shell commands under some circumstances. To disable this, see the `-R' option in Option details, the xdvi man page, and tex invocation, respectively.
Another security issue arises because it's very useful—almost
necessary—to make arbitrary fonts on user demand with mktexpk
and friends. Where do these files get installed? By default, the
mktexpk distributed with Kpathsea assumes a world-writable
/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.
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 VARTEXFONTS
in texmf.cnf to refer to some globally known directory.
See mktex configuration.
The first restriction you can apply is to make newly-created directories under texmf be append-only with an option in mktex.cnf. See mktex configuration.
Another approach is to establish a group (or user) for TeX files,
make the texmf tree writable only to that group (or user), and
make 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.)
The mktex... 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.
Any directories created by the mktex... scripts have the
same permissions as their parent directory, unless the
appendonlydir feature is used, in which case the sticky bit is
always set.
This section describes the default installation hierarchy of the distribution. It conforms to both the GNU coding standards and the TeX directory structure (TDS) standard. For rationale and further explanation, please see those documents. The GNU standard is available as ftp://prep.ai.mit.edu/pub/gnu/standards/standards.texi and mirrors. The TDS document is available from CTAN:/tex-archive/tds (see unixtex.ftp).
You can change the default paths in many ways (see Changing search paths). One common desire is to put everything (binaries and all) under a single top-level directory such as /usr/local/texmf or /opt/texmf—in the terms used below, make prefix and texmf the same. For specific instructions on doing that, see configure scenarios.
Here is a skeleton of the default directory structure, extracted from the TDS document:
prefix/ installation root (/usr/local by default) bin/ executables man/ man pages include/ C header files info/ GNU info files lib/ libraries (libkpathsea.*) share/ architecture-independent files texmf/ TDS root bibtex/ BibTeX input files bib/ BibTeX databases base/ base distribution (e.g., `xampl.bib') misc/ single-file databases pkg/ name of a package bst/ BibTeX style files base/ base distribution (e.g., `plain.bst', `acm.bst') misc/ single-file styles pkg/ name of a package doc/ additional documentation dvips/ `.pro', `.ps', `psfonts.map' fonts/ font-related files type/ file type (e.g., `tfm', `pk') mode/ type of output device (types `pk' and `gf' only) supplier/ name of a font supplier (e.g., `public') typeface/ name of a typeface (e.g., `cm') dpinnn/ font resolution (types `pk' and `gf' only) metafont/ Metafont (non-font) input files base/ base distribution (e.g., `plain.mf') misc/ single-file packages (e.g., `modes.mf') pkg/ name of a package (e.g., `mfpic') metapost/ MetaPost input files base/ base distribution (e.g., `plain.mp') misc/ single-file packages pkg/ name of a package support/ support files for MetaPost-related utilities (e.g., `trfonts.map') mft/ `MFT' inputs (e.g., `plain.mft') tex/ TeX input files format/ name of a format (e.g., `plain') base/ base distribution for format (e.g., `plain.tex') misc/ single-file packages (e.g., `webmac.tex') local/ local additions to or local configuration files for format pkg/ name of a package (e.g., `graphics', `mfnfss') generic/ format-independent packages hyphen/ hyphenation patterns (e.g., `hyphen.tex') images/ image input files (e.g., Encapsulated PostScript) misc/ single-file format-independent packages (e.g., `null.tex'). pkg/ name of a package (e.g., `babel') web2c/ implementation-dependent files (.pool, .fmt, texmf.cnf, etc.)
Some concrete examples for most file types:
/usr/local/bin/tex
/usr/local/man/man1/xdvi.1
/usr/local/info/kpathsea.info
/usr/local/lib/libkpathsea.a
/usr/local/share/texmf/bibtex/bst/base/plain.bst
/usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
/usr/local/share/texmf/fonts/source/public/pandora/pnr10.mf
/usr/local/share/texmf/fonts/tfm/public/cm/cmr10.tfm
/usr/local/share/texmf/fonts/type1/adobe/utopia/putr.pfa
/usr/local/share/texmf/metafont/base/plain.mf
/usr/local/share/texmf/metapost/base/plain.mp
/usr/local/share/texmf/tex/plain/base/plain.tex
/usr/local/share/texmf/tex/generic/hyphen/hyphen.tex
/usr/local/share/texmf/web2c/tex.pool
/usr/local/share/texmf/web2c/tex.fmt
/usr/local/share/texmf/web2c/texmf.cnf
This
is ftp://ftp.tug.org/tex/unixtex.ftp, last updated 26 December
2003. Also available as http://www.tug.org/unixtex.ftp. The
IP address is currently [130.225.2.178]. It is also in
Kpathsea source distributions as etc/unixtex.ftp (although the
network version is usually newer). Mail tex-k@mail.tug.org
with comments or questions.
Following are general instructions for Unix or other sites who wish to acquire the Web2c distribution, (plain) TeX, LaTeX (2e), BibTeX, Metafont, MetaPost, DVI processors for the X window system, PostScript, the PCL language in the HP LaserJet, and related programs. They are oriented towards building from the original sources, though some information on alternative packages is included in the last section. See also http://www.tug.org/web2c/, the Web2c and Kpathsea home page.
Please note that the Web2c distribution is a bare-bones distribution in source form, and building a complete installation from it is a non-trivial matter. For most uses, it is a better idea to install a distribution with pre-packaged binaries for your platform. The principal example of such a distribution is TeX Live (http://www.tug.org/texlive/), which is based on the Web2c sources.
Please consider joining the TeX Users Group (TUG) or another user group of your choice to help support the maintenance and development of the programs you retrieve. See http://www.tug.org/join.html for information and the membership registration form, and http://www.tug.org/usergroups.html for a listing of all user groups.
For actual installation instructions after obtaining the necessary sources, see Installation. A copy is in the distribution file kpathsea/INSTALL.
In many places we refer to CTAN:. This is both a host name and a directory name. Here are the primary locations:
ftp://ctan.tug.org/tex-archive/ (Vermont, USA) ftp://ftp.dante.de/tex-archive/ (Germany) ftp://ftp.tex.ac.uk/tex-archive/ (England)
CTAN has many mirrors worldwide; see the top-level file README.mirrors from one of the sites above or see http://www.tug.org/CTAN.sites.
You can also access CTAN via the World Wide Web, electronic mail, or NFS. The same README.mirrors file explains how.
You will need to retrieve some or all of the following archives, depending on your needs (don't forget to set binary mode for file transfers):
Additional drivers, macro files, and other support are needed to build a working system. These are available in teTeX.
All that said, the originating host for the software above is ftp.tug.org. You can retrieve these distributions (but not much else) from the tex/ directory on that host.
Numerous organizations distribute various TeX CD-ROM's (and DVD's):
If you know of additional TeX distributions to add to this list, please inform tex-k@mail.tug.org.
Many other TeX implementations are available in CTAN:/systems, including ready-to-run distributions for Unix, Amiga, Acorn, VMS, Macintosh, DOS, and Windows (in various forms). Although Web2c has support in the source code for many operating systems, and in fact some of the other distributions are based on it, it's unlikely to work as distributed on anything but Unix. (Please contribute improvements!)
The principal user-oriented Unix distribution based on Web2c is the teTeX distribution. It includes complete sources, and runs on all modern Unix variants, including Linux. It contains many TeX-related programs besides those in the core Web2c.
The host labrea.stanford.edu is the original source for the files for which Donald Knuth is directly responsible: tex.web, plain.tex, etc. However, unless you want to build your TeX library tree ab initio, it is more reliable and less work to retrieve these files as part of the above packages. In any case, labrea is not the canonical source for anything except what was created by Stanford TeX project, so do not rely on all the files available at that ftp site being up-to-date.
(A copy of this chapter is in the file kpathsea/BUGS.)
If you have problems or suggestions, please report them to tex-k@mail.tug.org using the bug checklist below.
Please report bugs in the documentation; not only factual errors or inconsistent behavior, but unclear or incomplete explanations, typos, wrong fonts, ...
Before reporting a bug, please check below to be sure it isn't already known (see Common problems).
Bug reports should be sent via electronic mail to tex-k@mail.tug.org, or by postal mail to 135 Center Hill Road / Plymouth, MA 02360 / USA.
The general principle is that a good bug report includes all the information necessary for reproduction. Therefore, to enable investigation, your report should include the following:
make program you are using (the output of uname -a is a
start on the first two, though often incomplete). If the bug involves
the X window system, include X version and supplier information as well
(examples: X11R6 from MIT; X11R4 from HP; OpenWindows 3.3 bundled with
SunOS 4.1.4).
configure. This is recorded in the
config.status files.
If you are reporting a bug in `configure' itself, it's probably
system-dependent, and it will be unlikely the maintainers can do
anything useful if you merely report that thus-and-such is broken.
Therefore, you need to do some additional work: for some bugs, you can
look in the file config.log where the test that failed should
appear, along with the compiler invocation and source program in
question. You can then compile it yourself by hand, and discover why
the test failed. Other `configure' bugs do not involve the
compiler; in that case, the only recourse is to inspect the
configure shell script itself, or the Autoconf macros that
generated configure.
KPATHSEA_DEBUG
to `-1' before running the program. Please look at the log
yourself to make sure the behavior is really a bug before reporting it;
perhaps “old” environment variable settings are causing files not to
be found, for example.
GNU shar, available from ftp://prep.ai.mit.edu/pub/gnu is
a convenient way of packaging multiple (possibly binary) files for
electronic mail. If you feel your input files are too big to send by
email, you can ftp them to ftp://ftp.tug.org/incoming (that
directory is writable, but not readable).
NULL value being dereferenced, for
example), please send the details along. If the program involved is
TeX or Metafont, and the crash is happening at apparently-sound code,
however, the bug may well be in the compiler, rather than in the program
or the library (see TeX or Metafont failing).
Web2c and Kpathsea in general are discussed on the mailing list tex-k@mail.tug.org. To join, email tex-k-request@mail.tug.org with a line consisting of
subscribe you@your.preferred.email.address
in the body of the message.
You do not need to join to submit a report, nor will it affect whether you get a response. There is no Usenet newsgroup equivalent (if you can be the one to set this up, email `tex-k-request'). Traffic on the list is fairly light, and is mainly bug reports and enhancement requests to the software. The best way to decide if you want to join or not is read some of the archives from ftp://ftp.tug.org/mail/archives/tex-k/.
Be aware that large data files are sometimes included in bug reports. If this is a problem for you, do not join the list.
If you only want announcements of new releases, not bug reports and discussion, join tex-archive@math.utah.edu (via mail to tex-archive-request@math.utah.edu).
If you are looking for general TeX help, such as how to use LaTeX, please use the mailing list info-tex@shsu.edu mailing list, which is gatewayed to the `comp.text.tex' Usenet newsgroup (or post to the newsgroup; the gateway is bidirectional).
Kpathsea provides a number of runtime debugging options, detailed below by their names and corresponding numeric values. When the files you expect aren't being found, the thing to do is enable these options and examine the output.
You can set these with some runtime argument (e.g., `-d') to the program; in that case, you should use the numeric values described in the program's documentation (which, for Dvipsk and Xdvik, are different than those below). It's best to give the `-d' (or whatever) option first, for maximal output. Dvipsk and Xdvik have additional program-specific debugging options as well.
You can also set the environment variable KPATHSEA_DEBUG; in this
case, you should use the numbers below. If you run the program under a
debugger and set the variable kpathsea_debug, also use the numbers
below.
In any case, by far the simplest value to use is `-1', which will turn on all debugging output. This is usually better than guessing which particular values will yield the output you need.
Debugging output always goes to standard error, so you can redirect it easily. For example, in Bourne-compatible shells:
dvips -d -1 ... 2>/tmp/debug
It is sometimes helpful to run the standalone Kpsewhich utility (see Invoking kpsewhich), instead of the original program.
In any case, you can not use the names below; you must always use somebody's numbers. (Sorry.) To set more than one option, just sum the corresponding numbers.
KPSE_DEBUG_STAT (1)KPSE_DEBUG_HASH (2)KPSE_DEBUG_FOPEN (4)KPSE_DEBUG_PATHS (8)kpse_format_info_type structure defined in
tex-file.h.
KPSE_DEBUG_EXPAND (16)KPSE_DEBUG_SEARCH (32)KPSE_DEBUG_VARS (64)GSFTOPK_DEBUG (128)gsftopk program.
MAKETEX_DEBUG (512)mktex programs instead of the
traditional shell scripts, this will report the name of the site file
(mktex.cnf by default) which is read, directories created by
mktexdir, the full path of the ls-R database built by
mktexlsr, font map searches, MT_FEATURES in effect,
parameters from mktexnam, filenames added by
mktexupd, and some subsidiary commands run by the programs.
MAKETEX_FINE_DEBUG (1024)mktex programs are used, this will print
additional debugging info from functions internal to these programs.
Debugging output from Kpathsea is always written to standard error, and
begins with the string `kdebug:'. (Except for hash table buckets,
which just start with the number, but you can only get that output
running under a debugger. See comments at the hash_summary_only
variable in kpathsea/db.c.)
Kpathsea can record the time and filename found for each successful search. This may be useful in finding good candidates for deletion when your filesystem is full, or in discovering usage patterns at your site.
To do this, define the environment or config file variable
TEXMFLOG. The value is the name of the file to append the
information to. The file is created if it doesn't exist, and appended
to if it does.
Each successful search turns into one line in the log file: two words
separated by a space. The first word is the time of the search, as the
integer number of seconds since “the epoch”, i.e., UTC midnight 1
January 1970 (more precisely, the result of the time system
call). The second word is the filename.
For example, after setenv TEXMFLOG /tmp/log, running Dvips on
story.dvi appends the following lines:
774455887 /usr/local/share/texmf/dvips/config.ps
774455887 /usr/local/share/texmf/dvips/psfonts.map
774455888 /usr/local/share/texmf/dvips/texc.pro
774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk
774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk
774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
774455889 /usr/local/share/texmf/dvips/texc.pro
Only filenames that are absolute are recorded, to preserve some semblance of privacy.
Here are some common problems with configuration, compilation, linking, execution, ...
If a program complains it cannot find fonts (or other input files), any of several things might be wrong. In any case, you may find the debugging options helpful. See Debugging.
Unfortunately, Kpathsea's subdirectory searching has an irremediable deficiency: If a directory d being searched for subdirectories contains plain files and symbolic links to other directories, but no true subdirectories, d will be considered a leaf directory, i.e., the symbolic links will not be followed. See Subdirectory expansion.
You can work around this problem by creating an empty dummy subdirectory in d. Then d will no longer be a leaf, and the symlinks will be followed.
The directory immediately followed by the `//' in the path specification, however, is always searched for subdirectories, even if it is a leaf. Presumably you would not have asked for the directory to be searched for subdirectories if you didn't want it to be.
mktexpk (or
mktexmf or mktextfm) will try to create them. If
these rather complicated shell scripts fail, you'll eventually get an
error message saying something like `Can't find font
fontname'. The best solution is to fix (or at least report) the
bug in mktexpk; the workaround is to generate the necessary
fonts by hand with Metafont, or to grab them from a CTAN site
(see unixtex.ftp).
If your program takes an excessively long time to find fonts or other input files, but does eventually succeed, here are some possible culprits:
It is best to have only directories (and perhaps a README) in the upper levels of the directory structure, and it's very important to have only files, and no subdirectories, in the leaf directories where the dozens of TFM, PK, or whatever files reside.
In any case, you may find the debugging options helpful in determining precisely when the disk or network is being pounded. See Debugging.
Metafont outputs fonts in bitmap format, tuned for a particular device at a particular resolution, in order to allow for the highest-possible quality of output. Some DVI-to-whatever programs, such as Dvips, try to generate these on the fly when they are needed, but this generation may fail in several cases.
If mktexpk runs, but fails with this error:
mktexpk: Can't guess mode for nnn dpi devices.
mktexpk: Use a config file to specify the mode, or update me.