diff options
Diffstat (limited to '')
| -rw-r--r-- | compilerplugins/README | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/compilerplugins/README b/compilerplugins/README new file mode 100644 index 000000000..c48341e0f --- /dev/null +++ b/compilerplugins/README @@ -0,0 +1,69 @@ +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=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), + 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=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 +in rewriting mode (during which no object files are generate). + + +== Code documentation / howtos == + +http://wiki.documentfoundation.org/Clang_plugins + |