automake.texi

LINUX下的源码工具,可自己分析,或者直接装在系统上作为应用

@cindex Uniform naming scheme

Automake macros (from here on referred to as @emph{variables}) generally
follow a @dfn{uniform naming scheme} that makes it easy to decide how
programs (and other derived objects) are built, and how they are
installed.  This scheme also supports @code{configure} time
determination of what should be built.

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

@cindex Primary variable, defined

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

@cindex pkglibdir, defined
@cindex pkgincludedir, defined
@cindex pkgdatadir, defined

@vindex pkglibdir
@vindex pkgincludedir
@vindex pkgdatadir

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,
The GNU Coding Standards}).  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.  For instance, @code{pkglibdir} is defined as
@code{$(datadir)/@@PACKAGE@@}.
@cvindex PACKAGE

@cindex EXTRA_, prepending

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 statically know the entire list of objects that may be built in
order to generate a @file{Makefile.in} that will work in all cases.

@cindex EXTRA_PROGRAMS, defined
@cindex Example, EXTRA_PROGRAMS
@cindex cpio example

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 without a prefix (e.g. @code{PROGRAMS}) 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.

@cindex Extending list of installation directories
@cindex Installation directories, extending list

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 (e.g. @samp{zar}) is valid if a variable of
the same name with @samp{dir} appended is defined (e.g. @code{zardir}).

@cindex HTML support, example

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

@cindex noinst primary prefix, definition

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

@cindex check primary prefix, definition

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,  , Uniform, Generalities
@section How derived variables are named

@cindex canonicalizing Automake macros

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 macro naming rules.  All characters in the name except
for letters, numbers, and the underscore are turned into underscores
when making macro references.  For example, if your program is named
@code{sniff-glue}, the derived variable name would be
@code{sniff_glue_SOURCES}, not @code{sniff-glue_SOURCES}.


@node Examples, Invoking Automake, Generalities, Top
@chapter Some example packages

@menu
* Complete::                    A simple example, start to finish
* Hello::                       A classic program
* etags::                       Building etags and ctags
@end menu


@node Complete, Hello, Examples, Examples
@section A simple example, start to finish

@cindex Complete example

Let's suppose you just finished writing @code{zardoz}, a program to make
your head float from vortex to vortex.  You've been using Autoconf to
provide a portability framework, but your @file{Makefile.in}s have been
ad-hoc.  You want to make them bulletproof, so you turn to Automake.

@cindex AM_INIT_AUTOMAKE, example use

The first step is to update your @file{configure.in} to include the
commands that @code{automake} needs.  The simplest way to do this is to
add an @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:

@example
AM_INIT_AUTOMAKE(zardoz, 1.0)
@end example

Since your program doesn't have any complicating factors (e.g., it
doesn't use @code{gettext}, it doesn't want to build a shared library),
you're done with this part.  That was easy!

@cindex aclocal program, introduction
@cindex aclocal.m4, preexisting
@cindex acinclude.m4, defined

Now you must regenerate @file{configure}.  But to do that, you'll need
to tell @code{autoconf} how to find the new macro you've used.  The
easiest way to do this is to use the @code{aclocal} program to generate
your @file{aclocal.m4} for you.  But wait... you already have an
@file{aclocal.m4}, because you had to write some hairy macros for your
program.  The @code{aclocal} program lets you put your own macros into
@file{acinclude.m4}, so simply rename and then run:

@example
mv aclocal.m4 acinclude.m4
aclocal
autoconf
@end example

@cindex zardoz example

Now it is time to write your @file{Makefile.am} for @code{zardoz}.
Since @code{zardoz} is a user program, you want to install it where the
rest of the user programs go.  Additionally, @code{zardoz} has some
Texinfo documentation.  Your @file{configure.in} script uses
@code{AC_REPLACE_FUNCS}, so you need to link against @samp{@@LIBOBJS@@}.
So here's what you'd write:

@example
bin_PROGRAMS = zardoz
zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
zardoz_LDADD = @@LIBOBJS@@

