manual: add FAQ `Debugging Make Rules'.

* doc/automake.texi (Debugging Make Rules): New FAQ section.
(Top, FAQ): Adjust menus, and capitalization of the description
of the `Hard-Coded Install Paths' node.
(Multiple Outputs): Add comment to restore font-lock for vim.
Suggestion by Karl Berry.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>

diff --git a/ChangeLog b/ChangeLog
index 6841864..05608e2 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2009-04-19  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
+       manual: add FAQ `Debugging Make Rules'.
+       * doc/automake.texi (Debugging Make Rules): New FAQ section.
+       (Top, FAQ): Adjust menus, and capitalization of the description
+       of the `Hard-Coded Install Paths' node.
+       (Multiple Outputs): Add comment to restore font-lock for vim.
+       Suggestion by Karl Berry.
+
        Let XFile::lock warn and fail with parallel non-GNU make, too.
        * lib/Automake/XFile.pm (lock): Also match `-j' for parallel BSD
        make, and `-P' for parallel HP-UX make.

diff --git a/doc/automake.texi b/doc/automake.texi
index 7b18cf4..444fb21 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -337,7 +337,8 @@ Frequently Asked Questions about Automake
 * Renamed Objects::             Why are object files sometimes renamed?
 * Per-Object Flags::            How to simulate per-object flags?
 * Multiple Outputs::            Writing rules for tools with many output files
-* Hard-Coded Install Paths::    Installing to Hard-Coded Locations
+* Hard-Coded Install Paths::    Installing to hard-coded locations
+* Debugging Make Rules::        Strategies when things don't work as expected
 
 History of Automake
 
@@ -10295,7 +10296,8 @@ lists.
 * Renamed Objects::             Why are object files sometimes renamed?
 * Per-Object Flags::            How to simulate per-object flags?
 * Multiple Outputs::            Writing rules for tools with many output files
-* Hard-Coded Install Paths::    Installing to Hard-Coded Locations
+* Hard-Coded Install Paths::    Installing to hard-coded locations
+* Debugging Make Rules::        Strategies when things don't work as expected
 @end menu
 
 @node CVS
@@ -11439,6 +11441,7 @@ $(ELCFILES): elc-stamp
           fi; \
         fi
 @end example
+@c $$
 
 For completeness it should be noted that GNU @command{make} is able to
 express rules with multiple output files using pattern rules
@@ -11580,6 +11583,44 @@ expects two possible layouts, otherwise it's easy, and the benefits for
 non-root users are really worth the extra @command{sed} invocation.
 
 
+@node Debugging Make Rules
+@section Debugging Make Rules
+@cindex debugging rules
+@cindex rules, debugging
+
+The rules and dependency trees generated by @command{automake} can get
+rather complex, and leave the developer head-scratching when things
+don't work as expected.  Besides the debug options provided by the
+@command{make} command (@pxref{Options Summary,,, make, The GNU Make
+Manual}), here's a couple of further hints for debugging makefiles
+generated by @command{automake} effectively:
+
+@itemize
+@item
+If less verbose output has been enabled in the package with the
+@samp{silent-rules} option (@pxref{Options}), you can use
+@code{make V=1} to see the commands being executed.
+@item
+@code{make -n} can help show what would be done without actually doing
+it.  Note however, that this will @emph{still execute} commands prefixed
+with @samp{+}, and, when using GNU @command{make}, commands that contain
+the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
+Execution,,, make, The GNU Make Manual}).
+Typically, this is helpful to show what recursive rules would do, but it
+means that, in your own rules, you should not mix such recursion with
+actions that change any files.@footnote{Automake's @samp{dist} and
+@samp{distcheck} rules had a bug in this regard in that they created
+directories even with @option{-n}, but this has been fixed in Automake
+1.11.}  Furthermore, note that GNU @command{make} will update
+prerequisites for the @file{Makefile} file itself even with @option{-n}
+(@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
+@item
+@code{make SHELL="/bin/bash -vx"} can help debug complex rules.
+@xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
+portability quirks associated with this construct.
+@end itemize
+
+
 @node History
 @chapter History of Automake