Summary

Refine the -Werror flag to support lint categories just like -Xlint does. So, for example -Werror:all,-preview would cause an error if any warning other than a preview warning occurred.

Problem

-Xlint allows one to customize which warnings should appear and which should be hidden. This caters to different needs in different scenarios - a "one size fits all" approach is too limiting.

The same logic applies to -Werror: there are scenarios where some warnings are more salient than others to whether a build should fail. Allowing -Werror to function like -Xlint with per-lint category customizations would accomodate this.

Solution

First, preserve the existing behavior:

• If no -Werror flag of any kind appears at all, then no warning will trigger an error.
• If only the -Werror flag is given, then any warning will trigger an error.

Next, add support for "custom" flags like -Werror:all, -Werror:none, and -Werror:foo,-bar.

These flags will be parsed and interpreted exactly like the corresponding -Xlint flags, with one exception: If no -Xlint flag appears at all, then a non-empty set of default lint warning categories is enabled, whereas if no -Werror flag appears at all, then the default behavior is as it is today, namely, no warning will trigger an error (i.e., the default set is empty).

Note that the existing -Xlint flag has a particular behavior when conflicting flags are combined. For example, -Xlint:all -Xlint:none -Xlint:foo -Xlint:-foo equals -Xlint:all. This same behavior has been preserved and carried over to -Werror.

Corner Case #1

Currently -Werror turns every warning into an error, even warnings that have no associated lint category. So that raises a question, does -Werror:all also turn every warning into an error, or only those warnings that have an associated lint category?

The conservative choice here (i.e., more errors) is the former choice, i.e., make -Werror:all behave just like -Werror, so that's how we implement it. This is a slight breach of orthogonality; however, it addresses the likely and reasonable developer belief that -Werror:all should be "at least as strong as" -Werror. In particular, when a developer discovers one particular lint category foo is causing build failures and they want to disable that category, they are likely going to replace their existing -Werror flag with -Werror:all,-foo. If they do, we don't want them to unknowingly disable all non-lint warnings from generating errors.

Corner Case #2

What about a seemingly contradictory combination like -Werror:serial -Xlint:-serial? This means what it says, i.e., disable serial warnings but error out if any serial warnings occur: but the "error out if any serial warnings occur" will never apply because that will never happen.

Alias Concerns

Recently, support for lint category aliases was added as part of JDK-8354556. That commit changed the name of the "synchronization" lint category to "identity", and then made "synchronization" an alias of it for backward compatibility. Logically, lint category aliases are truly just aliases, i.e., different names for the same underlying lint category. The compiler logic deals with the underlying lint categories, not their aliases.

Because it's therefore possible to refer to the same lint category using different names, some confusion could occur. For example, two flags -Werror:identity -Werror:-synchronization would have no net effect. Of course, this is already true for -Xlint as well, so nothing new here, other than a new opportunity for this confusion to arise.

Specification

Here is the diff of the output of the command javac --help && javac --help-extra && javac --help-lint:

@@ -73,7 +73,11 @@
         Override location of upgradeable modules
   -verbose                     Output messages about what the compiler is doing
   --version, -version          Version information
-  -Werror                      Terminate compilation if warnings occur
+  -Werror                      Terminate compilation if any warnings occur
+  -Werror:<key>(,<key>)*
+        Specify lint categories for which warnings should terminate compilation,
+        separated by comma. Precede a key by '-' to exclude the specified category.
+        Use --help-lint to see the supported keys.

   --add-exports <module>/<package>=<other-module>(,<other-module>)*
         Specify a package to be considered as exported from its
@@ -90,7 +94,7 @@
         Disable support for documentation comments with lines beginning '///'
   -Djava.endorsed.dirs=<dirs>  Override location of endorsed standards path
   -Djava.ext.dirs=<dirs>       Override location of installed extensions
-  --help-lint                  Print the supported keys for -Xlint
+  --help-lint                  Print the supported keys for -Xlint and -Werror
   --patch-module <module>=<file>(:<file>)*
         Override or augment a module with classes and resources
         in JAR files or directories
@@ -1,4 +1,4 @@
-The supported keys for -Xlint are:
+The supported keys for -Xlint and -Werror are:
     all                  Enable all warning categories
     auxiliaryclass       Warn about an auxiliary class that is hidden in a source file, and is used from other files.
     cast                 Warn about use of unnecessary casts.
@@ -45,3 +45,6 @@
     preview              Warn about use of preview language features.
     restricted           Warn about use of restricted methods.
     none                 Disable all warning categories
+Lint categories and their aliases can be used interchangeably. For example,
+the flags "-Xlint:identity" and "-Werror:synchronization" will properly
+cause warnings in the "identity" lint category to terminate compilation.

Here's the man page diff (source):

@@ -448,7 +448,16 @@ ### Standard Options
 :   Prints version information.

 <a id="option-Werror">`-Werror`</a>
-:   Terminates compilation when warnings occur.
+:   Terminates compilation when any warnings occur; this includes warnings in all lint
+    categories, as well as non-lint warnings.
+
+<a id="option-Werror-custom">`-Werror:`\[`-`\]*key*(`,`\[`-`\]*key*)\*</a>
+:   Specify lint categories for which warnings should terminate compilation. The keys
+    `all` and `none` include or exclude all categories (respectively); other keys include
+    the corresponding category, or exclude it if preceded by a hyphen (`-`). By default,
+    no categories are included. In order to terminate compilation, the category must also
+    be enabled (via [`-Xlint`](#option-Xlint-custom), if necessary).
+    See [`-Xlint`](#option-Xlint-custom) below for the list of lint category keys.

 ### Extra Options

Here's the man page diff (troff):

@@ -433,7 +433,17 @@
               Prints version information.

        ‐Werror
-              Terminates compilation when warnings occur.
+              Terminates compilation when any warnings  occur;  this  includes
+              warnings in all lint categories, as well as non‐lint warnings.
+
+       ‐Werror:[‐]key(,[‐]key)*
+              Specify lint categories for which warnings should terminate com‐
+              pilation.   The  keys  all and none include or exclude all cate‐
+              gories (respectively); other keys include the corresponding cat‐
+              egory, or exclude it if preceded by a hyphen (‐).   By  default,
+              no  categories are included.  In order to terminate compilation,
+              the category must also be enabled (via  ‐Xlint,  if  necessary).
+              See ‐Xlint below for the list of lint category keys.

    Extra Options
        ‐‐add‐exports module/package=other‐module(,other‐module)*