Installation
************

Here are the basic steps for configuration and installation:

 1. configure.  This automatically determines most system dependencies.

 2. If necessary, edit the definitions in Makefile or c-auto.h. See System dependencies, below, for additional definitions you may need to make.

 3. make.

 4. make install. This installs the library, header files, and documentation.

 5. make distclean.  This removes all files created by the build.

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.

System dependencies
===================

Although configure can reliably determine most aspects of your system, there are a few things it does not do.

Default paths
-------------

The directories into which files are installed are defined in the top-level Makefile. The default paths which programs use to search for inputs are defined in kpathsea/paths.h.  You will almost certainly want to change either or both of these to match your preferred local directory structure.

Both of these files are automatically created: the Makefile at configure time, kpathsea/paths.h at compile time. Thus, to change the default paths, the simplest thing to do is edit the template files Makefile.in and paths.h.in before running configure.

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

The file kpathsea/HIER has some explanation of the default setup.

A caveat: If you put $HOME or ~ in any of the paths, do not search that component recursively: when you run as root, you might wind up searching (say) /zoneinfo/Brazil/tex/macros. And of course it will take quite some time to look at every directory on the system.

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. This is reported to be necessary on Linux.

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, compiling with GCC. This seems an impossible task.

The X11R5 <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>.  Result: conflicting definitions.

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.

putenv
------

If you are on a Net2/BSD or other system which has a putenv that knows how to avoid garbage when the same environment variable is set many times, define SMART_PUTENV. (And if you can write a test for this that could be incorporated into the configure script, please send it to the address given in Bugs.)

The configure script
====================

(This section is largely from the Autoconf manual, by David MacKenzie. See Running configure scripts (Autoconf).)

The configure script that comes with this distribution was generated by the Autoconf program.  Thus, you can regenerate configure by rerunning Autoconf.  You might want to do this if a new version of Autoconf is released, for example.

The purpose of configure is to adapt the present source to the particulars of your system.  For example, the name of the directory header file (dirent.h or sys/dir.h), whether the GNU C compiler gcc is available, and so on.

Normally, you do not need to give any options to configure; just cd to the directory with the source code and type configure.  Exceptions: if . is not in your PATH, you must type ./configure; if you are using a non-Bourne compatible shell on systems that do not support #!, you must type sh configure.

Running configure takes a minute or two.  While it is running, it prints some messages that tell what it is doing.  If you don't want to see the messages, run configure with its standard output redirected to /dev/null; e.g., configure >/dev/null. On the other hand, if you want to see even more messages, give configure the -v option.

To compile the package in a different directory from the one containing the source code, you must use a variant of Make that supports the VPATH variable, such as GNU Make.  cd to the directory where you want the object files and executables to go and run configure with the option --srcdir=DIR, where DIR is the directory that contains the source code.  Using this option is unnecessary if the source code is in the parent directory of the one in which you are compiling; configure automatically checks for the source code in .. if it does not find it in ..

configure (in the top-level directory) guesses the default installation prefix (we'll call it $(prefix), which is the corresponding Make variable) by looking for a directory which contains an executable named tex, and using its parent.  In the package subdirectories, such as kpathsea, configure doesn't try to guess the prefix (to avoid a conflict with the guess made at the top level); the default /usr/local is left.

You can override this default guess for the installation prefix by giving configure the option --prefix=PATH.  You can also specify separate installation prefixes for architecture-specific files and architecture-independent files by giving configure the option --exec-prefix=XPATH (which substitutes for the Make variable $(exec_prefix)).  Then XPATH will be the prefix for installing programs and libraries.  Data files and documentation will still use $(prefix).

You can tell configure to figure out the configuration for your system, and record it in a file config.status, without actually configuring the package.  To do this, give configure the --no-create option.  Later, you can run ./config.status to actually configure the package.  This option is useful mainly in Makefile rules for updating config.status and the Makefile itself.  You can also give config.status the --recheck option, which makes it rerun configure with the same arguments you used before.  This is useful if you change configure.

configure ignores any other arguments that you give it.

On systems that require unusual options for compilation or linking that the package's configure script does not know about, you can give configure initial values for variables by setting them in the environment.  In Bourne-compatible shells, you can do that on the command line like this:

     CC='gcc -traditional' LIBS=-lposix sh configure

The Make variables that you might want to override with environment variables when running configure are:

(For these variables, any value given in the environment overrides the value that configure would choose.)

CC
     The C compiler program.  The default is gcc if that is in your PATH, cc otherwise.

INSTALL
     The program to use to install files.  The default is install if you have it, cp otherwise.

(For these variables, any value given in the environment is added to the value that configure chooses.)

DEFS
     Configuration options, in the form -Dfoo -Dbar....

LIBS
     Libraries to link with, in the form -lfoo -lbar....

Of course, problems requiring manual intervention (e.g., setting these variables) should ideally be fixed by updating either the Autoconf macros or the configure.in file for that package.

Reporting bugs
==============

If you encounter problems, 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 YOUR-PREFERRED-EMAIL-ADDRESS

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

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

When compiling with old C compilers, you may get some warnings about ``illegal pointer combinations''.  These are spurious; ignore them.  I do not want 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.