office-gobmx/compilerplugins
Stephan Bergmann e63e769bd3 Introduce a better mechanism to suppress false loplugin warnings
...by annotating occurrences of false warnings with [-loplugin:<name>] comments
in source files and letting individual plugins opt-in to watch out for such
suppression annotations, rather than maintaining lists of excluded source files
in the individual plugins.  (See the new loplugin::Plugin::suppressWarningsAt.)

Instead of making all calls to loplugin::Plugin::report check for suppression
annotations, the intent is that this check will only be added opt-in to those
places in the plugins that are prone to emitting false warnings.  In general it
is better to have plugins that don't produce false warnings in the first place,
or at least let those warnings be addressed with trivial and harmless source
code modifications, avoiding the need for any suppression mechanism.

As a proof of concept, I have removed the exclude list from
loplugin:redundantfcast and instead annotated the relevant source code.  (And
thereby found that three of the six originally excluded files didn't need to be
excluded any more at all?)

For now, this mechanism looks for comments (both //... and /*...*/, even
documentation-style /**...*/) that overlap the current and/or the preceding
line, because at least for code controlled by clang-format it is often easier to
move comments to a line of their own, preceding the commented code.  Looking
also at the current line (and not only at the preceding one) opens the door for
erroneous over-eager annotation, where an annotation that was meant to address a
false warning on the current line would also silence a potentially true warning
on the following line.  This probably doesn't cause much trouble in practice,
but is up for potential change.

Change-Id: I91ce7a0e5248886a60b471b1a153867f16bb5cea
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/133365
Tested-by: Jenkins
Reviewed-by: Stephan Bergmann <sbergman@redhat.com>
2022-04-25 18:21:24 +02:00
..
clang Introduce a better mechanism to suppress false loplugin warnings 2022-04-25 18:21:24 +02:00
.gitignore Move compilerplugins-related .gitignore content to compilerplugins/.gitignore 2020-08-17 13:38:04 +02:00
LICENSE.TXT Bump copyright year to 2021 2021-01-03 00:15:27 +01:00
Makefile remove SOLARENV variable 2013-11-02 22:07:53 +01:00
Makefile-clang.mk Build compilerplugings code with -fvisibility-inlines-hidden 2021-01-20 22:17:35 +01:00
Makefile.mk Revert "Revert "compilerplugins: Build them in parallel."" 2017-09-22 10:59:15 +02:00
README.md make FORCE_COMPILE_ALL more flexible than all or nothing 2021-09-18 19:24:46 +02:00

Compiler plugins

Overview

This directory contains code for compiler plugins. These are used to perform additional actions during compilation (such as additional warnings) and also to perform mass code refactoring.

Currently only the Clang compiler is supported http://wiki.documentfoundation.org/Development/Clang.

Usage

Compiler plugins are enabled automatically by --enable-dbgutil if Clang headers are found or explicitly using --enable-compiler-plugins.

Functionality

There are two kinds of plugin actions:

  • compile checks - these are run during normal compilation
  • rewriters - these must be run manually and modify source files

Each source has a comment saying whether it's compile check or a rewriter and description of functionality.

Compile Checks

Used during normal compilation to perform additional checks. All warnings and errors are marked '[loplugin]' in the message.

Rewriters

Rewriters analyse and possibly modify given source files. Usage: make COMPILER_PLUGIN_TOOL=<rewriter_name> Additional optional make arguments:

  • it is possible to also pass FORCE_COMPILE=all to make to trigger rebuild of all source files, even those that are up to date. FORCE_COMPILE takes a list of gbuild targets specifying where to run the rewriter ('all' means everything, '-' prepended means to not enable, '/' appended means everything in the directory; there is no ordering, more specific overrides more general, and disabling takes precedence). Example: FORCE_COMPILE="all -sw/ -Library_sc"

  • UPDATE_FILES=<scope> - limits which modified files will be actually written back with the changes

    • mainfile - only the main .cxx file will be modified (default)
    • all - all source files involved will be modified (possibly even header files from other LO modules), 3rd party header files are however never modified
    • <module> - only files in the given LO module (toplevel directory) will be modified (including headers)

Modifications will be written directly to the source files.

Some rewriter plugins are dual-mode and can also be used in a non-rewriting mode in which they emit warnings for problematic code that they would otherwise automatically rewrite. When any rewriter is enabled explicitly via make COMPILER_PLUGIN_TOOL=<rewriter_name> it works in rewriting mode (and all other plugins are disabled), but when no rewriter is explicitly enabled (i.e., just make), all dual-mode rewriters are enabled in non-rewriting mode (along with all non-rewriter plugins; and all non--dual-mode plugins are disabled). The typical process to use such a dual-mode rewriter X in rewriting mode is

make COMPILER_PLUGIN_WARNINGS_ONLY=X \
&& make COMPILER_PLUGIN_TOOL=X FORCE_COMPILE=all UPDATE_FILES=all

which first generates a full build without failing due to warnings from plugin X in non-rewriting mode (in case of --enable-werror) and then repeats the build in rewriting mode (during which no object files are generate).

Code Documentation / HowTos

https://wiki.documentfoundation.org/Clang_plugins