www/hacking.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2           "http://www.w3.org/TR/html4/strict.dtd">
   3 <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
   4 <html>
   5 <head>
   6   <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
   7   <title>Hacking on clang</title>
   8   <link type="text/css" rel="stylesheet" href="menu.css" />
   9   <link type="text/css" rel="stylesheet" href="content.css" />
  10 </head>
  11 <body>
  12 <!--#include virtual="menu.html.incl"-->
  13 <div id="content">
  14   <!--*********************************************************************-->
  15   <h1>Hacking on Clang</h1>
  16   <!--*********************************************************************-->
  17
  18   <p>This document provides some hints for how to get started hacking
  19   on Clang for developers who are new to the Clang and/or LLVM
  20   codebases.</p>
  21     <ul>
  22       <li><a href="#style">Coding Standards</a></li>
  23       <li><a href="#docs">Developer Documentation</a></li>
  24       <li><a href="#debugging">Debugging</a></li>
  25       <li><a href="#testing">Testing</a></li>
  26       <ul>
  27         <li><a href="#testingNonWindows">Testing on Unix-like Systems</a></li>
  28         <li><a href="#testingWindows">Testing using Visual Studio on Windows</a></li>
  29         <li><a href="#testingCommands">Testing on the Command Line</a></li>
  30       </ul>
  31       <li><a href="#patches">Creating Patch Files</a></li>
  32       <li><a href="#irgen">LLVM IR Generation</a></li>
  33     </ul>
  34
  35   <!--=====================================================================-->
  36   <h2 id="docs">Coding Standards</h2>
  37   <!--=====================================================================-->
  38
  39   <p>Clang follows the
  40   LLVM <a href="http://llvm.org/docs/CodingStandards.html">Coding
  41   Standards</a>. When submitting patches, please take care to follow these standards
  42   and to match the style of the code to that present in Clang (for example, in
  43   terms of indentation, bracing, and statement spacing).</p>
  44
  45   <p>Clang has a few additional coding standards:</p>
  46   <ul>
  47     <li><i>cstdio is forbidden</i>: library code should not output diagnostics
  48       or other information using <tt>cstdio</tt>; debugging routines should
  49       use <tt>llvm::errs()</tt>. Other uses of <tt>cstdio</tt> impose behavior
  50       upon clients and block integrating Clang as a library. Libraries should
  51       support <tt>raw_ostream</tt> based interfaces for textual
  52       output. See <a href="http://llvm.org/docs/CodingStandards.html#ll_raw_ostream">Coding
  53       Standards</a>.</li>
  54   </ul>
  55
  56   <!--=====================================================================-->
  57   <h2 id="docs">Developer Documentation</h2>
  58   <!--=====================================================================-->
  59
  60   <p>Both Clang and LLVM use doxygen to provide API documentation. Their
  61   respective web pages (generated nightly) are here:</p>
  62     <ul>
  63       <li><a href="http://clang.llvm.org/doxygen">Clang</a></li>
  64       <li><a href="http://llvm.org/doxygen">LLVM</a></li>
  65     </ul>
  66
  67   <p>For work on the LLVM IR generation, the LLVM assembly language
  68   <a href="http://llvm.org/docs/LangRef.html">reference manual</a> is
  69   also useful.</p>
  70
  71   <!--=====================================================================-->
  72   <h2 id="debugging">Debugging</h2>
  73   <!--=====================================================================-->
  74
  75   <p>Inspecting data structures in a debugger:</p>
  76     <ul>
  77       <li>Many LLVM and Clang data structures provide
  78         a <tt>dump()</tt> method which will print a description of the
  79         data structure to <tt>stderr</tt>.</li>
  80       <li>The <a href="docs/InternalsManual.html#QualType"><tt>QualType</tt></a>
  81       structure is used pervasively. This is a simple value class for
  82       wrapping types with qualifiers; you can use
  83       the <tt>isConstQualified()</tt>, for example, to get one of the
  84       qualifiers, and the <tt>getTypePtr()</tt> method to get the
  85       wrapped <tt>Type*</tt> which you can then dump.</li>
  86     </ul>
  87
  88   <!--=====================================================================-->
  89   <h2 id="testing">Testing</h2>
  90   <!--=====================================================================-->
  91
  92   <p><i>[Note: The test running mechanism is currently under revision, so the
  93   following might change shortly.]</i></p>
  94
  95   <!--=====================================================================-->
  96   <h3 id="testingNonWindows">Testing on Unix-like Systems</h3>
  97   <!--=====================================================================-->
  98
  99   <p>Clang includes a basic regression suite in the tree which can be
 100   run with <tt>make test</tt> from the top-level clang directory, or
 101   just <tt>make</tt> in the <em>test</em> sub-directory.
 102   <tt>make VERBOSE=1</tt> can be used to show more detail
 103   about what is being run.</p>
 104
 105   <p>If you built LLVM and Clang using CMake, the test suite can be run
 106   with <tt>make clang-test</tt> from the top-level LLVM directory.</p>
 107
 108   <p>The tests primarily consist of a test runner script running the compiler
 109   under test on individual test files grouped in the directories under the
 110   test directory.  The individual test files include comments at the
 111   beginning indicating the Clang compile options to use, to be read
 112   by the test runner. Embedded comments also can do things like telling
 113   the test runner that an error is expected at the current line.
 114   Any output files produced by the test will be placed under
 115   a created Output directory.</p>
 116
 117   <p>During the run of <tt>make test</tt>, the terminal output will
 118   display a line similar to the following:</p>
 119
 120   <ul><tt>--- Running clang tests for i686-pc-linux-gnu ---</tt></ul>
 121
 122   <p>followed by a line continually overwritten with the current test
 123   file being compiled, and an overall completion percentage.</p>
 124
 125   <p>After the <tt>make test</tt> run completes, the absence of any
 126   <tt>Failing Tests (count):</tt> message indicates that no tests
 127   failed unexpectedly.  If any tests did fail, the
 128   <tt>Failing Tests (count):</tt> message will be followed by a list
 129   of the test source file paths that failed.  For example:</p>
 130
 131   <tt><pre>
 132   Failing Tests (3):
 133       /home/john/llvm/tools/clang/test/SemaCXX/member-name-lookup.cpp
 134       /home/john/llvm/tools/clang/test/SemaCXX/namespace-alias.cpp
 135       /home/john/llvm/tools/clang/test/SemaCXX/using-directive.cpp
 136   </pre></tt>
 137
 138   <p>If you used the <tt>make VERBOSE=1</tt> option, the terminal
 139   output will reflect the error messages from the compiler and
 140   test runner.</p>
 141
 142   <p>The regression suite can also be run with Valgrind by running
 143   <tt>make test VG=1</tt> in the top-level clang directory.</p>
 144
 145   <p>For more intensive changes, running
 146   the <a href="http://llvm.org/docs/TestingGuide.html#testsuiterun">LLVM
 147   Test Suite</a> with clang is recommended. Currently the best way to
 148   override LLVMGCC, as in: <tt>make LLVMGCC="clang -std=gnu89"
 149   TEST=nightly report</tt> (make sure <tt>clang</tt> is in your PATH or use the
 150   full path).</p>
 151
 152   <!--=====================================================================-->
 153   <h3 id="testingWindows">Testing using Visual Studio on Windows</h3>
 154   <!--=====================================================================-->
 155
 156   <p>The Clang test suite can be run from either Visual Studio or
 157   the command line.</p>
 158
 159   <p>Note that the test runner is based on
 160   Python, which must be installed.  Find Python at:
 161   <a href="http://www.python.org/download/">http://www.python.org/download/</a>.
 162   Download the latest stable version (2.6.2 at the time of this writing).</p>
 163
 164   <p>The GnuWin32 tools are also necessary for running the tests.
 165   Get them from <a href="http://getgnuwin32.sourceforge.net/">
 166   http://getgnuwin32.sourceforge.net/</a>.
 167   If the environment variable <tt>%PATH%</tt> does not have GnuWin32,
 168   or if other grep(s) supercedes GnuWin32 on <tt>%PATH%,</tt>
 169   you should specify <tt>LLVM_LIT_TOOLS_DIR</tt>
 170   to CMake explicitly.</p>
 171
 172   <p>The cmake build tool is set up to create Visual Studio project files
 173   for running the tests, "clang-test" being the root.  Therefore, to
 174   run the test from Visual Studio, right-click the clang-test project
 175   and select "Build".</p>
 176
 177   <p>
 178     Please see also
 179     <a href="http://llvm.org/docs/GettingStartedVS.html">Getting Started
 180     with the LLVM System using Microsoft Visual Studio</a> and
 181     <a href="http://llvm.org/docs/CMake.html">Building LLVM with CMake</a>.
 182   </p>
 183
 184   <!--=====================================================================-->
 185   <h3 id="testingCommands">Testing on the Command Line</h3>
 186   <!--=====================================================================-->
 187
 188   <p>To run all the tests from the command line, execute a command like
 189   the following:</p>
 190
 191   <tt>
 192   python (path to llvm)/llvm/utils/lit/lit.py -sv --no-progress-bar
 193  (path to llvm)/llvm/tools/clang/test
 194   </tt>
 195
 196   <p>For CMake builds e.g. on Windows with Visual Studio, you will need
 197   to specify your build configuration (Debug, Release, etc.) via
 198   <tt>--param=build_config=(build config)</tt>.</p>
 199
 200   <p>To run a single test:</p>
 201
 202   <tt>
 203   python (path to llvm)/llvm/utils/lit/lit.py -sv --no-progress-bar
 204  (path to llvm)/llvm/tools/clang/test/(dir)/(test)
 205   </tt>
 206
 207   <p>For example:</p>
 208
 209   <tt>
 210   python C:/Tools/llvm/utils/lit/lit.py -sv --no-progress-bar
 211   C:/Tools/llvm/tools/clang/test/Sema/wchar.c
 212   </tt>
 213
 214   <p>The -sv option above tells the runner to show the test output if
 215   any tests failed, to help you determine the cause of failure.</p>
 216
 217   <p>Your output might look something like this:</p>
 218
 219 <tt><pre>lit.py: lit.cfg:152: note: using clang: 'C:/Tools/llvm/bin/Release\\clang.EXE'
 220 -- Testing: Testing: 2534 tests, 4 threads --
 221 Testing: 0 .. 10.. 20.. 30.. 40.. 50.. 60.. 70.. 80.. 90..
 222 Testing Time: 81.52s
 223   Expected Passes    : 2503
 224   Expected Failures  : 28
 225   Unsupported Tests  : 3
 226 </pre></tt>
 227
 228   <p>The statistic, "Unexpected Failures" (not shown if all tests pass), is the important one.</p>
 229
 230   <!--=====================================================================-->
 231   <h2 id="patches">Creating Patch Files</h2>
 232   <!--=====================================================================-->
 233
 234   <p>To return changes to the Clang team, unless you have checkin
 235   privileges, the preferred way is to send patch files to the
 236   cfe-commits mailing list, with an explanation of what the patch is for.
 237   Or, if you have questions, or want to have a wider discussion of what
 238   you are doing, such as if you are new to Clang development, you can use
 239   the cfe-dev mailing list also.
 240   </p>
 241
 242   <p>To create these patch files, change directory
 243   to the llvm/tools/clang root and run:</p>
 244
 245   <ul><tt>svn diff (relative path) >(patch file name)</tt></ul>
 246
 247   <p>For example, for getting the diffs of all of clang:</p>
 248
 249   <ul><tt>svn diff . >~/mypatchfile.patch</tt></ul>
 250
 251   <p>For example, for getting the diffs of a single file:</p>
 252
 253   <ul><tt>svn diff lib/Parse/ParseDeclCXX.cpp >~/ParseDeclCXX.patch</tt></ul>
 254
 255   <p>Note that the paths embedded in the patch depend on where you run it,
 256   so changing directory to the llvm/tools/clang directory is recommended.</p>
 257
 258   <!--=====================================================================-->
 259   <h2 id="irgen">LLVM IR Generation</h2>
 260   <!--=====================================================================-->
 261
 262   <p>The LLVM IR generation part of clang handles conversion of the
 263     AST nodes output by the Sema module to the LLVM Intermediate
 264     Representation (IR). Historically, this was referred to as
 265     "codegen", and the Clang code for this lives
 266     in <tt>lib/CodeGen</tt>.</p>
 267
 268   <p>The output is most easily inspected using the <tt>-emit-llvm</tt>
 269     option to clang (possibly in conjunction with <tt>-o -</tt>). You
 270     can also use <tt>-emit-llvm-bc</tt> to write an LLVM bitcode file
 271     which can be processed by the suite of LLVM tools
 272     like <tt>llvm-dis</tt>, <tt>llvm-nm</tt>, etc. See the LLVM
 273     <a href="http://llvm.org/docs/CommandGuide/">Command Guide</a>
 274     for more information.</p>
 275
 276 </div>
 277 </body>
 278 </html>