Bug and doc fixes

[platform/upstream/automake.git] / automake.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename automake.info
@settitle automake
@setchapternewpage off
@c %**end of header

@include version.texi

@c Yes, this appears in many Texinfo files.  He's just a likeable guy.
@ifinfo
@set Francois Franc,ois
@end ifinfo
@tex
@set Francois Fran\noexpand\ptexc cois
@end tex

@ifinfo
@format
START-INFO-DIR-ENTRY
* automake: (automake).         Making Makefile.in's
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
This file documents GNU automake @value{VERSION}

Copyright (C) 1995 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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph


@end ignore
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.
@end ifinfo


@titlepage
@title GNU Automake
@subtitle For version @value{VERSION}, @value{UPDATED}
@c copyright page
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995 Free Software Foundation, Inc.
@sp 2
This is the first edition of the GNU Automake documentation,@*
and is consistent with GNU Automake @value{VERSION}.@*
@sp 2
Published by the Free Software Foundation @*
675 Massachusetts Avenue, @*
Cambridge, MA 02139 USA @*

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 Free Software Foundation.
@end titlepage

@c Define an index of configure variables.
@defcodeindex cv
@c Define an index of options.
@defcodeindex op
@c Define an index of targets.
@defcodeindex tr

@ifinfo
@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top GNU Automake

This file documents the GNU Automake package for creating GNU
Standards-compliant Makefiles from template files.  This edition
documents version @value{VERSION}.

@menu
* Introduction::                Automake's purpose
* Invoking Automake::           Creating a Makefile.in
* Generalities::                General ideas
* configure::                   Scanning configure.in
* Top level::                   The top-level Makefile.am
* Programs::                    Building programs and libraries
* Other objects::               Other derived objects
* Documentation::               Building documentation
* Install::                     What gets installed
* Clean::                       What gets cleaned
* Dist::                        What goes in a distribution
* Tests::                       Support for test suites
* Options::                     Changing Automake's behavior
* Miscellaneous::               Miscellaneous rules
* Extending::                   Extending Automake
* Distributing::                Distributing the Makefile.in
* Examples::                    Some example packages
* Future::                      Some ideas for the future
* Variables::                   Index of variables
* Configure variables::         Index of configure variables and macros
* Targets::                     Index of targets
@end menu

@end ifinfo

@node Introduction
@chapter Introduction

Automake is a tool for automatically generating
@file{Makefile.in}s from files called @file{Makefile.am}.  The
@file{Makefile.am} is basically a series of @code{make} macro
definitions (with rules being thrown in occasionally).  The generated
@file{Makefile.in}s are compliant with the GNU Makefile standards.

The GNU Makefile Standards Document
(@pxref{Makefile Conventions, , , standards.info, The GNU Coding Standards})
is long, complicated, and subject to change.  The goal of Automake is to
remove the burden of Makefile maintenance from the back of the
individual GNU maintainer (and put it on the back of the Automake
maintainer).

The typical Automake input files is simply a series of macro
definitions.  Each such file is processed to create a
@file{Makefile.in}.  There should generally be one @file{Makefile.am}
per directory of a project.

Automake does constrain a project in certain ways; for instance it
assumes that the project uses Autoconf
(@pxref{Top, , The Autoconf Manual, autoconf.info, The Autoconf Manual}),
and enforces certain restrictions on the @file{configure.in} contents.

@code{Automake} requires @code{perl} in order to generate the
@file{Makefile.in}s.  However, the distributions created by Automake are
fully GNU standards-compliant, and do not require @code{perl} in order
to be built.

Mail suggestions and bug reports for Automake to tromey@@cygnus.com.


@node Invoking Automake
@chapter Creating a @file{Makefile.in}

To create all the @file{Makefile.in}s for a package, run the
@code{automake} program in the top level directory, with no arguments.
@code{automake} will automatically find each appropriate
@file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
and generate the corresponding @file{Makefile.in}.

You can optionally give @code{automake} an argument; @samp{.am} is
appended to the argument and the result is used as the name of the input
file.  This feature is generally only used to automatically rebuild an
out-of-date @file{Makefile.in}.  Note that @code{automake} must always
be run from the topmost directory of a project, even if being used to
regenerate the @file{Makefile.in} in some subdirectory.  This is
necessary because @code{automake} must scan @file{configure.in}, and
because @code{automake} uses the knowledge that a @file{Makefile.in} is
in a subdirectory to change its behavior in some cases.

@code{automake} accepts the following options:

@table @code
@item --amdir=@var{dir}
Look for Automake data files in directory @var{dir} instead of in the
installation directory.  This is typically used for debugging.

@item --foreign
An alias for @samp{--strictness=foreign}.

@item --gnits
An alias for @samp{--strictness=gnits}.

@item --gnu
An alias for @samp{--strictness=gnu}.

@item --help
Print a summary of the command line options and exit.

@item --include-deps
Include all automatically generated dependency information
(@pxref{Dependencies}) in the generated
@file{Makefile.in}.  This is generally done when making a distribution;
see @ref{Dist}.

@item --add-missing
Automake requires certain common files to exist in certain situations;
for instance @file{config.guess} is required if @file{configure.in} runs
@code{AC_CANONICAL_HOST}.  Automake is distributed with several of these
files; this option will cause the missing ones to be automatically added
to the package, whenever possible.

@item --output-dir=@var{dir}
Put the generated @file{Makefile.in} in the directory @var{dir}.
Ordinarily each @file{Makefile.in} is created in the directory of the
corresponding @file{Makefile.am}.  This option is used when making
distributions.

@item --strictness=@var{level}
Set the global strictness to @var{level}; this can be overridden in each
@file{Makefile.am} if required.  @xref{Generalities} for more
information.

