Copyright 2013-2022 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 information supplements the generic installation instructions in
the file 'INSTALL'.  It is meant for people building from the
development repository, rather than a distribution archive.
Distribution archives include a 'configure' script, among other files;
the repository does not.  If you want to start building the 'groff'
system using an existing 'configure' script, you don't need the
information in this file.

Dependencies
------------

The dependencies documented in the 'INSTALL.extra' file are required, as
are several others.

* You will need Autoconf version 2.68 or higher and Automake version
  1.12.2 or higher.  These requirements are asserted in the
  'bootstrap.conf' file.

  On operating systems supporting concurrent installation of multiple
  versions of the GNU Autotools, set environment variables as in the
  following example, adjusting the version numbers as required.

    $ export AUTOMAKE_VERSION=1.14
    $ export AUTOCONF_VERSION=2.69

* You will need a 'yacc' program.  We recommend Berkeley yacc ('byacc')
  or GNU Bison ('bison').

* groff's Texinfo manual is generated in several formats: GNU Info,
  HTML, plain text, TeX DVI, and PDF.  The former three require
  'makeinfo' from GNU Texinfo 5.0 or later.  The latter two additionally
  require a TeX installation, such as TeX Live.  If TeX is not
  installed, the DVI and PDF formats of the manual cannot be generated.
  This will cause a build failure only if the Texinfo source file
  "groff.texi" is updated and the make(1) "dist" or relevant file
  targets are manually specified.

* You will need the 'xpmtoppm', 'pnmdepth', and 'pnmtops' programs from
  the Netpbm distribution.


Bootstrapping from a Git checkout
---------------------------------

Invoke the bootstrap script.

    $ ./bootstrap


What bootstrapping does
-----------------------

The foregoing procedure will do two things:

  - clone the gnulib repository as a Git submodule in 'gnulib', add the
    needed gnulib source files in 'lib' as well as required gnulib m4
    macros in 'gnulib_m4'; and

  - invoke 'autoreconf', which will call the GNU Autotools ('aclocal',
    'autoconf', 'automake') in the right order to create the following
    files.

    -- INSTALL (a symlink to gnulib's INSTALL file)
    -- Makefile.in
    -- aclocal.m4
    -- autom4te.cache/
    -- build-aux/ (which contains all the helper scripts)
    -- configure
    -- src/include/config.hin

'aclocal.m4' is a generated file; groff's m4 macros are included via the
'acinclude.m4' file.


Building
--------

You can now invoke the 'configure' script.  It produces the
'config.status' script, which generates the Makefile.  Then call 'make'
to build the groff project.  You can do these from the source tree.

    $ ./configure
    $ make # run with -j option if desired

You can alternatively build groff outside of its source tree, which is
cleaner, leaving fewer files to confuse 'git status' if you aim to
undertake development.

    $ mkdir build
    $ cd build
    $ ../configure
    $ make # run with -j option if desired

A separate build tree need not be a subdirectory of the source.


Evaluation
----------

Several dozen sanity checks can be performed within the build tree.

    $ make check # run with -j option if desired


Installation
------------

When the build is finished you can install the groff build artifacts.

    $ make install install-doc # run with 'sudo' if necessary


Uninstalling
------------

See "Uninstalling" in the 'INSTALL.extra' file.


Rebuilding
----------

Start over from "Building" above.


##### Editor settings
Local Variables:
fill-column: 72
mode: text
End:
# vim: set autoindent textwidth=72: