Text of clang.llvm.org › docs › LibASTMatchersTutorial.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Tutorial for building tools using LibTooling and LibASTMatchers - Clang

Hide navigation sidebar Hide table of contents sidebar Back to top Edit this page Toggle table of contents sidebar Tutorial for building tools using LibTooling and LibASTMatchers # This document is intended to show how to build a useful source-to-source translation tool based on Clang’s LibTooling . It is explicitly aimed at people who are new to Clang, so all you should need is a working knowledge of C++ and the command line.

In order to work on the compiler, you need some basic knowledge of the abstract syntax tree (AST). To this end, the reader is encouraged to skim the Introduction to the Clang AST Step 0: Obtaining Clang # As Clang is part of the LLVM project, you’ll need to download LLVM’s source code first. Both Clang and LLVM are in the same git repository, under different directories. For further information, see the getting started guide . mkdir ~/clang-llvm && cd ~/clang-llvm git clone https://github.com/llvm/llvm-project.git Next you need to obtain the CMake build system and Ninja build tool. cd ~/clang-llvm git clone https://github.com/martine/ninja.git cd ninja git checkout release ./configure.py --bootstrap sudo cp ninja /usr/bin/ cd ~/clang-llvm git clone https://gitlab.kitware.com/cmake/cmake.git cd cmake git checkout next ./bootstrap make sudo make install Okay.

Now we’ll build Clang! cd ~/clang-llvm mkdir build && cd build cmake -G Ninja ../llvm-project/llvm -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_TESTS=ON ninja ninja check # Test LLVM only. ninja clang-test # Test Clang only. ninja install And we’re live. All of the tests should pass. Finally, we want to set Clang as its own compiler. cd ~/clang-llvm/build ccmake ../llvm-project/llvm The second command will bring up a GUI for configuring Clang.

You need to set the entry for CMAKE_CXX_COMPILER . Press 't' to turn on advanced mode. Scroll down to CMAKE_CXX_COMPILER , and set it to /usr/bin/clang++ , or wherever you installed it. Press 'c' to configure, then 'g' to generate CMake’s files. Finally, run ninja one last time, and you’re done. Step 1: Create a ClangTool # Now that we have enough background knowledge, it’s time to create the simplest productive ClangTool in existence: a syntax checker.

While this already exists as clang-check , it’s important to understand what’s going on. First, we’ll need to create a new directory for our tool and tell CMake that it exists. As this is not going to be a core clang tool, it will live in the clang-tools-extra repository. cd ~/clang-llvm/llvm-project mkdir clang-tools-extra/loop-convert echo 'add_subdirectory(loop-convert)' >> clang-tools-extra/CMakeLists.txt vim clang-tools-extra/loop-convert/CMakeLists.txt CMakeLists.txt should have the following contents: set ( LLVM_LINK_COMPONENTS support ) add_clang_executable ( loop - convert LoopConvert . cpp ) target_link_libraries ( loop - convert PRIVATE clangAST clangASTMatchers clangBasic clangFrontend clangSerialization clangTooling ) With that done, Ninja will be able to compile our tool.

Let’s give it something to compile! Put the following into clang-tools-extra/loop-convert/LoopConvert.cpp . A detailed explanation of why the different parts are needed can be found in the LibTooling documentation . // Declares clang::SyntaxOnlyAction. #include "clang/Frontend/FrontendActions.h" #include "clang/Tooling/CommonOptionsParser.h" #include "clang/Tooling/Tooling.h" // Declares llvm::cl::extrahelp. #include "llvm/Support/CommandLine.h" using namespace clang :: tooling ; using namespace llvm ; // Apply a custom category to all command-line options so that they are the // only ones displayed. static llvm :: cl :: OptionCategory MyToolCategory ( "my-tool options" ); // CommonOptionsParser declares HelpMessage with a description of the common // command-line options related to the compilation database and input files. // It's nice to have this help message in all tools. static cl :: extrahelp CommonHelp ( CommonOptionsParser :: HelpMessage ); // A help message for this specific tool can be added afterwards. static cl :: extrahelp MoreHelp ( " \n More help text... \n " ); int main ( int argc , const char ** argv ) { auto ExpectedParser = CommonOptionsParser :: create ( argc , argv , MyToolCategory ); if ( !

ExpectedParser ) { // Fail gracefully for unsupported options. llvm :: errs () << ExpectedParser . takeError (); return 1 ; } CommonOptionsParser & OptionsParser = ExpectedParser . get (); ClangTool Tool ( OptionsParser . getCompilations (), OptionsParser . getSourcePathList ()); return Tool . run ( newFrontendActionFactory < clang :: SyntaxOnlyAction > (). get ()); } And that’s it! You can compile our new tool by running ninja from the build directory. cd ~/clang-llvm/build ninja You should now be able to run the syntax checker, which is located in ~/clang-llvm/build/bin , on any source file.

Try it! echo "int main() { return 0; }" > test.cpp bin/loop-convert test.cpp -- Note the two dashes after we specify the source file. The additional options for the compiler are passed after the dashes rather than loading them from a compilation database - there just aren’t any options needed right now. Intermezzo: Learn AST matcher basics # Clang recently introduced the ASTMatcher library to provide a simple, powerful, and concise way to describe specific patterns in the AST.

Implemented as a DSL powered by macros and templates (see ASTMatchers.h if you’re curious), matchers offer the feel of algebraic data types common to functional programming languages. For example, suppose you wanted to examine only binary operators. There is a matcher to do exactly that, conveniently named binaryOperator . I’ll give you one guess what this matcher does: binaryOperator ( hasOperatorName ( "+" ), hasLHS ( integerLiteral ( equals ( 0 )))) Shockingly, it will match against addition expressions whose left hand side is exactly the literal 0.

It will not match against other forms of 0, such as '\0' or NULL , but it will match against macros that expand to 0. The matcher will also not match against calls to the overloaded operator '+' , as there is a separate operatorCallExpr matcher to handle overloaded operators. There are AST matchers to match all the different nodes of the AST, narrowing matchers to only match AST nodes fulfilling specific criteria, and traversal matchers to get from one kind of AST node to another.

For a complete list of AST matchers, take a look at the AST Matcher References All matchers that are nouns describe entities in the AST and can be bound, so that they can be referred to whenever a match is found. To do so, simply call the method bind on these matchers, e.g.: variable ( hasType ( isInteger ())). bind ( "intvar" ) Step 2: Using AST matchers # Okay, on to using matchers for real. Let’s start by defining a matcher which will capture all for statements that define a new variable initialized to zero.

Let’s start with matching all for loops: forStmt () Next, we want to specify that a single variable is declared in the first portion of the loop, so we can extend the matcher to forStmt ( hasLoopInit ( declStmt ( hasSingleDecl ( varDecl ())))) Finally, we can add the condition that the variable is initialized to zero. forStmt ( hasLoopInit ( declStmt ( hasSingleDecl ( varDecl ( hasInitializer ( integerLiteral ( equals ( 0 )))))))) It is fairly easy to read and understand the matcher definition (“match loops whose init portion declares a single variable which is initialized to the integer literal 0”), but deciding that every piece is necessary is more difficult.

Note that this matcher will not match loops whose variables are initialized to '\0' , 0.0 , NULL , or any form of zero besides the integer 0. The last step is giving the matcher a name and binding the ForStmt as we will want to do something with it: StatementMatcher LoopMatcher = forStmt ( hasLoopInit ( declStmt ( hasSingleDecl ( varDecl ( hasInitializer ( intege

The rest of this page is on the live site.