compilerplugins/README.md

   1 # Compiler plugins
   2
   3 ## Overview
   4
   5 This directory contains code for compiler plugins. These are used to perform
   6 additional actions during compilation (such as additional warnings) and
   7 also to perform mass code refactoring.
   8
   9 Currently only the Clang compiler is supported <http://wiki.documentfoundation.org/Development/Clang>.
  10
  11 ## Usage
  12
  13 Compiler plugins are enabled automatically by `--enable-dbgutil` if Clang headers
  14 are found or explicitly using `--enable-compiler-plugins`.
  15
  16 ## Functionality
  17
  18 There are two kinds of plugin actions:
  19
  20 - compile checks - these are run during normal compilation
  21 - rewriters - these must be run manually and modify source files
  22
  23 Each source has a comment saying whether it's compile check or a rewriter
  24 and description of functionality.
  25
  26 ### Compile Checks
  27
  28 Used during normal compilation to perform additional checks.
  29 All warnings and errors are marked '[loplugin]' in the message.
  30
  31 ### Rewriters
  32
  33 Rewriters analyse and possibly modify given source files.
  34 Usage: `make COMPILER_PLUGIN_TOOL=<rewriter_name>`
  35 Additional optional make arguments:
  36
  37 - it is possible to also pass `FORCE_COMPILE_ALL=1` to make to trigger rebuild of all source files,
  38     even those that are up to date.
  39 - `UPDATE_FILES=<scope>` - limits which modified files will be actually written back with the changes
  40     - `mainfile` - only the main `.cxx` file will be modified (default)
  41     - `all` - all source files involved will be modified (possibly even header files from other LO modules),
  42         3rd party header files are however never modified
  43     - `<module>` - only files in the given LO module (toplevel directory) will be modified (including headers)
  44
  45 Modifications will be written directly to the source files.
  46
  47 Some rewriter plugins are dual-mode and can also be used in a non-rewriting mode
  48 in which they emit warnings for problematic code that they would otherwise
  49 automatically rewrite.  When any rewriter is enabled explicitly via `make
  50 COMPILER_PLUGIN_TOOL=<rewriter_name>` it works in rewriting mode (and all other
  51 plugins are disabled), but when no rewriter is explicitly enabled (i.e., just
  52 `make`), all dual-mode rewriters are enabled in non-rewriting mode (along with
  53 all non-rewriter plugins; and all non--dual-mode plugins are disabled).  The
  54 typical process to use such a dual-mode rewriter X in rewriting mode is
  55
  56     make COMPILER_PLUGIN_WARNINGS_ONLY=X \
  57     && make COMPILER_PLUGIN_TOOL=X FORCE_COMPILE_ALL=1 UPDATE_FILES=all
  58
  59 which first generates a full build without failing due to warnings from plugin
  60 X in non-rewriting mode (in case of `--enable-werror`) and then repeats the build
  61 in rewriting mode (during which no object files are generate).
  62
  63
  64 ## Code Documentation / HowTos
  65
  66 <https://wiki.documentfoundation.org/Clang_plugins>