[cfe-commits] r160047 - /cfe/trunk/docs/HowToSetupToolingForLLVM.html

Wed Jul 11 07:27:44 PDT 2012

Author: alexfh
Date: Wed Jul 11 09:27:44 2012
New Revision: 160047

URL: http://llvm.org/viewvc/llvm-project?rev=160047&view=rev
Log:
How to set up clang tools for llvm

Summary: How to guide for setting up clang tooling for llvm repo.

Test Plan: this is untested

Reviewers: klimek, djasper

Reviewed By: klimek

Differential Revision: http://llvm-reviews.chandlerc.com/D3

Added:
    cfe/trunk/docs/HowToSetupToolingForLLVM.html

Added: cfe/trunk/docs/HowToSetupToolingForLLVM.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/HowToSetupToolingForLLVM.html?rev=160047&view=auto
==============================================================================

--- cfe/trunk/docs/HowToSetupToolingForLLVM.html (added)
+++ cfe/trunk/docs/HowToSetupToolingForLLVM.html Wed Jul 11 09:27:44 2012
@@ -0,0 +1,150 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+          "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>How To Setup Clang Tooling For LLVM</title>
+<link type="text/css" rel="stylesheet" href="../menu.css">
+<link type="text/css" rel="stylesheet" href="../content.css">
+</head>
+<body>
+
+<!--#include virtual="../menu.html.incl"-->
+
+<div id="content">
+
+<h1>How To Setup Clang Tooling For LLVM</h1>
+<p>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. <code>clang-check</code>). This document
+provides information on how to set up and use Clang Tooling for the LLVM source
+code.</p>
+
+
+<!-- ======================================================================= -->
+<h2><a name="introduction">Introduction</a></h2>
+<!-- ======================================================================= -->
+
+<p>Clang Tooling needs a compilation database to figure out specific build
+options for each file. Currently it can create a compilation database from the
+<code>compilation_commands.json</code> file, generated by CMake. When invoking
+clang tools, you can either specify a path to a build directory using a command
+line parameter <code>-p</code> 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.</p>
+
+<!-- ======================================================================= -->
+<h2><a name="using-make">Setup Clang Tooling Using CMake and Make</a></h2>
+<!-- ======================================================================= -->
+
+<p>If you intend to use make to build LLVM, you should have CMake 2.8.6 or later
+installed (can be found <a href="http://cmake.org">here</a>).</p>
+<p>First, you need to generate Makefiles for LLVM with CMake. You need to make
+a build directory and run CMake from it:</p>
+<pre>
+  mkdir your/build/directory
+  cd your/build/directory
+  cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources
+</pre>
+
+<p>If you want to use clang instead of GCC, you can add
+<code>-DCMAKE_C_COMPILER=/path/to/clang
+  -DCMAKE_CXX_COMPILER=/path/to/clang++</code>.
+You can also use ccmake, which provides a curses interface to configure CMake
+variables for lazy people.</p>
+
+<p>As a result, the new <code>compile_commands.json</code> 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:</p>
+<pre>
+  ln -s $PWD/compile_commands.json path/to/llvm/source/
+</pre>
+
+<p>Now you are ready to build and test LLVM using make:</p>
+<pre>
+  make check-all
+</pre>
+
+<!-- ======================================================================= -->
+<h2><a name="using-tools">Using Clang Tools</a></h2>
+<!-- ======================================================================= -->
+
+<p>After you completed the previous steps, you are ready to run clang tools. If
+you have a recent clang installed, you should have <code>clang-check</code> in
+$PATH. Try to run it on any .cpp file inside the LLVM source tree:</p>
+<pre>
+  clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp
+</pre>
+<p>If you're using vim, it's convenient to have clang-check integrated. Put this
+into your .vimrc:</p>
+<pre>
+  set makeprg=clang-check\ %
+  map <F5> :make<CR><CR>
+</pre>
+
+<p>When editing C++ code, hit F5 to reparse the current buffer. The output will
+go into the error window, which you can enable with <code>:cope</code>.</p>
+
+
+<!-- ======================================================================= -->
+<h2><a name="using-ninja">(Experimental) Using Ninja Build System</a></h2>
+<!-- ======================================================================= -->
+
+<p>Optionally you can use the <a
+  href="https://github.com/martine/ninja">Ninja</a> 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.</p>
+<p>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:</p>
+<pre>
+  git clone git://cmake.org/cmake.git
+  cd cmake
+  ./bootstrap
+  make
+  sudo make install
+</pre>
+
+<p>Having the correct version of CMake, you can clone the Ninja git repository
+and build Ninja from sources:</p>
+<pre>
+  git clone git://github.com/martine/ninja.git
+  cd ninja/
+  ./bootstrap.py
+</pre>
+<p>This will result in a single binary <code>ninja</code> in the current
+directory. It doesn't require installation and can just be copied to any
+location inside <code>$PATH</code>, say <code>/usr/local/bin/</code>:</p>
+<pre>
+  sudo cp ninja /usr/local/bin/
+  sudo chmod a+rx /usr/local/bin/ninja
+</pre>
+<p>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:</p>
+<pre>
+  mkdir your/build/directory
+  cd your/build/directory
+  cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources
+</pre>
+
+<p>If you want to use clang instead of GCC, you can add
+<code>-DCMAKE_C_COMPILER=/path/to/clang
+  -DCMAKE_CXX_COMPILER=/path/to/clang++</code>.
+You can also use ccmake, which provides a curses interface to configure CMake
+variables in an interactive manner.</p>
+
+<p>As a result, the new <code>compile_commands.json</code> 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:</p>
+<pre>
+  ln -s $PWD/compile_commands.json path/to/llvm/source/
+</pre>
+
+<p>Now you are ready to build and test LLVM using Ninja:</p>
+<pre>
+  ninja check-all
+</pre>
+<p>Other target names can be used in the same way as with make.</p>
+</div>
+</body>
+</html>
+



