Patch: FYI: more doc updates

[Tom Tromey]

I'm checking this in.
This adds some missing stuff.

I think this is all the documentation updates that were on my "must
do" list.

Right now I think I have one more bug I want to look at.

Tom

Index: ChangeLog
from  Tom Tromey  <address@hidden>
        * 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.

Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.233
diff -u -r1.233 automake.texi
--- automake.texi 2001/07/30 22:00:06 1.233
+++ automake.texi 2001/07/31 05:17:58
@@ -1673,11 +1673,11 @@
 @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 @@
 * 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
 
address@hidden Introductory blathering
+
 @cindex PROGRAMS, bindir
 @vindex bin_PROGRAMS
 @vindex sbin_PROGRAMS
@@ -1750,11 +1753,13 @@
 
 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}.
 
address@hidden 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,10 +1778,31 @@
 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
address@hidden and @code{rmt} under special circumstances.
+In this case, @file{hello-linux.o} would be added, via a
address@hidden 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}:
 
address@hidden
+if LINUX
+hello_SOURCES = hello-linux.c
+else
+hello_SOURCES = hello-generic.c
+endif
address@hidden example
+
+When using conditionals like this you don't need to use the
address@hidden 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
address@hidden under special circumstances.
+
 @cindex EXTRA_PROGRAMS, defined
 
 In this case, you must notify Automake of all the programs that can
@@ -1787,6 +1813,11 @@
 in @code{EXTRA_PROGRAMS}.
 @vindex EXTRA_PROGRAMS
 
+Of course you can use Automake conditionals to determine the programs to
+be built.
+
address@hidden 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 @@
 generated.
 
 
address@hidden A Library, Program and Library Variables, A Program, Programs
address@hidden A Library, A Shared Library, A Program, Programs
 @section Building a library
 
 @cindex _LIBRARIES primary, defined
@@ -1899,8 +1930,79 @@
 configure-time must be added to the @code{BUILT_SOURCES} variable
 (@pxref{Sources}).
 
+
address@hidden A Shared Library, Program and Library Variables, A Library, 
Programs
address@hidden Building a Shared Library
+
address@hidden 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.
+
address@hidden _LTLIBRARIES primary, defined
address@hidden LTLIBRARIES primary, defined
address@hidden Primary variable, LTLIBRARIES
address@hidden Example of shared libraries
+
address@hidden suffix .la, defined
+
+Automake uses Libtool to build libraries declared with the
address@hidden primary.  Each @samp{_LTLIBRARIES} variable is a list
+of shared libraries to build.  For instance, to create a library named
address@hidden and its corresponding shared libraries, and install
+them in @samp{libdir}, write:
+
address@hidden
+lib_LTLIBRARIES = libgettext.la
address@hidden example
+
address@hidden lib_LTLIBRARIES
address@hidden pkglib_LTLIBRARIES
address@hidden noinst_LTLIBRARIES
address@hidden check_LTLIBRARIES
+
address@hidden check_LTLIBRARIES, not allowed
+
+Note that shared libraries @emph{must} be installed, so
address@hidden is not allowed.  However,
address@hidden is allowed.  This feature should be used for
+libtool ``convenience libraries''.
+
address@hidden suffix .lo, defined
+
+For each library, the @address@hidden variable contains the
+names of extra libtool objects (@file{.lo} files) to add to the shared
+library.  The @address@hidden variable contains any
+additional libtool flags, such as @samp{-version-info} or
address@hidden
+
address@hidden @@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
address@hidden  The libtool manual contains more details on this topic.
 
address@hidden Program and Library Variables, LIBOBJS, A Library, Programs
+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
address@hidden), Automake does not know the eventual
+installation directory; for such libraries you must add the
address@hidden option to the appropriate @samp{_LDFLAGS} variable by
+hand.
+
+Ordinarily, Automake requires that a shared library's name start with
address@hidden  However, if you are building a dynamically loadable module
+then you might wish to use a "nonstandard" name.  In this case, put
address@hidden into the @samp{_LDFLAGS} variable.
+
address@hidden Automake, Using Automake with Libtool, The Libtool Manual,
+libtool, The Libtool Manual}, for more information.
+
+
address@hidden 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 @@
 @end table
 
 
