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'.
     *Note 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 *Note Bugs::.)

The `configure' script
======================

  (This section is largely from the Autoconf manual, by David MacKenzie.
*Note Running `configure' scripts: (autoconf)Running configure Scripts.)

  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 (*note
Reporting Bugs: (gcc)Bugs.) 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.

