Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 8eefcd353c1d06a10104f69e5079ebab3183f9a3 / . / www / hacking.html
blob: 3bbc0eaea84b9d62e37610915c5d13d91249d246 [file] [log] [blame]
Cedric Venet3d658642009-02-14 20:20:19 +0000[diff] [blame]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>
Daniel Dunbar79bba502010-01-22 02:04:46 +0000[diff] [blame]22 <li><a href="#style">Coding Standards</a></li>
Cedric Venet3d658642009-02-14 20:20:19 +0000[diff] [blame]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>
Eli Friedmand1e1ef32009-08-03 19:42:28 +0000[diff] [blame]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>
Cedric Venet3d658642009-02-14 20:20:19 +0000[diff] [blame]31 <li><a href="#irgen">LLVM IR Generation</a></li>
32 </ul>
33
34 <!--=====================================================================-->
Daniel Dunbar79bba502010-01-22 02:04:46 +0000[diff] [blame]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 <!--=====================================================================-->
Cedric Venet3d658642009-02-14 20:20:19 +0000[diff] [blame]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
Eli Friedmand1e1ef32009-08-03 19:42:28 +0000[diff] [blame]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
Cedric Venet3d658642009-02-14 20:20:19 +0000[diff] [blame]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
Eli Friedmand1e1ef32009-08-03 19:42:28 +0000[diff] [blame]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
Cedric Venet3d658642009-02-14 20:20:19 +0000[diff] [blame]102 about what is being run.</p>
103
Eli Friedmand1e1ef32009-08-03 19:42:28 +0000[diff] [blame]104 <p>The tests primarily consist of a test runner script running the compiler
105 under test on individual test files grouped in the directories under the
106 test directory. The individual test files include comments at the
107 beginning indicating the Clang compile options to use, to be read
108 by the test runner. Embedded comments also can do things like telling
109 the test runner that an error is expected at the current line.
110 Any output files produced by the test will be placed under
111 a created Output directory.</p>
112
113 <p>During the run of <tt>make test</tt>, the terminal output will
114 display a line similar to the following:</p>
115
116 <ul><tt>--- Running clang tests for i686-pc-linux-gnu ---</tt></ul>
117
118 <p>followed by a line continually overwritten with the current test
119 file being compiled, and an overall completion percentage.</p>
120
121 <p>After the <tt>make test</tt> run completes, the absence of any
122 <tt>Failing Tests (count):</tt> message indicates that no tests
123 failed unexpectedly. If any tests did fail, the
124 <tt>Failing Tests (count):</tt> message will be followed by a list
125 of the test source file paths that failed. For example:</p>
126
127 <tt><pre>
128 Failing Tests (3):
129 /home/john/llvm/tools/clang/test/SemaCXX/member-name-lookup.cpp
130 /home/john/llvm/tools/clang/test/SemaCXX/namespace-alias.cpp
131 /home/john/llvm/tools/clang/test/SemaCXX/using-directive.cpp
132 </pre></tt>
133
134 <p>If you used the <tt>make VERBOSE=1</tt> option, the terminal
135 output will reflect the error messages from the compiler and
136 test runner.</p>
137
Cedric Venet3d658642009-02-14 20:20:19 +0000[diff] [blame]138 <p>The regression suite can also be run with Valgrind by running
139 <tt>make test VG=1</tt> in the top-level clang directory.</p>
140
141 <p>For more intensive changes, running
142 the <a href="http://llvm.org/docs/TestingGuide.html#testsuiterun">LLVM
143 Test Suite</a> with clang is recommended. Currently the best way to
Daniel Dunbar12e57bc2009-08-06 16:47:53 +0000[diff] [blame]144 override LLVMGCC, as in: <tt>make LLVMGCC="clang -std=gnu89"
145 TEST=nightly report</tt> (make sure <tt>clang</tt> is in your PATH or use the
Cedric Venet3d658642009-02-14 20:20:19 +0000[diff] [blame]146 full path).</p>
Eli Friedmand1e1ef32009-08-03 19:42:28 +0000[diff] [blame]147
148 <!--=====================================================================-->
149 <h3 id="testingWindows">Testing using Visual Studio on Windows</h3>
150 <!--=====================================================================-->
151
John Thompson99ff8da2009-11-06 00:06:29 +0000[diff] [blame]152 <p>The Clang test suite can be run from either Visual Studio or
153 the command line.</p>
Eli Friedmand1e1ef32009-08-03 19:42:28 +0000[diff] [blame]154
John Thompson99ff8da2009-11-06 00:06:29 +0000[diff] [blame]155 <p>Note that the test runner is based on
Eli Friedmand1e1ef32009-08-03 19:42:28 +0000[diff] [blame]156 Python, which must be installed. Find Python at:
157 <a href="http://www.python.org/download">http://www.python.org/download</a>.
158 Download the latest stable version (2.6.2 at the time of this writing).</p>
Chris Lattner357f7ce2009-08-20 06:17:11 +0000[diff] [blame]159
160 <p>The GnuWin32 tools are also necessary for running the tests.
161 (Note that the grep from MSYS or Cygwin doesn't work with the tests
162 because of embedded double-quotes in the search strings. The GNU
163 grep does work in this case.)
164 Get them from <a href="http://getgnuwin32.sourceforge.net">
165 http://getgnuwin32.sourceforge.net</a>.</p>
John Thompson99ff8da2009-11-06 00:06:29 +0000[diff] [blame]166
167 <p>The cmake build tool is set up to create Visual Studio project files
168 for running the tests, "clang-test" being the root. Therefore, to
169 run the test from Visual Studio, right-click the clang-test project
170 and select "Build".</p>
171
172 <p>To run all the tests from the command line, execute a command like
173 the following:</p>
174
175 <tt>
176 python (path to llvm)/llvm/utils/lit/lit.py -sv --no-progress-bar
177 (path to llvm)/llvm/tools/clang/test
178 </tt>
179
180 <p>To run a single test:</p>
181
182 <tt>
183 python (path to llvm)/llvm/utils/lit/lit.py -sv --no-progress-bar
184 (path to llvm)/llvm/tools/clang/test/(dir)/(test)
185 </tt>
186
187 <p>For example:</p>
188
189 <tt>
190 python C:/Tools/llvm/utils/lit/lit.py -sv --no-progress-bar
191 C:/Tools/llvm/tools/clang/test/Sema/wchar.c
192 </tt>
193
194 <p>The -sv option above tells the runner to show the test output if
195 any tests failed, to help you determine the cause of failure.</p>
196
197 <p>Note that a few tests currently fail on Windows. We are working to
198 correct this. Therefore your output might look something like this:</p>
199
200<tt><pre>lit.py: lit.cfg:152: note: using clang: 'C:/Tools/llvm/bin/Debug\\clang.EXE'
John Thompson99ff8da2009-11-06 00:06:29 +0000[diff] [blame]201-- Testing: 1723 tests, 2 threads --
202FAIL: Clang::(test path) (659 of 1723)
203******************** TEST 'Clang::(test path)' FAILED ********************
204Script:
205 (commands run)
206Command Output (stdout):
207 (output here)
208Command Output (stderr):
209 (output here)
210********************
211Testing Time: 83.66s
212********************
213Failing Tests (1):
214 Clang::(test path)
215 Expected Passes : 1704
216 Expected Failures : 18
217 Unexpected Failures: 1
218</pre></tt>
219
220 <p>The last statistic, "Unexpected Failures", is the important one.</p>
Eli Friedmand1e1ef32009-08-03 19:42:28 +0000[diff] [blame]221
222 <!--=====================================================================-->
223 <h2 id="patches">Creating Patch Files</h2>
224 <!--=====================================================================-->
225
226 <p>To return changes to the Clang team, unless you have checkin
227 privileges, the prefered way is to send patch files to the
228 cfe-commits mailing list, with an explanation of what the patch is for.
229 Or, if you have questions, or want to have a wider discussion of what
230 you are doing, such as if you are new to Clang development, you can use
231 the cfe-dev mailing list also.
232 </p>
233
234 <p>To create these patch files, change directory
235 to the llvm/tools/clang root and run:</p>
236
237 <ul><tt>svn diff (relative path) >(patch file name)</tt></ul>
238
239 <p>For example, for getting the diffs of all of clang:</p>
240
241 <ul><tt>svn diff . >~/mypatchfile.patch</tt></ul>
242
243 <p>For example, for getting the diffs of a single file:</p>
244
245 <ul><tt>svn diff lib/Parse/ParseDeclCXX.cpp >~/ParseDeclCXX.patch</tt></ul>
246
247 <p>Note that the paths embedded in the patch depend on where you run it,
248 so changing directory to the llvm/tools/clang directory is recommended.</p>
Cedric Venet3d658642009-02-14 20:20:19 +0000[diff] [blame]249
250 <!--=====================================================================-->
251 <h2 id="irgen">LLVM IR Generation</h2>
252 <!--=====================================================================-->
253
254 <p>The LLVM IR generation part of clang handles conversion of the
255 AST nodes output by the Sema module to the LLVM Intermediate
256 Representation (IR). Historically, this was referred to as
257 "codegen", and the Clang code for this lives
258 in <tt>lib/CodeGen</tt>.</p>
259
260 <p>The output is most easily inspected using the <tt>-emit-llvm</tt>
261 option to clang (possibly in conjunction with <tt>-o -</tt>). You
262 can also use <tt>-emit-llvm-bc</tt> to write an LLVM bitcode file
263 which can be processed by the suite of LLVM tools
264 like <tt>llvm-dis</tt>, <tt>llvm-nm</tt>, etc. See the LLVM
265 <a href="http://llvm.org/docs/CommandGuide/">Command Guide</a>
266 for more information.</p>
267
268</div>
269</body>
270</html>