From 93ca0217a2aa3047c10518e991ab8578e90829e7 Mon Sep 17 00:00:00 2001 From: Sean Silva Date: Thu, 13 Dec 2012 01:10:46 +0000 Subject: docs: More reST conversion. Sorry for the large commit, but it is much faster to convert in batches. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@170067 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/HowToSetupToolingForLLVM.rst | 211 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 docs/HowToSetupToolingForLLVM.rst (limited to 'docs/HowToSetupToolingForLLVM.rst') diff --git a/docs/HowToSetupToolingForLLVM.rst b/docs/HowToSetupToolingForLLVM.rst new file mode 100644 index 0000000000..0c4cccafca --- /dev/null +++ b/docs/HowToSetupToolingForLLVM.rst @@ -0,0 +1,211 @@ +=================================== +How To Setup Clang Tooling For LLVM +=================================== + +Clang Tooling provides infrastructure to write tools that need syntactic +and semantic infomation about a program. This term also relates to a set +of specific tools using this infrastructure (e.g. ``clang-check``). This +document provides information on how to set up and use Clang Tooling for +the LLVM source code. + +Introduction +============ + +Clang Tooling needs a compilation database to figure out specific build +options for each file. Currently it can create a compilation database +from the ``compilation_commands.json`` file, generated by CMake. When +invoking clang tools, you can either specify a path to a build directory +using a command line parameter ``-p`` or let Clang Tooling find this +file in your source tree. In either case you need to configure your +build using CMake to use clang tools. + +Setup Clang Tooling Using CMake and Make +======================================== + +If you intend to use make to build LLVM, you should have CMake 2.8.6 or +later installed (can be found `here `_). + +First, you need to generate Makefiles for LLVM with CMake. You need to +make a build directory and run CMake from it: + +:: + + mkdir your/build/directory + cd your/build/directory + cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources + +If you want to use clang instead of GCC, you can add +``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``. +You can also use ccmake, which provides a curses interface to configure +CMake variables for lazy people. + +As a result, the new ``compile_commands.json`` file should appear in the +current directory. You should link it to the LLVM source tree so that +Clang Tooling is able to use it: + +:: + + ln -s $PWD/compile_commands.json path/to/llvm/source/ + +Now you are ready to build and test LLVM using make: + +:: + + make check-all + +Using Clang Tools +================= + +After you completed the previous steps, you are ready to run clang +tools. If you have a recent clang installed, you should have +``clang-check`` in $PATH. Try to run it on any .cpp file inside the LLVM +source tree: + +:: + + clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp + +If you're using vim, it's convenient to have clang-check integrated. Put +this into your .vimrc: + +:: + + function! ClangCheckImpl(cmd) + if &autowrite | wall | endif + echo "Running " . a:cmd . " ..." + let l:output = system(a:cmd) + cexpr l:output + cwindow + let w:quickfix_title = a:cmd + if v:shell_error != 0 + cc + endif + let g:clang_check_last_cmd = a:cmd + endfunction + + function! ClangCheck() + let l:filename = expand('%') + if l:filename =~ '\.\(cpp\|cxx\|cc\|c\)$' + call ClangCheckImpl("clang-check " . l:filename) + elseif exists("g:clang_check_last_cmd") + call ClangCheckImpl(g:clang_check_last_cmd) + else + echo "Can't detect file's compilation arguments and no previous clang-check invocation!" + endif + endfunction + + nmap :call ClangCheck() + +When editing a .cpp/.cxx/.cc/.c file, hit F5 to reparse the file. In +case the current file has a different extension (for example, .h), F5 +will re-run the last clang-check invocation made from this vim instance +(if any). The output will go into the error window, which is opened +automatically when clang-check finds errors, and can be re-opened with +``:cope``. + +Other ``clang-check`` options that can be useful when working with clang +AST: + +- ``-ast-print`` - Build ASTs and then pretty-print them. +- ``-ast-dump`` - Build ASTs and then debug dump them. +- ``-ast-dump-filter=`` - Use with ``-ast-dump`` or + ``-ast-print`` to dump/print only AST declaration nodes having a + certain substring in a qualified name. Use ``-ast-list`` to list all + filterable declaration node names. +- ``-ast-list`` - Build ASTs and print the list of declaration node + qualified names. + +Examples: + +:: + + $ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-dump -ast-dump-filter ActionFactory::newASTConsumer + Processing: tools/clang/tools/clang-check/ClangCheck.cpp. + Dumping ::ActionFactory::newASTConsumer: + clang::ASTConsumer *newASTConsumer() (CompoundStmt 0x44da290 + (IfStmt 0x44d97c8 + <<>> + (ImplicitCastExpr 0x44d96d0 '_Bool':'_Bool' + ... + $ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-print -ast-dump-filter ActionFactory::newASTConsumer + Processing: tools/clang/tools/clang-check/ClangCheck.cpp. + Printing ::ActionFactory::newASTConsumer: + clang::ASTConsumer *newASTConsumer() { + if (this->ASTList.operator _Bool()) + return clang::CreateASTDeclNodeLister(); + if (this->ASTDump.operator _Bool()) + return clang::CreateASTDumper(this->ASTDumpFilter); + if (this->ASTPrint.operator _Bool()) + return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter); + return new clang::ASTConsumer(); + } + +(Experimental) Using Ninja Build System +======================================= + +Optionally you can use the `Ninja `_ +build system instead of make. It is aimed at making your builds faster. +Currently this step will require building Ninja from sources and using a +development version of CMake. + +To take advantage of using Clang Tools along with Ninja build you need +at least CMake 2.8.9. At the moment CMake 2.8.9 is still under +development, so you can get latest development sources and build it +yourself: + +:: + + git clone git://cmake.org/cmake.git + cd cmake + ./bootstrap + make + sudo make install + +Having the correct version of CMake, you can clone the Ninja git +repository and build Ninja from sources: + +:: + + git clone git://github.com/martine/ninja.git + cd ninja/ + ./bootstrap.py + +This will result in a single binary ``ninja`` in the current directory. +It doesn't require installation and can just be copied to any location +inside ``$PATH``, say ``/usr/local/bin/``: + +:: + + sudo cp ninja /usr/local/bin/ + sudo chmod a+rx /usr/local/bin/ninja + +After doing all of this, you'll need to generate Ninja build files for +LLVM with CMake. You need to make a build directory and run CMake from +it: + +:: + + mkdir your/build/directory + cd your/build/directory + cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources + +If you want to use clang instead of GCC, you can add +``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``. +You can also use ccmake, which provides a curses interface to configure +CMake variables in an interactive manner. + +As a result, the new ``compile_commands.json`` file should appear in the +current directory. You should link it to the LLVM source tree so that +Clang Tooling is able to use it: + +:: + + ln -s $PWD/compile_commands.json path/to/llvm/source/ + +Now you are ready to build and test LLVM using Ninja: + +:: + + ninja check-all + +Other target names can be used in the same way as with make. -- cgit v1.2.3