fully GNU standards-compliant, and do not require @code{perl} in order
to be built.
-Mail suggestions and bug reports for Automake to tromey@@cygnus.com.
+Mail suggestions and bug reports for Automake to
+bug-gnu-utils@@prep.ai.mit.edu.
@node Invoking Automake
@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 --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 --add-missing
-Automake requires certain common files to exist in certain situations;
-for instance @file{config.guess} is required if @file{configure.in} runs
-@code{AC_CANONICAL_HOST}. Automake is distributed with several of these
-files; this option will cause the missing ones to be automatically added
-to the package, whenever possible.
-
+@item -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.
@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.
+
+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 Depth
@section Depth
@code{automake} supports three kinds of directory hierarchy: ``flat'',
``shallow'', and ``deep''.
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
@end table
+@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,
should not be built until the @code{make check} command is run.
Possible primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
-@samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
-@samp{TEXINFOS}.
+@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
-@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.
+@node Canonicalization
+@section How derived variables are named
-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.
+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}.
-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
+@node configure
+@chapter Scanning @file{configure.in}
-@c FIXME discuss putting a copyright into Makefile.am here? I would but
-@c I don't know quite what to say.
+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.
-@c FIXME document customary ordering of Makefile.am here!
+@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 configure
-@chapter Scanning @file{configure.in}
+@node Requirements
+@section Configuration requirements
-Automake requires certain variables to be defined and certain macros to
-be used in the package @file{configure.in}.
+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
-One such requirement is that @file{configure.in} must define the
-variables @code{PACKAGE} and @code{VERSION} with @code{AC_SUBST}.
+@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
@file{configure.in} the only place in your package where the version
number is defined; this makes releases simpler.
-Automake requires the use of the macro @code{AC_ARG_PROGRAM} if a
-program or script is installed.
+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
-If your package is not a flat distribution, Automake requires the use of
-@code{AC_PROG_MAKE_SET}.
+@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:
@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}. It can be empty. Also, the @code{AC_OUTPUT} command
-in @file{configure.in} must create @file{stamp-h}, eg:
+@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
corresponding to the current @file{Makefile.am}, whichever is
appropriate).
@cvindex AC_CONFIG_AUX_DIR
-
-@item AC_OUTPUT
-Automake uses this to determine which files to create.
-@cvindex AC_OUTPUT
+FIXME: give complete list of things looked for in this directory
@item AC_PATH_XTRA
Automake will insert definitions for the variables defined by
@item AC_FUNC_MEMCMP
@item AC_STRUCT_ST_BLOCKS
@item AM_FUNC_FNMATCH
-@item AC_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
@cvindex AC_REPLACE_FUNCS
@cvindex AC_REPLACE_GNU_GETOPT
@cvindex AM_FUNC_STRTOD
+@cvindex AM_WITH_REGEX
-Automake will also detect statements which put @samp{.o} files into
-@code{LIBOBJS}, and will treat these additional files in a similar way.
+@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 C++ source is included.
@cvindex AC_PROG_CXX
-@item AC_PROG_INSTALL
-@item AM_PROG_INSTALL
-@code{AM_PROG_INSTALL} is required if any scripts (@pxref{Scripts}) are
-installed by the package. Otherwise, @code{AC_PROG_INSTALL} is
-required. @code{AM_INIT_AUTOMAKE} automatically calls
-@code{AM_PROG_INSTALL}.
-@cvindex AC_PROG_INSTALL
-@cvindex AM_PROG_INSTALL
-@cvindex AM_INIT_AUTOMAKE
-
-@item AM_PROG_LIBTOOL
-Automake will turn on processing for @code{libtool} (@pxref{Top, , The
-Libtool Manual, libtool.info, The Libtool Manual}). This work is
-still preliminary.
-@cvindex AM_PROG_LIBTOOL
+@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
the package meets some of gettext's requirements.
@cvindex ud_GNU_GETTEXT
-@item jm_MAINTAINER_MODE
+@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.
+@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}
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
can share a single source file. The source file must be listed in each
@samp{_SOURCES} definition.
-Header files listed in a @samp{_SOURCES} definition will be ignored.
+Header files listed in a @samp{_SOURCES} definition will be included in
+the distribution but otherwise 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
using the @samp{prog_DEPENDENCIES} variable. Each program depends on
the contents of such a variable, but no further interpretation is done.
-Since program names are rewritten into Makefile macro names, program
-names must follow Makefile macro syntax. Sometimes it is useful to have
-a program whose name does not follow such rules. In these cases,
-Automake canonicalizes the program name. 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}, you would use @code{sniff_glue_SOURCES}, not
-@code{sniff-glue_SOURCES}.
-
@node A Library
@section Building a library
own compilation in some special cases.
Some variables are inherited from Autoconf; these are @code{CC},
-@code{CFLAGS}, @code{CPPFLAGS}, @code{CXX}, @code{CXXFLAGS},
-@code{DEFS}, @code{LDFLAGS}, and @code{LIBS}.
+@code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
+@code{LIBS}.
There are some additional variables which Automake itself defines:
@section Yacc and Lex support
Automake has somewhat idiosyncratic support for Yacc and Lex.
-
-
+FIXME: describe it here.
@node C++
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.
-A few additional variables are defined when a C++ source file is seen.
+@item CXXLINK
+The command used to actually link a C++ program.
+@end table
@node ANSI
@file{ansi2knr.1} to be in the same directory as the ANSI C source;
these files are distributed with Automake.
Also, the package @file{configure.in} must call the macro
-@code{fp_C_PROTOTYPES}.
-@cvindex fp_C_PROTOTYPES
+@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
@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
@vindex SCRIPTS
@code{automake} does not assume that scripts are derived objects; such
-objects are must be deleted by hand; see @ref{Clean} for more
-information.
+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:
bin_SCRIPTS = automake
@end example
-Since @code{automake} appears in the @code{AC_OUTPUT} macro,
-dependencies for it are automatically generated.
+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}.
@vindex HEADERS
All header files must be listed somewhere; missing ones will not appear
-in the distribution. Often it is most convenient to list uninstalled
-headers with the rest of the sources for a program. @xref{A Program}.
-Headers listed in a @samp{_SOURCES} variable need not be listed in any
+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
If the current directory contains Texinfo source, you must declare it
with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
into info, and thus the @code{info_TEXINFOS} macro is most commonly used
-here. Note that any Texinfo source file must end in the @samp{.texi}
-extension (@samp{.texinfo} won't work).
+here. Note that any Texinfo source file must end in the @samp{.texi} or
+@samp{.texinfo} extension.
@vindex TEXINFOS
@vindex info_TEXINFOS
kpathsea_TEXINFOS = install.texi copying.texi freedom.texi
@end example
-Automake will warn if a directory containing Texinfo source does not
-also contain the file @file{texinfo.tex}. This file is supplied with
-Automake.
+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}.
Naturally, Automake handles the details of actually installing your
program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
-@code{LIBRARIES}, @code{DATA} and @code{HEADERS} are automatically
-installed in the appropriate places.
+@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.
@vindex DISTCLEANFILES
@vindex MAINTAINERCLEANFILES
-In Automake, the @code{automake} program is not automatically removed,
-because it is an executable script. So this code in @file{Makefile.am}
-causes it to be removed by @samp{make clean}:
-
-@example
-CLEANFILES = automake
-@end example
-
@node Dist
@chapter What Goes in a Distribution
@item @code{ansi2knr}
@item @code{path/ansi2knr}
-Turn on automatic de-ANSI-fication. 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.
+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}.
@example
install-exec-hook:
- $(LN) $(bindir)/program $(bindir)/proglink
+ ln $(bindir)/program $(bindir)/proglink
@end example
@c FIXME should include discussion of variables you can use in these
@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)
+AM_INIT_AUTOMAKE(hello, 1.3)
AC_PROG_CC
AC_PROG_CPP
AC_PROG_INSTALL
## 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
projects / platform / upstream / automake.git / commitdiff