Lines Matching +full:clang +full:- +full:tools +full:- +full:extra
2 Tutorial for building tools using LibTooling and LibASTMatchers
5 This document is intended to show how to build a useful source-to-source
6 translation tool based on Clang's `LibTooling <LibTooling.html>`_. It is
7 explicitly aimed at people who are new to Clang, so all you should need
12 skim the :doc:`Introduction to the Clang
15 Step 0: Obtaining Clang
18 As Clang is part of the LLVM project, you'll need to download LLVM's
19 source code first. Both Clang and LLVM are maintained as Subversion
24 .. code-block:: console
26 mkdir ~/clang-llvm && cd ~/clang-llvm
28 cd llvm/tools
29 git clone http://llvm.org/git/clang.git
30 cd clang/tools
31 git clone http://llvm.org/git/clang-tools-extra.git extra
37 .. code-block:: console
39 cd ~/clang-llvm
46 cd ~/clang-llvm
54 Okay. Now we'll build Clang!
56 .. code-block:: console
58 cd ~/clang-llvm
60 cmake -G Ninja ../llvm -DLLVM_BUILD_TESTS=ON # Enable tests; default is off.
63 ninja clang-test # Test Clang only.
69 you can catch LLVM and Clang out of sync. Running ``'git svn rebase'``
70 in both the llvm and clang directories should fix any problems.
72 Finally, we want to set Clang as its own compiler.
74 .. code-block:: console
76 cd ~/clang-llvm/build
79 The second command will bring up a GUI for configuring Clang. You need
82 ``/usr/bin/clang++``, or wherever you installed it. Press ``'c'`` to
92 already exists as ``clang-check``, it's important to understand what's
96 that it exists. As this is not going to be a core clang tool, it will
97 live in the ``tools/extra`` repository.
99 .. code-block:: console
101 cd ~/clang-llvm/llvm/tools/clang
102 mkdir tools/extra/loop-convert
103 echo 'add_subdirectory(loop-convert)' >> tools/extra/CMakeLists.txt
104 vim tools/extra/loop-convert/CMakeLists.txt
112 add_clang_executable(loop-convert
115 target_link_libraries(loop-convert
123 ``tools/extra/loop-convert/LoopConvert.cpp``. A detailed explanation of
127 .. code-block:: c++
129 // Declares clang::SyntaxOnlyAction.
130 #include "clang/Frontend/FrontendActions.h"
131 #include "clang/Tooling/CommonOptionsParser.h"
132 #include "clang/Tooling/Tooling.h"
136 using namespace clang::tooling;
139 // Apply a custom category to all command-line options so that they are the
141 static llvm::cl::OptionCategory MyToolCategory("my-tool options");
144 // command-line options related to the compilation database and input files.
145 // It's nice to have this help message in all tools.
155 return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get());
161 .. code-block:: console
163 cd ~/clang-llvm/build
167 ``~/clang-llvm/build/bin``, on any source file. Try it!
169 .. code-block:: console
172 bin/loop-convert test.cpp --
176 them from a compilation database - there just aren't any options needed
182 Clang recently introduced the :doc:`ASTMatcher
194 .. code-block:: c++
215 .. code-block:: c++
226 .. code-block:: c++
233 .. code-block:: c++
240 .. code-block:: c++
255 .. code-block:: c++
268 .. code-block:: c++
270 #include "clang/ASTMatchers/ASTMatchers.h"
271 #include "clang/ASTMatchers/ASTMatchFinder.h"
273 using namespace clang;
274 using namespace clang::ast_matchers;
283 if (const ForStmt *FS = Result.Nodes.getNodeAs<clang::ForStmt>("forLoop"))
284 FS->dump();
290 .. code-block:: c++
308 .. code-block:: console
310 cd ~/clang-llvm/llvm/llvm_build/
311 ninja loop-convert
312 vim ~/test-files/simple-loops.cc
313 bin/loop-convert ~/test-files/simple-loops.cc
324 for translation to range-based syntax? Range based loops over arrays of
327 - start at index ``0``
328 - iterate consecutively
329 - end at index ``N-1``
335 require a pre- or post-increment of the same variable declared in the
341 would like to allow, and punting extra comparisons to the callback.
343 In any case, we can start building this sub-matcher. We can require that
346 .. code-block:: c++
350 Specifying what is incremented introduces another quirk of Clang's AST:
356 .. code-block:: c++
365 .. code-block:: c++
374 .. code-block:: c++
388 only one problem - we don't know which array we're iterating over
393 .. code-block:: c++
397 It makes sense to ensure that the left-hand side is a reference to a
398 variable, and that the right-hand side has integer type.
400 .. code-block:: c++
408 ``test-files/simple.cpp``, zero of them have a matching condition. A
410 previous iteration of loop-convert, shows us the answer:
430 applied to the first operand (i.e. the LHS) of the less-than operator,
431 an L-value to R-value conversion applied to the expression referencing
437 .. code-block:: c++
446 extracting the identifier strings into variables, we have array-step-2
459 its ``Context`` and ``Nodes`` members. Clang uses the ``ASTContext``
471 .. code-block:: c++
473 #include "clang/AST/ASTContext.h"
477 .. code-block:: c++
495 .. code-block:: c++
501 if (!FS || !Context->getSourceManager().isFromMainFile(FS->getForLoc()))
509 llvm::outs() << "Potential array-based loop discovered.\n";
512 Clang associates a ``VarDecl`` with each variable to represent the variable's
517 .. code-block:: c++
521 First->getCanonicalDecl() == Second->getCanonicalDecl();
527 .. code-block:: c++
536 though Clang has already done the hard work for us by providing a way to
539 .. code-block:: c++
546 First->Profile(FirstID, *Context, true);
547 Second->Profile(SecondID, *Context, true);
558 test-files/simple.cpp, try to figure out which ones will be considered