# 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.

```c++
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<>`:

```c++
static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description");
```

## Defining pragmas

Plugins can also define pragmas by declaring a `PragmaHandler` and
registering it using `PragmaHandlerRegistry::Add<>`:

```c++
// Define a pragma handler for #pragma example_pragma
class ExamplePragmaHandler : public PragmaHandler {
public:
  ExamplePragmaHandler() : PragmaHandler("example_pragma") { }
  void HandlePragma(Preprocessor &PP, PragmaIntroducer Introducer,
                    Token &PragmaTok) {
    // Handle the pragma
  }
};

static PragmaHandlerRegistry::Add<ExamplePragmaHandler> Y("example_pragma","example pragma description");
```

## Defining attributes

Plugins can define attributes by declaring a `ParsedAttrInfo` and registering
it using `ParsedAttrInfoRegister::Add<>`:

```c++
class ExampleAttrInfo : public ParsedAttrInfo {
public:
  ExampleAttrInfo() {
    Spellings.push_back({ParsedAttr::AS_GNU,"example"});
  }
  AttrHandling handleDeclAttribute(Sema &S, Decl *D,
                                   const ParsedAttr &Attr) const override {
    // Handle the attribute
    return AttributeApplied;
  }
};

static ParsedAttrInfoRegistry::Add<ExampleAttrInfo> Z("example_attr","example attribute description");
```

The members of `ParsedAttrInfo` that a plugin attribute must define are:

- `Spellings`, which must be populated with every [Spelling](https://clang.llvm.org/doxygen/structclang_1_1ParsedAttrInfo_1_1Spelling.html) of the
  attribute, each of which consists of an attribute syntax and how the
  attribute name is spelled for that syntax. If the syntax allows a scope then
  the spelling must be "scope::attr" if a scope is present or "::attr" if not.

The members of `ParsedAttrInfo` that may need to be defined, depending on the
attribute, are:

- `NumArgs` and `OptArgs`, which set the number of required and optional
  arguments to the attribute.
- `diagAppertainsToDecl`, which checks if the attribute has been used on the
  right kind of declaration and issues a diagnostic if not.
- `handleDeclAttribute`, which is the function that applies the attribute to
  a declaration. It is responsible for checking that the attribute's arguments
  are valid, and typically applies the attribute by adding an `Attr` to the
  `Decl`. It returns either `AttributeApplied`, to indicate that the
  attribute was successfully applied, or `AttributeNotApplied` if it wasn't.
- `diagAppertainsToStmt`, which checks if the attribute has been used on the
  right kind of statement and issues a diagnostic if not.
- `handleStmtAttribute`, which is the function that applies the attribute to
  a statement. It is responsible for checking that the attribute's arguments
  are valid, and typically applies the attribute by adding an `Attr` to the
  `Stmt`. It returns either `AttributeApplied`, to indicate that the
  attribute was successfully applied, or `AttributeNotApplied` if it wasn't.
- `diagLangOpts`, which checks if the attribute is permitted for the current
  language mode and issues a diagnostic if not.
- `existsInTarget`, which checks if the attribute is permitted for the given
  target.

To see a working example of an attribute plugin, see [the Attribute.cpp example](https://github.com/llvm/llvm-project/blob/main/clang/examples/Attribute/Attribute.cpp).

## Putting it all together

Let's look at an example plugin that prints top-level function names. This
example is checked into the clang repository; please take a look at
the [latest version of PrintFunctionNames.cpp](https://github.com/llvm/llvm-project/blob/main/clang/examples/PrintFunctionNames/PrintFunctionNames.cpp).

## Running the plugin

### Using the compiler driver

The Clang driver accepts the `-fplugin` option to load a plugin.
Clang plugins can receive arguments from the compiler driver command
line via the `fplugin-arg-<plugin name>-<argument>` option. Using this
method, the plugin name cannot contain dashes itself, but the argument
passed to the plugin can.

```console
$ export BD=/path/to/build/directory
$ make -C $BD CallSuperAttr
$ clang++ -fplugin=$BD/lib/CallSuperAttr.so \
          -fplugin-arg-call_super_plugin-help \
          test.cpp
```

If your plugin name contains dashes, either rename the plugin or use the
cc1 command line options listed below.

### Using the cc1 command line

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:

```console
$ 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](https://github.com/llvm/llvm-project/blob/main/clang/examples/PrintFunctionNames/README.txt)

### Using the clang command line

Using `-fplugin=plugin` on the clang command line passes the plugin
through as an argument to `-load` on the cc1 command line. If the plugin
class implements the `getActionType` method then the plugin is run
automatically. For example, to run the plugin automatically after the main AST
action (i.e. the same as using `-add-plugin`):

```c++
// Automatically run the plugin after the main AST action
PluginASTAction::ActionType getActionType() override {
  return AddAfterMainAction;
}
```

### Interaction with `-clear-ast-before-backend`

To reduce peak memory usage of the compiler, plugins are recommended to run
*before* the main action, which is usually code generation. This is because
having any plugins that run after the codegen action automatically turns off
`-clear-ast-before-backend`. `-clear-ast-before-backend` reduces peak
memory by clearing the Clang AST after generating IR and before running IR
optimizations. Use `CmdlineBeforeMainAction` or `AddBeforeMainAction` as
`getActionType` to run plugins while still benefitting from
`-clear-ast-before-backend`. Plugins must make sure not to modify the AST,
otherwise they should run after the main action.