@item --verbose
Cause Automake to print information about which files are being read or
created.

@item --version
Print the version number of Automake and exit.
@end table


@node Generalities
@chapter General ideas

@section Depth
@code{automake} supports three kinds of directory hierarchy: ``flat'',
``shallow'', and ``deep''.

A @dfn{flat} package is one in which all the files are in a single
directory.  The @file{Makefile.am} for such a package by definition
lacks a @code{SUBDIRS} macro.  An example of such a package is
@code{termutils}.
@vindex SUBDIRS

A @dfn{deep} package is one in which all the source lies in
subdirectories; the top level directory contains mainly configuration
information.  GNU cpio is a good example of such a package, as is GNU
@code{tar}.  The top level @file{Makefile.am} for a deep package will
contain a @code{SUBDIRS} macro, but no other macros to define objects
which are built.

A @dfn{shallow} package is one in which the primary source resides in
the top-level directory, while various parts (typically libraries)
reside in subdirectories.  @code{automake} is one such package (as is
GNU @code{make}, which does not currently use @code{automake}).


@section Strictness
While Automake is intended to be used by maintainers of GNU packages, it
does make some effort to accomodate those who wish to use it, but do not
want to use all the GNU conventions.

To this end, Automake supports three levels of @dfn{strictness} -- the
strictness indicating how stringently Automake should check standards
conformance.

The valid strictness levels are:

@table @samp
@item foreign
Automake will check for only those things which are absolutely
required for proper operations.  For instance, whereas GNU standards
dictate the existence of a @file{NEWS} file, it will not be required in
this mode.  The name comes from the fact that Automake is intended to be
used for GNU programs; these relaxed rules are not the standard mode of
operation.

@item gnu
Automake will check -- as much as possible -- for compliance to the GNU
standards for packages.  This is the default.

@item gnits
Automake will check for compliance to the as-yet-unwritten GNITS
standards.  These are based on the GNU standards, but are even more
detailed.  Unless you are a GNITS standards contributor, it is
recommended that you avoid this option until such time as the GNITS
standard is actually published.
@end table


@section The Uniform Naming Scheme
Automake variables generally follow a uniform naming scheme that makes
it easy to decide how programs (and other derived objects) are built,
and how they are installed.  This scheme also supports @code{configure}
time determination of what should be built.

At @code{make} time, certain variables are used to determine which
objects are to be built.  These variables are called @dfn{primary}
variables.  For instance, the primary variable @code{PROGRAMS} holds a
list of programs which are to be compiled and linked.
@vindex PROGRAMS

A different set of variables is used to decide where the built objects
should be installed.  These variables are named after the primary
variables, but have a prefix indicating which standard directory should
be used as the installation directory.  The standard directory names are
given in the GNU standards
(@pxref{Directory Variables, , , standards.info, The GNU Coding
Standards}).
@code{automake} extends this list with @code{pkglibdir},
@code{pkgincludedir}, and @code{pkgdatadir}; these are the same as the
non-@samp{pkg} versions, but with @samp{@@PACKAGE@@} appended.
@cvindex PACKAGE

For each primary, there is one additional variable named by prepending
@samp{EXTRA_} to the primary name.  This variable is used to list
objects which may or may not be built, depending on what
@code{configure} decides.  This variable is required because Automake
must know the entire list of objects to be built in order to generate a
@file{Makefile.in} that will work in all cases.

For instance, @code{cpio} decides at configure time which programs are
built.  Some of the programs are installed in @code{bindir}, and some
are installed in @code{sbindir}:

@example
EXTRA_PROGRAMS = mt rmt
bin_PROGRAMS = cpio pax
sbin_PROGRAMS = @@PROGRAMS@@
@end example

Defining a primary variable is an error.

Note that the common @samp{dir} suffix is left off when constructing the
variable names; thus one writes @samp{bin_PROGRAMS} and not
@samp{bindir_PROGRAMS}.

Not every sort of object can be installed in every directory.  Automake
will flag those attempts it finds in error.  Automake will also diagnose
obvious misspellings in directory names.

Sometimes the standard directories -- even as augmented by Automake --
are not enough.  In particular it is sometimes useful, for clarity, to
install objects in a subdirectory of some predefined directory.  To this
end, Automake allows you to extend the list of possible installation
directories.  A given prefix (eg @samp{zar}) is valid if a variable of
the same name with @samp{dir} appended is defined (eg @samp{zardir}).

For instance, until HTML support is part of Automake, you could use this
to install raw HTML documentation:

@example
htmldir = $(prefix)/html
html_DATA = automake.html
@end example

The special prefix @samp{noinst} indicates that the objects in question
should not be installed at all.

Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
@samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
@samp{TEXINFOS}.
@vindex PROGRAMS
@vindex LIBRARIES
@vindex SCRIPTS
@vindex DATA
@vindex HEADERS
@vindex MANS
@vindex TEXINFOS

@section General Operation
Automake essentially works by reading a @file{Makefile.am} and
generating a @file{Makefile.in}.  The macro definitions and targets in
the @file{Makefile.am} are copied into the generated file.

Automake tries to group comments with adjoining targets (or variable
definitions) in an intelligent way.

A target defined in @file{Makefile.am} generally overrides any such
target of a similar name that would be automatically generated by
@code{automake}.  Although this is a supported feature, it is generally
best to avoid making use of it, as sometimes the generated rules are
very particular.

