head 1.1; branch 1.1.1; access; symbols netbsd-11-0-RC4:1.1.1.4 netbsd-11-0-RC3:1.1.1.4 netbsd-11-0-RC2:1.1.1.4 netbsd-11-0-RC1:1.1.1.4 perseant-exfatfs-base-20250801:1.1.1.4 netbsd-11:1.1.1.4.0.10 netbsd-11-base:1.1.1.4 netbsd-10-1-RELEASE:1.1.1.4 perseant-exfatfs-base-20240630:1.1.1.4 perseant-exfatfs:1.1.1.4.0.8 perseant-exfatfs-base:1.1.1.4 netbsd-8-3-RELEASE:1.1.1.3 netbsd-9-4-RELEASE:1.1.1.3 netbsd-10-0-RELEASE:1.1.1.4 netbsd-10-0-RC6:1.1.1.4 netbsd-10-0-RC5:1.1.1.4 netbsd-10-0-RC4:1.1.1.4 netbsd-10-0-RC3:1.1.1.4 netbsd-10-0-RC2:1.1.1.4 netbsd-10-0-RC1:1.1.1.4 netbsd-10:1.1.1.4.0.6 netbsd-10-base:1.1.1.4 netbsd-9-3-RELEASE:1.1.1.3 cjep_sun2x:1.1.1.4.0.4 cjep_sun2x-base:1.1.1.4 cjep_staticlib_x-base1:1.1.1.4 netbsd-9-2-RELEASE:1.1.1.3 cjep_staticlib_x:1.1.1.4.0.2 cjep_staticlib_x-base:1.1.1.4 netbsd-9-1-RELEASE:1.1.1.3 phil-wifi-20200421:1.1.1.4 phil-wifi-20200411:1.1.1.4 phil-wifi-20200406:1.1.1.4 netbsd-8-2-RELEASE:1.1.1.3 netbsd-9-0-RELEASE:1.1.1.3 netbsd-9-0-RC2:1.1.1.3 netbsd-9-0-RC1:1.1.1.3 netbsd-9:1.1.1.3.0.16 netbsd-9-base:1.1.1.3 phil-wifi-20190609:1.1.1.3 netbsd-8-1-RELEASE:1.1.1.3 netbsd-8-1-RC1:1.1.1.3 pgoyette-compat-merge-20190127:1.1.1.3 pgoyette-compat-20190127:1.1.1.3 pgoyette-compat-20190118:1.1.1.3 pgoyette-compat-1226:1.1.1.3 pgoyette-compat-1126:1.1.1.3 pgoyette-compat-1020:1.1.1.3 pgoyette-compat-0930:1.1.1.3 pgoyette-compat-0906:1.1.1.3 netbsd-7-2-RELEASE:1.1.1.2 pgoyette-compat-0728:1.1.1.3 clang-337282:1.1.1.3 netbsd-8-0-RELEASE:1.1.1.3 phil-wifi:1.1.1.3.0.14 phil-wifi-base:1.1.1.3 pgoyette-compat-0625:1.1.1.3 netbsd-8-0-RC2:1.1.1.3 pgoyette-compat-0521:1.1.1.3 pgoyette-compat-0502:1.1.1.3 pgoyette-compat-0422:1.1.1.3 netbsd-8-0-RC1:1.1.1.3 pgoyette-compat-0415:1.1.1.3 pgoyette-compat-0407:1.1.1.3 pgoyette-compat-0330:1.1.1.3 pgoyette-compat-0322:1.1.1.3 pgoyette-compat-0315:1.1.1.3 netbsd-7-1-2-RELEASE:1.1.1.2 pgoyette-compat:1.1.1.3.0.12 pgoyette-compat-base:1.1.1.3 netbsd-7-1-1-RELEASE:1.1.1.2 clang-319952:1.1.1.3 matt-nb8-mediatek:1.1.1.3.0.10 matt-nb8-mediatek-base:1.1.1.3 clang-309604:1.1.1.3 perseant-stdc-iso10646:1.1.1.3.0.8 perseant-stdc-iso10646-base:1.1.1.3 netbsd-8:1.1.1.3.0.6 netbsd-8-base:1.1.1.3 prg-localcount2-base3:1.1.1.3 prg-localcount2-base2:1.1.1.3 prg-localcount2-base1:1.1.1.3 prg-localcount2:1.1.1.3.0.4 prg-localcount2-base:1.1.1.3 pgoyette-localcount-20170426:1.1.1.3 bouyer-socketcan-base1:1.1.1.3 pgoyette-localcount-20170320:1.1.1.3 netbsd-7-1:1.1.1.2.0.16 netbsd-7-1-RELEASE:1.1.1.2 netbsd-7-1-RC2:1.1.1.2 clang-294123:1.1.1.3 netbsd-7-nhusb-base-20170116:1.1.1.2 bouyer-socketcan:1.1.1.3.0.2 bouyer-socketcan-base:1.1.1.3 clang-291444:1.1.1.3 pgoyette-localcount-20170107:1.1.1.2 netbsd-7-1-RC1:1.1.1.2 pgoyette-localcount-20161104:1.1.1.2 netbsd-7-0-2-RELEASE:1.1.1.2 localcount-20160914:1.1.1.2 netbsd-7-nhusb:1.1.1.2.0.14 netbsd-7-nhusb-base:1.1.1.2 clang-280599:1.1.1.2 pgoyette-localcount-20160806:1.1.1.2 pgoyette-localcount-20160726:1.1.1.2 pgoyette-localcount:1.1.1.2.0.12 pgoyette-localcount-base:1.1.1.2 netbsd-7-0-1-RELEASE:1.1.1.2 clang-261930:1.1.1.2 netbsd-7-0:1.1.1.2.0.10 netbsd-7-0-RELEASE:1.1.1.2 netbsd-7-0-RC3:1.1.1.2 netbsd-7-0-RC2:1.1.1.2 netbsd-7-0-RC1:1.1.1.2 clang-237755:1.1.1.2 clang-232565:1.1.1.2 clang-227398:1.1.1.2 tls-maxphys-base:1.1.1.2 tls-maxphys:1.1.1.2.0.8 netbsd-7:1.1.1.2.0.6 netbsd-7-base:1.1.1.2 clang-215315:1.1.1.2 clang-209886:1.1.1.2 yamt-pagecache:1.1.1.2.0.4 yamt-pagecache-base9:1.1.1.2 tls-earlyentropy:1.1.1.2.0.2 tls-earlyentropy-base:1.1.1.2 riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.1.1.2 riastradh-drm2-base3:1.1.1.2 clang-202566:1.1.1.2 clang-201163:1.1.1.2 clang-199312:1.1.1.1 clang-198450:1.1.1.1 clang-196603:1.1.1.1 clang-195771:1.1.1.1 LLVM:1.1.1; locks; strict; comment @# @; 1.1 date 2013.11.28.14.14.47; author joerg; state Exp; branches 1.1.1.1; next ; commitid ow8OybrawrB1f3fx; 1.1.1.1 date 2013.11.28.14.14.47; author joerg; state Exp; branches; next 1.1.1.2; commitid ow8OybrawrB1f3fx; 1.1.1.2 date 2014.02.14.20.07.00; author joerg; state Exp; branches 1.1.1.2.4.1 1.1.1.2.8.1 1.1.1.2.12.1; next 1.1.1.3; commitid annVkZ1sc17rF6px; 1.1.1.3 date 2017.01.11.10.40.45; author joerg; state Exp; branches 1.1.1.3.14.1; next 1.1.1.4; commitid CNnUNfII1jgNmxBz; 1.1.1.4 date 2019.11.13.22.19.10; author joerg; state dead; branches; next ; commitid QD8YATxuNG34YJKB; 1.1.1.2.4.1 date 2014.02.14.20.07.00; author yamt; state dead; branches; next 1.1.1.2.4.2; commitid WSrDtL5nYAUyiyBx; 1.1.1.2.4.2 date 2014.05.22.16.18.18; author yamt; state Exp; branches; next ; commitid WSrDtL5nYAUyiyBx; 1.1.1.2.8.1 date 2014.02.14.20.07.00; author tls; state dead; branches; next 1.1.1.2.8.2; commitid jTnpym9Qu0o4R1Nx; 1.1.1.2.8.2 date 2014.08.19.23.47.19; author tls; state Exp; branches; next ; commitid jTnpym9Qu0o4R1Nx; 1.1.1.2.12.1 date 2017.03.20.06.52.30; author pgoyette; state Exp; branches; next ; commitid jjw7cAwgyKq7RfKz; 1.1.1.3.14.1 date 2020.04.13.07.46.20; author martin; state dead; branches; next ; commitid X01YhRUPVUDaec4C; desc @@ 1.1 log @Initial revision @ text @============= 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 ` 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. .. code-block:: c++ bool ParseArgs(const CompilerInstance &CI, const std::vector& 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<>``: .. code-block:: c++ static FrontendPluginRegistry::Add 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 `_. .. code-block:: c++ #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(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& 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 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 :option:`-load` command line option. This will load all plugins that are registered, and you can select the plugins to run by specifying the :option:`-plugin` option. Additional parameters for the plugins can be passed with :option:`-plugin-arg-`. 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 :option:`-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 :option:`-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: .. code-block:: 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 `_ @ 1.1.1.1 log @Import Clang 3.4rc1 r195771. @ text @@ 1.1.1.2 log @Import Clang 3.5svn r201163. @ text @d50 2 a51 2 example is checked into the clang repository; please take a look at the `latest version of PrintFunctionNames.cpp d54 60 @ 1.1.1.2.12.1 log @Sync with HEAD @ text @a45 20 Defining pragmas ================ Plugins can also define pragmas by declaring a ``PragmaHandler`` and registering it using ``PragmaHandlerRegistry::Add<>``: .. code-block:: c++ // Define a pragma handler for #pragma example_pragma class ExamplePragmaHandler : public PragmaHandler { public: ExamplePragmaHandler() : PragmaHandler("example_pragma") { } void HandlePragma(Preprocessor &PP, PragmaIntroducerKind Introducer, Token &PragmaTok) { // Handle the pragma } }; static PragmaHandlerRegistry::Add Y("example_pragma","example pragma description"); a56 4 Using the cc1 command line -------------------------- d58 1 a58 1 loaded via the `-load` command line option. This will load all plugins d60 2 a61 2 `-plugin` option. Additional parameters for the plugins can be passed with `-plugin-arg-`. d66 1 a66 1 * Directly call the parsing process by using the `-cc1` option; this d71 1 a71 1 `-Xclang`. a90 16 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`): .. code-block:: c++ // Automatically run the plugin after the main AST action PluginASTAction::ActionType getActionType() override { return AddAfterMainAction; } @ 1.1.1.3 log @Import Clang pre-4.0.0 r291444. @ text @a45 20 Defining pragmas ================ Plugins can also define pragmas by declaring a ``PragmaHandler`` and registering it using ``PragmaHandlerRegistry::Add<>``: .. code-block:: c++ // Define a pragma handler for #pragma example_pragma class ExamplePragmaHandler : public PragmaHandler { public: ExamplePragmaHandler() : PragmaHandler("example_pragma") { } void HandlePragma(Preprocessor &PP, PragmaIntroducerKind Introducer, Token &PragmaTok) { // Handle the pragma } }; static PragmaHandlerRegistry::Add Y("example_pragma","example pragma description"); a56 4 Using the cc1 command line -------------------------- d58 1 a58 1 loaded via the `-load` command line option. This will load all plugins d60 2 a61 2 `-plugin` option. Additional parameters for the plugins can be passed with `-plugin-arg-`. d66 1 a66 1 * Directly call the parsing process by using the `-cc1` option; this d71 1 a71 1 `-Xclang`. a90 16 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`): .. code-block:: c++ // Automatically run the plugin after the main AST action PluginASTAction::ActionType getActionType() override { return AddAfterMainAction; } @ 1.1.1.3.14.1 log @Mostly merge changes from HEAD upto 20200411 @ text @@ 1.1.1.4 log @Mark old LLVM instance as dead. @ text @@ 1.1.1.2.8.1 log @file ClangPlugins.rst was added on branch tls-maxphys on 2014-08-19 23:47:19 +0000 @ text @d1 90 @ 1.1.1.2.8.2 log @Rebase to HEAD as of a few days ago. @ text @a0 90 ============= 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 ` 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. .. code-block:: c++ bool ParseArgs(const CompilerInstance &CI, const std::vector& 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<>``: .. code-block:: c++ static FrontendPluginRegistry::Add 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 checked into the clang repository; please take a look at the `latest version of PrintFunctionNames.cpp `_. Running the plugin ================== To run a plugin, the dynamic library containing the plugin registry must be loaded via the :option:`-load` command line option. This will load all plugins that are registered, and you can select the plugins to run by specifying the :option:`-plugin` option. Additional parameters for the plugins can be passed with :option:`-plugin-arg-`. 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 :option:`-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 :option:`-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: .. code-block:: 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 `_ @ 1.1.1.2.4.1 log @file ClangPlugins.rst was added on branch yamt-pagecache on 2014-05-22 16:18:18 +0000 @ text @d1 90 @ 1.1.1.2.4.2 log @sync with head. for a reference, the tree before this commit was tagged as yamt-pagecache-tag8. this commit was splitted into small chunks to avoid a limitation of cvs. ("Protocol error: too many arguments") @ text @a0 90 ============= 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 ` 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. .. code-block:: c++ bool ParseArgs(const CompilerInstance &CI, const std::vector& 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<>``: .. code-block:: c++ static FrontendPluginRegistry::Add 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 checked into the clang repository; please take a look at the `latest version of PrintFunctionNames.cpp `_. Running the plugin ================== To run a plugin, the dynamic library containing the plugin registry must be loaded via the :option:`-load` command line option. This will load all plugins that are registered, and you can select the plugins to run by specifying the :option:`-plugin` option. Additional parameters for the plugins can be passed with :option:`-plugin-arg-`. 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 :option:`-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 :option:`-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: .. code-block:: 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 `_ @