getting a handle on build warnings

[Jonathan Gibbons]

The JDK build generates a whole lot of warnings along the way. This is
bad because these warnings can sometimes mask real errors. For a
variety of reasons, it appears to be hard to try and get rid of all the
warnings, so this message is about a set of possible ideas to try and
get some control over the problem, by providing a relatively general
framework to use within the build, to minimize the introduction of new
warnings, and by providing a reporting framework for those developers
that *are* interested in reducing the warnings in their code.

1. Collecting warnings.

The simplest, easiest way to collect the warnings is to save the output from
a build, for subsequent processing by any new tools we provide.

David Herron has also suggested we could prefix the build macros for
selected commands like cc, javac, javadoc etc such that the output from
each invocation of the command is appended to a log, perhaps a directory
specific log.  For example, the macro to invoke javac could instead invoke
    savelog -a $(pwd)/javac.log javac ...
where savelog is a new command to run a subcommand and save its  output.

Whichever way we go, the first step in getting a handle on warnings would
be to save the output from the commands generating the warnings.

2.  Analyzing and normalizing warnings.

Warnings can be divided into two groups:
- those we know how to and want to deal with, and
- those we don't.
Ignore the latter group for now. Perhaps in time we'll figure out how to 
deal
with them and become interested in dealing with them.

We can select the warnings in the first group with grep or regular 
expressions.
Then we want to normalize the warnings.

Normalizing a warning consists of a number of steps:
- remove any information specific to that instance of the build.
    Typically, this will mean the head of any user-specific paths, such 
as absolute
    paths on the build machine.
- remove any information that may not be inherent to the warning
    Typically, this will mean line numbers  in the build.  Someone could 
edit the
    text in the source file ahead of the warning, and change the line number
    used in the warning. This should not change the normalized form of the
    warning
- adjust the location of the warning to be relative to one of the standard
    "subroots" within the tree, such as "src/share/classes",
    "src/PLATFORM/classes", etc.  In addition, standardize file separators
    in the location of the warning.

At the end of the normalization, warnings should all begin with a location,
such as the following made up examples,
    java/lang/String.java: warning: unchecked type
    com/sun/tools/javac/Main.java: warning: using deprecated method

Sorting the overall set of warnings would be good too.

3. Reporting and further analysis

If Release Engineering could produce a normalized list of warnings for
each promoted build, it would be possible for a developer to compare
the results of any new build against the "official" set of currently known
warnings, to see if any new warnings have been introduced. 

PIT testing could verify that no new warnings have been introduced,
and possibly give waivers for any justifiable new warnings.

The "official" set of currently known warnings could be posted on OpenJDK,
so that OpenJDK developers outside of Sun could compare their results
to the published results.

Developers could put "assertions" into the build to assert that portions
of the code are warning-free. -Werror achieves that to a limited extent
but doesn't work on tools like javadoc, which processes large amounts
of code which may not all be warning-free.

 From the normalized list of warnings, it would be possible a summary
table, grouped by package, and sorted either alphabetically or by
quantity. This way, we could see where are the worst offending source
files, and perhaps use that as motivation for fixing warnings.

Summary

Dealing with warnings has proven almost impossibly difficult over the
years. The  ideas presented here make it simpler to deal with the
problems by identifying warnings that we know how to fix, in areas where
we are interested in fixing them. In addition, it provides a way we can
ensure that the situation doesn't get any worse, going forward.

-- Jon