1 files changed, 69 insertions, 0 deletions
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=<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
+