fixlet

[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 @*
59 Template 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 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
* 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
* Gnits::                       The effect of --gnu and --gnits
* 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
bug-gnu-utils@@prep.ai.mit.edu.


@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 -a
@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.  In general if Automake tells you a
file is missing, try using this option.

@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 --build-dir=@var{dir}
Tell Automake where the build directory is.  This option is used when
including dependencies into a @file{Makefile.in} generated by @code{make
dist}; it should not be used otherwise.

@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 -i
@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 -o @var{dir}
@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 --srcdir-name=@var{dir}
Tell Automake the name of the source directory used in the current
build.  This option is used when including dependencies into a
@file{Makefile.in} generated by @code{make dist}; it should not be used
otherwise.

@item -s @var{level}
@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 -v
@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

There are a few basic ideas that will help 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
@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.  This allows you to add essentially 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.

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 (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.

When examining a variable definition, Automake will recursively examine
variables referenced in the definition.  Eg if Automake is looking at
the content of @samp{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 @samp{foo_SOURCES}.

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 Depth
@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}).


@node Strictness
@section Strictness
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.

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

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


@node Uniform
@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.

The special prefix @samp{check} indicates that the objects in question
should not be built until the @code{make check} command is run.

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


@node Canonicalization
@section How derived variables are named

Sometimes a Makefile variable name is derived from some text the user
supplies.  For instance program names are rewritten into Makefile macro
names.  Automake canonicalizes this text, so that it does not have to
follow Makefile variable naming rules.  All characters in the name
except for letters, numbers, and the underscore are turned into
underscores when making macro references.  Eg, if your program is named
@code{sniff-glue}, the derived variable name would be
@code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}.


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

Automake scans the package's @file{configure.in} to determine certain
information about the package.  Some @code{autoconf} macros are required
and some variables must be defined in @file{configure.in}.  Automake
will also use information from @file{configure.in} to further tailor its
output.

@menu
* Requirements::                Configuration requirements
* Optional::                    Other things Automake recognizes
* Invoking aclocal::            Auto-generating aclocal.m4
* Macros::                      Autoconf macros supplied with Automake
* Extending aclocal::           Writing your own aclocal macros
@end menu


@node Requirements
@section Configuration requirements

The simplest way to meet the basic Automake requirements is to use the
macro @code{AM_INIT_AUTOMAKE} (FIXME: xref).  But if you prefer, you can
do the required steps by hand:
@cvindex AM_INIT_AUTOMAKE

@itemize @bullet
@item
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 defines @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 doesn't do any interpretation of @code{PACKAGE} or
@code{VERSION}, except in @samp{Gnits} mode (FIXME xref).

@item
Use the macro @code{AC_ARG_PROGRAM} if a program or script is installed.
@cvindex AC_ARG_PROGRAM

@item
Use @code{AC_PROG_MAKE_SET} if the package is not flat.
@cvindex AC_PROG_MAKE_SET

@item
Use @code{AM_PROG_INSTALL} if any scripts (@pxref{Scripts}) are
installed by the package.  Otherwise, use @code{AC_PROG_INSTALL}.
@cvindex AC_PROG_INSTALL
@cvindex AM_PROG_INSTALL
@end itemize


Here are the other macros which Automake requires but which are not run
by @code{AM_INIT_AUTOMAKE}:

@table @code
@item AC_OUTPUT
Automake uses this to determine which files to create.  Listed files
named @code{Makefile} are treated as @file{Makefile}s.  Other listed
files are treated differently.  Currently the only difference is that a
@file{Makefile} is removed by @code{make distclean}, while other files
are removed by @code{make clean}.
@c FIXME: this is in violation of standards!
@cvindex AC_OUTPUT
@end table

@node Optional
@section Other things Automake recognizes

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.  If you do use this macro, you must create the file
@file{stamp-h.in} in your source directory.  It can be empty.  Also, the
@code{AC_OUTPUT} command in @file{configure.in} must create
@file{stamp-h}, eg:
@example
AC_OUTPUT(Makefile,
[test -z "$CONFIG_HEADERS" || echo timestamp > stamp-h])
@end example
@cvindex AC_CONFIG_HEADER
Note that Automake does not currently currently check to make sure the
@code{AC_OUTPUT} command is correct.  Hopefully a future version of
@code{autoconf} will let Automake handle this automatically.

