path: root/doc/automake.mom

.\" -*- mode: text; coding: utf-8; -*-
.\"
.\" Copyright ©2014 - 2022 Free Software Foundation
.\" 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
.\"
.\" Permission is hereby granted, free of charge, to any person
.\" obtaining a copy of this software and associated documentation
.\" files (the "Software"), to deal in the Software without restriction,
.\" including, without limitation, the rights to use, copy, modify,
.\" merge, publish, distribute, sublicense, and sell copies of
.\" the Software, and to permit persons to whom the Software is
.\" furnished to do so, subject to the following conditions:
.\" 
.\" The above copyright notice and this permission notice shall be
.\" included in all copies, or substantial portions, of the Software;
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
.\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
.\" NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
.\" HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
.\" WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
.\" FROM, OUT OF, OR IN CONNECTION WITH, THE SOFTWARE, OR THE USE OF,
.\" OR OTHER DEALINGS IN, THE SOFTWARE.
.\"
.\"  Formatted with the mom macros
.\" .RW (reduce) and .EW (expand) control track kerning
.\" .WS controls word spacing
.\"  Hanging punctuation and hyphens are inserted manually
.\"
.TITLE     "Using Automake in the Groff project"
.AUTHOR    "Bertrand Garrigues"
.COPYRIGHT "2014, 2017 Free Software Foundation"
.COVER     TITLE AUTHOR DOCTYPE COPYRIGHT
.
.PAPER      LETTER
.PRINTSTYLE TYPESET
.
.HEADING_STYLE 1 NUMBER
.HEADING_STYLE 2 NUMBER
.HEADING_STYLE 3 NUMBER
.HEADING_STYLE 4 NUMBER
.
.QUOTE_INDENT 2m
.CODE_FONT CB
.
\# Table of contents
.TOC_PADDING 2
.SPACE_TOC_ITEMS
.AUTO_RELOCATE_TOC
.TOC_ENTRY_STYLE 2 FONT I
.TOC_LEAD 14
.
.NO_SHIM \" Flex-spaced
.
.START
.
.PP
This is a quick overview of how to use `automake' in the groff
project, and is intended to help the developers and contributors
find their way when they have to make changes to the sources files
or to the data that are installed.  If you need more details on
`automake', here are some reading suggestions:
.
.LEFT
.SP 3p
.
.LIST
.SHIFT_LIST 1m
.ITEM
The Automake Manual:
\*[FWD 1m]\c
.PDF_WWW_LINK https://www.gnu.org/software/automake/manual/automake.html
.SP 3p
.ITEM
A book by John Calcote, with good practical examples:
\*[FWD 1m]\c
.PDF_WWW_LINK http://fsmsh.com/2753
.SP 3p
.ITEM
This site, by Diego Petteno, with good practical examples too:
\*[FWD 1m]\c
.PDF_WWW_LINK https://autotools.io/index.html
.LIST OFF
.
.JUSTIFY
.HY DEFAULT
.
.HEADING 1 "Overview, the initial build"
.
.HEADING 2 "First build"
.
.PP
Groff integrates the `gnulib' and uses its `bootstrap' script.  When
compiling from the git repository, you should first invoke this
script:
.QUOTE
.CODE
$ ./bootstrap
.CODE OFF
.QUOTE OFF
This will:
.
.QUAD LEFT
.HY OFF
.
.LIST
.SHIFT_LIST 1m
.ITEM
.SP 3p
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'.
.SP 3p
.ITEM
Invoke autoreconf that will call all the `GNU autotools' (`aclocal',
`autoheader', `autoconf', `automake') in the right order for
creating the following files:
.LIST DASH
.SHIFT_LIST .5m
.SP 3p
.ITEM
INSTALL (a symlink to gnulib's INSTALL file)
.ITEM
Makefile.in
.ITEM
aclocal.m4
.ITEM
autom4te.cache/
.ITEM
build-aux/ (that contains all the helper scripts) 
.ITEM
configure
.ITEM
src/include/config.hin
.LIST BACK
.LIST OFF
.
.SP 3p
.JUSTIFY
.HY DEFAULT
.
.WS +2
.EW .5
The file aclocal.m4 is generated and the groff m4 macros are
included via the acinclude.m4 file.
.WS DEFAULT
.EW 0
.
.PP  
At this point you can invoke the `configure' script and call `make'
to build the groff project.  You can do it in the source tree:
.QUOTE
.CODE
$ ./configure
$ make
.CODE OFF
.QUOTE OFF
You can also build groff in an out-of-source build tree, which is
cleaner:
.QUOTE
.CODE
$ mkdir build
$ cd build
$ ../configure
$ make
.CODE OFF
.QUOTE OFF
Parallel build is also supported: `make' can be invoked
with the -j option, which will greatly speed up the build.
.
.HEADING 2 "Automake in the autotools process"
.
.PP
Automake's main job is to generate a Makefile.in file (this file is
maintained manually on projects using only autoconf).  The main file
processed by `automake' is the Makefile.am file, which eventually
generates a Makefile.  The (simplified) process is:
.
.SP 3p
.QUAD LEFT
.HY OFF
.
.LIST
.SHIFT_LIST 1m
.ITEM
`aclocal' generates the `aclocal.m4' file from `configure.ac' and
the user-defined macros in `acinclude.m4'.
.ITEM
`autoheader' generates config.h.in.
.ITEM
`autoconf' generates the `configure' script from `aclocal.m4' and `configure.ac'
.ITEM
`automake' generates Makefile.in from Makefile.am and the
`configure.ac' file.  It also generates some helper scripts, on the
groff project they are located in build-aux.
.ITEM
`configure' generates `config.status'
.ITEM
`config.status' generates the Makefile and config.h.
.LIST OFF
.
.SP 3p
.JUSTIFY
.HY DEFAULT
.
.WS -2
.RW .16
Finally, `autoreconf' is the program that can be used to call these
various tools in the correct order.
.RW 0
.WS DEFAULT
.
.PP
Automake defines a set of special variables that are used to
generate various build rules in the final Makefile.  Note however
that if Automake's predefined rules are not enough, you still have
the possibility of adding handwritten standard `make' rules in a
Makefile.am; these rules will be copied verbatim in the Makefile.in
and then in the final Makefile.
.
.HEADING 2 "Modification of autotools files"
.
.PP
Previously, when groff used `autoconf' only and not `automake',
you had to invoke manually the autotools, depending on what you
modified.  For example, to change the file `aclocal.m4', you had
to run the shell command `aclocal -I m4'; to recreate the files
`configure' and `Makefile', you had to use the command 'autoreconf
- I m4'.
.PP
Now, as groff uses `automake', you don't need to run `autoreconf'.
If you make some changes in Makefile.am or configure.ac, all the
files that need to be updated will be regenerated when you execute
`make'.
.
.HEADING 1 "Building a program"
.
.HEADING 2 "A program and its source files"
.
.PP
Generally speaking, when using `automake' you will have to write a
Makefile.am file and use the variable \*[CODE]bin_PROGRAMS\*[CODE OFF]
to declare a program that should be built, and then list the
sources of this program in a variable that starts with the name of
your program and ends with \*[CODE]_SOURCES\*[CODE OFF]\&.  In the
groff project we have only 1 top-level Makefile.am that includes
several \&.am files.
.PP
Take for example the build of grolbp, in src/devices/grolbp/grolbp.am. 
The file starts with:
.QUOTE ADJUST -4p
.CODE
bin_PROGRAMS += grolbp
.CODE OFF
.QUOTE OFF
This says that a program named `grolbp' is added to the list of the
programs that should be built.  The variable
\*[CODE]bin_PROGRAMS\*[CODE OFF] is initialized to an empty string in
the top-level Makefile.am, which includes grolbp.am.  (We will see later
why we don't write directly
\*[CODE]bin_PROGRAMS\~=\~grolbp\*[CODE OFF] in a Makefile.am in the
grolbp directory.)
.PP
Then, we list the sources of grolbp like this:
.QUOTE ADJUST -4p
.IL 1m
.HI 1m
.CODE
grolbp_SOURCES = \\
src/devices/grolbp/lbp.cpp \\
src/devices/grolbp/lbp.h \\
src/devices/grolbp/charset.h
.CODE OFF
.QUOTE OFF
.ILQ
As you added `grolbp' to \*[CODE]bin_PROGRAMS\*[CODE OFF],
you need to define the sources of grolbp in the variable
\*[CODE]grolbp_SOURCES\*[CODE OFF]\&.  If you write in another file
\*[CODE]bin_PROGRAMS += foo\*[CODE OFF] you will list the sources
of `foo' in \*[CODE]foo_SOURCES\*[CODE OFF]\&.
.PP
With these two statements, the resulting generated Makefile
will contain everything that is needed to build, clean,
install and uninstall the `grolbp' binary when invoking the
adequate `make' command.  Also, the source files listed in
\*[CODE]grolbp_SOURCES\*[CODE OFF] will automatically be included in
the distribution tarball.  That is why the headers are also listed
in \*[CODE]grolbp_SOURCES\*[CODE OFF]: it is not necessary to add
them in order to correctly build `grolbp', but this way the headers
will be distributed.
.
.SP 3p
.QUAD LEFT
.HY OFF
.
.LIST
.SHIFT_LIST 1m
.ITEM
The path to the files are relative to the top-level directory.
.ITEM
The binaries are generated in the top-level build directory.
.ITEM
The \&.o files are generated in the directory where the source files
are located, or, in the case of an out-of-source build tree, in a
directory that is the replication of the source tree directory.
For example if you built groff in a `build' directory, lbp.o
(object file from src/devices/grolbp/lbp.cpp) will be located in
build/src/devices/grolbp/lbp.o.
.LIST OFF
.
.SP 3p
.JUSTIFY
.HY DEFAULT
.
We will also see later the reasons; this is due to the non-recursive
make design.
.
.HEADING 2 "Linking against a library"
.
.PP
To list which libraries grolbp needs to link against, we just write:
.QUOTE
.IL
.HI
.CODE
grolbp_LDADD = $(LIBM) \\
libdriver.a \\
libgroff.a \\
lib/libgnu.a
.CODE OFF
.QUOTE OFF
.ILQ
Again, we use the variable \*[CODE]grolbp_LDADD\*[CODE OFF] because
we added a program named `grolbp'.  This will also automatically
set build dependencies between `grolbp' and the libraries it needs:
`libdriver.a' and `libgroff.a', that are convenience libraries built
within the groff project, will be compiled before grolbp.
.
.HEADING 2 "Preprocessor flags"
.
.PP
Preprocessor flags that are common to all the binaries are listed
in the variable \*[CODE]AM_CPPFLAGS\*[CODE OFF] in the top-level
Makefile.am.  If a `foo' binary needs specific preprocessor
flags, use \*[CODE]foo_CPPFLAGS\*[CODE OFF], for example, in
src/devices/xditview/xditview.am, extra flags are needed to build
gxditview and are added like this:
.QUOTE
.IL
.HI
.CODE
gxditview_CPPFLAGS = $(AM_CPPFLAGS) $(X_CFLAGS) -Dlint \\
-I$(top_builddir)/src/devices/xditview
.CODE OFF
.QUOTE OFF
.ILQ
.PP
The use of specific CPPFLAGS changes the name of the generated objects:
the \&.o object files are prefixed with the name of the program.
For example, the \&.o file corresponding to
src/devices/xditview/device.c will be
src/devices/xditview/gxditview-device.o.
.
.HEADING 2 "Cleaning"
.
.PP
You don't need to write rules to clean the programs listed in
\*[CODE]bin_PROGRAMS\*[CODE OFF], `automake' will write them for
you.  However, some programs might have generated sources that
should be cleaned.  In this case, you have mainly two special
variables to list extra files that should be cleaned:
.
.SP 3p
.QUAD LEFT
.HY OFF
.
.LIST
.SHIFT_LIST 1m
.ITEM
\*[CODE]MOSTLYCLEANFILES\*[CODE OFF] for files that should be
cleaned by `make mostlyclean'
.ITEM
\*[CODE]CLEANFILES\*[CODE OFF ] for files that should be cleaned by
`make clean'
.LIST OFF
.
.JUSTIFY
.HY DEFAULT
.SP 3p
.
There is also the possibility of writing custom rules.  We will see
that later.
.
.HEADING 2 "Dependencies"
.
.PP
We have already seen that when linking against a convenience
library, the dependencies are already created by `automake'.
However, some dependencies still need to be manually added, for
example when a source file includes a generated header.  In this
case, the easiest way is to add a plain-make dependency.  For
example, src/roff/groff/groff.cpp includes defs.h, which is a
generated header.  We just add in src/roff/groff/groff.am:
.QUOTE
.CODE
src/roff/groff/groff.$(OBJEXT): defs.h
.CODE OFF
.QUOTE OFF
.
.HEADING 2 "Scripts"
.
.PP
Apart from \*[CODE]bin_PROGRAMS\*[CODE OFF], there is another
similar special variable for scripts:  \*[CODE]bin_SCRIPTS\*[CODE OFF]\&.
The scripts listed in this variable will automatically be
built (of course you have to provide your custom rule to build the
script), installed and uninstalled when invoking `make', `make
install' and `make uninstall'.  The main difference is that unlike
the programs listed in \*[CODE]bin_PROGRAMS\*[CODE OFF], the scripts
will not be cleaned by default.  They are not distributed by default
either.  In the groff project, \*[CODE]bin_SCRIPTS\*[CODE OFF] are
cleaned because they are added to \*[CODE]MOSTLYCLEANFILES\*[CODE OFF]
in the top-level Makefile.am.
.PP
A simple example are the gropdf and pdfmom scripts in
src/devices/gropdf/gropdf.am:
.CODE_SIZE 84
.QUOTE_INDENT 1
.QUOTE
.CODE
bin_SCRIPTS += gropdf pdfmom
  [...]
gropdf: $(gropdf_dir)/gropdf.pl $(SH_DEPS_SED_SCRIPT)
        $(AM_V_GEN)$(RM) $@ \\
        sed -f $(SH_DEPS_SED_SCRIPT) \\
            -e "s|[@]VERSION[@]|$(VERSION)|" \\
            -e "s|[@]PERL[@]|$(PERL)|" \\
            -e "s|[@]GROFF_FONT_DIR[@]|$(fontpath)|" \\
            -e "s|[@]RT_SEP[@]|$(RT_SEP)|" $(gropdf_dir)/gropdf.pl \\
            >$@ \
        && chmod +x $@

pdfmom: $(gropdf_dir)/pdfmom.pl $(SH_DEPS_SED_SCRIPT)
        $(AM_V_GEN)$(RM) $@ \\
        sed -f $(SH_DEPS_SED_SCRIPT) \\
            -e "s|[@]VERSION[@]|$(VERSION)|" \\
            -e "s|[@]RT_SEP[@]|$(RT_SEP)|" \\
            -e "s|[@]PERL[@]|$(PERL)|" $(gropdf_dir)/pdfmom.pl \\
            >$@
        && chmod +x $@
.QUOTE OFF
.QUOTE_INDENT 2m
.CODE_SIZE 100
In this example, the `@' symbol is protected by square brackets to
prevent the substitution of the variable by `automake'.
.
.HEADING 1 "Non-recursive make schema"
.
.PP
There are two possibilities for organizing the Makefile.am of a
large project, using a recursive or a non-recursive `make'.
.
.HEADING 2 "1st possibility: make recursion"
.
.PP
A top level Makefile.am includes another Makefile.am, using the
\*[CODE]SUBDIRS\*[CODE OFF] directive, and the Makefile.am of each
sub-directory lists the programs that should be built.  If we had
chosen this type of organization, we would have a Makefile.am in
src/devices/grolbp and in each directory that contain sources to
build a program (tbl, eqn, troff, and so on).  We would write in the
top-level Makefile.am:
.QUOTE
.IL
.HI
.CODE
SUBDIRS = src/devices/grolbp \\
\&... (and all the dir that build a program or a script)
.CODE OFF
.QUOTE OFF
and in src/devices/grolbp, we would have a file Makefile.am that
contains:
.QUOTE
.CODE
bin_PROGRAMS = grolbp
grolbp_SOURCES = lbp.cpp lbp.h charset.h
.CODE OFF
.QUOTE OFF
.PP
Only `grolbp' is affected to the variable \*[CODE]bin_PROGRAMS\*[CODE OFF]\&.
It would be the same in, say, src/roff/troff: you would have a Makefile.am
with \*[CODE]bin_PROGRAMS = troff\*[CODE OFF]\&.  We would have
one generated Makefile per Makefile.am file: in the build tree
you will have the top-level Makefile, grolbp's Makefile in
src/devices/grolbp, troff's Makefile in src/roff/troff, and so on.
When calling `make' to build everything, `make' will be recursively
called in all the directories that have a Makefile.  Thus, the
paths are logically relative to the directory that contains the
Makefile.am.
.PP
This approach has the disadvantage of making dependencies harder
to resolve: each Makefile does not know the targets of the other
Makfiles.  It also makes the build slower.
.
.HEADING 2 "Non-recursive make used by the Groff project"
.
.PP
The second possibility, which was chosen for the groff project, is to use
a non-recursive make schema.  It is described in paragraph 7.3 of
the Automake manual ("An Alternative Approach to Subdirectories"),
based on the following paper from Peter Miller:
.PDF_WWW_LINK http://miller.emu.id.au/pmiller/books/rmch/ \
  SUFFIX . "\*[IT]Recursive Make Considered Harmful\*[PREV]"
.PP
The idea is to have a single Makefile that contains all the rules.
That is why we have only a single Makefile.am in the top-level
directory which includes all the \&.am files that define rules
to build the various programs.  The inclusion is done with the
\*[CODE]include\*[CODE OFF] directive, not \*[CODE]SUBDIRS\*[CODE OFF]\&.
Using `include' is like copying the contents of the included
file into the top-level Makefile.am, and will not generate other
Makefile.
.PP
We first say in this top-level Makefile.am:
.QUOTE
.CODE 
bin_PROGAMS = 
.CODE OFF
.QUOTE OFF
and then all the \&.am files that define a program to be built (e.g.
src/devices/grolbp/grolbp.am, src/roff/troff/troff.am, and so on)
overload this variable, so that at the end, all the programs that
should be built are listed in this \*[CODE]bin_PROGRAMS\*[CODE OFF]
variable.  This is the reason why all the paths in the various \&.am
files are relative to the top-level directory: at the end we will
have only one Makefile in the top-level directory of the build tree.
.PP
As the resulting single Makefile knows all the targets, the
dependencies are easier to manage.  The build is also faster,
particularly when compiling a single file: `make' is called once only
and the file will be instantly rebuilt, while on a recursive make
system, `make' will have to be invoked in all the sub-directories.
.PP
Note also that in order to make `gnulib' work with this
non-recursive schema, the `--automake-subdir'
configuration should be selected in bootstrap.conf.
.
.HEADING 1 "Installing data"
.
.PP
Variables that end with \*[CODE]_DATA\*[CODE OFF] are special
variables used to list files that should be installed in a
particular location.  The prefix of the variables should refer to
another previously defined variable that ends with a `dir' suffix.
This variable that ends with `dir' defines where the files should be
installed.
.
.HEADING 2 "A simple case"
.
.PP
For example, in font/devX100/devX100.am, we can see this:
.QUOTE
.CODE
if !WITHOUT_X11
devX100fontdir = $(fontdir)/devX100
devX100font_DATA = $(DEVX100FONTS)
endif
.SP
EXTRA_DIST += $(DEVX100FONTS)
.CODE OFF
.QUOTE OFF
.WS -4
\*[CODE]DEVX100FONTS\*[CODE OFF] is just a list of font files,
defined at the beginning of devX100.am.  \*[CODE]fontdir\*[CODE OFF]
is where all the font directories are installed, it is defined
in the top-level Makefile.am.  The conditional
\*[CODE]if\~!WITHOUT_X11\*[CODE OFF]
is used to prevent the installation of
these files if X11 is not available.
.WS DEFAULT
.PP
We first define where we wants to install the devX100 fonts with:
.QUOTE
.CODE
devX100fontdir = $(fontdir)/devX100
.CODE OFF
.QUOTE OFF
Because we declared a variable ending with `dir', we are allowed
to define \*[CODE]devX100font_DATA\*[CODE OFF] (you remove the
`dir' suffix and add \*[CODE]_DATA\*[CODE OFF]).  Wildcards are not
supported in the special variables that end with
\*[CODE]_DATA\*[CODE OFF]\&.
.PP
With these two lines, `make install' will install the files
listed in \*[CODE]DEVX100FONTS\*[CODE OFF] and `make uninstall'
will uninstall them.  \*[CODE]devX100fontdir\*[CODE OFF] will be
automatically created if missing during the installation
process, but not removed during the uninstall.  The complete
\*[CODE]fontdir\*[CODE OFF] is removed by a custom uninstall rule
(uninstall_groffdirs in Makefile.am).
.PP
Because the files listed in \*[CODE]devX100font_DATA\*[CODE OFF]
are not distributed by default, we explicitly added them to the
\*[CODE]EXTRA_DIST\*[CODE OFF] variable, which lists all the files
that should be distributed and that are not taken into account by
the default automake rules.
.QUOTE
.CODE
  EXTRA_DIST += $(DEVX100FONTS)
.CODE OFF
.QUOTE OFF
Another possibility would have been to add a `dist' prefix to the
\*[CODE]devX100font_DATA\*[CODE OFF] variable, in this case the use
of \*[CODE]EXTRA_DIST\*[CODE OFF] is useless (except of course if
\*[CODE]WITHOUT_X11\*[CODE OFF] is true, in this case we don't
install the files but we still have to distribute them):
.QUOTE
.CODE
if !WITHOUT_X11
devX100fontdir = $(fontdir)/devX100
dist_devX100font_DATA = $(DEVX100FONTS)
else
EXTRA_DIST += $(DEVX100FONTS)
endif
.CODE OFF
.QUOTE OFF
.
.HEADING 2 "Dealing with generated files"
.
.PP
In the previous example, all the font files that must be installed
were already present in the source tree.  But in some cases,
you need to generate the files you intend to install.  In this
case, the files should be installed but not distributed.  A
simple way to deal with this is to add a `nodist' prefix to your
\*[CODE]xxx_DATA\*[CODE OFF] variable.
.PP
For example in font/devps/devps.am, we have a list of
font files already present in the source tree, defined
by \*[CODE]DEVPSFONTFILES\*[CODE OFF], and another list
of font files that are generated, listed in the variable
\*[CODE]DEVPSFONTFILES_GENERATED\*[CODE OFF]\&.  They should all
by installed in a `devps' directory under the fontdir.  Thus
the following three lines, where we use the `dist' and `nodist'
prefixes:
.QUOTE
.CODE
devpsfontdir = $(fontdir)/devps
dist_devpsfont_DATA = $(DEVPSFONTFILES) 
nodist_devpsfont_DATA = $(DEVPSFONTFILES_GENERATED)
.CODE OFF
.QUOTE OFF
The generated files are not cleaned by default, thus we add:
.QUOTE
.CODE
MOSTLYCLEANFILES += $(DEVPSFONTFILES_GENERATED)
.CODE OFF
.QUOTE OFF
.
.HEADING 1 "Extending Automake's rules"
.
.HEADING 2 "Local clean rules"
.
.PP
In most of the cases, the files that need to be cleaned are
automatically determined by `automake', or were added to the
\*[CODE]MOSTCLEANFILES\*[CODE OFF] or \*[CODE]CLEANFILES\*[CODE OFF]
variables.  However, you might need to define a specific rule
to clean some files that were not added to any list.  Automake
defines a set of targets to extend the clean targets with your
own rules: clean-local, mostlyclean-local, distclean-local or
maintainerclean-local.  An example of such extension exists in
font/devpdf/devpdf.am: because some fonts are not explicitly listed
in a \*[CODE]xxx_DATA\*[CODE OFF] variable but generated by a custom
rule, we define an extra rule to extend the `mostlyclean' target:
.CODE_SIZE 92
.QUOTE
.CODE
mostlyclean-local: mostlyclean_devpdf_extra
mostlyclean_devpdf_extra:
        @echo Cleaning font/devpdf
        rm -rf $(top_builddir)/font/devpdf/enc \\
          $(top_builddir)/font/devpdf/map;
        if test -d $(top_builddir)/font/devpdf; then \\
          for f in $(GROFF_FONT_FILES); do \\
            rm -f $(top_builddir)/font/devpdf/$$f; \\
          done; \\
        fi
.CODE OFF
.QUOTE OFF
.
.NO_FLEX OFF \" Prevent upcoming NEWPAGE from disabling flex-spacing.
.HEADING 2 "Local install/uninstall rules and hooks"
.
.PP
Similarly to the clean rules, there are extensions to install and
uninstall rules.  They come with two flavous, local rules and hooks.
.
.SP 3p
.QUAD LEFT
.HY OFF
.
.LIST
.SHIFT_LIST 1m
.ITEM
There are 2 rules to extend install commands: `install-exec-local'
for binaries and `install-data-local' for data.
.ITEM
There is 1 uninstall local rule: `uninstall-local'.
.LIST OFF
.
.SP 3p
.JUSTIFY
.HY DEFAULT
.
There are no guarantees on the order of execution of these local
rules.  An example of local rule is the installation of GXditview.ad
and GXditview-color.ad files in src/devices/xditview/xditview.am: if
theses files are already installed, the old files are first saved.
Also, the final file that is installed is stripped from its \&.ad
suffix.  Thus the usage of a custom rule rather than the definition
of a \*[CODE]xxx_DATA\*[CODE OFF] variable:
.FLEX
.QUOTE
.CODE
# Custom installation of GXditview.ad and GXditview-color.ad
install-data-local: install_xditview
uninstall-local: uninstall_xditview
.SP
[...]
install_xditview: $(xditview_srcdir)/GXditview.ad
        -test -d $(DESTDIR)$(appdefdir) \\
          || $(mkinstalldirs) $(DESTDIR)$(appdefdir)
        if test -f $(DESTDIR)$(appdefdir)/GXditview; then \\
          mv $(DESTDIR)$(appdefdir)/GXditview \\
            $(DESTDIR)$(appdefdir)/GXditview.old; \\
        fi
        [...]
        $(INSTALL_DATA) $(xditview_srcdir)/GXditview.ad \\
          $(DESTDIR)$(appdefdir)/GXditview
.CODE OFF
.QUOTE OFF
.PP
Hooks, on the other hand, are guaranteed to be executed after all the
standard targets have been executed.
.BR
.SP 3p
.QUAD LEFT
.HY OFF
.
.LIST
.SHIFT_LIST 1m
.SP 3p
.ITEM
There are 2 install hooks: `install-exec-hook' and
`install-data-hook'.
.ITEM
There is 1 uninstall hook: `unintall-hook'
.LIST OFF
.
.SP 3p
.JUSTIFY
.HY DEFAULT
.
.PP
An example of hook is the `uninstall_groffdirs' rule in the
top-level Makefile.am.  This hook is used to remove all the
directories specific to groff introduced by the installation
process.  Obviously it could not be a local extension of `uninstall'
because the order of execution is not guaranteed.
.QUOTE
.CODE
# directories specific to groff
uninstall-hook: uninstall_groffdirs
uninstall_groffdirs:
        if test -d $(DESTDIR)$(datasubdir); then \\
          rm -rf $(DESTDIR)$(fontdir); \\
          rm -rf $(DESTDIR)$(oldfontdir); \\
          rmdir $(DESTDIR)$(datasubdir); \\
        fi
        [...]
.CODE OFF
.QUOTE OFF
.TOC
.\" Local Variables:
.\" mode: nroff
.\" End:
.\" vim: filetype=groff: