Go to the first, previous, next, last section, table of contents.


2. Installation

Here are the basic steps for configuration and installation:

  1. Edit the file `make/paths.make' if you want to make changes to the installation directories or paths that will have effect across different runs of configure. Alternatively, override the Make variables on the command line when you run Make. Exception: to reliably change the top-level `prefix', you must give `configure' the option `-prefix=prefix', instead of changing the value in `paths.make'.
  2. Edit `kpathsea/texmf.cnf.in' to change the local paths to match your local setup. See section `Default paths' in Kpathsea, for more details on changing the paths. A copy is in `kpathsea/INSTALL'. See `kpathsea/HIER' for an explanation of the default setup. If the paths do not match where the files actually are, the programs will probably start up Very, Very, Slowly, and/or not be able to find the fonts or other input files.
  3. sh configure (in the top-level directory). This makes system-dependent `#define's' in `*/c-auto.h' (from the corresponding `c-auto.h.in') and creates a `Makefile' (from the corresponding `Makefile.in', by doing `@var@' and `ac_include' substitutions). Perhaps the most common desire is to compile with optimization instead of or as well as debugging. You can change the options passed to the compiler by changing `CFLAGS', either for configure or make. For example:
    prompt$ env CFLAGS="-g -O" configure
    prompt$ make
    or
    prompt$ configure
    prompt$ make CFLAGS="-g -O"
    
    See section `Running configure scripts' in Autoconf, for detailed configure options. (A copy is in `kpathsea/CONFIGURE'.)
  4. make (still in the top-level directory). Barring configuration and compiler bugs, this will compile all the programs. See section `Common problems' in Kpathsea, for system-dependent problems (this section is also in `kpathsea/INSTALL'). This also creates the `texmf.cnf' and `paths.h' files that define the default search paths.
  5. make install. This installs the library, header files, and documentation. Or make install-data to just install the architecture-independent files. Or make install-exec to just install the (binary) archive library file. Since I only distribute Kpathsea as part of another package, you will probably be doing the above in a top-level directory that contains a `Makefile', `kpathsea', and the other package. But you can do the installation in `kpathsea' itself, if you only want to install the library, not the other package.
  6. The first time you install any manual in Info, you have to add a line (you choose where) to the `dir' file in your `$(infodir)' directory. A sample line to add is given near the top of the Texinfo source files (`kpathsea/kpathsea.texi' and `dvipsk/dvips.texi').
  7. make distclean. This removes all files created by the build.

See section 4.7 Filename database (ls-R), for a description of an externally-generated database that can help speed searches.

See section 3. Debugging, for runtime debugging support that may help track down problems.

Do not attempt to use any version of Kpathsea with any program except the version that the program came with, unless you are a glutton for punishment.

2.1 Default paths

To summarize the chain of events that go into defining the default paths:

  1. `configure' creates a `Makefile' from each `Makefile.in'.
  2. When Make runs in the `kpathsea' directory, it creates a file `texmf.sed' that substitutes the Make value of $(var) for a string @var@. The variables in question are the one that define the installation directories.
  3. `texmf.sed' (and a little extra magic--see `kpathsea/Makefile') is applied to `texmf.cnf.in' to generate `texmf.cnf'. This is the file that will eventually be installed and used by the programs to look up programs.
  4. The definitions in `texmf.cnf' are changed into the form of C `#define''s, producing `paths.h'. These values will be the compile-time defaults; they are not used unless no `texmf.cnf' file can be found at runtime. (That's a partial lie: the compile-time defaults are what 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.)

The purpose of this elaborate sequence is to avoid having the same information in more than one place. If you change the installation directories or top-level prefix before running `configure', those changes will propagate through the whole sequence. If you change the default paths in `texmf.cnf.in', those changes are propagated to the compile-time defaults.

Alternatively, you can ignore the whole mess and edit `texmf.cnf' after it is installed. Maybe even copying it into place beforehand so you can complete the installation, if TeX or Metafont is having trouble finding their input files.

Unfortunately, editing `Makefile.in' does not work in one common case--changing the prefix or exec_prefix variables. For these, you must use the `-prefix' or `-exec-prefix' options to configure. See section `Running configure scripts' in Autoconf. (That's another partial lie: editing does work, as long as a program named tex is not in your PATH.)

See section 6. TeX directory structure, for a description of some ways to arrange the TeX library files, and some features of the distributed paths that may not be obvious. The file `kpathsea/HIER' is a copy of that section.

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 potentially run Make in the subdirectories.)

2.2 Common problems

Some common problems with compilation, linking, or execution are described below.

2.2.1 Unable to find files

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 in determining precisely where the fonts (or whatever) are being looked for. See the program's documentation for its debugging options, and also see section 3. Debugging.

2.2.2 Slow path searching

If your program takes an excessively long time to find fonts or other input files, but does eventually succeed, here are some possible culprits:

In any case, you may find the debugging options helpful in determining precisely when the disk or network is being pounded. See section 3. Debugging, and also see the program's documentation.

2.2.3 XtInherit

On DEC OSF/1 1.x systems, the loader has a bug that manifests itself in the following error (all on one line, but for the sake of the paper width it's broken here):

xdvik/xdvi: /sbin/loader: Fatal Error: search_for_undefineds: 
     symbol _XtInherit should not have any relocation entry

According to Michael Rickabaugh `<mjr@quarry.enet.dec.com>':