@item AC_CONFIG_AUX_DIR
Automake will look for various helper scripts, such as
@file{mkinstalldirs}, in the directory named in this macro invocation.
If not seen, the scripts are looked for in their ``standard'' locations
(either the top source directory, or in the source directory
corresponding to the current @file{Makefile.am}, whichever is
appropriate).
@cvindex AC_CONFIG_AUX_DIR
FIXME: give complete list of things looked for in this directory

@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_CHECK_TOOL
Automake will ensure that @file{config.guess} and @file{config.sub}
exist.  Also, the @file{Makefile} variables @samp{host_alias} and
@samp{host_triplet} are introduced.
@c fixme xref autoconf docs.
@cvindex AC_CANONICAL_HOST
@cvindex AC_CHECK_TOOL
@vindex host_alias
@vindex host_triplet

@item AC_CANONICAL_SYSTEM
This is similar to @code{AC_CANONICAL_HOST}, but also defines the
@file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
@cvindex AC_CANONICAL_SYSTEM
@vindex build_alias
@vindex target_alias

@item AC_FUNC_ALLOCA
@item AC_FUNC_GETLOADAVG
@item AC_FUNC_MEMCMP
@item AC_STRUCT_ST_BLOCKS
@item AM_FUNC_FNMATCH
@item AM_FUNC_STRTOD
@item AC_REPLACE_FUNCS
@item AC_REPLACE_GNU_GETOPT
@item AM_WITH_REGEX
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 AM_FUNC_FNMATCH
@cvindex AC_FUNC_FNMATCH
@cvindex AC_REPLACE_FUNCS
@cvindex AC_REPLACE_GNU_GETOPT
@cvindex AM_FUNC_STRTOD
@cvindex AM_WITH_REGEX

@item LIBOBJS
Automake will detect statements which put @samp{.o} files into
@code{LIBOBJS}, and will treat these additional files as if they were
discovered via @code{AC_REPLACE_FUNCS}.
@cvindex LIBOBJS

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

@item AC_PROG_CXX
This is required if any C++ source is included.
@cvindex AC_PROG_CXX

@c @item AM_PROG_LIBTOOL
@c Automake will turn on processing for @code{libtool} (@pxref{Top, , The
@c Libtool Manual, libtool.info, The Libtool Manual}).  This work is
@c still preliminary.
@c @cvindex AM_PROG_LIBTOOL

@item AC_PROG_YACC
If a Yacc source file is seen, then you must either use this macro or
declare the variable @samp{YACC} in @file{configure.in}.  The former is
preferred.
@cvindex AC_PROG_YACC
@cvindex YACC

@item AC_DECL_YYTEXT
This macro is required if there is Yacc source in the package.
@cvindex AC_DECL_YYTEXT

@item AC_PROG_LEX
If a Lex source file is seen, then this macro must be used.
@cvindex AC_PROG_LEX

@item ALL_LINGUAS
If Automake sees that this variable is set in @file{configure.in}, it
will check the @file{po} directory to ensure that all the named
@samp{.po} files exist, and that all the @samp{.po} files that exist are
named.
@cvindex ALL_LINGUAS

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

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

@item AM_MAINTAINER_MODE
This macro adds a @samp{--enable-maintainer-mode} option to
@code{configure}.  If this is used, @code{automake} will cause
``maintainer-only'' rules to be turned off by default in the generated
@file{Makefile.in}s.  This macro is disallowed in @samp{Gnits} mode.
FIXME xref.
@cvindex jm_MAINTAINER_MODE
@end table


@node Invoking aclocal
@section Auto-generating aclocal.m4

The @code{aclocal} program will automatically generate @file{aclocal.m4}
files based on the contents of @file{configure.in}.

... explain why on earth you'd want to do this

@code{aclocal} accepts the following options:

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

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

@item --output=@var{file}
Cause the output to be put into @var{file} instead of @file{aclocal.m4}.

@item --verbose
Print the names of the files it examines.

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


@node Macros
@section Autoconf macros supplied with Automake

@c consider generating this node automatically from m4 files.

@table @code
@item AM_FUNC_FNMATCH
If the @code{fnmatch} function is not available, or does not work
correctly (like the one on SunOS 5.4), add @samp{fnmatch.o} to output
variable @code{LIBOBJS}.

@item AM_FUNC_STRTOD
If the @code{strtod} function is not available, or does not work
correctly (like the one on SunOS 5.4), add @samp{strtod.o} to output
variable @code{LIBOBJS}.

