Home | History | Annotate | Download | only in www
      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>
    279