diff options
Diffstat (limited to 'compilerplugins/README.md')
| -rw-r--r-- | compilerplugins/README.md | 53 |
1 files changed, 25 insertions, 28 deletions
diff --git a/compilerplugins/README.md b/compilerplugins/README.md index c48341e0f0d2..e076f408f07a 100644 --- a/compilerplugins/README.md +++ b/compilerplugins/README.md @@ -1,69 +1,66 @@ -Compiler plugins. +# Compiler plugins - -== Overview == +## 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). - +Currently only the Clang compiler is supported <http://wiki.documentfoundation.org/Development/Clang>. -== Usage == +## Usage -Compiler plugins are enabled automatically by --enable-dbgutil if Clang headers -are found or explicitly using --enable-compiler-plugins. +Compiler plugins are enabled automatically by `--enable-dbgutil` if Clang headers +are found or explicitly using `--enable-compiler-plugins`. - -== Functionality == +## 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 === +### Compile Checks Used during normal compilation to perform additional checks. All warnings and errors are marked '[loplugin]' in the message. - -=== Rewriters === +### Rewriters Rewriters analyse and possibly modify given source files. -Usage: make COMPILER_PLUGIN_TOOL=<rewriter_name> +Usage: `make COMPILER_PLUGIN_TOOL=<rewriter_name>` Additional optional make arguments: -- it is possible to also pass FORCE_COMPILE_ALL=1 to make to trigger rebuild of all source files, + +- it is possible to also pass `FORCE_COMPILE_ALL=1` to make to trigger rebuild of all source files, even those that are up to date. -- 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), +- `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) + - `<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 +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 +`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=1 UPDATE_FILES=all + make COMPILER_PLUGIN_WARNINGS_ONLY=X \ + && make COMPILER_PLUGIN_TOOL=X FORCE_COMPILE_ALL=1 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 +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 == - -http://wiki.documentfoundation.org/Clang_plugins +## Code Documentation / HowTos +<http://wiki.documentfoundation.org/Clang_plugins> |