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   (Note that the grep from MSYS or Cygwin doesn't work with the tests
 166   because of embedded double-quotes in the search strings.  The GNU
 167   grep does work in this case.)
 168   Get them from <a href="http://getgnuwin32.sourceforge.net">
 169   http://getgnuwin32.sourceforge.net</a>.</p>
 170
 171   <p>The cmake build tool is set up to create Visual Studio project files
 172   for running the tests, "clang-test" being the root.  Therefore, to
 173   run the test from Visual Studio, right-click the clang-test project
 174   and select "Build".</p>
 175
 176   <!--=====================================================================-->
 177   <h3 id="testingCommands">Testing on the Command Line</h3>
 178   <!--=====================================================================-->
 179
 180   <p>To run all the tests from the command line, execute a command like
 181   the following:</p>
 182
 183   <tt>
 184   python (path to llvm)/llvm/utils/lit/lit.py -sv --no-progress-bar
 185  (path to llvm)/llvm/tools/clang/test
 186   </tt>
 187
 188   <p>To run a single test:</p>
 189
 190   <tt>
 191   python (path to llvm)/llvm/utils/lit/lit.py -sv --no-progress-bar
 192  (path to llvm)/llvm/tools/clang/test/(dir)/(test)
 193   </tt>
 194
 195   <p>For example:</p>
 196
 197   <tt>
 198   python C:/Tools/llvm/utils/lit/lit.py -sv --no-progress-bar
 199   C:/Tools/llvm/tools/clang/test/Sema/wchar.c
 200   </tt>
 201
 202   <p>The -sv option above tells the runner to show the test output if
 203   any tests failed, to help you determine the cause of failure.</p>
 204
 205   <p>Your output might look something like this:</p>
 206
 207 <tt><pre>lit.py: lit.cfg:152: note: using clang: 'C:/Tools/llvm/bin/Release\\clang.EXE'
 208 -- Testing: Testing: 2534 tests, 4 threads --
 209 Testing: 0 .. 10.. 20.. 30.. 40.. 50.. 60.. 70.. 80.. 90..
 210 Testing Time: 81.52s
 211   Expected Passes    : 2503
 212   Expected Failures  : 28
 213   Unsupported Tests  : 3
 214 </pre></tt>
 215
 216   <p>The statistic, "Unexpected Failures" (not shown if all tests pass), is the important one.</p>
 217
 218   <!--=====================================================================-->
 219   <h2 id="patches">Creating Patch Files</h2>
 220   <!--=====================================================================-->
 221
 222   <p>To return changes to the Clang team, unless you have checkin
 223   privileges, the prefered way is to send patch files to the
 224   cfe-commits mailing list, with an explanation of what the patch is for.
 225   Or, if you have questions, or want to have a wider discussion of what
 226   you are doing, such as if you are new to Clang development, you can use
 227   the cfe-dev mailing list also.
 228   </p>
 229
 230   <p>To create these patch files, change directory
 231   to the llvm/tools/clang root and run:</p>
 232
 233   <ul><tt>svn diff (relative path) >(patch file name)</tt></ul>
 234
 235   <p>For example, for getting the diffs of all of clang:</p>
 236
 237   <ul><tt>svn diff . >~/mypatchfile.patch</tt></ul>
 238
 239   <p>For example, for getting the diffs of a single file:</p>
 240
 241   <ul><tt>svn diff lib/Parse/ParseDeclCXX.cpp >~/ParseDeclCXX.patch</tt></ul>
 242
 243   <p>Note that the paths embedded in the patch depend on where you run it,
 244   so changing directory to the llvm/tools/clang directory is recommended.</p>
 245
 246   <!--=====================================================================-->
 247   <h2 id="irgen">LLVM IR Generation</h2>
 248   <!--=====================================================================-->
 249
 250   <p>The LLVM IR generation part of clang handles conversion of the
 251     AST nodes output by the Sema module to the LLVM Intermediate
 252     Representation (IR). Historically, this was referred to as
 253     "codegen", and the Clang code for this lives
 254     in <tt>lib/CodeGen</tt>.</p>
 255
 256   <p>The output is most easily inspected using the <tt>-emit-llvm</tt>
 257     option to clang (possibly in conjunction with <tt>-o -</tt>). You
 258     can also use <tt>-emit-llvm-bc</tt> to write an LLVM bitcode file
 259     which can be processed by the suite of LLVM tools
 260     like <tt>llvm-dis</tt>, <tt>llvm-nm</tt>, etc. See the LLVM
 261     <a href="http://llvm.org/docs/CommandGuide/">Command Guide</a>
 262     for more information.</p>
 263
 264 </div>
 265 </body>
 266 </html>