compilerplugins/clang/sharedvisitor/README

   1 These tools generate another "plugin" which in fact only dispatches Visit* and Traverse*
   2 calls to all other plugins registered with it. This means that there is just one
   3 RecursiveASTVisitor pass for all those plugins instead of one per each, which
   4 with the current number of plugins actually makes a performance difference.
   5
   6 If you work on a plugin, comment out LO_CLANG_SHARED_PLUGINS in Makefile-clang.mk in order
   7 to disable the feature (re-generating takes time).
   8
   9 There are two tools:
  10 - analyzer, which analyses one .cxx file (one plugins) and writes info about it to a .plugininfo
  11   file, this allows parallelising this part, since it can take some time
  12 - generator, which reads all the .plugininfo files and generates sharedvisitor.cxx
  13
  14 Requirements for plugins:
  15 - Can use Visit* and Traverse* functions, but not WalkUp*.
  16 - Visit* functions can generally remain unmodified.
  17 - run() function must be split into preRun() and postRun() if there's any additional functionality
  18   besides calling TraverseDecl(). The shared visitor will call the preRun() and postRun() functions
  19   as necessary while calling its own run(). The run() function of the plugin must stay
  20   (in case of a non-shared build) but should generally look like this:
  21     if( preRun())
  22         if( TraverseDecl(compiler.getASTContext().getTranslationUnitDecl()))
  23             postRun();
  24 - Traverse* functions must be split into PreTraverse* and PostTraverse*, similarly to how run()
  25   is handled, the Traverse* function should generally look like this:
  26         bool ret = true;
  27         if( PreTraverse*(decl))
  28         {
  29             ret = RecursiveASTVisitor::Traverse*(decl);
  30             PostTraverse*(decl, ret);
  31         }
  32         return ret;
  33
  34
  35 TODO:
  36 - Create macros for the standardized layout of run(), Traverse*, etc.?
  37 - Possibly check plugin sources more thoroughly (e.g. that run() doesn't actually do more).
  38 - Have one tool that extracts info from plugin .cxx files into some .txt file and another tool
  39   that generates sharedvisitor.cxx based on those files? That would generally make the generation
  40   faster when doing incremental changes. The .txt file could also contain some checksum of the .cxx
  41   to avoid the analysing pass completely if just the timestamp has changed.
  42 - Do not re-compile sharedvisitor.cxx if its contents have not actually changed.
  43 - Is it possible to make the clang code analyze just the .cxx without also parsing all the headers?
  44 - Instead of having to comment out LO_CLANG_SHARED_PLUGINS, implement --enable-compiler-plugins=debug .
  45 - Try make analyzer use a precompiled header of Clang headers, for better performance.