Automake also allows a form of comment which is @emph{not} copied into
the output; all lines beginning with @samp{##} are completely ignored by
Automake.

It is customary to make the first line of @file{Makefile.am} read:

@example
## Process this file with automake to produce Makefile.in
@end example

@c FIXME discuss putting a copyright into Makefile.am here?  I would but
@c I don't know quite what to say.

@c FIXME document customary ordering of Makefile.am here!


@node configure
@chapter Scanning @file{configure.in}

Automake requires certain variables to be defined and certain macros to
be used in the package @file{configure.in}.

One such requirement is that @file{configure.in} must define the
variables @code{PACKAGE} and @code{VERSION} with @code{AC_SUBST}.
@cvindex PACKAGE
@cvindex VERSION
@code{PACKAGE} should be the name of the package as it appears when
bundled for distribution.  For instance, Automake definees
@code{PACKAGE} to be @samp{automake}.  @code{VERSION} should be the
version number of the release that is being developed.  We recommend
that you make @file{configure.in} the only place in your package where
the version number is defined; this makes releases simpler.

Automake also requires the use of the macros @code{AC_ARG_PROGRAM}
@cvindex AC_ARG_PROGRAM

If your package is not a flat distribution, Automake requires the use of
@code{AC_PROG_MAKE_SET}.
@cvindex AC_PROG_MAKE_SET

Automake will also recognize the use of certain macros and tailor the
generated @file{Makefile.in} appropriately.  Currently recognized macros
and their effects are:

@table @code
@item AC_CONFIG_HEADER
Automake will generate rules to automatically regenerate the config
header.
@cvindex AC_CONFIG_HEADER

@item AC_OUTPUT
Automake uses this to determine which files to create.
@cvindex AC_OUTPUT

@item AC_PATH_XTRA
Automake will insert definitions for the variables defined by
@code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
or library.
@cvindex AC_PATH_XTRA

@item AC_CANONICAL_HOST
@item AC_CANONICAL_SYSTEM
Automake will ensure that @file{config.guess} and @file{config.sub}
exist.
@cvindex AC_CANONICAL_HOST
@cvindex AC_CANONICAL_SYSTEM

@item AC_FUNC_ALLOCA
@item AC_FUNC_GETLOADAVG
@item AC_FUNC_MEMCMP
@item AC_STRUCT_ST_BLOCKS
@item fp_FUNC_FNMATCH
@item AC_REPLACE_FUNCS
Automake will ensure that the appropriate source files are part of the
distribution, and will ensure that the appropriate dependencies are
generated for these objects.  @xref{A Library} for more
information.
@cvindex AC_FUNC_ALLOCA
@cvindex AC_FUNC_GETLOADAVG
@cvindex AC_FUNC_MEMCMP
@cvindex AC_STRUCT_ST_BLOCKS
@cvindex fp_FUNC_FNMATCH
@cvindex AC_REPLACE_FUNCS

Automake will also detect statements which put @samp{.o} files into
@code{LIBOBJS}, and will treat these additional files in a similar way.
@cvindex LIBOBJS

@item AC_PROG_RANLIB
This is required if any libraries are built in the package.
@cvindex AC_PROG_RANLIB

@item AC_PROG_INSTALL
@item fp_PROG_INSTALL
@code{fp_PROG_INSTALL} is required if any scripts (@pxref{Scripts}) are
installed by the package.  Otherwise, @code{AC_PROG_INSTALL} is
required.
@cvindex AC_PROG_INSTALL
@cvindex fp_PROG_INSTALL

@item fp_C_PROTOTYPES
This is required when using automatic de-ANSI-fication, see @ref{ANSI}.
@cvindex fp_C_PROTOTYPES

@item ud_GNU_GETTEXT
This macro is required for packages which use GNU gettext (FIXME xref).
It is distributed with gettext.  Automake uses this macro to ensure that
the package meets some of gettext's requirements.
@cvindex ud_GNU_GETTEXT
@end table

The @samp{fp_} macros are from @value{Francois} Pinard, and are included
with Automake.  @code{automake} will tell where the macros can be found
if they are missing.


@node Top level
@chapter The top-level @file{Makefile.am}

In non-flat packages, the top level @file{Makefile.am} must tell
Automake which subdirectories are to be built.  This is done via the
@code{SUBDIRS} variable.
@vindex SUBDIRS

The @code{SUBDIRS} macro holds a list of subdirectories in which
building of various sorts can occur.  Many targets (eg @code{all}) in
the generated @file{Makefile} will run both locally and in all specified
subdirectories.  Note that the directories listed in @code{SUBDIRS} are
not required to contain @file{Makefile.am}s; only @file{Makefile}s
(after configuration).  This allows inclusion of libraries from packages
which do not use Automake (such as @code{gettext}).

In a deep package, the top-level @file{Makefile.am} is often very short.
For instance, here is the @file{Makefile.am} from the textutils
distribution:

@example
SUBDIRS = lib src doc man
EXTRA_DIST = @@README_ALPHA@@
@end example

@code{SUBDIRS} can contain configure substitutions (eg @samp{@@DIRS@@});
Automake itself does not actually examine the contents of this variable.

If @code{SUBDIRS} is defined, then your @file{configure.in} must include
@code{AC_PROG_MAKE_SET}.


@node Programs
@chapter Building Programs and Libraries

A large part of Automake's functionality is dedicated to making it easy
to build C programs and libraries.

@menu
* A Program::                   Building a program
* A Library::                   Building a library
* ANSI::                        Automatic de-ANSI-fication
* Dependencies::                Automatic dependency tracking
@end menu


@node A Program
@section Building a program

In a directory containing source that gets built into a program (as
opposed to a library), the @samp{PROGRAMS} primary is used.  Programs
can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
@code{pkglibdir}, or not at all.

For instance:

@example
bin_PROGRAMS = hello
@end example

In this simple case, the resulting @file{Makefile.in} will contain code
to generate a program named @code{hello}.  The variable
@code{hello_SOURCES} is used to specify which source files get built
into an executable:

@example
hello_SOURCES = hello.c
@end example

This causes @file{hello.c} to be compiled into @file{hello.o}, and then
linked to produce @file{hello}.

If @samp{prog_SOURCES} is needed, but not specified, then it defaults to
the single file @file{prog.c}.  Id est in the example above, the
definition of @code{hello_SOURCES} is actually redundant.
@vindex _SOURCES
@vindex SOURCES

Multiple programs can be built in a single directory.  Multiple programs
can share a single source file.  The source file must be listed in each
@samp{_SOURCES} definition.

Header files listed in a @samp{_SOURCES} definition will be ignored.
Lex (@samp{.l}) and yacc (@samp{.y}) files can also be listed; support
for these should work but is still preliminary.
@c lex & yacc should have a separate section

Sometimes it is useful to determine the programs that are to be built at
configure time.  For instance, GNU @code{cpio} only builts @code{mt} and
@code{rmt} under special circumstances.

In this case, you must notify @code{Automake} of all the programs that
can possibly be built, but at the same time cause the generated
@file{Makefile.in} to use the programs specified by @code{configure}.
This is done by having @code{configure} substitute values into each
@samp{_PROGRAMS} definition, while listing all optionally built programs in
@code{EXTRA_PROGRAMS}.
@vindex EXTRA_PROGRAMS

If you need to link against libraries that are not found by
@code{configure}, you can use @code{LDADD} to do so.  This variable
actually can be used to add any options to the linker command line.
@vindex LDADD

Sometimes, multiple programs are built in one directory but do not share
the same link-time requirements.  In this case, you can use the
@samp{@var{prog}_LDADD} variable (where @var{PROG} is the name of the
program as it appears in some @samp{_PROGRAMS} variable, and usually
written in lowercase) to override the global @code{LDADD}.  (If this
variable exists for a given program, then that program is not linked
using @code{LDADD}.)
@vindex _LDADD

For instance, in GNU cpio, @code{pax}, @code{cpio}, and @code{mt} are
linked against the library @file{libcpio.a}.  However, @code{rmt} is
built in the same directory, and has no such link requirement.  Also,
@code{mt} and @code{rmt} are only built on certain architectures.  Here
is what cpio's @file{src/Makefile.am} looks like (abridged):

@example
bin_PROGRAMS = cpio pax @@MT@@
libexec_PROGRAMS = @@RMT@@
EXTRA_PROGRAMS = mt rmt

LDADD = ../lib/libcpio.a @@INTLLIBS@@
rmt_LDADD =

cpio_SOURCES = @dots{}
pax_SOURCES = @dots{}
mt_SOURCES = @dots{}
rmt_SOURCES = @dots{}
@end example


@node A Library
@section Building a library

Building a library is much like building a program.  In this case, the
name of the primary is @samp{LIBRARIES}.  Libraries can be installed in
@code{libdir} or @code{pkglibdir}.

Each @samp{_LIBRARIES} variable is a list of the base names of
libraries to be built.  For instance to create a library named
@file{libcpio.a}, but not install it, you would write:

@example
noinst_LIBRARIES = cpio
@end example

The sources that go into a library are determined exactly as they are
for programs, via the @samp{_SOURCES} variables.  Note that programs and
libraries share a namespace, so one cannot have a program (@file{lob}) and
a library (@file{liblob.a}) with the same name in one directory.

Extra objects can be added to a library using the @samp{library_LIBADD}
variable.  This should be used for objects determined by
@code{configure}.  Again from cpio:
@vindex _LIBADD
@vindex LIBADD

@example
cpio_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
@end example

Note that Automake explicitly recognizes the use of @code{@@LIBOBJS@@}
and @code{@@ALLOCA@@} in the above example, and uses this information,
plus the list of @code{LIBOBJS} files derived from @file{configure.in}
to automatically include the appropriate source files in the
distribution (@pxref{Dist}).  These source files are also automatically
handled in the dependency-tracking scheme, see @xref{Dependencies}.


@node ANSI
@section Automatic de-ANSI-fication

Although the GNU standards prohibit it, some GNU programs are written in
ANSI C; see FIXME.  This is possible because each source file can be
``de-ANSI-fied'' before the actual compilation takes place.

If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
@vindex AUTOMAKE_OPTIONS
(@ref{Options}) contains the option @code{ansi2knr}
@opindex ansi2knr
then code to handle de-ANSI-fication is inserted into the generated
@file{Makefile.in}.

This causes each source file to be treated as ANSI C.  If an ANSI C
compiler is available, it is used.

This support requires the source files @file{ansi2knr.c} and
@file{ansi2knr.1} to be in the same directory as the ANSI C source;
these files are distributed with Automake.
Also, the package @file{configure.in} must call the macro
@code{fp_C_PROTOTYPES}.
@cvindex fp_C_PROTOTYPES


@node Dependencies
@section Automatic dependency tracking

As a developer it is often painful to continually update the
@file{Makefile.in} whenever the include-file dependencies change in a
project.  @code{automake} supplies a way to automatically track
dependency changes, and distribute the dependencies in the generated
@file{Makefile.in}.

Currently this support requires the use of GNU @code{make} and
@code{gcc}.  It might become possible in the future to supply a
different dependency generating program, if there is enough demand.

This mode is enabled by default if any C program or library is defined
in the current directory.

When you decide to make a distribution, the @code{dist} target will
@trindex dist
re-run @code{automake} with the @samp{--include-deps} option.  This
@c FIXME XREF?
causes the previously generated dependencies to be inserted into the
generated @file{Makefile.in}, and thus into the distribution.
@samp{--include-deps} also turns off inclusion of the dependency
generation code.

This mode can be suppressed by putting @code{no-dependencies} in the
variable @code{AUTOMAKE_OPTIONS}.
@vindex AUTOMAKE_OPTIONS
@opindex no-dependencies


@node Other objects
@chapter Other Derived Objects

Automake can handle derived objects which are not C programs.  Sometimes
the support for actually building such objects must be explicitly
supplied, but Automake will still automatically handle installation and
distribution.

@menu
* Scripts::                     Executable scripts
* Headers::                     Header files
* Data::                        Architecture-independent data files
@end menu


@node Scripts
@section Executable Scripts

It is possible to define and install programs which are scripts.  Such
programs are listed using the @samp{SCRIPTS} primary name.
@code{automake} doesn't define any dependencies for scripts; the
@file{Makefile.am} should include the appropriate rules.
@vindex SCRIPTS

@code{automake} does not assume that scripts are derived objects; such
objects are must be deleted by hand; see @ref{Clean} for more
information.

@code{automake} itself is a script that is generated at configure time
from @file{automake.in}.  Here is how this is handled:

@example
bin_SCRIPTS = automake
@end example

Since @code{automake} appears in the @code{AC_OUTPUT} macro,
dependencies for it are automatically generated.

Script objects can be installed in @code{bindir}, @code{sbindir},
@code{libexecdir}, or @code{pkgdatadir}.


@node Headers
@section Header files

Header files are specified by the @samp{HEADERS} family of variables.
Generally header files are not installed, so the @code{noinst_HEADERS}
variable will be the most used.
@vindex HEADERS

All header files must be listed somewhere; missing ones will not appear
in the distribution.  Often it is most convenient to list uninstalled
headers with the rest of the sources for a program.  @xref{A Program}.

Headers can be installed in @code{includedir}, @code{oldincludedir}, or
@code{pkgincludedir}.


@node Data
@section Architecture-independent data files

Automake supports the installation of miscellaneous data files using the
@samp{DATA} family of variables.
@vindex DATA

Such data can be installed in the directories @code{datadir},
@code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
@code{pkgdatadir}.

All such data files are included in the distribution.

Here is how @code{autoconf} installs its auxiliary data files:

@example
pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
compile.am data.am depend.am dist-subd-top.am dist-subd-vars.am \
dist-subd.am dist-vars.am dist.am footer.am header-vars.am header.am \
libscripts.am libprograms.am libraries-vars.am libraries.am library.am \
mans-vars.am mans.am packagedata.am program.am programs.am remake-hdr.am \
remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
texinfos-vars.am texinfos.am hack-make.sed nl-remove.sed
@end example


@node Documentation
@chapter Building documentation

Currently Automake provides support for Texinfo and man pages.

@menu
* Texinfo::                     Texinfo
* Man pages::                   Man pages
@end menu


@node Texinfo
@section Texinfo

If the current directory contains Texinfo source, you must declare it
with the @samp{TEXINFOS} primary.  Generally Texinfo files are converted
into info, and thus the @code{info_TEXINFOS} macro is most commonly used
here.  Note that any Texinfo source file must end in the @samp{.texi}
extension (@samp{.texinfo} won't work).
@vindex TEXINFOS
@vindex info_TEXINFOS

If the @samp{.texi} file @code{@@include}s @file{version.texi}, then that
file will be automatically generated.  @file{version.texi} defines three
Texinfo macros you can reference: @code{EDITION}, @code{VERSION}, and
@code{UPDATED}.  The first two hold the version number of your package
(but are kept separate for clarity); the last is the date the primary
file was last modified.  The @file{version.texi} support requires the
@code{mdate-sh} program; this program is supplied with Automake.

Sometimes an info file actually depends on more than one @samp{.texi}
file.  For instance, in the @code{xdvik} distribution,
@file{kpathsea.texi} includes the files @file{install.texi},
@file{copying.texi}, and @file{freedom.texi}.  You can tell Automake
about these dependencies using the @samp{texi_TEXINFOS} variable.  Here
is how @code{xdvik} could do it:
@vindex TEXINFOS
@vindex _TEXINFOS

@example
info_TEXINFOS = kpathsea.texi
kpathsea_TEXINFOS = install.texi copying.texi freedom.texi
@end example

Automake will warn if a directory containing Texinfo source does not
also contain the file @file{texinfo.tex}.  This file is supplied with
Automake.

Automake generates an @code{install-info} target; some people apparently
use this.


@node Man pages
@section Man pages

A package can also include man pages.  (Though see the GNU standards on
this matter, @ref{Man Pages, , , standards.info, The GNU Coding
Standards}.)  Man pages are declared using the @samp{MANS} primary.
Generally the @code{man_MANS} macro is used.  Man pages are
automatically installed in the correct subdirectory of @code{mandir},
based on the file extension.
@vindex MANS
@vindex man_MANS

@c Use @samp{make install} per documentation: (texi.info)code.
By default, man pages are installed by @samp{make install}.  However,
since the GNU project does not require man pages, many maintainers do
not expend effort to keep the man pages up to date.  In these cases, the
@code{no-installman} option will prevent the man pages from being
installed by default.  The user can still explicitly install them via
@samp{make install-man}.
@opindex no-installman
@trindex install-man

Here is how the documentation is handled in GNU @code{cpio} (which
includes both Texinfo documentation and man pages):

@example
info_TEXINFOS = cpio.texi
man_MANS = cpio.1 mt.1
@end example

Texinfo source, info pages and man pages are all considered to be source
for the purposes of making a distribution.


@node Install
@chapter What Gets Installed

Naturally, Automake handles the details of actually installing your
program once it has been built.  All @code{PROGRAMS}, @code{SCRIPTS},
@code{LIBRARIES}, @code{DATA} and @code{HEADERS} are automatically
installed in the appropriate places.

Automake also handles installing any specified info and man pages.

Automake generates separate @code{install-data} and @code{install-exec}
targets, in case the installer is installing on multiple machines which
share directory structure -- these targets allow the machine-independent
parts to be installed only once.  The @code{install} target depends on
both of these targets.
@trindex install-data
@trindex install-exec
@trindex install

Automake also generates an @code{uninstall} target, and an
@code{installdirs} target.
@trindex uninstall
@trindex installdirs

It is possible to extend this mechanism by defining an
@code{install-exec-local} or @code{install-data-local} target.  If these
targets exist, they will be run at @samp{make install} time.
@trindex install-exec-local
@trindex install-data-local


@node Clean
@chapter What Gets Cleaned

The GNU Makefile Standards specify a number of different clean rules.
@c FIXME xref
Generally the files that can cleaned are determined automatically by
Automake.  Of course, Automake also recognizes some variables that can
be defined to specify additional files to clean.  These variables are
@code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
@code{MAINTAINERCLEANFILES}.
@vindex MOSTLYCLEANFILES
@vindex CLEANFILES
@vindex DISTCLEANFILES
@vindex MAINTAINERCLEANFILES

In Automake, the @code{automake} program is not automatically removed,
because it is an executable script.  So this code in @file{Makefile.am}
causes it to be removed by @samp{make clean}:

@example
CLEANFILES = automake
@end example


@node Dist
@chapter What Goes in a Distribution

The @code{dist} target in the generated @file{Makefile.in} can be used
to generate a gzip'd @code{tar} file for distribution.  The tar file is
named based on the @var{PACKAGE} and @var{VERSION} variables.
@cvindex PACKAGE
@cvindex VERSION
@trindex dist

For the most part, the files to distribute are automatically found by
Automake: all source files are automatically included in a distribution,
as are all @file{Makefile.am}s and @file{Makefile.in}s.  Automake also
has a built-in list of commonly used files which, if present in the
current directory, are automatically included.  This list is printed by
@samp{automake --help}.  Also, files which are read by @code{configure}
(ie, the source files corresponding to the files specified in the
@code{AC_OUTPUT} invocation) are automatically distributed.

Still, sometimes there are files which must be distributed, but which
are not covered in the automatic rules.  These files should be listed in
the @code{EXTRA_DIST} variable.
@vindex EXTRA_DIST


@node Tests
@chapter Support for test suites

Automake supports a simple form of test suite.  If the variable
@code{TESTS} is defined, its value is taken to be a list of programs to
run in order to do the testing.  The programs can either be derived
objects or source objects; the generated rule will look both in
@var{srcdir} and @file{.}.

The testing is done via @samp{make check}.  The number of failures will
be printed at the end of the run.

In the future there will be some support for test suites which use
@code{DejaGnu}.


@node Options
@chapter Changing Automake's Behavior

Various features of Automake can be controlled by options in the
@file{Makefile.am}.  Such options are listed in a special variable named
@code{AUTOMAKE_OPTIONS}.  Currently understood options are:
@vindex AUTOMAKE_OPTIONS

@table @asis
@item @code{gnits}
@itemx @code{gnu}
@itemx @code{foreign}
The same as the corresponding @samp{--strictness} option.

@item @code{no-installman}
The generated @file{Makefile.in} will not cause man pages to be
installed by default.  However, an @code{install-man} target will still
be available for optional installation.

@item @code{ansi2knr}
Turn on automatic de-ANSI-fication.

@item @code{dist-shar}
Generate a @code{dist-shar} target as well as the ordinary @code{dist}
target.

@item @code{no-dependencies}
This is similar to using @samp{--include-deps} on the command line, but
is useful for those situations where you don't have the necessary bits
to make automatic dependency tracking work @xref{Dependencies}.  In this
case the effect is to effectively disable automatic dependency tracking.

@item @var{version}
A version number (eg @samp{0.30}) can be specified.  If Automake is not
newer than the version specified, creation of the @file{Makefile.in}
will be suppressed.
@end table

Unrecognized options are diagnosed by @code{automake}.


@node Miscellaneous
@chapter Miscellaneous Rules

There are a few rules and variables that didn't fit anywhere else.

@menu
* Tags::                        Interfacing to etags and mkid
* Suffixes::                    Handling new file extensions
* Built::                       Built sources
@end menu


@node Tags
@section Interfacing to @code{etags}

@code{automake} will generate rules to generate @file{TAGS} files for
use with GNU Emacs under some circumstances.

If any C source code or headers are present, then a @code{tags} target
will be generated for the directory.
@trindex tags

At the topmost directory of a multi-directory package, a @code{tags}
target file will be generated which, when run, will generate a
@file{TAGS} file that includes by reference all @file{TAGS} files from
subdirectories.

Also, if the variable @code{ETAGS_ARGS} is defined, a @code{tags} target
will be generated.  This variable is intended for use in directories
which contain taggable source that @code{etags} does not understand.

Here is how Automake generates tags for its source, and for nodes in its
Texinfo file:

@example
ETAGS_ARGS = automake.in --lang=none \
 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
@end example

Automake will also generate an @code{ID} target which will run
@code{mkid} on the source.  This is only supported on a
directory-by-directory basis.
@trindex id


@node Suffixes
@section Handling new file extensions

It is sometimes useful to introduce a new implicit rule to handle a file
type that Automake does not know about.  If this is done, you must
notify GNU Make of the new suffixes.  This can be done by putting a list
of new suffixes in the @code{SUFFIXES} variable.
@vindex SUFFIXES


@node Built
@section Built sources

FIXME write this


@node Extending
@chapter When Automake Isn't Enough

Sometimes @code{automake} isn't enough.  Then you just lose.

Actually, @code{automake}s implicit copying semantics means that many
problems can be worked around by simply adding some @code{make} targets
and rules to @file{Makefile.in}.  @code{automake} will ignore these
additions.

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

The targets that support a local version are @code{all}, @code{info},
@code{dvi}, @code{check}, @code{install-data}, @code{install-exec}, and
@code{uninstall}.
@trindex all
@trindex info
@trindex dvi
@trindex check
@trindex install-data
@trindex install-exec
@trindex uninstall

For instance, here is how to install a file in @file{/etc}:

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

@c FIXME should include discussion of variables you can use in these
@c rules


@node Distributing
@chapter Distributing @file{Makefile.in}s

Automake places no restrictions on the distribution of the resulting
@file{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
@samp{--add-missing} switch do fall under the GPL; examine each file
to see.


@node Examples
@chapter Some example packages

Here are some examples of how Automake can be used.

@menu
* Hello::                       The simplest GNU program
* Tricky::                      A trickier example
* Automake::                    Automake's own use
* Textutils::                   A deep hierarchy
@end menu

@node Hello
@section The simplest GNU program

@code{hello} is renowned for its classic simplicity and versatility.
What better place to begin a tour?  The below shows what could be used
as the Hello distribution's @file{Makefile.am}.

@example
bin_PROGRAMS = hello
hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h
hello_LDADD = @@ALLOCA@@
info_TEXINFOS = hello.texi
hello_TEXINFOS = gpl.texi

EXTRA_DIST = testdata

check-local: hello
        @@echo expect no output from diff
        ./hello > test.out
        diff -c $(srcdir)/testdata test.out
        rm -f test.out
@end example

Of course, Automake also requires some minor changes to
@file{configure.in}.  The new @file{configure.in} would read:

@example
dnl Process this file with autoconf to produce a configure script.
AC_INIT(hello.c)
VERSION=1.3
AC_SUBST(VERSION)
PACKAGE=hello
AC_SUBST(PACKAGE)
AC_PROG_CC
AC_PROG_CPP
AC_PROG_INSTALL
AC_STDC_HEADERS
AC_HAVE_HEADERS(string.h fcntl.h sys/file.h)
AC_ALLOCA
AC_OUTPUT(Makefile)
@end example

If Hello were really going to use Automake, the @file{version.c} file
would probably be deleted, or changed so as to be automatically
generated.


@node Tricky
@section A tricker example

Here is another, trickier example.  It shows how to generate two
programs (@code{ctags} and @code{etags}) from the same source file
(@file{etags.c}).  The difficult part is that each compilation of
@file{etags.c} requires different @code{cpp} flags.

@example
bin_PROGRAMS = etags ctags
ctags_SOURCES =
ctags_LDADD = ctags.o

etags.o:
        $(COMPILE) -DETAGS_REGEXPS etags.c

ctags.o:
        $(COMPILE) -DCTAGS -o ctags.o etags.c
@end example

Note that @code{ctags_SOURCES} is defined to be empty -- that way no
implicit value is substituted.  The implicit value, however, is used to
generate @code{etags} from @file{etags.o}.


@node Automake
@section Automake uses itself

Automake, of course, uses itself to generate its @file{Makefile.in}.
Since Automake is a shallow package, it has more than one
@file{Makefile.am}.  Here is the top-level @file{Makefile.am}:

@example
## Process this file with automake to create Makefile.in

AUTOMAKE_OPTIONS = gnits
MAINT_CHARSET = latin1
PERL = @@PERL@@

SUBDIRS = tests

bin_SCRIPTS = automake
info_TEXINFOS = automake.texi

pkgdata_DATA = clean-kr.am clean.am compile-kr.am compile-vars.am \
compile.am data.am depend.am \
dist-vars.am footer.am header.am header-vars.am \
kr-vars.am libraries-vars.am \
libraries.am library.am mans-vars.am \
program.am programs.am remake-hdr.am \
remake-subd.am remake.am scripts.am subdirs.am tags.am tags-subd.am \
tags-clean.am \
texi-version.am texinfos-vars.am texinfos.am \
libraries-clean.am programs-clean.am data-clean.am \
COPYING INSTALL texinfo.tex \
ansi2knr.c ansi2knr.1 \
aclocal.m4

## These must all be executable when installed.
pkgdata_SCRIPTS = config.guess config.sub install-sh mdate-sh mkinstalldirs

CLEANFILES = automake

# The following requires a fixed version of the Emacs 19.30 etags.
ETAGS_ARGS = automake.in --lang=none \
 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi

## `test -x' is not portable.  So we use Perl instead.  If Perl
## doesn't exist, then this test is meaningless anyway.
# Check to make sure some installed files are executable.
installcheck-local:
        $(PERL) -e "exit ! -x '$(pkgdatadir)/config.guess';"
        $(PERL) -e "exit ! -x '$(pkgdatadir)/config.sub';"
        $(PERL) -e "exit ! -x '$(pkgdatadir)/install-sh';"
        $(PERL) -e "exit ! -x '$(pkgdatadir)/mdate-sh';"
        $(PERL) -e "exit ! -x '$(pkgdatadir)/mkinstalldirs';"

# Some simple checks:
# * syntax check with perl4 and perl5.
# * make sure the scripts don't use 'true'
# * expect no instances of '$@{...@}'
# These are only really guaranteed to work on my machine.
maintainer-check: automake check
        $(PERL) -c -w automake
        @@if grep '^[^#].*true' $(srcdir)/[a-z]*.am; then \
          echo "can't use 'true' in GNU Makefile" 1>&2; \
          exit 1;                               \
        else :; fi
        @@if test `fgrep '$$@{' $(srcdir)/[a-z]*.am | wc -l` -ne 0; then \
          echo "found too many uses of '\$$@{'" 1>&2; \
          exit 1;                               \
        fi
        if $(SHELL) -c 'perl4.036 -v' >/dev/null 2>&1; then \
          perl4.036 -c -w automake; \
        else :; fi

# Tag before making distribution.  Also, don't make a distribution if
# checks fail.  Also, make sure the NEWS file is up-to-date.
cvs-dist: maintainer-check
        @@if sed 1q NEWS | grep -e "$(VERSION)" > /dev/null; then :; else \
          echo "NEWS not updated; not releasing" 1>&2; \
          exit 1;                               \
        fi
        cvs tag `echo "Release-$(VERSION)" | sed 's/\./-/g'`
        $(MAKE) dist
@end example

As you can see, Automake defines many of its own rules, to make the
maintainer's job easier.  For instance the @code{cvs-dist} rule
automatically tags the current version in the CVS repository, and then
makes a standard distribution.

Automake consists primarily of one program, @code{automake}, and a
number of auxiliary scripts.  Automake also installs a number of
programs which are possibly installed via the @samp{--add-missing}
option; these scripts are listed in the @code{pkgdata_SCRIPTS} variable.

Automake also has a @file{tests} subdirectory, as indicated in the
@code{SUBDIRS} variable above.  Here is @file{tests/Makefile.am}:

@example
## Process this file with automake to create Makefile.in

AUTOMAKE_OPTIONS = gnits

TESTS = mdate.test vtexi.test acoutput.test instexec.test checkall.test \
acoutnoq.test acouttbs.test libobj.test proginst.test acoutqnl.test \
confincl.test spelling.test prefix.test badprog.test depend.test

EXTRA_DIST = defs
@end example

This is where all the tests are really run.  @file{defs} is an
initialization file used by each test script; it is explicitly mentioned
because @code{automake} has no way of automatically finding it.


@node Textutils
@section A deep hierarchy

The GNU textutils are a collection of programs for manipulating text
files.  They are distributed as a deep package.  The textutils have only
recently been modified to use Automake; the examples come from a
prerelease.

Here is the top-level @file{Makefile.am}:

@example
SUBDIRS = lib src doc man
@end example

In the @file{lib} directory, a library is built which is used by each
textutil.  Here is @file{lib/Makefile.am}:

@example
noinst_LIBRARIES = tu

EXTRA_DIST = rx.c regex.c

tu_SOURCES = error.h getline.h getopt.h linebuffer.h \
long-options.h md5.h regex.h rx.h xstrtod.h xstrtol.h xstrtoul.h \
error.c full-write.c getline.c getopt.c getopt1.c \
linebuffer.c long-options.c md5.c memchr.c safe-read.c \
xmalloc.c xstrtod.c xstrtol.c xstrtoul.c

tu_LIBADD = @@REGEXOBJ@@ @@LIBOBJS@@ @@ALLOCA@@
@end example

The @file{src} directory contains the source for all the textutils -- 23
programs in all.  The @file{Makefile.am} for this directory also
includes some simple checking code, and constructs a @file{version.c}
file on the fly:

@example
bin_PROGRAMS = cat cksum comm csplit cut expand fmt fold head join md5sum \
nl od paste pr sort split sum tac tail tr unexpand uniq wc

noinst_HEADERS = system.h version.h
DISTCLEANFILES = stamp-v version.c

INCLUDES = -I$(top_srcdir)/lib

LDADD = version.o ../lib/libtu.a

$(PROGRAMS): version.o ../lib/libtu.a

AUTOMAKE_OPTIONS = ansi2knr

version.c: stamp-v
stamp-v: Makefile
        rm -f t-version.c
        echo '#include <config.h>' > t-version.c
        echo '#include "version.h"' >> t-version.c
        echo 'const char *version_string = "'GNU @@PACKAGE@@ @@VERSION@@'";' \
                >> t-version.c
        if cmp -s version.c t-version.c; then   \
          rm t-version.c;                       \
        else                                    \
          mv t-version.c version.c;             \
        fi
        echo timestamp > $@@

check: md5sum
        ./md5sum \
         --string="" \
         --string="a" \
         --string="abc" \
         --string="message digest" \
         --string="abcdefghijklmnopqrstuvwxyz" \
         --string="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" \
         --string="12345678901234567890123456789012345678901234567890123456789012345678901234567890" \
       | diff -c $(srcdir)/md5-test.rfc -
@end example

The @file{doc} directory builds the info documentation for the
textutils:

@example
info_TEXINFOS = textutils.texi
@end example

And, last, the @file{man} directory installs the man pages for all the
textutils:

@example
man_MANS = cat.1 cksum.1 comm.1 csplit.1 cut.1 expand.1 fmt.1 fold.1 head.1 \
join.1 md5sum.1 nl.1 od.1 paste.1 pr.1 sort.1 split.1 sum.1 tac.1 tail.1 \
tr.1 unexpand.1 uniq.1 wc.1
@end example

You can now see how easy it is to handle even a largish project using
Automake.


@node Future
@chapter Some ideas for the future

Here are some things that might happen in the future:

@itemize @bullet
@item
HTML support.

@item
The output will be cleaned up.  For instance, only variables which are
actually used will appear in the generated @file{Makefile.in}.

@item
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
@w{ISO 10646} with the UTF-8 encoding.
@end itemize


@node Variables
@unnumbered Index of Variables

@printindex vr


@node Configure variables
@unnumbered Index of Configure Variables and Macros

@printindex cv


@node Targets
@unnumbered Index of Targets

@printindex tr


@bye