From c16158772d64cab8a4ed1f165cab57d307998e78 Mon Sep 17 00:00:00 2001 From: Hossein Date: Tue, 23 Mar 2021 14:20:32 +0430 Subject: Using .md extension/Markdown syntax for modules README Renaming all README files for all top level modules to README.md, applying no content change at this stage to be able to track history of the files. These files should be edited to use correct Markdown syntax later. Change-Id: I542fa3f3d32072156f16eaad2211a397cc212665 Reviewed-on: https://gerrit.libreoffice.org/c/core/+/112977 Tested-by: Jenkins Reviewed-by: Christian Lohmaier --- compilerplugins/README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 compilerplugins/README.md (limited to 'compilerplugins/README.md') diff --git a/compilerplugins/README.md b/compilerplugins/README.md new file mode 100644 index 000000000000..c48341e0f0d2 --- /dev/null +++ b/compilerplugins/README.md @@ -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= +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= - 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 + - - 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=" 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 + -- cgit