@c Copyright (C) 1992 Free Software Foundation.
@c This is part of the GNU font utilities manual.
@c For copying conditions, see the file fontutil.texi.

@node Installation, Overview, Introduction, Top
@chapter Installation

@cindex installation
@cindex configuration

@xref{Prereqs}, for what you need to have installed before you can
compile these programs.

After that, here's what to do:

@itemize @bullet

@item
Run @code{sh configure} in the top-level directory.  This tries to figure
out system dependencies and the installation prefix.  @xref{configure},
for options and other information about the @code{configure} script.

@flindex GNUmakefile@r{, editing}
@flindex include/c-auto.h@r{, editing}
@cindex search paths, defining default
@item
If necessary, edit the paths or other definitions in the top-level
@file{GNUmakefile} and in @file{include/c-auto.h}.

@item
Run GNU make.  For example, if it's installed as @file{make}, just type
@samp{make} in the top-level directory.  If all goes well, this will
compile all the programs.

@item
Install the programs and supporting data files with @code{make install}.

@end itemize

If you encounter problems anywhere along the line, let us know.  Known
problems are listed below (@pxref{Problems}).
@xref{Bugs}, for details on how to submit a useful bug report.

@menu
* configure::                   Options and frills for the `configure' script.
* Prereqs::                     What's needed before installation.
* Problems::                    Known trouble.
@end menu


@node configure, Prereqs,  , Installation
@section The @code{configure} script

@cindex prefix for installation directories
@cindex installation directories
@pindex configure @r{script, running}

@cindex MacKenzie, David
(This section is largely from the Autoconf manual, by David MacKenzie.
@xref{Running configure Scripts, , Running @code{configure} scripts,
autoconf, Autoconf}.)

@flindex aclocal.m4
The @code{configure} script that comes with the font utilities is
generated automatically by the Autoconf program.  You can regenerate
@code{configure} by rerunning Autoconf (for example, if a new version of
Autoconf is released); you must arrange for Autoconf to use the macros
in @file{./aclocal.m4} (@pxref{Generating configure, , Generating
@code{configure}, autoconf, Autoconf}).

The purpose of @code{configure} is to adapt the source code to your
system: for example, the name of the directory header file
(@file{dirent.h} or @file{sys/dir.h}), whether an @code{install} program
is available, and so on.

@vindex PATH@r{, @file{.} omitted from}
Normally, you do not need to give any options to @code{configure}; you
@code{cd} to the directory with the source code and type
@samp{configure}.  Exceptions: if @file{.} is not in your @code{PATH},
you must type @samp{./configure}; if you are using a
non-Bourne-compatible shell on some old systems, you must samp @samp{sh
configure}.

@pindex configure @r{output, suppressing}
@cindex verbose @code{configure} messages, suppressing
@cindex suppressing @code{configure} output
@flindex /dev/null
Running @code{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 @code{configure} with its standard output
redirected to @file{/dev/null}; for example, @samp{configure >/dev/null}.

@vindex VPATH
@cindex compilation in another directory
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
@code{VPATH} variable, such as GNU Make.  @code{cd} to the
directory where you want the object files and executables to go and run
@code{configure} with the option @samp{--srcdir=@var{dir}}, where
@var{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; @code{configure} automatically
checks for the source code in @file{..} if it does not find it in
@file{.}.

@pindex gcc@r{, location of used for installation}
@cindex installation prefix, default
@vindex prefix @r{Make variable}
@code{configure} guesses the default installation prefix (we'll call it
@code{$(prefix)}) by looking for the directory which contains the
command @code{gcc}, and using its parent.  For example, if @code{gcc} is
installed as @file{/usr/local/gnu/bin/gcc}, @code{$(prefix)} will be set
to @file{/usr/local/gnu}.

@opindex -prefix
@opindex -exec-prefix
@cindex architecture dependencies and installation
You can override this default guess for the installation prefix by giving
@code{configure} the option @samp{--prefix=@var{path}}.  You can also
specify separate installation prefixes for architecture-specific files
and architecture-independent files by giving @code{configure} the option
@samp{--exec_prefix=@var{xpath}}. Then @var{xpath} will be the prefix
for installing programs and libraries.  Data files and documentation
will still use the regular prefix.  Normally, all files are installed
using the regular prefix.

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

@code{configure} ignores any other arguments that you give it.

On systems that require unusual options for compilation or linking that
the package's @code{configure} script does not know about, you can give
@code{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:

@example
CC='gcc -traditional' LIBS=-lposix sh configure
@end example

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

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

@table @code

@vindex CC @r{variable for configuration}
@item CC
The C compiler program.  The default is @code{gcc} if that is in your
@code{PATH}, @code{cc} otherwise.

@vindex INSTALL @r{variable for configuration}
@item INSTALL
The program to use to install files.  The default is @code{install} if you
have it, @code{cp} otherwise.
@end table

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

@table @code
@vindex DEFS @r{variable for configuration}
@item DEFS
Configuration options, in the form @samp{-Dfoo -Dbar@dots{}}.  Packages
that use the Autoconf macro @code{AC_CONFIG_HEADER} (including the file
utilities) do not use this variable.

@vindex LIBS @r{variable for configuration}
@item LIBS
Libraries to link with, in the form @samp{-lfoo -lbar@dots{}}.
@end table

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


@node Prereqs, Problems, configure, Installation
@section Prerequisites

@cindex prerequisites to compilation

To compile and use these programs, the following are necessary:

@itemize @bullet

@pindex gcc
@cindex GNU C compiler
@item
The GNU C compiler, version 1.40 or newer.

@cindex GNU make
@pindex make
@item
GNU Make; probably any version newer than 3.50 or so will do.

@cindex X11 libraries
@cindex libraries, X11
@item
X11R4 or R5 unshared libraries and headers.  These are only necessary to
run XBfe (@pxref{XBfe}) or for Limn (@pxref{Limn}) to display its
results online.  (You also need an X11 server, naturally.)  You might be
able to compile using the X11 shared libraries, but we haven't tried
that.

@pindex gftopk
@pindex pltotf
@cindex Metafont
@cindex @TeX{}
@item
To make any substantial use of the fonts you create, you will probably
need @TeX{}, Metafont, and their friends, especially @code{PLtoTF} and
@code{GFtoPK}.

@cindex Ghostscript
@pindex gs
@item
Ghostscript, version 2.4 or newer.
You only need this if you want to use GSrenderfont or BZRedit.

@pindex gawk @r{prerequisite to GSrenderfont}
@item
The GNU Awk program, @code{gawk}.  This is only needed if you want to
use GSrenderfont.

@end itemize

See the section below for information on how to get all these programs.

@menu
* Archives::                    Where to find programs.
@end menu


@node Archives,  ,  , Prereqs
@subsection Archives

@cindex software archives
@cindex ftp archives
@cindex archives, software

@cindex GNU software, obtaining
@flindex prep.ai.mit.edu
The canonical source for all GNU software, including the GNU C compiler,
GNU make, and Ghostscript, is @file{prep.ai.mit.edu
[18.71.0.38]:pub/gnu}.  That directory is replicated at many other sites
around the world, including:

@table @asis

@item United States:
@example
  wuarchive.wustl.edu   gatekeeper.dec.com:pub/GNU
  uxc.cso.uiuc.edu      ftp.uu.net:packages/gnu
@end example

@item Europe:
@example
  archive.eu.net        src.doc.ic.ac.uk:gnu    ftp.funet.fi
  nic.funet.fi:pub/gnu  ugle.unit.no            isy.liu.se
  ftp.diku.dk
@end example

@item elsewhere:
@example
  ftp.cs.titech.ac.jp   utsun.s.u-tokyo.ac.jp:ftpsync/prep
  archie.au:gnu
@end example

@end table

@flindex DISTRIB
@cindex prices for GNU software
@cindex ordering GNU software
You can also order tapes with GNU software from the Free Software
Foundation (thereby supporting the development of the font utilities and
the rest of the GNU project); send mail to @samp{gnu@@prep.ai.mit.edu}
for the latest prices and ordering information, or retrieve the file
@file{DISTRIB} from a GNU archive.

@cindex X window system, obtaining
@flindex export.lcs.mit.edu
@flindex gatekeeper.dec.com
The canonical source for the X window system is
@file{export.lcs.mit.edu:pub/R5}.  That directory is also shadowed at
many other sites, including @samp{gatekeeper.dec.com}.  The FSF also
sells X distribution tapes.

@cindex @TeX{}, obtaining
@flindex byron.u.washington.edu
@TeX{} is more scattered.  A complete Unix @TeX{} distribution is
available for ftp on the machine @file{byron.u.washington.edu}, or by ordering a
tape from the University of Washington (send email to
@samp{elisabet@@u.washington.edu}.  What is on @file{byron} for
ftp is often out-of-date, though.

@pindex web2c
@flindex ftp.cs.umb.edu
@flindex ics.uci.edu
@flindex ftp.th-darmstadt.de
The canonical sources for just Web2C---the port of just @TeX{},
Metafont, and friends to Unix, without DVI processors, fonts, macro
packages, etc.---are:

@example
ftp.cs.umb.edu [192.12.26.23]:pub/tex/                  @r{(Boston)}
ics.uci.edu [128.195.1.1]:TeX/                          @r{(California)}
ftp.th-darmstadt.de [130.83.55.75]:pub/tex/src/web2c/   @r{(Germany)}
@end example

@flindex web.tar.Z
@flindex web2c.tar.Z
At all these sites, the files to retrieve are @file{web.tar.Z} and
@file{web2c.tar.Z}.

@pindex dvips
@pindex xdvi
@cindex Rokicki, Tom
@cindex Vojta, Paul
@flindex labrea.stanford.edu
The DVI-to-PostScript driver we recommend is Tom Rokicki's Dvips, and
the X window system driver we recommend is Paul Vojta's XDvi.  These
programs are available from, respectively,
@example
labrea.stanford.edu:pub/dvips*
export.lcs.mit.edu:contrib/xdvi.tar.Z
@end example

@cindex path searching
We have modified XDvi and Dvips to use the same path searching code as
the current distribution of @TeX{} and these font utilities; the
modified versions are available from @file{ftp.cs.umb.edu:pub/tex}.

@flindex modes.mf
@cindex Metafont modes
To use Metafont, you must have a file defining output devices.
(@xref{Metafont and BZRto}.)  We recommend you obtain @file{modes.mf}
from
@example
ftp.cs.umb.edu:pub/tex/modes.mf
@end example

@flindex fontname.texi
@cindex naming scheme for @TeX{} fonts
@cindex filenames for fonts
You can retrieve the document describing all the details of the naming
scheme for @TeX{} fonts from

@example
ftp.cs.umb.edu [192.12.26.23]:pub/tex/fontname.tar.Z
@end example


@node Problems,  , Prereqs, Installation
@section Problems

@cindex problems in installation
@cindex trouble in installation
@cindex installation problems

This section lists some things which have caused trouble during
installation.  If you encounter other problems, please send a bug
report.  @xref{Bugs}, for how to submit a useful bug report.

@itemize @bullet

@opindex -static
@cindex static linking, warning about
@item
You may get a warning from the compiler about @samp{-static} being an
unrecognized option.  Ignore it.  (This has already been reported to
@samp{bug-gcc}.)

@cindex dynamic linking
@cindex static linking vs.@: dynamic linking
@cindex linking, dynamic
@cindex SunOS linking
@pindex /bin/ld
@item
Under SunOS 4.x, the programs which use X (XBfe and Limn) cannot be
dynamically linked, because (apparently) @file{/bin/ld} pulls in the
entire @file{.sa} file, and the Form, Label, and Viewport widgets are
multiply defined.  (To us, this seems to defeat the whole purpose of
having libraries.  It also seems bizarre to us that X was written so
that these multibyte functions are always needed (via
@code{__Xsi@dots{}}), and furthermore that the multibyte functions need
to specifically call the dynamic linking functions.)

@findex dlsym
@findex dlclose
@findex dlopen
The file @file{lib/dlsym.c} (from the MIT X distribution) defines the
@code{dlsym}, @code{dlclose}, and @code{dlopen} symbols, so static
linking should work now.

@cindex Xaw library, linking with
If the current setup fails, it might work to change @samp{-lXaw} in
the definition of @code{X_libraries} in @file{lib/defs.make} to
the full pathname of the Xaw library.

@cindex GCC crash
@cindex compiler crash
@flindex imageto/main.c
@item
On many machines (Sun 3 or Sun 4 running SunOS 4.1, Sun386i running
4.0.2, 386 running ISC 2.2), GCC 1.40 gets a fatal error compiling
@file{imageto/main.c} with @samp{-O}.  Just use @samp{-g} for that file,
or use a newer version of GCC.

@flindex math.h@r{, wrong}
@findex fmod@r{, wrong prototype for}
@cindex Interactive Unix
@item
On a 386 running Interactive UNIX 2.2, @file{<math.h>} declares the
wrong prototype for @code{fmod}: the routine takes two doubles, not one.
We simply corrected our system include file.

@findex XtIsRealized
@findex XtWindowOfObject
@vindex NULL
@cindex warnings in @file{Bitmap.c}
@cindex compiler warnings in @file{Bitmap.c}
@flindex Bitmap.c
@flindex widgets/Bitmap.c
@flindex IntrinsicP.h
@flindex X11/IntrinsicP.h
You may get compiler warnings for the file @file{widgets/Bitmap.c} at
the lines which use the Xt function @code{XtIsRealized} on systems which
define @code{NULL} as @code{(void *) 0}.  The reason is that macro
definition of @code{XtIsRealized} in @file{<X11/IntrinsicP.h>}
incorrectly compares the result of @code{XtWindowOfObject} to
@code{NULL}, instead of @code{0}.  If the warnings bother you, fix
@file{IntrinsicP.h}.

@flindex XBfe @r{resource file}
@cindex XBfe failing
@cindex Limn online display failing
@flindex Limn @r{resource file}
@cindex X programs failing
@cindex X resources unrecognized
@cindex application resources, under X
@vindex XAPPLRESDIR
@item
The application resource files @file{limn/Limn} and @file{xbfe/XBfe}
must be installed in a directory where your X server can find them.
This directory varies according to how X was installed; in the default X
distribution, it is @file{/usr/lib/X11/app-defaults}.  If you cannot (or
do not want to) write in the default directory, you can install them
elsewhere and set the @code{XAPPLRESDIR} environment variable to that
directory.  See the tutorial on resources that comes with the MIT X
distribution (@file{mit/doc/tutorial/resources.txt}) for more
information.

@end itemize

Good luck.
