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