This is a bug fixed in DEC OSF/1 2.0.

If you know how, installing `/sbin/loader' from a 2.0 system onto a
1.3 system will work.  Make sure that `/usr' is not mounted
when you do this.  (If you forget about umounting /usr, it is
possible most of your filesystems will become corrupted.)

Otherwise, I suggest getting a hold of a 2.0 CD and running
`/usr/sbin/installupdate'.

Alternatively, you may be able to use the freely available X11 libraries that come with the MIT distribution (on `ftp.x.org', for example).

Linking statically, perhaps only with some of the X libraries, may also work. (if you find the definitive workaround, please let me know.)

2.2.4 wchar_t

The upshot of all the following is that if you get error messages regarding wchar_t, try defining NO_FOIL_X_WCHAR_T (for Web2c) or FOIL_X_WCHAR_T (for everything else).

wchar_t has caused infinite trouble. None of my code ever uses wchar_t; all I want to do is include X header files and various system header files, possibly compiling with GCC. This seems an impossible task!

The X11 header `<Xlib.h>' and GCC's `<stddef.h>' have conflicting definitions for wchar_t.

The particulars: `<X11/Xlib.h>' from MIT X11R5 defines wchar_t if X_WCHAR is defined, which is defined if X_NOT_STDC_ENV is defined, and we define that if STDC_HEADERS is not defined (`configure' decides if STDC_HEADERS gets defined). But when compiling with gcc on SunOS 4.1.x, STDC_HEADERS is not defined (`string.h' doesn't declare the `mem'* functions), so we do get X's wchar_t---and we also get gcc's wchar_t from its `<stddef.h>'. Conflict.

On the other hand, SunOS 4.1.1 with some other X configurations actually needs GCC to define wchar_t, and fails otherwise.

My current theory is to define wchar_t to a nonsense symbol before the X include files are read; that way its definition (if any) will be ignored by other system include files. Going along with that, define X_WCHAR to tell X not to use `<stddef.h>', that we've already included, but instead to make its own definition.

But this is not the end of the story. The X11 include files distributed with DG/UX 5.4.2 for the Aviion have been modified to include `<_int_wchar_t.h>' if X_WCHAR, so our #define will not have any typedef to change--but the uses of wchar_t in the X include files will be changed to reference this undefined symbol. So there's nothing to foil in this case. I don't know how to detect this automatically, so it's up to you to define NO_FOIL_X_WCHAR_T yourself.

2.2.5 ShellWidgetClass

This section is adapted from question 47 from the `comp.sys.sun.admin' FAQ.

If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x, you may get undefined symbols _get_wmShellWidgetClass and _get_applicationShellWidgetClass. This problem does not arise with the standard MIT libraries under SunOS.

The cause is bugs in the Xmu shared library as shipped from Sun. There are several fixes:

Here is the information for getting the two patches:

Patch ID: 100512-02
Bug ID's: 1086793, 1086912, 1074766
Description: 4.1.x OpenWindows 3.0 libXt jumbo patch

Patch ID: 100573-03
Bug ID: 1087332
Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared
libXmu.

The way to statically link with libXmu depends on whether you are using a Sun compiler (e.g., cc) or gcc. If the format, alter the x_libs make variable to include

-Bstatic -lXmu -Bdynamic

If you are using gcc, include `-static' in `LDFLAGS'; this will link all libraries statically. If you want to link only Xmu statically and everything else dynamically, you have to do it by hand: run gcc -v, grab the ld line, and add the `-B''s given above around -lXmu.

The reason is that gcc moves all linker options to the front of the ld command line. So you can't specify different options for different libraries. When I reported this to the GCC maintainers, the reply was that they would happily merge in the changes, but they didn't want to take the time to do it themselves.

2.2.6 Pointer combination warnings

When compiling with old C compilers, you may get some warnings about "illegal pointer combinations". These are spurious; just ignore them. I decline to clutter up the source with casts to get rid of them.

In general, if you have trouble with a system C compiler, I advise trying the GNU C compiler. (And vice versa, unfortunately; but in that case I also recommend reporting a bug to the GCC bug list.)

2.3 Shared library

You can compile Kpathsea as a shared library. The advantage in doing this is that the different executables can then share the code, decreasing memory usage. (The other advantage in general of shared libraries is that it's possible to update the library and programs independently. But since the Kpathsea interface is not and can not be frozen, that doesn't apply here.)

Under Solaris, use `-K pic -xstrconst' if you compile with a Sun compiler, `-fpic' if you use GCC. Also add `-L$(libdir) -R$(libdir)' to `LDFLAGS' when you link the binaries, so that the library can be found, and users do not have set `LD_LIBRARY_PATH'.

(If you know how to make Kpathsea shared on other systems, please send a message to the bug address in the next section.)

2.4 Reporting bugs

If you encounter problems, please report them to `tex-k@cs.umb.edu'. Include the version number of the library, the system you are using, and enough information to reproduce the bug in your report. To get on this mailing list yourself, email `tex-k-request@cs.umb.edu' with a message whose body contains a line

subscribe you@your.preferred.address

To avoid wasted effort and time (both mine and yours), I strongly advise applying the principles given in the GNU C manual (see section `Reporting Bugs' in The GNU CC manual) to your bug reports.

Please also report bugs in this documentation--not only factual errors, but unclear explanations, typos, wrong fonts, ...


Go to the first, previous, next, last section, table of contents.