compilerplugins/README

   1 Compiler plugins.
   2
   3
   4 == Overview ==
   5
   6 This directory contains code for compiler plugins. These are used to perform
   7 additional actions during compilation (such as additional warnings) and
   8 also to perform mass code refactoring.
   9
  10 Currently only the Clang compiler is supported (http://wiki.documentfoundation.org/Development/Clang).
  11
  12
  13 == Usage ==
  14
  15 Compiler plugins are enabled automatically by --enable-dbgutil if Clang headers
  16 are found or explicitly using --enable-compiler-plugins.
  17
  18
  19 == Functionality ==
  20
  21 There are two kinds of plugin actions:
  22 - compile checks - these are run during normal compilation
  23 - rewriters - these must be run manually and modify source files
  24
  25 Each source has a comment saying whether it's compile check or a rewriter
  26 and description of functionality.
  27
  28 === Compile checks ===
  29
  30 Used during normal compilation to perform additional checks.
  31 All warnings and errors are marked '[loplugin]' in the message.
  32
  33
  34 === Rewriters ===
  35
  36 Rewriters analyse and possibly modify given source files.
  37 Usage: make COMPILER_PLUGIN_TOOL=<rewriter_name>
  38 Additional optional make arguments:
  39 - it is possible to also pass FORCE_COMPILE_ALL=1 to make to trigger rebuild of all source files,
  40     even those that are up to date.
  41 - UPDATE_FILES=<scope> - limits which modified files will be actually written back with the changes
  42     - mainfile - only the main .cxx file will be modifed (default)
  43     - all - all source files involved will be modified (possibly even header files from other LO modules),
  44         3rd party header files are however never modified
  45     - <module> - only files in the given LO module (toplevel directory) will be modified (including headers)
  46
  47 Modifications will be written directly to the source files.
  48
  49
  50 == Code documentation / howtos ==
  51
  52 http://wiki.documentfoundation.org/Clang_plugins
  53