From 0b77cd4e5d5b846219ba7eb27f2be0bbd54956c6 Mon Sep 17 00:00:00 2001 From: Ralf Wildenhues Date: Sat, 18 Apr 2009 23:03:17 +0200 Subject: [PATCH] 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 --- ChangeLog | 7 +++++++ doc/automake.texi | 45 +++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 50 insertions(+), 2 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6841864e3..05608e2d2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,12 @@ 2009-04-19 Ralf Wildenhues + 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 7b18cf45f..444fb21fa 100644 --- 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 -- 2.47.2