@menu
* A Program:: Building a program
* A Library:: Building a library
+* A Shared Library:: Building a Libtool library
* Program and Library Variables::
Variables controlling program and
library builds
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
-* A Shared Library:: Building a Libtool library
* Program variables:: Variables used when building a program
* Yacc and Lex:: Yacc and Lex support
* C++ Support::
* Support for Other Languages::
* ANSI:: Automatic de-ANSI-fication
* Dependencies:: Automatic dependency tracking
+* EXEEXT:: Support for executable extensions
@end menu
@node A Program, A Library, Programs, Programs
@section Building a program
+@subsection Introductory blathering
+
@cindex PROGRAMS, bindir
@vindex bin_PROGRAMS
@vindex sbin_PROGRAMS
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
+should not include the header file generated by @file{configure} in a
@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}.
+@subsection Conditional compilations
+
You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
@samp{_SOURCES} variable. The reason for this is a bit hard to explain,
but suffice to say that it simply won't work. Automake will give an
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.
+In this case, @file{hello-linux.o} would be added, via a
+@file{configure} substitution, to @code{hello_LDADD} in order to cause
+it to be built and linked in.
+
+An often simpler way to compile source files conditionally is to use
+Automake conditionals. For instance, you could use this construct to
+conditionally use @file{hello-linux.c} or @file{hello-generic.c} as the
+basis for your program @file{hello}:
+
+@example
+if LINUX
+hello_SOURCES = hello-linux.c
+else
+hello_SOURCES = hello-generic.c
+endif
+@end example
+
+When using conditionals like this you don't need to use the
+@samp{EXTRA_} variable, because Automake will examine the contents of
+each variable to construct the complete list of source files.
+
+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 @code{EXTRA_PROGRAMS}.
@vindex EXTRA_PROGRAMS
+Of course you can use Automake conditionals to determine the programs to
+be built.
+
+@subsection Linking the program
+
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.
generated.
-@node A Library, Program and Library Variables, A Program, Programs
+@node A Library, A Shared Library, A Program, Programs
@section Building a library
@cindex _LIBRARIES primary, defined
(@pxref{Sources}).
-@node Program and Library Variables, LIBOBJS, A Library, Programs
+@node A Shared Library, Program and Library Variables, A Library, 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.
+
+Ordinarily, Automake requires that a shared library's name start with
+@samp{lib}. However, if you are building a dynamically loadable module
+then you might wish to use a "nonstandard" name. In this case, put
+@code{-module} into the @samp{_LDFLAGS} variable.
+
+@xref{Using Automake, Using Automake with Libtool, The Libtool Manual,
+libtool, The Libtool Manual}, for more information.
+
+
+@node Program and Library Variables, LIBOBJS, A Shared Library, Programs
@section Program and Library Variables
Associated with each program are a collection of variables which can be
@end table
-@node LIBOBJS, A Shared Library, Program and Library Variables, Programs
+@node LIBOBJS, Program variables, Program and Library Variables, Programs
@section Special handling for LIBOBJS and ALLOCA
@cindex @@LIBOBJS@@, special handling
@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.
-
-Ordinarily, Automake requires that a shared library's name start with
-@samp{lib}. However, if you are building a dynamically loadable module
-then you might wish to use a "nonstandard" name. In this case, put
-@code{-module} into the @samp{_LDFLAGS} variable.
-
-@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
+@node Program variables, Yacc and Lex, LIBOBJS, Programs
@section Variables used when building a program
Occasionally it is useful to know which @file{Makefile} variables
the same functionality. This macro is deprecated; we suggest using
@samp{AM_CPPFLAGS} instead.
+@item AM_CFLAGS
+This is the variable which the @file{Makefile.am} author can use to pass
+in additional C compiler flags. It is more fully documented elsewhere.
+In some situations, this is not used, in preference to the
+per-executable (or per-library) @code{CFLAGS}.
+
@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.
+This is the command used to actually link a C program. It already
+includes @samp{-o $@@} and the usual variable references (for instance,
+@code{CFLAGS}); it takes as ``arguments'' the names of the object files
+and libraries to link in.
@end vtable
@item CXXFLAGS
Any flags to pass to the C++ compiler.
+@item AM_CXXFLAGS
+The maintainer's variant of @code{CXXFLAGS}.
+
@item CXXCOMPILE
The command used to actually compile a C++ source file. The file name
is appended to form the complete command line.
@item FFLAGS
Any flags to pass to the Fortran 77 compiler.
+@item AM_FFLAGS
+The maintainer's variant of @code{FFLAGS}.
+
@item RFLAGS
Any flags to pass to the Ratfor compiler.
+@item AM_RFLAGS
+The maintainer's variant of @code{RFLAGS}.
+
@item F77COMPILE
The command used to actually compile a Fortran 77 source file. The file
name is appended to form the complete command line.
currently has no way to build @code{ansi2knr} for the build machine.
-@node Dependencies, , ANSI, Programs
+@node Dependencies, EXEEXT, ANSI, Programs
@section Automatic dependency tracking
As a developer it is often painful to continually update the
@cindex Dependency tracking, disabling
+@node EXEEXT, , Dependencies, Programs
+@section Support for executable extensions
+
+@cindex Executable extension
+@cindex Extension, executable
+@cindex Windows
+
+On some platforms, such as Windows, executables are expected to have an
+extension such as @samp{.exe}. On these platforms, some compilers (GCC
+among them) will automatically generate @file{foo.exe} when asked to
+generate @file{foo}.
+
+Automake provides mostly-transparent support for this. Unfortunately
+the support isn't completely transparent; if you want your package to
+support these platforms then you must assist.
+
+One thing you must be aware of is that, internally, Automake rewrites
+something like this:
+
+@example
+bin_PROGRAMS = liver
+@end example
+
+to this:
+
+@example
+bin_PROGRAMS = liver$(EXEEXT)
+@end example
+
+The targets Automake generates are likewise given the @samp{$(EXEEXT)}
+extension. @code{EXEEXT}
+
+However, Automake cannot apply this rewriting to @code{configure}
+substitutions. This means that if you are conditionally building a
+program using such a substitution, then your @file{configure.in} must
+take care to add @samp{$(EXEEXT)} when constructing the output variable.
+
+With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
+to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is implicit.
+
+Sometimes maintainers like to write an explicit link rule for their
+program. Without executable extension support, this is easy---you
+simply write a target with the same name as the program. However, when
+executable extension support is enabled, you must instead add the
+@samp{$(EXEEXT)} suffix.
+
+Unfortunately, due to the change in Autoconf 2.50, this means you must
+always add this extension. However, this is a problem for maintainers
+who know their package will never run on a platform that has executable
+extensions. For those maintainers, the @code{no-exeext} option
+(@pxref{Options}) will disable this feature. This works in a fairly
+ugly way; if @code{no-exeext} is seen, then the presence of a target
+named @code{foo} in @file{Makefile.am} will override an
+automake-generated target of the form @code{foo$(EXEEXT)}. Without the
+@code{no-exeext} option, this use will give an error.
+
+
@node Other objects, Other GNU Tools, Programs, Top
@chapter Other Derived Objects
projects / platform / upstream / automake.git / commitdiff