@item AM_C_PROTOTYPES
@item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
@item AM_INIT_AUTOMAKE
@item AM_MAINTAINER_MODE
@item AM_PATH_LISPDIR
@item AM_PROG_CC_STDC
@item AM_PROG_INSTALL
@item AM_SANITY_CHECK_CC
@item AM_SYS_POSIX_TERMIOS
@item AM_TYPE_PTRDIFF_T
@item AM_WITH_DMALLOC
@item AM_WITH_REGEX
@end table


@node Extending aclocal
@section Writing your own aclocal macros

... explain format of macro files
... explain how to get your own macros installed (using acinstall)
... explain situations where this is actually useful (eg gettext)


@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}.

The use of @code{SUBDIRS} is not restricted to just the top-level
@file{Makefile.am}.  Automake can be used to construct packages of
arbitrary depth.


@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
* LIBOBJS::                     Special handling for LIBOBJS and ALLOCA
* Program variables::           Variables used when building a program
* Yacc and Lex::                Yacc and Lex support
* C++::                         C++ and other languages
* 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}.  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 included in
the distribution but otherwise ignored.  In case it isn't obvious, you
should not include the header file generated by @file{configure} in an
@samp{_SOURCES} variable; this file should not be distributed.
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 builds @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

It is also occasionally useful to have a program depend on some other
target which is not actually part of that program.  This can be done
using the @samp{prog_DEPENDENCIES} variable.  Each program depends on
the contents of such a variable, but no further interpretation is done.

If @samp{prog_DEPENDENCIES} is not supplied, it is computed by Automake.
The automatically-assigned value is the contents of @samp{prog_LDADD}
with all the @samp{-l} and @samp{-L} options removed.  Be warned that
@file{configure} substitutions are preserved; this can lead to bad
dependencies if you are not careful.


@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


@node LIBOBJS
@section Special handling for LIBOBJS and ALLOCA

Automake explicitly recognizes the use of @code{@@LIBOBJS@@} and
@code{@@ALLOCA@@}, 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}.

@code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
@samp{_LDADD} or @samp{_LIBADD} variable.


@node Program variables
@section Variables used when building a program

Occasionally it is useful to know which @file{Makefile} variables
Automake uses for compilations; for instance you might need to do your
own compilation in some special cases.

Some variables are inherited from Autoconf; these are @code{CC},
@code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
@code{LIBS}.


There are some additional variables which Automake itself defines:

@table @code
@item INCLUDES
A list of @samp{-I} options.  This can be set in your @file{Makefile.am}
if you have special directories you want to look in.

@item COMPILE
This is the command used to actually compile a C source file.  The
filename is appended to form the complete command line.

@item LINK
This is the command used to actually link a C program.
@end table


@node Yacc and Lex
@section Yacc and Lex support

Automake has somewhat idiosyncratic support for Yacc and Lex.
FIXME: describe it here.


@node C++
@section C++ and other languages

Automake includes full support for C++, and rudimentary support for
other languages.  Support for other languages will be improved based on
demand.

Any package including C++ code must use @code{AC_PROG_CXX} in its
@file{configure.in}.

A few additional variables are defined when a C++ source file is seen:

@table @code
@item CXX
The name of the C++ compiler.

@item CXXFLAGS
Any flags to pass to the C++ compiler.

@item CXXCOMPILE
The command used to actually compile a C++ source file.  The file name
is appended to form the complete command line.

@item CXXLINK
The command used to actually link a C++ program.
@end table


@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{AM_C_PROTOTYPES}.
@cvindex AM_C_PROTOTYPES

Automake also handles finding the @code{ansi2knr} support files in some
other directory in the current package.  This is done by prepending the
relative path to the appropriate directory to the @code{ansi2knr}
option.  For instance, suppose the package has ANSI C code in the
@file{src} and @file{lib} subdirs.  The files @file{ansi2knr.c} and
@file{ansi2knr.1} appear in @file{lib}.  Then this could appear in
@file{src/Makefile.am}:

@example
AUTOMAKE_OPTIONS = ../lib/ansi2knr
@end example

Note that the directory holding the @code{ansi2knr} support files must
be built before all other directories using these files.  Automake does
not currently check that this is the case.


@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

If you unpack a distribution made by @code{make dist}, and you want to
turn on the dependency-tracking code again, simply run @code{automake}
with no arguments.


