diff options
author | Paul Smith <psmith@gnu.org> | 2023-03-18 17:24:45 -0400 |
---|---|---|
committer | Paul Smith <psmith@gnu.org> | 2023-04-02 10:02:18 -0400 |
commit | a0d1e76d604df5bd006fd5ed6a69963d3c6b4d7a (patch) | |
tree | 02d739d8168207be28535f359b0a6583f231f047 /doc | |
parent | 03ecd94488b85adc38746ec3e7c2a297a522598e (diff) | |
download | make-git-a0d1e76d604df5bd006fd5ed6a69963d3c6b4d7a.tar.gz |
Add support for .WARNINGS special variable
Create a new special variable, .WARNINGS, to allow per-makefile
control over warnings. The command line settings will override
this.
Move the handling of warning flags to a new file: src/warning.c.
Allow the decode to work with generic strings, and call it from
decode_switches().
* Makefile.am: Add new file src/warning.c.
* build_w32.bat: Ditto.
* builddos.bat: Ditto.
* po/POTFILES.in: Ditto.
* src/makeint.h: #define for the .WARNINGS variable name.
* src/warning.h: Add declarations for methods moved from main.c.
Rename the enum warning_state to warning_action.
* src/warning.c: New file. Move all warning encode/decode here
from main.c.
* src/main.c: Move methods into warning.c and call those methods
instead.
(main): Set .WARNINGS as a special variable.
* src/job.c (construct_command_argv): Rename to warning_action.
* src/read.c (tilde_expand): Ditto.
* src/variable.c (set_special_var): Update warnings when the
.WARNINGS special variable is set.
* tests/scripts/options/warn: Check invalid warning options.
* tests/scripts/variables/WARNINGS: Add tests for the .WARNINGS
special variable.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/make.texi | 131 |
1 files changed, 87 insertions, 44 deletions
diff --git a/doc/make.texi b/doc/make.texi index b3cc57a0..2dd6f1c9 100644 --- a/doc/make.texi +++ b/doc/make.texi @@ -7043,6 +7043,10 @@ a target-specific value). Note @code{make} is smart enough not to add a prerequisite listed in @code{.EXTRA_PREREQS} as a prerequisite to itself. +@item .WARNINGS +Changes the actions taken when @code{make} detects warning conditions in the +makefile. @xref{Warnings, ,Makefile Warnings}. + @end table @node Conditionals, Functions, Using Variables, Top @@ -9309,69 +9313,108 @@ correct them all before the next attempt to compile. This is why Emacs' @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: +GNU Make can detect some types of incorrect usage in makefiles. When one of +these incorrect usages is detected, GNU Make can perform one of these actions: + +@table @samp +@item ignore +@cindex warning action ignore +@cindex ignore, warning action +Ignore the usage. + +@item warn +@cindex warning action warn +@cindex warn, warning action +Show a warning about the usage and continue processing the makefile. + +@item error +@cindex warning action error +@cindex error, warning action +Show an error for the usage and immediately stop processing the makefile. +@end table + +@noindent +The types of warnings GNU Make can detect are: @table @samp @item invalid-var +@findex invalid-var +@cindex warning invalid variable Assigning to an invalid variable name (e.g., a name containing whitespace). +The default action is @samp{warn}. @item invalid-ref -Using an invalid variable name in a variable reference. +@findex invalid-ref +@cindex warning invalid reference +Using an invalid variable name in a variable reference. The default action is +@samp{warn}. @item undefined-var -Referencing a variable that has not been defined. +@findex undefined-var +@cindex warning undefined variable +Referencing a variable that has not been defined. The default action is +@samp{ignore}. Note the deprecated @code{--warn-undefined-variables} option +sets the action for this warning to @samp{warn}. @end table -When one of these incorrect usages is detected, GNU Make can perform one of -these actions: +The actions for these warnings can be changed by specifying warning control +options. Each warning control option consists of either a warning type, or a +warning action, or a warning type and warning action separated by a colon +(@code{:}). Multiple control options are separated by either whitespace or +commas. -@table @samp -@item ignore -Ignore the usage. +If the control option is just a warning type, then the action associated with +that type is set to @code{warn}. If the option is just an action, then that +action is applied to all warning types (a ``global action''). -@item warn -Show a warning about the usage and continue processing the makefile. +``Global actions'' take precedence over default actions. Actions associated +with a specific warning type take precedence over ``global actions'' and +default actions. -@item error -Show an error for the usage and immediately stop processing the makefile. -@end table +If multiple control options provide actions for the same warning type, the +last action specified will be used. -The default action of GNU Make when no warning control options are provided -is @samp{ignore} for @samp{undefined-var}, and @samp{warn} for -@samp{invalid-var} and @samp{invalid-ref}. +There are two ways to specify control options: using the @code{--warn} command +line option, or using the @code{.WARNINGS} variable. -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. +@subsubheading The @code{.WARNINGS} variable +@findex .WARNINGS +Warning control options provided in the @code{.WARNINGS} variable take effect +as soon as the variable assignment is parsed and will last until this instance +of @code{make} finishes parsing all makefiles. These settings will not be +passed to recursive invocations of @code{make}. + +Note that the value of this variable is expanded immediately, even if the +recursive expansion assignment operator (@code{=}) is used. + +Each assignment of @code{.WARNINGS} completely replaces any previous settings. +If you want to preserve the previous settings, use the @code{+=} assignment +operator. + +Currently, assigning @code{.WARNINGS} as a target-specific or pattern-specific +variable has no effect. This may change in the future. + +@subsubheading The @code{--warn} option +@cindex @code{--warn} +The @code{--warn} 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} take affect after the +assignment is parsed. This option is passed to sub-makes through the +@code{MAKEFLAGS} variable. 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}. +@code{--warn} option in @code{MAKEFLAGS} with a standard order. + +Specifying @code{--warn} with no arguments is equivalent to using +@code{--warn=warn}, which sets the action for all warning types to +@samp{warn}. + +Any action specified with an @code{--warn} option will take precedence over +actions provided in the makefile with @code{.WARNINGS}. This means if you use +@code{--warn=error}, for example, all warnings will be treated as errors +regardless of any @code{.WARNINGS} assignments. @node Temporary Files, Options Summary, Warnings, Running @section Temporary Files |