* Miscellaneous:: Miscellaneous rules
* Extending:: Extending Automake
* Distributing:: Distributing the Makefile.in
-* Future:: Some ideas for the future.
+* 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
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}.
+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:
@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
-@samp{AC_CANONICAL_HOST}. Automake is distributed with several of these
+@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.
@code{automake} supports three kinds of directory hierarchy: ``flat'',
``shallow'', and ``deep''.
-A 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
-@samp{SUBDIRS} macro. An example of such a package is @code{termutils}.
+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 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
-@samp{SUBDIRS} macro, but no other macros to define objects which are
-built.
+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 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}).
+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
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 ``strictness'' -- the
+To this end, Automake supports three levels of @dfn{strictness} -- the
strictness indicating how stringently Automake should check standards
conformance.
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 ``primary''
-variables. For instance, the primary variable @samp{PROGRAMS} holds a
+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
given in the GNU standards
(@pxref{Directory Variables, , , standards.info, The GNU Coding
Standards}).
-@code{automake} extends this list with @samp{pkglibdir},
-@samp{pkgincludedir}, and @samp{pkgdatadir}; these are the same as the
+@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
@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 @samp{bindir}, and some
-are installed in @samp{sbindir}:
+built. Some of the programs are installed in @code{bindir}, and some
+are installed in @code{sbindir}:
@example
EXTRA_PROGRAMS = mt rmt
@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}
be used in the package @file{configure.in}.
One such requirement is that @file{configure.in} must define the
-variables @samp{PACKAGE} and @samp{VERSION} with @samp{AC_SUBST}.
+variables @code{PACKAGE} and @code{VERSION} with @code{AC_SUBST}.
@cvindex PACKAGE
@cvindex VERSION
-@samp{PACKAGE} should be the name of the package as it appears when
+@code{PACKAGE} should be the name of the package as it appears when
bundled for distribution. For instance, Automake definees
-@samp{PACKAGE} to be @samp{automake}. @samp{VERSION} should be the
+@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 @samp{AC_ARG_PROGRAM}
+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
-@samp{AC_PROG_MAKE_SET}.
+@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 @samp
+@table @code
@item AC_CONFIG_HEADER
Automake will generate rules to automatically regenerate the config
header.
@item AC_PATH_XTRA
Automake will insert definitions for the variables defined by
-@samp{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
+@code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
or library.
@cvindex AC_PATH_XTRA
@cvindex fp_FUNC_FNMATCH
@cvindex AC_REPLACE_FUNCS
-Automake will also detect statements which put @file{.o} files into
-@samp{LIBOBJS}, and will treat these additional files in a similar way.
+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
@item AC_PROG_INSTALL
@item fp_PROG_INSTALL
-@samp{fp_PROG_INSTALL} is required if any scripts (@pxref{Scripts}) are
-installed by the package. Otherwise, @samp{AC_PROG_INSTALL} is
+@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
@cvindex ud_GNU_GETTEXT
@end table
-The ``fp_'' macros are from @value{Francois} Pinard, and are included
+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.
In non-flat packages, the top level @file{Makefile.am} must tell
Automake which subdirectories are to be built. This is done via the
-@samp{SUBDIRS} variable.
+@code{SUBDIRS} variable.
@vindex SUBDIRS
-The @samp{SUBDIRS} macro holds a list of subdirectories in which
-building of various sorts can occur. Many targets (eg @samp{all}) in
+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 @samp{SUBDIRS} are
+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}).
@example
SUBDIRS = lib src doc man
-DIST_OTHER = @@README_ALPHA@@
+EXTRA_DIST = @@README_ALPHA@@
@end example
-@samp{SUBDIRS} can contain configure substitutions (eg @samp{@@DIRS@@});
+@code{SUBDIRS} can contain configure substitutions (eg @samp{@@DIRS@@});
Automake itself does not actually examine the contents of this variable.
-If @samp{SUBDIRS} is defined, then your @file{configure.in} must include
+If @code{SUBDIRS} is defined, then your @file{configure.in} must include
@code{AC_PROG_MAKE_SET}.
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 @samp{bindir}, @samp{sbindir}, @samp{libexecdir},
-@samp{pkglibdir}, or not at all.
+can be installed in @code{bindir}, @code{sbindir}, @code{libexecdir},
+@code{pkglibdir}, or not at all.
For instance:
In this simple case, the resulting @file{Makefile.in} will contain code
to generate a program named @code{hello}. The variable
-@samp{hello_SOURCES} is used to specify which source files get built
+@code{hello_SOURCES} is used to specify which source files get built
into an executable:
@example
linked to produce @file{hello}.
If @samp{prog_SOURCES} is needed, but not specified, then it defaults to
-the single file @samp{prog.c}. Id est In the example above, the
-definition of @samp{hello_SOURCES} is actually redundant.
+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
-``_SOURCES'' definition.
+@samp{_SOURCES} definition.
-Header files listed in a ``_SOURCES'' definition will be ignored. Lex
-(``.l'') and yacc (``.y'') files can also be listed; support for these
-should work but is still preliminary.
+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
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
-``_PROGRAMS'' definition, while listing all optionally built programs in
-@samp{EXTRA_PROGRAMS}.
+@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 @samp{LDADD} to do so. This variable
+@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 ``_PROGRAMS'' variable, and usually
-written in lowercase) to override the global @samp{LDADD}. (If this
+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 @samp{LDADD}.)
+using @code{LDADD}.)
@vindex _LDADD
For instance, in GNU cpio, @code{pax}, @code{cpio}, and @code{mt} are
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
-@samp{libdir} or @samp{pkglibdir}.
+@code{libdir} or @code{pkglibdir}.
-Each @samp{where_LIBRARIES} variable is a list of the base names of
+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:
@end example
The sources that go into a library are determined exactly as they are
-for programs, via the ``_SOURCES'' variables. Note that programs and
-libraries share a namespace, so one cannot have a program (``lob'') and
-a library (``liblob.a'') with the same name in one directory.
+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
cpio_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
@end example
-Note that Automake explicitly recognizes the use of @samp{@@LIBOBJS@@}
-and @samp{@@ALLOCA@@} in the above example, and uses this information,
-plus the list of @samp{LIBOBJS} files derived from @file{configure.in}
+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}.
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 @samp{AUTOMAKE_OPTIONS}
+If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
@vindex AUTOMAKE_OPTIONS
-(@ref{Options}) contains the option @samp{ansi2knr}
+(@ref{Options}) contains the option @code{ansi2knr}
@opindex ansi2knr
then code to handle de-ANSI-fication is inserted into the generated
@file{Makefile.in}.
@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
-@samp{fp_C_PROTOTYPES}.
+@code{fp_C_PROTOTYPES}.
@cvindex fp_C_PROTOTYPES
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 @samp{dist} target will
+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?
@samp{--include-deps} also turns off inclusion of the dependency
generation code.
-This mode can be suppressed by putting @samp{no-dependencies} in the
-variable @samp{AUTOMAKE_OPTIONS}.
+This mode can be suppressed by putting @code{no-dependencies} in the
+variable @code{AUTOMAKE_OPTIONS}.
@vindex AUTOMAKE_OPTIONS
@opindex no-dependencies
bin_SCRIPTS = automake
@end example
-Since @code{automake} appears in the @samp{AC_OUTPUT} macro,
+Since @code{automake} appears in the @code{AC_OUTPUT} macro,
dependencies for it are automatically generated.
-Script objects can be installed in @samp{bindir}, @samp{sbindir},
-@samp{libexecdir}, or @samp{pkgdatadir}.
+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 @samp{noinst_HEADERS}
+Generally header files are not installed, so the @code{noinst_HEADERS}
variable will be the most used.
@vindex HEADERS
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 @samp{info_TEXINFOS} macro is most commonly used
-here. Note that any Texinfo source file must end in the @file{.texi}
-extension (@file{.texinfo} won't work).
+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 @file{.texi} file ``@@include''s @file{version.texi}, then that
+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: @samp{EDITION}, @samp{VERSION}, and
-@samp{UPDATED}. The first two hold the version number of your package
+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 @file{.texi}
-file. For instance, in the @samp{xdvik} distribution,
+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 @samp{xdvik} could do it:
+is how @code{xdvik} could do it:
@vindex TEXINFOS
@vindex _TEXINFOS
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 @samp{man_MANS} macro is used. Man pages are
+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
-By default, man pages are installed by @code{make install}. However,
+@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
-@samp{no-installman} option will prevent the man pages from being
+@code{no-installman} option will prevent the man pages from being
installed by default. The user can still explicitly install them via
-@code{make install-man}.
+@samp{make install-man}.
@opindex no-installman
@trindex install-man
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.
+Texinfo source, info pages and man pages are all considered to be source
+for the purposes of making a distribution.
@node Install
Automake also handles installing any specified info and man pages.
-Automake generates separate @samp{install-data} and @samp{install-exec}
+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 @samp{install} target depends on
+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 @samp{uninstall} target, and an
-@samp{installdirs} target.
+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
-@samp{install-exec-local} or @samp{install-data-local} target. If these
-targets exist, they will be run at @code{make install} time.
+@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
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
-@samp{MOSTLYCLEANFILES}, @samp{CLEANFILES}, @samp{DISTCLEANFILES}, and
-@samp{MAINTAINERCLEANFILES}.
+@code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
+@code{MAINTAINERCLEANFILES}.
@vindex MOSTLYCLEANFILES
@vindex CLEANFILES
@vindex DISTCLEANFILES
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 @code{make clean}:
+causes it to be removed by @samp{make clean}:
@example
CLEANFILES = automake
@node Dist
@chapter What Goes in a Distribution
-The @samp{dist} target in the generated @file{Makefile.in} can be used
+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
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
-@code{automake --help}. Also, files which are read by @code{configure}
+@samp{automake --help}. Also, files which are read by @code{configure}
(ie, the source files corresponding to the files specified in the
-@samp{AC_OUTPUT} invocation) are automatically distributed.
+@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 @samp{DIST_OTHER} variable.
-@vindex DIST_OTHER
+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
-@samp{TESTS} is defined, its value is taken to be a list of programs to
+@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 @code{make check}. The number of failures will
+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
Various features of Automake can be controlled by options in the
@file{Makefile.am}. Such options are listed in a special variable named
-@samp{AUTOMAKE_OPTIONS}. Currently understood options are:
+@code{AUTOMAKE_OPTIONS}. Currently understood options are:
@vindex AUTOMAKE_OPTIONS
@table @asis
-@item @samp{gnits}
-@itemx @samp{gnu}
-@itemx @samp{foreign}
+@item @code{gnits}
+@itemx @code{gnu}
+@itemx @code{foreign}
The same as the corresponding @samp{--strictness} option.
-@item @samp{no-installman}
+@item @code{no-installman}
The generated @file{Makefile.in} will not cause man pages to be
-installed by default. However, an @samp{install-man} target will still
+installed by default. However, an @code{install-man} target will still
be available for optional installation.
-@item @samp{ansi2knr}
+@item @code{ansi2knr}
Turn on automatic de-ANSI-fication.
-@item @samp{dist-shar}
-Generate a @samp{dist-shar} target as well as the ordinary @samp{dist}
+@item @code{dist-shar}
+Generate a @code{dist-shar} target as well as the ordinary @code{dist}
target.
-@item @samp{no-dependencies}
+@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
@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 @samp{tags} target
+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 @samp{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 @samp{ETAGS_ARGS} is defined, a @samp{tags} target
+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.
--regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
@end example
-Automake will also generate an @samp{id} target which will run
+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
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 @samp{SUFFIXES} variable.
+of new suffixes in the @code{SUFFIXES} variable.
@vindex SUFFIXES
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 ``-local'' version you can specify in your
+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 @samp{all}, @samp{info},
-@samp{dvi}, @samp{check}, @samp{install-data}, @samp{install-exec}, and
-@samp{uninstall}.
+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
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
@printindex cv
+
@node Targets
@unnumbered Index of Targets
projects / thirdparty / automake.git / commitdiff
