docs: More reST conversion.

Sorry for the large commit, but it is much faster to convert in batches.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@170067 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 149 insertions, 0 deletions

diff --git a/docs/ClangPlugins.rst b/docs/ClangPlugins.rst
new file mode 100644
index 0000000000..cf53817229
--- /dev/null
+++ b/docs/ClangPlugins.rst
@@ -0,0 +1,149 @@
+=============
+Clang Plugins
+=============
+
+Clang Plugins make it possible to run extra user defined actions during
+a compilation. This document will provide a basic walkthrough of how to
+write and run a Clang Plugin.
+
+Introduction
+============
+
+Clang Plugins run FrontendActions over code. See the :doc:`FrontendAction
+tutorial <RAVFrontendAction>` on how to write a FrontendAction
+using the RecursiveASTVisitor. In this tutorial, we'll demonstrate how
+to write a simple clang plugin.
+
+Writing a PluginASTAction
+=========================
+
+The main difference from writing normal FrontendActions is that you can
+handle plugin command line options. The PluginASTAction base class
+declares a ParseArgs method which you have to implement in your plugin.
+
+::
+
+      bool ParseArgs(const CompilerInstance &CI,
+                     const std::vector<std::string>& args) {
+        for (unsigned i = 0, e = args.size(); i != e; ++i) {
+          if (args[i] == "-some-arg") {
+            // Handle the command line argument.
+          }
+        }
+        return true;
+      }
+
+Registering a plugin
+====================
+
+A plugin is loaded from a dynamic library at runtime by the compiler. To
+register a plugin in a library, use FrontendPluginRegistry::Add:
+
+::
+
+      static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description");
+
+Putting it all together
+=======================
+
+Let's look at an example plugin that prints top-level function names.
+This example is also checked into the clang repository; please also take
+a look at the latest `checked in version of
+PrintFunctionNames.cpp <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_.
+
+::
+
+    #include "clang/Frontend/FrontendPluginRegistry.h"
+    #include "clang/AST/ASTConsumer.h"
+    #include "clang/AST/AST.h"
+    #include "clang/Frontend/CompilerInstance.h"
+    #include "llvm/Support/raw_ostream.h"
+    using namespace clang;
+
+    namespace {
+
+    class PrintFunctionsConsumer : public ASTConsumer {
+    public:
+      virtual bool HandleTopLevelDecl(DeclGroupRef DG) {
+        for (DeclGroupRef::iterator i = DG.begin(), e = DG.end(); i != e; ++i) {
+          const Decl *D = *i;
+          if (const NamedDecl *ND = dyn_cast<NamedDecl>(D))
+            llvm::errs() << "top-level-decl: \"" << ND->getNameAsString() << "\"\n";
+        }
+
+        return true;
+      }
+    };
+
+    class PrintFunctionNamesAction : public PluginASTAction {
+    protected:
+      ASTConsumer *CreateASTConsumer(CompilerInstance &CI, llvm::StringRef) {
+        return new PrintFunctionsConsumer();
+      }
+
+      bool ParseArgs(const CompilerInstance &CI,
+                     const std::vector<std::string>& args) {
+        for (unsigned i = 0, e = args.size(); i != e; ++i) {
+          llvm::errs() << "PrintFunctionNames arg = " << args[i] << "\n";
+
+          // Example error handling.
+          if (args[i] == "-an-error") {
+            DiagnosticsEngine &D = CI.getDiagnostics();
+            unsigned DiagID = D.getCustomDiagID(
+              DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'");
+            D.Report(DiagID);
+            return false;
+          }
+        }
+        if (args.size() && args[0] == "help")
+          PrintHelp(llvm::errs());
+
+        return true;
+      }
+      void PrintHelp(llvm::raw_ostream& ros) {
+        ros << "Help for PrintFunctionNames plugin goes here\n";
+      }
+
+    };
+
+    }
+
+    static FrontendPluginRegistry::Add<PrintFunctionNamesAction>
+    X("print-fns", "print function names");
+
+Running the plugin
+==================
+
+To run a plugin, the dynamic library containing the plugin registry must
+be loaded via the -load command line option. This will load all plugins
+that are registered, and you can select the plugins to run by specifying
+the -plugin option. Additional parameters for the plugins can be passed
+with -plugin-arg-<plugin-name>.
+
+Note that those options must reach clang's cc1 process. There are two
+ways to do so:
+
+-  Directly call the parsing process by using the -cc1 option; this has
+   the downside of not configuring the default header search paths, so
+   you'll need to specify the full system path configuration on the
+   command line.
+-  Use clang as usual, but prefix all arguments to the cc1 process with
+   -Xclang.
+
+For example, to run the print-function-names plugin over a source file
+in clang, first build the plugin, and then call clang with the plugin
+from the source tree:
+
+::
+
+      $ export BD=/path/to/build/directory
+      $ (cd $BD && make PrintFunctionNames )
+      $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \
+            -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \
+            -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \
+            tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \
+            -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \
+            -plugin -Xclang print-fns
+
+Also see the print-function-name plugin example's
+`README <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_