diff options
Diffstat (limited to 'compilerplugins/README.md')
-rw-r--r-- | compilerplugins/README.md | 71 |
1 files changed, 71 insertions, 0 deletions
diff --git a/compilerplugins/README.md b/compilerplugins/README.md new file mode 100644 index 0000000000..8f8a51bd6f --- /dev/null +++ b/compilerplugins/README.md @@ -0,0 +1,71 @@ +# 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> |