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 -- 221Testing: 0 .. 10.. 20.. 30.. 40.. 50.. 60.. 70.. 80.. 90.. 222Testing 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