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