automake.texi

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

* A Shared Library::            Building a Libtool library
* Program variables::           Variables used when building a program
* Yacc and Lex::                Yacc and Lex support
* C++ Support::                 
* Fortran 77 Support::          
* Support for Other Languages::  
* ANSI::                        Automatic de-ANSI-fication
* Dependencies::                Automatic dependency tracking
@end menu


@node A Program, A Library, Programs, Programs
@section Building a program

@cindex PROGRAMS, bindir
@vindex bin_PROGRAMS
@vindex sbin_PROGRAMS
@vindex libexec_PROGRAMS
@vindex pkglib_PROGRAMS
@vindex noinst_PROGRAMS

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 (@samp{noinst}).

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 version.c getopt.c getopt1.c getopt.h system.h 
@end example

This causes each mentioned @samp{.c} file to be compiled into the
corresponding @samp{.o}.  Then all are linked to produce @file{hello}.

@cindex _SOURCES primary, defined
@cindex SOURCES primary, defined
@cindex Primary variable, SOURCES

If @samp{@var{prog}_SOURCES} is needed, but not specified, then it
defaults to the single file @file{prog.c}.
@vindex _SOURCES
@vindex SOURCES

Multiple programs can be built in a single directory.  Multiple programs
can share a single source file, which must be listed in each
@samp{_SOURCES} definition.

@cindex Header files in _SOURCES
@cindex _SOURCES and header files

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; see @ref{Yacc
and Lex}.

@cindex EXTRA_prog_SOURCES, defined

Automake must know all the source files that could possibly go into a
program, even if not all the files are built in every circumstance.
Any files which are only conditionally built should be listed in the
appropriate @samp{EXTRA_} variable.  For instance, if
@file{hello-linux.c} were conditionally included in @code{hello}, the
@file{Makefile.am} would contain:

@example
EXTRA_hello_SOURCES = hello-linux.c
@end example

Similarly, 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.

@cindex EXTRA_PROGRAMS, defined

In this case, you must notify 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

@cindex prog_LDADD, defined

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

@cindex _LDFLAGS, defined

@samp{@var{prog}_LDADD} is inappropriate for passing program-specific
linker flags (except for @samp{-l} and @samp{-L}).  So, use the
@samp{@var{prog}_LDFLAGS} variable for this purpose.
@vindex _LDFLAGS

@cindex _DEPENDENCIES, defined

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{@var{prog}_DEPENDENCIES} variable.  Each program depends
on the contents of such a variable, but no further interpretation is
done.

If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
Automake.  The automatically-assigned value is the contents of
@samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
and @samp{-L} options removed.  The configure substitutions that are
left in are only @samp{@@LIBOBJS@@} and @samp{@@ALLOCA@@}; these are
left because it is known that they will not cause an invalid value for
@samp{@var{prog}_DEPENDENCIES} to be generated.


@node A Library, LIBOBJS, A Program, Programs
@section Building a library

@cindex _LIBRARIES primary, defined
@cindex LIBRARIES primary, defined
@cindex Primary variable, LIBRARIES

@vindex lib_LIBRARIES
@vindex pkglib_LIBRARIES
@vindex noinst_LIBRARIES

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

@xref{A Shared Library}, for information on how to build shared
libraries using Libtool and the @samp{LTLIBRARIES} primary.

Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
For instance to create a library named @file{libcpio.a}, but not install
it, you would write:

@example
noinst_LIBRARIES = libcpio.a
@end example

The sources that go into a library are determined exactly as they are
for programs, via the @samp{_SOURCES} variables.  Note that the library
name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
not @samp{liblob.a_SOURCES}.

@cindex _LIBADD primary, defined
@cindex LIBADD primary, defined
@cindex Primary variable, LIBADD

Extra objects can be added to a library using the
@samp{@var{library}_LIBADD} variable.  This should be used for objects
determined by @code{configure}.  Again from @code{cpio}:
@vindex _LIBADD
@vindex LIBADD

@example
libcpio_a_LIBADD = @@LIBOBJS@@ @@ALLOCA@@
@end example


@node LIBOBJS, A Shared Library, A Library, Programs
@section Special handling for LIBOBJS and ALLOCA

@cindex @@LIBOBJS@@, special handling
@cindex @@ALLOCA@@, special handling

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 A Shared Library, Program variables, LIBOBJS, Programs
@section Building a Shared Library

@cindex Shared libraries, support for

Building shared libraries is a relatively complex matter.  For this
reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
Libtool Manual}) was created to help build shared libraries in a
platform-independent way.

