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