@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
* Sources::                     Derived sources
@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 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, a target
for it is 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 clearest to list uninstalled headers
with the rest of the sources for a program.  @xref{A Program}.  Headers
listed in a @samp{_SOURCES} variable need not be listed in any
@samp{_HEADERS} variable.

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{automake} 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 Sources
@section Built sources

Occasionally a file which would otherwise be called ``source'' (eg a C
@samp{.h} file) is actually derived from some other file.  Such files
should be listed in the @code{BUILT_SOURCES} variable.
@vindex BUILT_SOURCES

Files listed in @code{BUILT_SOURCES} are built before any automatic
dependency tracking is done.  Built sources are included in a
distribution.


@node Other GNU Tools
@chapter Other GNU Tools

Since Automake is primarily intended to generate @file{Makefile.in}s for
use in GNU programs, it tries hard to interoperatoe with other GNU
tools.

@menu
* Emacs Lisp::                  Emacs Lisp
* gettext::                     Gettext
@end menu

@node Emacs Lisp
@section Emacs Lisp

Automake provides some support for Emacs Lisp.  The @samp{LISP} primary
is used to hold a list of @samp{.el} files.  Possible prefixes for this
primary are @samp{lisp_} and @samp{noinst_}.  Note that if
@code{lisp_LISP} is defined, then @file{configure.in} must run
@code{AM_PATH_LISPDIR} (fixme xref).
@vindex LISP
@vindex lisp_LISP
@vindex noinst_LISP

By default Automake will byte-compile all Emacs Lisp source files using
the Emacs found by @code{AM_PATH_LISPDIR}.  If you wish to avoid
byte-compiling, simply define the variable @samp{ELCFILES} to be empty.
@vindex ELCFILES

@node gettext
@section Gettext

If @code{ud_GNU_GETTEXT} is seen in @file{configure.in}, then Automake
turns on support for GNU gettext, a message catalog system for
internationalization
(@pxref{GNU Gettext, , , gettext.info, GNU gettext utilities}).

The @code{gettext} support in Automake requires the addition of two
subdirectories to the package, @file{intl} and @file{po}.  Automake
ensure that these directories exist and are mentioned in @code{SUBDIRS}.

Furthermore, Automake checks that the definition of @samp{ALL_LINGUAS}
in @file{configure.in} corresponds to all the valid @samp{.po} files,
and nothing more.


@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} or
@samp{.texinfo} extension.
@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

By default, Automake requires the file @file{texinfo.tex} to appear in
the same directory as the Texinfo source.  However, if you used
@code{AC_CONFIG_AUX_DIR} in @file{configure.in}, then @file{texinfo.tex}
is looked for there.  Automake supplies @file{texinfo.tex}.

Automake generates an @code{install-info} target; some people apparently
use this.  By default, info pages are installed by @samp{make install}.
This can be prevented via the @code{no-installinfo} option.


@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{LISP}, @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


@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; more
precisely it is named @samp{@var{PACKAGE}-@var{VERSION}.tar.gz}.
@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

Occasionally it is useful to be able to change the distribution before
it is packaged up.  If the @code{dist-hook} target exists, it is run
after the distribution directory is filled, but before the actual tar
(or shar) file is created.  One way to use this is for distributing file
in subdirectories for which a new @file{Makefile.am} is overkill:

@example
dist-hook:
        mkdir $(distdir)/random
        cp -p random/a1 random/a2 $(distdir)/random
@end example

Automake also generates a @code{distcheck} target which can be help to
ensure that a given distribution will actually work.  @code{distcheck}
makes a distribution, and then tries to do a @code{VPATH} build.
@trindex distcheck
@c FIXME: document distcheck-hook here

@node Tests
@chapter Support for test suites

Automake supports a two forms 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 number of failures will be printed at
the end of the run.  The variable @code{TESTS_ENVIRONMENT} can be used
to set environment variables for the test run; the environment variable
@code{srcdir} is set in the rule.
@vindex TESTS
@vindex TESTS_ENVIRONMENT

If @samp{dejagnu} appears in @code{AUTOMAKE_OPTIONS}, then the a
@code{dejagnu}-based test suite is assumed.  The value of the variable
@code{DEJATOOL} is passed as the @code{--tool} argument to
@code{runtest}; it defaults to the name of the package.  The variables
@code{EXPECT}, @code{RUNTEST} and @code{RUNTESTFLAGS} can also be
overridden to provide project-specific values.  For instance, you will
need to do this if you are testing a compiler toolchain, because the
default values do not take into account host and target names.
@opindex dejagnu
@vindex DEJATOOL
@vindex EXPECT
@vindex RUNTEST
@vindex RUNTESTFLAGS
@c FIXME xref dejagnu