info_TEXINFOS = zardoz.texi
@end example

Now you can run @code{automake --add-missing} to generate your
@file{Makefile.in} and grab any auxiliary files you might need, and
you're done!


@node Hello, etags, Complete, Examples
@section A classic program

@cindex Example, GNU Hello
@cindex Hello example
@cindex GNU Hello, example

@uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
renowned for its classic simplicity and versatility.  This section shows
how Automake could be used with the GNU Hello package.  The examples
below are from the latest beta version of GNU Hello, but with all of the
maintainer-only code stripped out, as well as all copyright comments.

Of course, GNU Hello is somewhat more featureful than your traditional
two-liner.  GNU Hello is internationalized, does option processing, and
has a manual and a test suite.  GNU Hello is a deep package.

@cindex configure.in, from GNU Hello
@cindex GNU Hello, configure.in
@cindex Hello, configure.in

Here is the @file{configure.in} from GNU Hello:

@example
dnl Process this file with autoconf to produce a configure script.
AC_INIT(src/hello.c)
AM_INIT_AUTOMAKE(hello, 1.3.11)
AM_CONFIG_HEADER(config.h)

dnl Set of available languages.
ALL_LINGUAS="de fr es ko nl no pl pt sl sv"

dnl Checks for programs.
AC_PROG_CC
AC_ISC_POSIX

dnl Checks for libraries.

dnl Checks for header files.
AC_STDC_HEADERS
AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)

dnl Checks for library functions.
AC_FUNC_ALLOCA

dnl Check for st_blksize in struct stat
AC_ST_BLKSIZE

dnl internationalization macros
AM_GNU_GETTEXT
AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
           src/Makefile tests/Makefile tests/hello],
   [chmod +x tests/hello])
@end example

The @samp{AM_} macros are provided by Automake (or the Gettext library);
the rest are standard Autoconf macros.


The top-level @file{Makefile.am}:

@example
EXTRA_DIST = BUGS ChangeLog.O
SUBDIRS = doc intl po src tests
@end example

As you can see, all the work here is really done in subdirectories.

The @file{po} and @file{intl} directories are automatically generated
using @code{gettextize}; they will not be discussed here.

@cindex Texinfo file handling example
@cindex Example, handling Texinfo files

In @file{doc/Makefile.am} we see:

@example
info_TEXINFOS = hello.texi
hello_TEXINFOS = gpl.texi
@end example

This is sufficient to build, install, and distribute the GNU Hello
manual.

@cindex Regression test example
@cindex Example, regression test

Here is @file{tests/Makefile.am}:

@example
TESTS = hello
EXTRA_DIST = hello.in testdata
@end example

The script @file{hello} is generated by @code{configure}, and is the
only test case.  @code{make check} will run this test.

@cindex INCLUDES, example usage

Last we have @file{src/Makefile.am}, where all the real work is done:

@example
bin_PROGRAMS = hello
hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h 
hello_LDADD = @@INTLLIBS@@ @@ALLOCA@@
localedir = $(datadir)/locale
INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
@end example


@node etags,  , Hello, Examples
@section Building etags and ctags

@cindex Example, ctags and etags
@cindex ctags Example
@cindex etags 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: etags.c
        $(COMPILE) -DETAGS_REGEXPS -c etags.c

ctags.o: etags.c
        $(COMPILE) -DCTAGS -o ctags.o -c 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.
@code{ctags_DEPENDENCIES} is generated by Automake.

The above rules won't work if your compiler doesn't accept both
@samp{-c} and @samp{-o}.  The simplest fix for this is to introduce a
bogus dependency (to avoid problems with a parallel @code{make}):

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

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

Also, these explicit rules do not work if the de-ANSI-fication feature
is used (@pxref{ANSI}).  Supporting de-ANSI-fication requires a little
more work:

@example
etags._o: etags._c ctags.o
        $(COMPILE) -DETAGS_REGEXPS -c etags.c

ctags._o: etags._c
        $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
@end example