@cindex _LTLIBRARIES primary, defined
@cindex LTLIBRARIES primary, defined
@cindex Primary variable, LTLIBRARIES
@cindex Example of shared libraries

@cindex suffix .la, defined

Automake uses Libtool to build libraries declared with the
@samp{LTLIBRARIES} primary.  Each @samp{_LTLIBRARIES} variable is a list
of shared libraries to build.  For instance, to create a library named
@file{libgettext.a} and its corresponding shared libraries, and install
them in @samp{libdir}, write:

@example
lib_LTLIBRARIES = libgettext.la
@end example

@vindex lib_LTLIBRARIES
@vindex pkglib_LTLIBRARIES
@vindex noinst_LTLIBRARIES
@vindex check_LTLIBRARIES

@cindex check_LTLIBRARIES, not allowed

Note that shared libraries @emph{must} be installed, so
@code{check_LTLIBRARIES} is not allowed.  However,
@code{noinst_LTLIBRARIES} is allowed.  This feature should be used for
libtool ``convenience libraries''.

@cindex suffix .lo, defined

For each library, the @samp{@var{library}_LIBADD} variable contains the
names of extra libtool objects (@file{.lo} files) to add to the shared
library.  The @samp{@var{library}_LDFLAGS} variable contains any
additional libtool flags, such as @samp{-version-info} or
@samp{-static}.

@cindex @@LTLIBOBJS@@, special handling

Where an ordinary library might include @code{@@LIBOBJS@@}, a libtool
library must use @code{@@LTLIBOBJS@@}.  This is required because the
object files that libtool operates on do not necessarily end in
@file{.o}.  The libtool manual contains more details on this topic.

For libraries installed in some directory, Automake will automatically
supply the appropriate @samp{-rpath} option.  However, for libraries
determined at configure time (and thus mentioned in
@code{EXTRA_LTLIBRARIES}), Automake does not know the eventual
installation directory; for such libraries you must add the
@samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
hand.

@xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
libtool, The Libtool Manual}, for more information.


@node Program variables, Yacc and Lex, A Shared Library, Programs
@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}.
@vindex LDFLAGS

There are some additional variables which Automake itself defines:

@vtable @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.  Automake already
provides some @samp{-I} options automatically.  In particular it
generates @samp{-I$(srcdir)} and a @samp{-I} pointing to the directory
holding @file{config.h} (if you've used @code{AC_CONFIG_HEADER} or
@code{AM_CONFIG_HEADER}).

@code{INCLUDES} can actually be used for other @code{cpp} options
besides @samp{-I}.  For instance, it is sometimes used to pass arbitrary
@samp{-D} options to the compiler.

@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 vtable


@node Yacc and Lex, C++ Support, Program variables, Programs
@section Yacc and Lex support

Automake has somewhat idiosyncratic support for Yacc and Lex.

Automake assumes that the @file{.c} file generated by @code{yacc} (or
@code{lex}) should be named using the basename of the input file.  That
is, for a yacc source file @file{foo.y}, Automake will cause the
intermediate file to be named @file{foo.c} (as opposed to
@file{y.tab.c}, which is more traditional).

The extension of a yacc source file is used to determine the extension
of the resulting @samp{C} or @samp{C++} file.  Files with the extension
@samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
@samp{.cxx}.

Likewise, lex source files can be used to generate @samp{C} or
@samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
@samp{.lxx} are recognized.

You should never explicitly mention the intermediate (@samp{C} or
@samp{C++}) file in any @samp{SOURCES} variable; only list the source
file.

The intermediate files generated by @code{yacc} (or @code{lex}) will be
included in any distribution that is made.  That way the user doesn't
need to have @code{yacc} or @code{lex}.

If a @code{yacc} source file is seen, then your @file{configure.in} must
define the variable @samp{YACC}.  This is most easily done by invoking
the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}).

Similarly, if a @code{lex} source file is seen, then your
@file{configure.in} must define the variable @samp{LEX}.  You can use
@samp{AC_PROG_LEX} to do this (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}).  Automake's @code{lex}
support also requires that you use the @samp{AC_DECL_YYTEXT}
macro---automake needs to know the value of @samp{LEX_OUTPUT_ROOT}.
This is all handled for you if you use the @code{AM_PROG_LEX} macro
(@pxref{Macros}).

@cindex ylwrap
@cindex yacc, multiple parsers
@cindex Multiple yacc parsers
@cindex Multiple lex lexers
@cindex lex, multiple lexers


Automake makes it possible to