In either case, the testing is done via @samp{make check}.


@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.  This option is disallowed at
@samp{GNU} strictness and above.
@trindex install-man

@item @code{no-installinfo}
The generated @file{Makefile.in} will not cause info pages to be built
or installed by default.  However, @code{info} and @code{install-info}
targets will still be available.  This option is disallowed at
@samp{GNU} strictness and above.
@trindex info
@trindex install-info

@item @code{ansi2knr}
@item @code{path/ansi2knr}
Turn on automatic de-ANSI-fication.  @xref{ANSI}.  If preceeded by a
path, the generated @file{Makefile.in} will look in the specified
directory to find the @file{ansi2knr} program.  Generally the path
should be a relative path to another directory in the same distribution
(though Automake currently does not check this).  It is up to you to
make sure that the specified directory is built before the current
directory; if @file{ansi2knr} does not exist then the build will fail.

@item @code{dejagnu}
Cause @code{dejagnu}-specific rules to be generated.  @xref{Tests}.

@item @code{dist-shar}
Generate a @code{dist-shar} target as well as the ordinary @code{dist}
target.  This new target will create a shar archive of the
distribution.
@trindex dist-shar

@item @code{dist-zip}
Generate a @code{dist-zip} target as well as the ordinary @code{dist}
target.  This new target will create a zip archive of the distribution.
@trindex dist-zip

@item @code{dist-tarZ}
Generate a @code{dist-tarZ} target as well as the ordinary @code{dist}
target.  This new target will create a compressed tar archive of the
distribution; a traditional @code{tar} and @code{compress} will be
assumed.  Warning: if you are actually using @code{GNU tar}, then the
generated archive might contain nonportable constructs.
@trindex dist-tarZ

@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.
@vindex ETAGS_ARGS

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

If you add filenames to @var{ETAGS_ARGS}, you will probably also
want to set @var{TAGS_DEPENDENCIES}.  The contents of this variable
are added directly to the dependencies for the @code{tags} target.
@vindex TAGS_DEPENDENCIES

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 Gnits
@chapter The effect of --gnu and --gnits

The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
variable) causes @code{automake} to check the following:

@itemize @bullet
@item
The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{COPYING},
@file{AUTHORS}, and @file{ChangeLog} are required at the topmost
directory of the package.

@item
The options @samp{no-installman} and @samp{no-installinfo} are
prohibited.
@end itemize

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, @samp{--gnu} can require certain
non-standard GNU programs to exist for use by various maintainer-only
targets; for instance in the future @code{pathchk} might be required for
@samp{make dist}.

The @samp{--gnits} option does everything that @samp{--gnu} does, and
checks the following as well:

@itemize @bullet
@item
@samp{make dist} will check to make sure the @file{NEWS} file has been
updated to the current version.

@item
The file @file{COPYING.LIB} is prohibited.

@item
@samp{VERSION} is checked to make sure its format complies with Gnits
standards.
@c FIXME xref when standards are finished

@item
If @samp{VERSION} indicates that this is an alpha release, and the file
@file{README-alpha} appears in the topmost directory of a package, then
it is included in the distribution.

@item
The file @file{THANKS} is required.
@end itemize


@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}.  Note that there are no @code{uninstall-exec-local} or
@code{uninstall-data-local} targets; just use @code{uninstall-local}.
It doesn't make sense to uninstall just data or just executables.
@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

Some targets also have a way to run another target, called a @dfn{hook},
after their work is done.  The hook is named after the principal target,
with @samp{-hook} appended.  The targets allowing hooks are
@code{install-data}, @code{install-exec}, @code{dist}, and
@code{distcheck}.
@trindex install-data-hook
@trindex install-exec-hook
@trindex dist-hook

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

@example
install-exec-hook:
        ln $(bindir)/program $(bindir)/proglink
@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)
AM_INIT_AUTOMAKE(hello, 1.3)
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
ctags_DEPENDENCIES = 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}.

@code{ctags_LDADD} is used to get @file{ctags.o} into the link line,
while @code{ctags_DEPENDENCIES} exists to make sure that @file{ctags.o}
gets built in the first place.

This is a somewhat pathological example.


@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

# 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