From 9ef7bf41a4aa55f9687ad8e01f38aeb1436e6fb5 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Tue, 31 Jul 2001 05:22:13 +0000 Subject: [PATCH] * automake.texi (A Program): Typo. Added subsections and more text about conditional compilation. (A Shared Library): Moved earlier. (Program variables): Updated LINK text. Added AM_CFLAGS. (C++ Support): Added AM_CXXFLAGS. (Fortran 77 Support): Added AM_FFLAGS and AM_RFLAGS. (EXEEXT): New node. --- ChangeLog | 8 ++ automake.texi | 270 +++++++++++++++++++++++++++++++++++--------------- 2 files changed, 196 insertions(+), 82 deletions(-) diff --git a/ChangeLog b/ChangeLog index dfc98187..a57d52fc 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,13 @@ 2001-07-30 Tom Tromey + * automake.texi (A Program): Typo. Added subsections and more + text about conditional compilation. + (A Shared Library): Moved earlier. + (Program variables): Updated LINK text. Added AM_CFLAGS. + (C++ Support): Added AM_CXXFLAGS. + (Fortran 77 Support): Added AM_FFLAGS and AM_RFLAGS. + (EXEEXT): New node. + * tests/Makefile.am (TESTS): Added aclibobj.test. * tests/aclibobj.test: New file. * automake.in (handle_lib_objects_cond): Avoid undefined variable diff --git a/automake.texi b/automake.texi index 354b69ac..f4d49ad7 100644 --- a/automake.texi +++ b/automake.texi @@ -1673,11 +1673,11 @@ to build programs and libraries. @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:: @@ -1687,12 +1687,15 @@ to build programs and libraries. * 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 @@ -1750,11 +1753,13 @@ can share a single source file, which must be listed in each 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 @@ -1773,9 +1778,30 @@ appropriate @samp{EXTRA_} variable. For instance, if 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 @@ -1787,6 +1813,11 @@ This is done by having @code{configure} substitute values into each 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. @@ -1849,7 +1880,7 @@ cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be 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 @@ -1900,7 +1931,78 @@ configure-time must be added to the @code{BUILT_SOURCES} variable (@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 @@ -2074,7 +2176,7 @@ it is required. @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 @@ -2091,78 +2193,7 @@ dependency-tracking scheme; see @xref{Dependencies}. @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 @@ -2193,12 +2224,21 @@ This does the same job as @samp{AM_CPPFLAGS}. It is an older name for 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 @@ -2349,6 +2389,9 @@ The name of the C++ compiler. @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. @@ -2402,9 +2445,15 @@ The name of the Fortran 77 compiler. @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. @@ -2739,7 +2788,7 @@ being built for a different host architecture. That is because automake 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 @@ -2785,6 +2834,63 @@ tracking by configuring with @code{--disable-dependency-tracking}. @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 -- 2.43.5