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 file contains information that supplements the generic installation
instructions in file 'INSTALL'.  It is meant for people building
directly from the development repository, rather than a release or
snapshot tarball.

If you want to start compiling the 'groff' system with an existing
'configure' script, you won't need the information in this file.  You
need it only if you want to build groff from its Git repository.

1. Initial build
----------------

You will need autoconf version 2.68 or higher and automake version
1.12.2 or higher.  These minimal versions are set in the bootstrap.conf
file.

On operating systems supporting concurrent installation of multiple
versions of the 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 also need to have 'pkg-config' installed on your system.

First invoke the bootstrap script.

    $ ./bootstrap

This will:

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

  - invoke autoreconf that will call the GNU Autotools ('aclocal',
    'autoconf', 'automake') in the right order for creating 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.

At this point you can 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 in the source tree.

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

You can also build groff outside of its source tree, which is cleaner.

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

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

    $ make install # run with 'sudo' if necessary

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

    $ make check # run with -j option if desired

Running these tests after building any substantive change to groff logic
is encouraged.


2. Guide to usage of 'automake' in groff
----------------------------------------

A document explaining the basics of automake and its usage in groff is
available in 'doc/automake.mom'; a PDF rendering is built but not
installed, since it is a developer-facing discussion.

Peruse it in 'doc/automake.pdf' in your build tree.


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