   This file documents GNU automake 1.4

   Copyright (C) 1995, 96, 97, 98 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

The effect of `--gnu' and `--gnits'
***********************************

   The `--gnu' option (or `gnu' in the `AUTOMAKE_OPTIONS' variable)
causes `automake' to check the following:

   * The files `INSTALL', `NEWS', `README', `COPYING', `AUTHORS', and
     `ChangeLog' are required at the topmost directory of the package.

   * The options `no-installman' and `no-installinfo' are prohibited.

   Note that this option will be extended in the future to do even more
checking; it is advisable to be familiar with the precise requirements
of the GNU standards.  Also, `--gnu' can require certain non-standard
GNU programs to exist for use by various maintainer-only targets; for
instance in the future `pathchk' might be required for `make dist'.

   The `--gnits' option does everything that `--gnu' does, and checks
the following as well:

   * `make dist' will check to make sure the `NEWS' file has been
     updated to the current version.

   * The file `COPYING.LIB' is prohibited.  The LGPL is apparently
     considered a failed experiment.

   * `VERSION' is checked to make sure its format complies with Gnits
     standards.

   * If `VERSION' indicates that this is an alpha release, and the file
     `README-alpha' appears in the topmost directory of a package, then
     it is included in the distribution.  This is done in `--gnits'
     mode, and no other, because this mode is the only one where version
     number formats are constrained, and hence the only mode where
     Automake can automatically determine whether `README-alpha' should
     be included.

   * The file `THANKS' is required.

The effect of `--cygnus'
************************

   Cygnus Solutions has slightly different rules for how a
`Makefile.in' is to be constructed.  Passing `--cygnus' to `automake'
will cause any generated `Makefile.in' to comply with Cygnus rules.

   Here are the precise effects of `--cygnus':

   * Info files are always created in the build directory, and not in
     the source directory.

   * `texinfo.tex' is not required if a Texinfo source file is
     specified.  The assumption is that the file will be supplied, but
     in a place that Automake cannot find.  This assumption is an
     artifact of how Cygnus packages are typically bundled.

   * `make dist' will look for files in the build directory as well as
     the source directory.  This is required to support putting info
     files into the build directory.

   * Certain tools will be searched for in the build tree as well as in
     the user's `PATH'.  These tools are `runtest', `expect',
     `makeinfo' and `texi2dvi'.

   * `--foreign' is implied.

   * The options `no-installinfo' and `no-dependencies' are implied.

   * The macros `AM_MAINTAINER_MODE' and `AM_CYGWIN32' are required.

   * The `check' target doesn't depend on `all'.

   GNU maintainers are advised to use `gnu' strictness in preference to
the special Cygnus mode.

When Automake Isn't Enough
**************************

   Automake's implicit copying semantics means that many problems can be
worked around by simply adding some `make' targets and rules to
`Makefile.in'.  Automake will ignore these additions.

   There are some caveats to doing this.  Although you can overload a
target already used by Automake, it is often inadvisable, particularly
in the topmost directory of a non-flat package.  However, various useful
targets have a `-local' version you can specify in your `Makefile.in'.
Automake will supplement the standard target with these user-supplied
targets.

   The targets that support a local version are `all', `info', `dvi',
`check', `install-data', `install-exec', `uninstall', and the various
`clean' targets (`mostlyclean', `clean', `distclean', and
`maintainer-clean').  Note that there are no `uninstall-exec-local' or
`uninstall-data-local' targets; just use `uninstall-local'.  It doesn't
make sense to uninstall just data or just executables.

   For instance, here is one way to install a file in `/etc':

     install-data-local:
             $(INSTALL_DATA) $(srcdir)/afile /etc/afile

   Some targets also have a way to run another target, called a "hook",
after their work is done.  The hook is named after the principal target,
with `-hook' appended.  The targets allowing hooks are `install-data',
`install-exec', `dist', and `distcheck'.

   For instance, here is how to create a hard link to an installed
program:

     install-exec-hook:
             ln $(bindir)/program $(bindir)/proglink

Distributing `Makefile.in's
***************************

   Automake places no restrictions on the distribution of the resulting
`Makefile.in's.  We still encourage software authors to distribute
their work under terms like those of the GPL, but doing so is not
required to use Automake.

   Some of the files that can be automatically installed via the
`--add-missing' switch do fall under the GPL; examine each file to see.

Some ideas for the future
*************************

   Here are some things that might happen in the future:

   * HTML support.

   * The output will be cleaned up.  For instance, only variables which
     are actually used will appear in the generated `Makefile.in'.

   * There will be support for automatically recoding a distribution.
     The intent is to allow a maintainer to use whatever character set
     is most convenient locally, but for all distributions to be
     Unicode or ISO 10646 with the UTF-8 encoding.

   * Rewrite in Guile.  This won't happen in the near future, but it
     will eventually happen.