blob: e2c2b217bfc30c7f7103aabaf2456745f9ad96d3 [file] [log] [blame] [view]
andybons3322f762015-08-24 21:37:091# Don't write a clang plugin
2
nodire7e901b02015-08-25 15:30:113[TOC]
4
andybons3322f762015-08-24 21:37:095Make sure you really want to write a clang plugin.
6
nodire7e901b02015-08-25 15:30:117* The clang plugin api is not stable. If you write a plugin, _you_ are
8 responsible for making sure it's updated when we update clang.
9* If you're adding a generally useful warning, it should be added to upstream
10 clang, not to a plugin.
11* You should not use a clang plugin to do things that can be done in a
12 PRESUBMIT check (e.g. checking that the headers in a file are sorted).
andybons3322f762015-08-24 21:37:0913
14Valid reasons for writing a plugin are for example:
15
nodire7e901b02015-08-25 15:30:1116* You want to add a chromium-specific error message.
17* You want to write an automatic code rewriter.
andybons3322f762015-08-24 21:37:0918
nodire7e901b02015-08-25 15:30:1119In both cases, please inform
xiaoyin.l1003c0b2016-12-06 02:51:1720[clang@chromium.org](https://groups.google.com/a/chromium.org/group/clang/topics)
nodire7e901b02015-08-25 15:30:1121of your plans before you pursue them.
andybons3322f762015-08-24 21:37:0922
23# Having said that
24
nodire7e901b02015-08-25 15:30:1125clang currently has minimal documentation on its plugin interface; it's mostly
26doxygen annotations in the source. This is an attempt to be half map to the
27header files/half tutorial.
andybons3322f762015-08-24 21:37:0928
29# Building your plugin
30
31## Just copy the clang build system
32
nodire7e901b02015-08-25 15:30:1133I suggest you make a new dir in `llvm/tools/clang/examples/` and copy the
34Makefile from `PrintFunctionNames` there. This way, you'll just leverage the
35existing clang build system. You can then build your plugin with
andybons3322f762015-08-24 21:37:0936
nodire7e901b02015-08-25 15:30:1137 make -C llvm/tools/clang/examples/myplugin
andybons3322f762015-08-24 21:37:0938
nodire7e901b02015-08-25 15:30:1139See [Using plugins](clang.md) on how to use your plugin while building chromium
40with clang.
andybons3322f762015-08-24 21:37:0941
nodire7e901b02015-08-25 15:30:1142## Use the interface in tools/clang/plugins/ChromeClassTester.h
andybons3322f762015-08-24 21:37:0943
nodire7e901b02015-08-25 15:30:1144Here's a canned interface that filters code, only passing class definitions in
45non-blacklisted headers. The users of `ChromeClassTester` are good code to study
46to see what you can do.
andybons3322f762015-08-24 21:37:0947
nodire7e901b02015-08-25 15:30:1148## Or if you're doing something really different, copy PrintFunctionNames.cpp
andybons3322f762015-08-24 21:37:0949
nodire7e901b02015-08-25 15:30:1150`PrintFunctionNames.cpp` is a plugin in the clang distribution. It is the Hello
51World of plugins. As a most basic skeleton, it's a good starting point. Change
52all the identifiers that start with `PrintFunction` to your desired name. Take
53note of the final line:
andybons3322f762015-08-24 21:37:0954
nodire7e901b02015-08-25 15:30:1155```cpp
andybons3322f762015-08-24 21:37:0956static FrontendPluginRegistry::Add<PrintFunctionNamesAction>
57X("print-fns", "print function names");
58```
59
nodire7e901b02015-08-25 15:30:1160This registers your `PluginASTAction` with a string plugin name that can be
61invoked on the command line. Note that everything else is in an anonymous
62namespace; all other symbols aren't exported.
andybons3322f762015-08-24 21:37:0963
nodire7e901b02015-08-25 15:30:1164Your `PluginASTAction` subclass exists just to build your `ASTConsumer`, which
65receives declarations, sort of like a SAX parser.
andybons3322f762015-08-24 21:37:0966
67## Your ASTConsumer
68
nodire7e901b02015-08-25 15:30:1169There is doxygen documentation on when each `ASTConsumer::Handle` method is
70called in `llvm/tools/clang/include/clang/AST/ASTConsumer.h`. For this
71tutorial, I'll assume you only want to look at type definitions (struct, class,
72enum definitions), so we'll start with:
andybons3322f762015-08-24 21:37:0973
nodire7e901b02015-08-25 15:30:1174```cpp
andybons3322f762015-08-24 21:37:0975class TagConsumer : public ASTConsumer {
nodire7e901b02015-08-25 15:30:1176 public:
77 virtual void HandleTagDeclDefinition(TagDecl *D) {
78 }
andybons3322f762015-08-24 21:37:0979};
andybons3322f762015-08-24 21:37:0980```
81
nodire7e901b02015-08-25 15:30:1182The data type passed in is the `Decl`, which is a giant class hierarchy spanning
83the following files:
andybons3322f762015-08-24 21:37:0984
nodire7e901b02015-08-25 15:30:1185* `llvm/tools/clang/include/clang/AST/DeclBase.h`: declares the `Decl` class,
86 along with some utility classes you won't use.
87* `llvm/tools/clang/include/clang/AST/Decl.h`: declares subclasses of `Decl`,
88 for example, `FunctionDecl` (a function declaration), `TagDecl` (the base class for struct/class/enum/etc), `TypedefDecl`, etc.
89* `llvm/tools/clang/include/clang/AST/DeclCXX.h`: C++ specific types.
90 You'll find most Decl subclasses dealing with templates here,
91 along with things like `UsingDirectiveDecl`, `CXXConstructorDecl`, etc.
andybons3322f762015-08-24 21:37:0992
nodire7e901b02015-08-25 15:30:1193The interface on these classes is massive; We'll only cover some of the basics,
94but some basics about source location and errors.
andybons3322f762015-08-24 21:37:0995
96## Emitting Errors
97
nodire7e901b02015-08-25 15:30:1198Lots of location information is stored in the `Decl` tree. Most `Decl`
99subclasses have multiple methods that return a `SourceLocation`, but lets use
100`TagDecl::getInnerLocStart()` as an example. (`SourceLocation` is defined in
101`llvm/tools/clang/include/clang/Basic/SourceLocation.h`, for reference.)
andybons3322f762015-08-24 21:37:09102
103Errors are emitted to the user through the `CompilerInstance`. You will probably want to pass the `CompilerInstance` object passed to `ASTAction::CreateASTConsumer` to your ASTConsumer subclass for reporting. You interact with the user through the `Diagnostic` object. You could report errors to the user like this:
104
nodire7e901b02015-08-25 15:30:11105```cpp
andybons3322f762015-08-24 21:37:09106void emitWarning(CompilerInstance& instance, SourceLocation loc, const char* error) {
107 FullSourceLoc full(loc, instance.getSourceManager());
108 unsigned id = instance.getCustomDiagID(Diagnostic::Warning, error);
109 DiagnosticBuilder B = instance.getDiagnostics().Report(full, id);
110}
111```
112
nodire7e901b02015-08-25 15:30:11113(The above is the simplest error reporting. See
114`llvm/tools/clang/include/clang/Basic/Diagnostic.h` for all the things you can
115do, like `FixItHint`s if you want to get fancy!)
andybons3322f762015-08-24 21:37:09116
117## Downcast early, Downcast often
118
nodire7e901b02015-08-25 15:30:11119The clang library will give you the most general types possible. For example
120`TagDecl` has comparably minimal interface. The library is designed so you will
121be downcasting all the time, and you won't use the standard `dynamic_cast<>()`
122builtin to do it. Instead, you'll use llvm/clang's home built RTTI system:
andybons3322f762015-08-24 21:37:09123
nodire7e901b02015-08-25 15:30:11124```cpp
andybons3322f762015-08-24 21:37:09125 virtual void HandleTagDeclDefinition(TagDecl* tag) {
126 if (CXXRecordDecl* record = dyn_cast<CXXRecordDecl>(tag)) {
127 // Do stuff with |record|.
128 }
129 }
130```
131
nodire7e901b02015-08-25 15:30:11132## A (not at all exhaustive) list of things you can do with (CXX)RecordDecl
andybons3322f762015-08-24 21:37:09133
nodire7e901b02015-08-25 15:30:11134* Iterate across all constructors (`CXXRecordDecl::ctor_begin()`,
135 `CXXReocrdDecl::ctor_end()`)
136* `CXXRecordDecl::isPOD()`: is this a Plain Old Datatype (a type that has no
137 construction or destruction semantics)?
138* Check if certain properties of the class: `CXXRecordDecl::isAbstract()`,
139 `CXXRecordDecl::hasTrivialConstructor()`,
140 `CXXRecordDecl::hasTrivialDestructor()`, etc.
141* Iterate across all fields/member variables (`RecordDecl::field_begin()`,
142 `RecordDecl::field_end()`)
143* Iterate across all of the base classes of a record type
144 (`CXXRecordDecl::bases_begin()`, `CXXRecordDecl::bases_end()`)
145* Get the simple string name `NamedDecl::getNameAsString()`. (This method is
146 deprecated, but the replacement assert()s on error conditions). (If you had
147 `struct One {}`, this method would return "One".)
andybons3322f762015-08-24 21:37:09148
149## Modifying existing plugins
150
nodire7e901b02015-08-25 15:30:11151If you want to add additional checks to the existing plugins, be sure to add the
152new diagnostic behind a flag (there are several examples of this in the plugins
153already). The reason for this is that the plugin is bundled with clang, and the
154new check will get deployed with the next clang roll. If your check fires, then
155the next clang roll would now be blocked on cleaning up the whole codebase for
156your check – and even if the check doesn't fire at the moment, maybe that
157regresses until the next clang roll happens. If your new check is behind a flag,
158then the clang roll can happen first, and you can add the flag to enable your
159check after that, and then turn on the check everywhere once you know that the
160codebase is clean.