address@hidden LIBOBJS, A Shared Library, Program and Library Variables, 
Programs
address@hidden LIBOBJS, Program variables, Program and Library Variables, 
Programs
 @section Special handling for LIBOBJS and ALLOCA
 
 @cindex @@LIBOBJS@@, special handling
@@ -2090,79 +2192,8 @@
 @code{@@LIBOBJS@@} and @code{@@ALLOCA@@} are specially recognized in any
 @samp{_LDADD} or @samp{_LIBADD} variable.
 
-
address@hidden A Shared Library, Program variables, LIBOBJS, Programs
address@hidden Building a Shared Library
-
address@hidden 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.
-
address@hidden _LTLIBRARIES primary, defined
address@hidden LTLIBRARIES primary, defined
address@hidden Primary variable, LTLIBRARIES
address@hidden Example of shared libraries
-
address@hidden suffix .la, defined
-
-Automake uses Libtool to build libraries declared with the
address@hidden primary.  Each @samp{_LTLIBRARIES} variable is a list
-of shared libraries to build.  For instance, to create a library named
address@hidden and its corresponding shared libraries, and install
-them in @samp{libdir}, write:
-
address@hidden
-lib_LTLIBRARIES = libgettext.la
address@hidden example
-
address@hidden lib_LTLIBRARIES
address@hidden pkglib_LTLIBRARIES
address@hidden noinst_LTLIBRARIES
address@hidden check_LTLIBRARIES
-
address@hidden check_LTLIBRARIES, not allowed
-
-Note that shared libraries @emph{must} be installed, so
address@hidden is not allowed.  However,
address@hidden is allowed.  This feature should be used for
-libtool ``convenience libraries''.
-
address@hidden suffix .lo, defined
-
-For each library, the @address@hidden variable contains the
-names of extra libtool objects (@file{.lo} files) to add to the shared
-library.  The @address@hidden variable contains any
-additional libtool flags, such as @samp{-version-info} or
address@hidden
-
address@hidden @@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
address@hidden  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
address@hidden), Automake does not know the eventual
-installation directory; for such libraries you must add the
address@hidden option to the appropriate @samp{_LDFLAGS} variable by
-hand.
-
-Ordinarily, Automake requires that a shared library's name start with
address@hidden  However, if you are building a dynamically loadable module
-then you might wish to use a "nonstandard" name.  In this case, put
address@hidden into the @samp{_LDFLAGS} variable.
-
address@hidden Automake, Using Automake with Libtool, The Libtool Manual,
-libtool, The Libtool Manual}, for more information.
-
-
address@hidden Program variables, Yacc and Lex, A Shared Library, Programs
address@hidden 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 @@
 the same functionality.  This macro is deprecated; we suggest using
 @samp{AM_CPPFLAGS} instead.
 
address@hidden 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,
address@hidden); it takes as ``arguments'' the names of the object files
+and libraries to link in.
 @end vtable
 
 
@@ -2349,6 +2389,9 @@
 @item CXXFLAGS
 Any flags to pass to the C++ compiler.
 
address@hidden 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 @@
 @item FFLAGS
 Any flags to pass to the Fortran 77 compiler.
 
address@hidden AM_FFLAGS
+The maintainer's variant of @code{FFLAGS}.
+
 @item RFLAGS
 Any flags to pass to the Ratfor compiler.
 
address@hidden 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 @@
 currently has no way to build @code{ansi2knr} for the build machine.
 
 
address@hidden Dependencies,  , ANSI, Programs
address@hidden Dependencies, EXEEXT, ANSI, Programs
 @section Automatic dependency tracking
 
 As a developer it is often painful to continually update the
@@ -2783,6 +2832,63 @@
 
 @cindex Disabling dependency tracking
 @cindex Dependency tracking, disabling
+
+
address@hidden EXEEXT, , Dependencies, Programs
address@hidden Support for executable extensions
+
address@hidden Executable extension
address@hidden Extension, executable
address@hidden 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:
+
address@hidden
+bin_PROGRAMS = liver
address@hidden example
+
+to this:
+
address@hidden
+bin_PROGRAMS = liver$(EXEEXT)
address@hidden 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
address@hidden(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
address@hidden option, this use will give an error.
 
 
 @node Other objects, Other GNU Tools, Programs, Top