[llvm-dev] Proposal to add preprocessor warning for unused command line macros

[Mats Bengtsson via llvm-dev]

This is a proposal for either adding a new, or updating an existing
command line option such that a diagnostic can optionally be produced
for unused -D macros.

Long-lived large projects with thousands of files and many
contributors have a tendency to accumulate build options over time. As
time passes some build options like macros become replaced, obsolete,
or simply no longer used.

At the same time it is becoming more and more common that build
environments such as Bazel are used to try to minimize the build
effort and more importantly speed up builds. Build acceleration tools
commonly use the build options, and among them macros, to determine if
the output from a build is equivalent or not with a later build of the
same compilation unit.

The commands ...

$ clang -DFOO example.c

.. and ...

$ clang -DBAR example.c

... produce 100% identical output, since neither macro FOO nor BAR
affect the compilation unit. However, the build acceleration tools
that do not run the preprocessor will not detect that the input to the
compilation stage is identical and so will treat the output as unequal
and run the build two times, when once would have been sufficient.

There are two command line options that at present do not produce a
diagnostic for an unused command line macro, but which might be
expanded to do this task also;

-Wunused-macros

Produces diagnostic only for macros defined in the main source code
file that are not subsequenty used. No diagnostic for command line
macros, and no diagnostic for macros defined in header files included
by the source code file.

-Wunused-command-line-argument

Produces diagnostic for command line arguments that are not
applicable. But there is no diagnostic for command line macros that
are not used.

An alternative might be to add a specific option for use by the
preprocessor to produce a diagnostic for macros defined on the command
line, but not used by the source code file. This is my proposed named
for such an option;

-Wunused-command-line-macros

It is more likely than not that some of the command line macros are
intended to be consumed only by header files included by the source
code file, and not used at all in the source code itself. So the
option should be be implemented such that only macros occurring on the
command line >after< the option are subject to produce a diagnostic,
if not used. So for example;

$ clang -DFOO -Wunused-command-line-macros -DBAR example.c

... if we assume the "example.c" source code file uses neither of the
two macros FOO and BAR, a diagnostic will only be produced for BAR,
and none for FOO.

Is this a reasonable proposal? Comments?

An alternate solution might be for the preprocessor to dump out a list
of macros it has seen during processing. The build acceleration tools
can then hoover up this information in order to make more informed
decisions on which build options actually have an effect on the
produced output.

Thank you for your attention,
Mats Bengtsson