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>For CMake builds e.g. on Windows with Visual Studio, you will need
 189   to specify your build configuration (Debug, Release, etc.) via
 190   <tt>--param=build_config=(build config)</tt>.</p>
 191
 192   <p>To run a single test:</p>
 193
 194   <tt>
 195   python (path to llvm)/llvm/utils/lit/lit.py -sv --no-progress-bar
 196  (path to llvm)/llvm/tools/clang/test/(dir)/(test)
 197   </tt>
 198
 199   <p>For example:</p>
 200
 201   <tt>
 202   python C:/Tools/llvm/utils/lit/lit.py -sv --no-progress-bar
 203   C:/Tools/llvm/tools/clang/test/Sema/wchar.c
 204   </tt>
 205
 206   <p>The -sv option above tells the runner to show the test output if
 207   any tests failed, to help you determine the cause of failure.</p>
 208
 209   <p>Your output might look something like this:</p>
 210
 211 <tt><pre>lit.py: lit.cfg:152: note: using clang: 'C:/Tools/llvm/bin/Release\\clang.EXE'
 212 -- Testing: Testing: 2534 tests, 4 threads --
 213 Testing: 0 .. 10.. 20.. 30.. 40.. 50.. 60.. 70.. 80.. 90..
 214 Testing Time: 81.52s
 215   Expected Passes    : 2503
 216   Expected Failures  : 28
 217   Unsupported Tests  : 3
 218 </pre></tt>
 219
 220   <p>The statistic, "Unexpected Failures" (not shown if all tests pass), is the important one.</p>
 221
 222   <!--=====================================================================-->
 223   <h2 id="patches">Creating Patch Files</h2>
 224   <!--=====================================================================-->
 225
 226   <p>To return changes to the Clang team, unless you have checkin
 227   privileges, the prefered way is to send patch files to the
 228   cfe-commits mailing list, with an explanation of what the patch is for.
 229   Or, if you have questions, or want to have a wider discussion of what
 230   you are doing, such as if you are new to Clang development, you can use
 231   the cfe-dev mailing list also.
 232   </p>
 233
 234   <p>To create these patch files, change directory
 235   to the llvm/tools/clang root and run:</p>
 236
 237   <ul><tt>svn diff (relative path) >(patch file name)</tt></ul>
 238
 239   <p>For example, for getting the diffs of all of clang:</p>
 240
 241   <ul><tt>svn diff . >~/mypatchfile.patch</tt></ul>
 242
 243   <p>For example, for getting the diffs of a single file:</p>
 244
 245   <ul><tt>svn diff lib/Parse/ParseDeclCXX.cpp >~/ParseDeclCXX.patch</tt></ul>
 246
 247   <p>Note that the paths embedded in the patch depend on where you run it,
 248   so changing directory to the llvm/tools/clang directory is recommended.</p>
 249
 250   <!--=====================================================================-->
 251   <h2 id="irgen">LLVM IR Generation</h2>
 252   <!--=====================================================================-->
 253
 254   <p>The LLVM IR generation part of clang handles conversion of the
 255     AST nodes output by the Sema module to the LLVM Intermediate
 256     Representation (IR). Historically, this was referred to as
 257     "codegen", and the Clang code for this lives
 258     in <tt>lib/CodeGen</tt>.</p>
 259
 260   <p>The output is most easily inspected using the <tt>-emit-llvm</tt>
 261     option to clang (possibly in conjunction with <tt>-o -</tt>). You
 262     can also use <tt>-emit-llvm-bc</tt> to write an LLVM bitcode file
 263     which can be processed by the suite of LLVM tools
 264     like <tt>llvm-dis</tt>, <tt>llvm-nm</tt>, etc. See the LLVM
 265     <a href="http://llvm.org/docs/CommandGuide/">Command Guide</a>
 266     for more information.</p>
 267
 268 </div>
 269 </body>
 270 </html>