From 2611e1991fabe2a3ae929c6ebd4afbd4f550f306 Mon Sep 17 00:00:00 2001 From: Paul Smith Date: Sun, 26 Feb 2023 18:04:14 -0500 Subject: Introduce a --warn command line option Replace the singleton --warn-undefined-variables with infrastructure to manage multiple warnings: the --warn option can take an action "ignore", "warn", or "error" (which will apply to all warnings), or a specific warning type and an action for that type. Multiple options can be provided and are consolidated. * NEWS: Announce the new option. * doc/make.1: Document in the man page. * doc/make.texi (Warnings): Document in the user's manual. * Makefile.am: Add new header warning.h. * src/warning.h: Define enum for actions and warning types, and macros to test whether they are set. Keep the default settings separate so that we can correctly reconstruct MAKEFLAGS. * src/makeint.h: Remove deprecated warn_undefined_variables_flag. * src/main.c: Create global variables to hold warning settings. (switches): Add a new switch for --warn. (initialize_warnings): Set the default warning actions. (main): Call initialize_warnings(). (encode_warning_state, decode_warning_state): Convert warning states between strings and enums. (encode_warning_name, decode_warning_name): Convert warning names between strings and enums. (decode_warn_flags): Convert a --warn option into enum values. If deprecated warn_undefined_variables_flag is set convert it to --warn. (decode_switches): Don't remove duplicates of --warn since order matters. Call decode_warn_flags() to handle --warn. (define_makeflags): Special-case handling of --warn options written to MAKEFLAGS: write out the current settings. * src/read.c (tilde_expand): Use new warning control macros. * src/variable.c (warn_undefined): Ditto. * src/job.c (construct_command_argv): Ditto. * tests/scripts/options/warn: Rename from warn-undefined-variables and add tests for --warn. * tests/scripts/variables/MAKEFLAGS: Expect the new behavior. --- doc/make.1 | 30 +++++++++++++++++++++- doc/make.texi | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 104 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/make.1 b/doc/make.1 index f02afbee..933a8273 100644 --- a/doc/make.1 +++ b/doc/make.1 @@ -364,8 +364,36 @@ command on the given file before running except that the modification time is changed only in the imagination of .BR make . .TP 0.5i +\fB\-\-warn\fR[=\fIARG[\fR,\fIARG\fR]] +Control warning reporting for makefiles. This option can appear multiple times. +In case of conflicts, later settings override earlier settings. +.I ARG +can be an action; one of +.IR ignore , +.IR warn , +or +.I error +to set the default action for all warnings, or it can be a specific warning: +.I undefined-var +(referencing an undefined variable). The behavior of each warning can be set +by adding +.BI : action +after the warning name. If an action is not specified the default is +.IR warn . +If no +.I ARG +is provided the action for all warnings is +.IR warn . +If no +.B \-\-warn +option is provided the default action for +.I undefined-var +is +.IR ignore . +.TP 0.5i .B \-\-warn\-undefined\-variables -Warn when an undefined variable is referenced. +A deprecated alternative for +.BR \-\-warn=undefined-var . .SH "EXIT STATUS" GNU Make exits with a status of zero if all makefiles were successfully parsed and no targets that were built failed. A status of one will be returned diff --git a/doc/make.texi b/doc/make.texi index aa488eb7..31db623b 100644 --- a/doc/make.texi +++ b/doc/make.texi @@ -310,6 +310,7 @@ How to Run @code{make} an alternate compiler and other things. * Testing:: How to proceed past some errors, to test compilation. +* Warnings:: How to control reporting of makefile issues. * Temporary Files:: Where @code{make} keeps its temporary files. * Options Summary:: Summary of Options @@ -5170,7 +5171,7 @@ compatibility. It has the same value as @code{MAKEFLAGS} except that it does not contain the command line variable definitions, and it always begins with a hyphen unless it is empty (@code{MAKEFLAGS} begins with a hyphen only when it begins with an option that has no single-letter -version, such as @samp{--warn-undefined-variables}). @code{MFLAGS} was +version, such as @samp{--no-print-directory}). @code{MFLAGS} was traditionally used explicitly in the recursive @code{make} command, like this: @@ -8873,6 +8874,7 @@ determines that some target is not already up to date. an alternate compiler and other things. * Testing:: How to proceed past some errors, to test compilation. +* Warnings:: How to control reporting of makefile issues. * Temporary Files:: Where @code{make} keeps its temporary files. * Options Summary:: Summary of Options @end menu @@ -9265,7 +9267,7 @@ overridden. This is to use the @code{override} directive, which is a line that looks like this: @samp{override @var{variable} = @var{value}} (@pxref{Override Directive, ,The @code{override} Directive}). -@node Testing, Temporary Files, Overriding, Running +@node Testing, Warnings, Overriding, Running @section Testing the Compilation of a Program @cindex testing compilation @cindex compilation, testing @@ -9303,7 +9305,68 @@ program, perhaps to find several independent problems so that you can correct them all before the next attempt to compile. This is why Emacs' @kbd{M-x compile} command passes the @samp{-k} flag by default. -@node Temporary Files, Options Summary, Testing, Running +@node Warnings, Temporary Files, Testing, Running +@section Makefile Warnings +@cindex warnings + +GNU Make can detect some types of incorrect usage in makefiles and show +warnings about them. Currently these issues can be detected: + +@table @samp +@item undefined-var +Referencing a variable that has not been defined. +@end table + +When one of these incorrect usages is detected, GNU Make can perform one of +these actions: + +@table @samp +@item ignore +Ignore the usage. + +@item warn +Show a warning about the usage and continue processing the makefile. + +@item error +Show an error for the usage and immediately stop processing the makefile. +@end table + +The default action when no warning control options are provided for +@samp{undefined-var} is @samp{warn}. + +To modify this default behavior, you can use the @code{--warn} option. This +option can be specified on the command line, or by adding it to the +@code{MAKEFLAGS} variable (@pxref{Recursion, ,Recursive Use of @code{make}}). +Settings added to @code{MAKEFLAGS} are only affect after the assignment +statement. + +The @code{--warn} option can be provided multiple times: the effects are +cumulative with later options overriding over earlier options. When GNU Make +provides warning settings to sub-makes, they are all combined into a single +@code{--warn} option in @code{MAKEFLAGS}. + +If @code{--warn} is provided with no arguments then all issues are detected +and reported at the @samp{warn} level unless otherwise specified. + +If one of the actions (@samp{ignore}, @samp{warn}, @samp{error}) is provided +as an argument to @code{--warn}, then this action becomes the default for all +warning types. For example all warnings can be disabled by using +@code{--warn=ignore}, or all warnings can be considered fatal errors by using +@code{--warn=error}. + +Additionally, warning types can be specified. If the warning is listed alone, +then that warning is enabled with the @code{warn} action: e.g., +@code{--warn=undefined-var} will enable @samp{undefined-var} warnings with the +@samp{warn} action. Alternatively an action can be provided after the warning +type, separated by a @code{:}. So @code{--warn=undefined-var:error} enables +@samp{undefined-var} warnings with an action of @samp{error}. + +More specific settings take precedence over the global setting. For example, +an option @code{--warn=undefined-var:error,ignore} will set the action for +@samp{undefined-var} warnings to @samp{error}, and the action for all other +warnings to @samp{ignore}. + +@node Temporary Files, Options Summary, Warnings, Running @section Temporary Files @cindex temporary files @@ -9756,13 +9819,19 @@ running a @code{touch} command on the given file before running imagination of @code{make}. @xref{Instead of Execution, ,Instead of Executing Recipes}. + +@item --warn[=@var{arg}[,@var{arg}]] +@cindex @code{--warn} +@cindex warnings +Specify the handling of @ref{Warnings, ,Makefile Warnings} detected in +makefiles. + @item --warn-undefined-variables @cindex @code{--warn-undefined-variables} @cindex variables, warning for undefined @cindex undefined variables, warning message -Issue a warning message whenever @code{make} sees a reference to an -undefined variable. This can be helpful when you are trying to debug -makefiles which use variables in complex ways. +A deprecated name for @code{--warn=undefined-var}. @xref{Warnings, +,Makefile Warnings}. @end table @node Implicit Rules, Archives, Running, Top -- cgit v1.2.1