Copyright 1997-2018 Free Software Foundation, Inc.

    Copying and distribution of this file, with or without modification,
    are permitted in any medium without royalty provided the copyright
    notice and this notice are preserved.

This file contains information that supplements the generic
installation instructions in file `INSTALL'.


Normal Installation
===================

The simplest way to compile groff is:

  1. `cd' to the directory containing groff's source code and type
     `./configure' to configure groff for your system.  If you are
     using `csh' on an old version of System V, you might need to type
     `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile groff.

  3. Type `sudo make install' to install the groff programs and any
     data files and documentation.  `make install' is the only step for
     which you need `root' access; this is done by `sudo'.

  4. You can remove the groff binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile groff for
     a different kind of computer), type `make distclean'.


External Installation
=====================

It is also possible to perform the whole installation process outside
of the source code directory.  In this case a whole external build
directory structure is created without changing any parts of the source
code tree.  This is useful if the source code is read-only or if
several different installations, such as for multiple architectures,
should be constructed.

As an example we assume that the source code of the `groff' code is in
`/usr/local/src/groff', and that the build process should be done
within the directory `/home/my/groff.compile'.

  0. Create `/home/my/groff.compile' and change to that directory.

  1. Call `/usr/local/src/groff/configure' in that directory to
     configure groff for your system.  If you are using `csh' on an old
     version of System V, you might need to type `sh
     /usr/local/src/groff/configure' instead.

  2. Type `make' to compile groff in that directory.

  3. Type `sudo make install' to install the groff programs and any
     data files and documentation.

  4. You can remove the groff binaries and object files from the
     build directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.


Special Platforms
=================

For instructions how to build groff with DJGPP tools for MS-DOS and
MS-Windows, see the file arch/djgpp/README.

For instructions how to build groff with the MinGW tools for
MS-Windows, see the file README.MinGW.


Dependencies
============

groff is written in C++, so you need a C++ compiler.  The C++ source
files use a suffix of `.cpp', so your C++ compiler must be able to
handle this.  If you don't already have a C++ compiler, we suggest gcc
2.7.1 or later (gcc version 2 includes GNU C++ as well as GNU C).  From
gcc 2.5, it is no longer necessary to install libg++: the C++ header
files needed by groff are created by the gcc installation process.  To
override configure's choice of C++ compiler, you can set the CXX
environment variable.

If you have a library that provides a faster malloc than your system's
usual malloc, it is good idea to include it in LIBS.  For example,
using the malloc that comes with GNU Emacs version 20 can give a
worthwhile (and sometimes spectacular) performance improvement.

Many programs within the `groff' system are written in the Perl
language.  So you need a `perl' program with the least version of
`v5.6.1'.

In order to build the documentation you would need `makeinfo' from the
'texinfo' package, in fact `configure' will fail if this program is
not found unless you pass the option `with-doc=no'.

The `uchardet' library is an optional dependency of the `preconv'
program: if this library is found by `configure' it will be
automatically used by `preconv'.  In order to discover the presence of
the `uchardet' library you would also need to have the `pkg-config'
program installed on your system.


Miscellaneous
=============

If you want A4 or letter paper format and the configure script produces
an incorrect guess, say

  PAGE=xxx ./configure

where `xxx' should be either `A4' or `letter'.  Note that this only
affects the paper selection of some device drivers like grops (which
can be still overridden on the command line).  For compatibility with
ditroff, the default page length in gtroff is always 11 inches.  The
page length can be changed with the `pl' request.

When you have built groff but not installed yet, you can use the
test-groff script to try groff out on one of the man pages.  (Use the
.n files not the .man files.)  The test-groff script sets up environment
variables to allow groff to run without being installed.  For example,
you could do

  ./test-groff -man -Tascii src/roff/groff/groff.n | less

to display the groff(1) man page with the `less' pager.

To get a DVI, PDF, or HTML version of the groff texinfo manual, say
`make groff.dvi', `make groff.pdf', or `make groff.html', respectively,
in the `doc' subdirectory (after configuring the groff package).  Note
that you need texinfo version 4.8 as a prerequisite.

If you have problems, read the PROBLEMS file.  If this doesn't help
and you need support, please contact the `groff' mailing list.  If you
think that you have found a bug, please submit a report in our bug
tracker at

  https://savannah.gnu.org/projects/groff

##### Emacs settings
Local Variables:
mode: text
End: