* doc/automake.texi (Linking, Program and Library Variables):

Mention the file extensions that usually appear in _DEPENDENCIES,
and point to BUILT_SOURCES and example of _DEPENDENCIES uses.  A
couple of people have been listing sources files in _DEPENDENCIES
lately.

diff --git a/ChangeLog b/ChangeLog
index 54ce2d8195afee8810f24c3b8aa483da2f55d2e3..8f73110f10f36ea7eac66b58b5f997e5cd3cfccb 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2006-01-06  Alexandre Duret-Lutz  <adl@gnu.org>
 
+       * doc/automake.texi (Linking, Program and Library Variables):
+       Mention the file extensions that usually appear in _DEPENDENCIES,
+       and point to BUILT_SOURCES and example of _DEPENDENCIES uses.  A
+       couple of people have been listing sources files in _DEPENDENCIES
+       lately.
+
        * doc/automake.texi: Bump copyright year.
        * automake.in ($gen_copyright, version): Likewise.
        * aclocal.in (write_aclocal, version): Likewise.

diff --git a/doc/automake.texi b/doc/automake.texi
index a0149038174dab13346a5cc47d8e52a100c7de22..d0451f61f2703214456494c56c9fb80aa61e2a57 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3214,9 +3214,18 @@ this purpose.
 @vindex maude_DEPENDENCIES
 It is also occasionally useful to have a program depend on some other
 target that is not actually part of that program.  This can be done
-using the @code{@var{prog}_DEPENDENCIES} variable.  Each program depends
-on the contents of such a variable, but no further interpretation is
-done.
+using the @code{@var{prog}_DEPENDENCIES} variable.  Each program
+depends on the contents of such a variable, but no further
+interpretation is done.
+
+Since these dependencies are associated to the link rule used to
+create the programs they should normally list files used by the link
+command.  That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
+files.  In rare cases you may need to add other kinds of files such as
+linker scripts, but @emph{listing a source file in
+@code{_DEPENDENCIES} is wrong}.  If some source file needs to be built
+before all the components of a program are built, consider using the
+@code{BUILT_SOURCES} variable instead (@pxref{Sources}).
 
 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
 Automake.  The automatically-assigned value is the contents of
@@ -3227,6 +3236,9 @@ configure substitutions that are left in are only @samp{$(LIBOBJS)} and
 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
 generated.
 
+@ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
+is useful.
+
 @cindex @code{LDADD} and @option{-l}
 @cindex @option{-l} and @code{LDADD}
 We recommend that you avoid using @option{-l} options in @code{LDADD}
@@ -4085,10 +4097,22 @@ option, so they should not be mode-specific options (those belong to
 the compiler or linker flags).  @xref{Libtool Flags}.
 
 @item maude_DEPENDENCIES
-It is also occasionally useful to have a program depend on some other
-target that is not actually part of that program.  This can be done
-using the @code{_DEPENDENCIES} variable.  Each program depends on the
-contents of such a variable, but no further interpretation is done.
+It is also occasionally useful to have a target (program or library)
+depend on some other file that is not actually part of that target.
+This can be done using the @code{_DEPENDENCIES} variable.  Each
+targets depends on the contents of such a variable, but no further
+interpretation is done.
+
+Since these dependencies are associated to the link rule used to
+create the programs they should normally list files used by the link
+command.  That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
+for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
+and @file{*.$(OBJEXT)} files for static libraries.  In rare cases you
+may need to add other kinds of files such as linker scripts, but
+@emph{listing a source file in @code{_DEPENDENCIES} is wrong}.  If
+some source file needs to be built before all the components of a
+program are built, consider using the @code{BUILT_SOURCES} variable
+(@pxref{Sources}).
 
 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
 The automatically-assigned value is the contents of @code{_LDADD} or
@@ -4098,6 +4122,11 @@ 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 @code{_DEPENDENCIES} to be generated.
 
+@code{_DEPENDENCIES} is more likely used to perform conditional
+compilation using an @code{AC_SUBST} variable that contains a list of
+objects.  @xref{Conditional Sources}, and @ref{Conditional Libtool
+Sources}.
+
 @item maude_LINK
 You can override the linker on a per-program basis.  By default the
 linker is chosen according to the languages used by the program.  For