source: trunk/essentials/sys-devel/automake-1.4/automake.texi

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

@include version.texi

@dircategory GNU admin
@direntry
* automake: (automake).         Making Makefile.in's
@end direntry

@dircategory Individual utilities
@direntry
* aclocal: (automake)Invoking aclocal.          Generating aclocal.m4
@end direntry

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

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.

@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}
@author David MacKenzie and Tom Tromey

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995, 96 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 @*
59 Temple Place - Suite 330, @*
Boston, MA 02111-1307 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 output variables.
@defcodeindex ov
@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
@c Define an index of commands.
@defcodeindex cm

@c Put the macros and variables into their own index.
@c @syncodeindex fn cp
@syncodeindex ov vr
@syncodeindex cv vr
@syncodeindex fn vr

@c Put everything else into one index (arbitrarily chosen to be the concept index).
@syncodeindex op cp
@syncodeindex tr cp
@syncodeindex cm cp

@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
* Generalities::                General ideas
* Examples::                    Some example packages
* Invoking Automake::           Creating a Makefile.in
* configure::                   Scanning configure.in
* Top level::                   The top-level Makefile.am
* Programs::                    Building programs and libraries
* Other objects::               Other derived objects
* Other GNU Tools::             Other GNU Tools
* 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
* Include::                     Including extra files in an Automake template.
* Conditionals::                Conditionals
* Gnits::                       The effect of @code{--gnu} and @code{--gnits}
* Cygnus::                      The effect of @code{--cygnus}
* Extending::                   Extending Automake
* Distributing::                Distributing the Makefile.in
* Future::                      Some ideas for the future
* Macro and Variable Index::    
* General Index::               
@end menu

@end ifinfo


@node Introduction, Generalities, Top, Top
@chapter Introduction

Automake is a tool for automatically generating @file{Makefile.in}s from
files called @file{Makefile.am}.  Each @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.

@cindex GNU Makefile standards

The GNU Makefile Standards Document
(@pxref{Makefile Conventions, , , standards, 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 file 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.

@cindex Constraints of Automake
@cindex Automake constraints

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

@cindex Automake requirements
@cindex Requirements, Automake

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.

@cindex BUGS, reporting
@cindex Reporting BUGS
@cindex E-mail, bug reports

Mail suggestions and bug reports for Automake to
@email{bug-automake@@gnu.org}.


@node Generalities, Examples, Introduction, Top
@chapter General ideas

The following sections cover a few basic ideas that will help you
understand how Automake works.

@menu
* General Operation::           General operation of Automake
* Depth::                       The kinds of packages
* Strictness::                  Standards conformance checking
* Uniform::                     The Uniform Naming Scheme
* Canonicalization::            How derived variables are named
@end menu


@node General Operation, Depth, Generalities, Generalities
@section General Operation

Automake works by reading a @file{Makefile.am} and generating a
@file{Makefile.in}.  Certain macros and targets defined in the
@file{Makefile.am} instruct Automake to generate more specialized code;
for instance, a @samp{bin_PROGRAMS} macro definition will cause targets
for compiling and linking programs to be generated.

@cindex Non-standard targets
@cindex cvs-dist, non-standard example
@trindex cvs-dist

The macro definitions and targets in the @file{Makefile.am} are copied
verbatim into the generated file.  This allows you to add arbitrary code
into the generated @file{Makefile.in}.  For instance the Automake
distribution includes a non-standard @code{cvs-dist} target, which the
Automake maintainer uses to make distributions from his source control
system.

@cindex GNU make extensions

Note that GNU make extensions are not recognized by Automake.  Using
such extensions in a @file{Makefile.am} will lead to errors or confusing
behavior.

Automake tries to group comments with adjoining targets and macro
definitions in an intelligent way.

@cindex Make targets, overriding
@cindex Overriding make targets

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.

@cindex Macros, overriding
@cindex Overriding make macros

Similarly, a macro defined in @file{Makefile.am} will override any
definition of the macro that @code{automake} would ordinarily create.
This feature is more often useful than the ability to override a target
definition.  Be warned that many of the macros generated by
@code{automake} are considered to be for internal use only, and their
names might change in future releases.

@cindex Recursive operation of Automake
@cindex Automake, recursive operation
@cindex Example of recursive operation

When examining a macro definition, Automake will recursively examine
macros referenced in the definition.  For example, if Automake is
looking at the content of @code{foo_SOURCES} in this snippet

@example
xs = a.c b.c
foo_SOURCES = c.c $(xs)
@end example

it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
contents of @code{foo_SOURCES}.

@cindex ## (special Automake comment)
@cindex Special Automake comment
@cindex Comment, special to Automake

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:

@cindex Makefile.am, first line
@cindex First line of Makefile.am

@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 Depth, Strictness, General Operation, Generalities
@section Depth

@cindex Flat package
@cindex Package, Flat
@cindex Shallow package
@cindex Package, shallow
@cindex Deep package
@cindex Package, deep

@code{automake} supports three kinds of directory hierarchy:
@samp{flat}, @samp{shallow}, and @samp{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

@cindex SUBDIRS, deep package

A @dfn{deep} package is one in which all the source lies in
subdirectories; the top level directory contains mainly configuration
information.  GNU @code{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.  Automake is one such package (as is GNU
@code{make}, which does not currently use @code{automake}).


@node Strictness, Uniform, Depth, Generalities
@section Strictness

@cindex Non-GNU packages

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

@cindex Strictness, defined
@cindex Strictness, foreign
@cindex foreign strictness
@cindex Strictness, gnu
@cindex gnits strictness
@cindex Strictness, gnits
@cindex gnits strictness

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 @dfn{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

For more information on the precise implications of the strictness
level, see @ref{Gnits}.


@node Uniform, Canonicalization, Strictness, Generalities
@section The Uniform Naming Scheme

@cindex Uniform naming scheme

Automake macros (from here on referred to as @emph{variables}) generally
follow a @dfn{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.

@cindex _PROGRAMS primary variable
@cindex PROGRAMS primary variable
@cindex Primary variable, PROGRAMS

@cindex Primary variable, defined

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