Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / 9e6111ad10d29802d8eff99c941d262979e99084 / . / docs / ReleaseNotes.html
blob: f1f70c77f7e357b59e93abb808706f36f7ae52c4 [file] [log] [blame]
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]3<html>
4<head>
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]5<title>Clang 3.2 Release Notes</title>
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame]6<link type="text/css" rel="stylesheet" href="../menu.css">
7<link type="text/css" rel="stylesheet" href="../content.css">
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]8<style type="text/css">
9td {
10 vertical-align: top;
11}
12</style>
13</head>
14<body>
15
16<!--#include virtual="../menu.html.incl"-->
17
18<div id="content">
19
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]20<h1>Clang 3.2 Release Notes</h1>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]21
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame]22<img style="float:right" src="http://llvm.org/img/DragonSmall.png"
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]23 width="136" height="136" alt="LLVM Dragon Logo">
24
25<ul>
26 <li><a href="#intro">Introduction</a></li>
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]27 <li><a href="#whatsnew">What's New in Clang 3.2?</a>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]28 <ul>
29 <li><a href="#majorfeatures">Major New Features</a></li>
Alexey Samsonovf7a4c352012-06-22 11:18:10 +0000[diff] [blame]30 <li><a href="#newflags">New Compiler Flags</a></li>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]31 <li><a href="#cchanges">C Language Changes</a></li>
Richard Smith45fb9952012-02-16 00:32:27 +0000[diff] [blame]32 <li><a href="#cxxchanges">C++ Language Changes</a></li>
Jean-Daniel Dupas3fd80872012-03-03 13:37:22 +0000[diff] [blame]33 <li><a href="#objcchanges">Objective-C Language Changes</a></li>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]34 <li><a href="#apichanges">Internal API Changes</a></li>
Gregory Szorc63419002012-05-12 20:45:56 +0000[diff] [blame]35 <li><a href="#pythonchanges">Python Binding Changes</a></li>
Richard Smith855746b2011-11-28 20:02:05 +0000[diff] [blame]36 </ul>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]37 </li>
38 <li><a href="#knownproblems">Known Problems</a></li>
39 <li><a href="#additionalinfo">Additional Information</a></li>
40</ul>
41
42<div class="doc_author">
43 <p>Written by the <a href="http://llvm.org/">LLVM Team</a></p>
44</div>
45
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]46<h1 style="color:red">These are in-progress notes for the upcoming Clang 3.2
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]47release.<br>
48You may prefer the
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]49<a href="http://llvm.org/releases/3.1/docs/ClangReleaseNotes.html">Clang 3.1
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]50Release Notes</a>.</h1>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]51
52<!-- ======================================================================= -->
53<h2 id="intro">Introduction</h2>
54<!-- ======================================================================= -->
55
56<p>This document contains the release notes for the Clang C/C++/Objective-C
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]57 frontend, part of the LLVM Compiler Infrastructure, release 3.2. Here we
58 describe the status of Clang in some detail, including major improvements
59 from the previous release and new feature work. For the general LLVM release
60 notes, see <a href="http://llvm.org/docs/ReleaseNotes.html">the LLVM
61 documentation</a>. All LLVM releases may be downloaded from the
62 <a href="http://llvm.org/releases/">LLVM releases web site</a>.</p>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]63
64<p>For more information about Clang or LLVM, including information about the
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]65 latest release, please check out the main please see the
66 <a href="http://clang.llvm.org">Clang Web Site</a> or the
67 <a href="http://llvm.org">LLVM Web Site</a>.
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]68
69<p>Note that if you are reading this file from a Subversion checkout or the main
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]70 Clang web page, this document applies to the <i>next</i> release, not the
71 current one. To see the release notes for a specific release, please see the
72 <a href="http://llvm.org/releases/">releases page</a>.</p>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]73
74<!-- ======================================================================= -->
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]75<h2 id="whatsnew">What's New in Clang 3.2?</h2>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]76<!-- ======================================================================= -->
77
78<p>Some of the major new features and improvements to Clang are listed here.
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]79 Generic improvements to Clang as a whole or to its underlying infrastructure
80 are described first, followed by language-specific sections with improvements
81 to Clang's support for those languages.</p>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]82
83<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
84<h3 id="majorfeatures">Major New Features</h3>
85<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
86
Richard Smithb2647022012-05-25 02:35:34 +0000[diff] [blame]87<h4 id="diagnostics">Improvements to Clang's diagnostics</h4>
Chandler Carrutha0df07d2011-11-28 22:17:58 +0000[diff] [blame]88
Richard Smithb2647022012-05-25 02:35:34 +0000[diff] [blame]89<p>Clang's diagnostics are constantly being improved to catch more issues,
90explain them more clearly, and provide more accurate source information about
91them. The improvements since the 3.1 release include:</p>
92
93<ul>
94 <li><tt>-Wuninitialized</tt> has been taught to recognise uninitialized uses
95 which always occur when an explicitly-written non-constant condition is either
96 <tt>true</tt> or <tt>false</tt>. For example:
97
98<pre>
99int f(bool b) {
100 int n;
101 if (b)
102 n = 1;
103 return n;
104}
105
Richard Smithbdb97ff2012-05-26 06:20:46 +0000[diff] [blame]106<b>sometimes-uninit.cpp:3:7: <span class="warning">warning:</span> variable 'n' is used uninitialized whenever 'if' condition is false [-Wsometimes-uninitialized]</b>
Richard Smithb2647022012-05-25 02:35:34 +0000[diff] [blame]107 if (b)
108 <span class="caret">^</span>
Richard Smithbdb97ff2012-05-26 06:20:46 +0000[diff] [blame]109<b>sometimes-uninit.cpp:5:10: <span class="note">note:</span></b> uninitialized use occurs here
110 return n;
111 <span class="caret">^</span>
112<b>sometimes-uninit.cpp:3:3: <span class="note">note:</span></b> remove the 'if' if its condition is always true
113 if (b)
114 <span class="caret">^~~~~~</span>
Richard Smithb2647022012-05-25 02:35:34 +0000[diff] [blame]115<b>sometimes-uninit.cpp:2:8: <span class="note">note:</span></b> initialize the variable 'n' to silence this warning
116 int n;
117 <span class="caret">^</span>
118 <span class="caret"> = 0</span>
119</pre>
120
121 This functionality can be enabled or disabled separately from
122 <tt>-Wuninitialized</tt> with the <tt>-Wsometimes-uninitialized</tt> warning
123 flag.</li>
Richard Trieue59331a2012-06-27 02:00:20 +0000[diff] [blame]124
125 <li>Template type diffing improves the display of diagnostics with templated
126 types in them.
127
128<pre>
129int f(vector&lt;map&lt;int, double&gt;&gt;);
130int x = f(vector&lt;map&lt;int, float&gt;&gt;());
131</pre>
132 The error message is the same, but the note is different based on the options selected.
133<pre>
134<b>template-diff.cpp:5:9: <span class="error">error:</span> no matching function for call to 'f'</b>
135int x = f(vector&lt;map&lt;int, float&gt;&gt;());
136 <span class="caret">^</span>
137</pre>
138 Templated type diffing with type elision (default):
139<pre>
140<b>template-diff.cpp:4:5: <span class="note">note:</span></b> candidate function not viable: no known conversion from 'vector&lt;map&lt;[...], <span class="template-highlight">float</span>&gt;&gt;' to 'vector&lt;map&lt;[...], <span class="template-highlight">double</span>&gt;&gt;' for 1st argument;
141int f(vector&lt;map&lt;int, double&gt;&gt;);
142 <span class="caret">^</span>
143</pre>
144 Templated type diffing without type elision (-fno-elide-type):
145<pre>
146<b>template-diff.cpp:4:5: <span class="note">note:</span></b> candidate function not viable: no known conversion from 'vector&lt;map&lt;int, <span class="template-highlight">float</span>&gt;&gt;' to 'vector&lt;map&lt;int, <span class="template-highlight">double</span>&gt;&gt;' for 1st argument;
147int f(vector&lt;map&lt;int, double&gt;&gt;);
148 <span class="caret">^</span>
149</pre>
150 Templated tree printing with type elision (-fdiagnostics-show-template-tree):
151<pre>
152<b>template-diff.cpp:4:5: <span class="note">note:</span></b> candidate function not viable: no known conversion for 1st argument;
153 vector&lt;
154 map&lt;
155 [...],
156 [<span class="template-highlight">float</span> != <span class="template-highlight">double</span>]&gt;&gt;
157int f(vector&lt;map&lt;int, double&gt;&gt;);
158 <span class="caret">^</span>
159</pre>
160 Templated tree printing without type elision (-fdiagnostics-show-template-tree -fno-elide-type):
161<pre>
162<b>template-diff.cpp:4:5: <span class="note">note:</span></b> candidate function not viable: no known conversion for 1st argument;
163 vector&lt;
164 map&lt;
165 int,
166 [<span class="template-highlight">float</span> != <span class="template-highlight">double</span>]&gt;&gt;
167int f(vector&lt;map&lt;int, double&gt;&gt;);
168 <span class="caret">^</span>
169</pre>
170
171 </li>
172
Richard Smithfd9d0e12012-11-06 19:23:14 +0000[diff] [blame]173 <li>Clang's <tt>-fcatch-undefined-behavior</tt> option has been renamed to
174 <tt>-fsanitize=undefined</tt> and has grown the ability to check for several
175 new types of undefined behavior. See the Users Manual for more information.
Richard Smith3f9411a2012-08-25 00:47:19 +0000[diff] [blame]176
Dmitri Gribenko4f35f742012-12-16 17:38:09 +0000[diff] [blame]177
178 <li><tt>-Wdocumentation</tt> enables warnings about documentation comments.
179 See section "Documentation comment support" for an example.</li>
180
Richard Smith3f9411a2012-08-25 00:47:19 +0000[diff] [blame]181 <!-- Flesh this out prior to release. -->
182
Richard Smithfd9d0e12012-11-06 19:23:14 +0000[diff] [blame]183 <!-- Document renaming of -faddress-sanitizer and -fthread-sanitizer. -->
184
Richard Smith3f9411a2012-08-25 00:47:19 +0000[diff] [blame]185 </li>
186
Richard Smithb2647022012-05-25 02:35:34 +0000[diff] [blame]187</ul>
188
Hans Wennborg5e2d5de2012-06-23 11:51:46 +0000[diff] [blame]189<h4 id="tlsmodel">Support for <code>tls_model</code> attribute</h4>
190
191<p>Clang now supports the <code>tls_model</code> attribute, allowing code that
192uses thread-local storage to explicitly select which model to use. The available
193models are <code>"global-dynamic"</code>, <code>"local-dynamic"</code>,
194<code>"initial-exec"</code> and <code>"local-exec"</code>. See
195<a href="http://www.akkadia.org/drepper/tls.pdf">ELF Handling For Thread-Local
196 Storage</a> for more information.</p>
197
198<p>The compiler is free to choose a different model if the specified model is not
199supported by the target, or if the compiler determines that a more specific
200model can be used.
201</p>
202
Dmitri Gribenko19d48ce2012-08-17 16:01:54 +0000[diff] [blame]203<h4>Type safety attributes</h4>
204<p>Clang now supports type safety attributes that allow checking during compile
205time that 'void *' function arguments and arguments for variadic functions are
206of a particular type which is determined by some other argument to the same
207function call.</p>
208
209<p>Usecases include:</p>
210<ul>
211<li>MPI library implementations, where these attributes enable checking that
212 buffer type matches the passed <code>MPI_Datatype</code>;</li>
213<li> HDF5 library -- similar usecase as for MPI;</li>
214<li> checking types of variadic functions' arguments for functions like
215<code>fcntl()</code> and <code>ioctl()</code>.</li>
216</ul>
217
218<p>See entries for <code>argument_with_type_tag</code>,
219<code>pointer_with_type_tag</code> and <code>type_tag_for_datatype</code>
220attributes in Clang language extensions documentation.</p>
221
Dmitri Gribenko4f35f742012-12-16 17:38:09 +0000[diff] [blame]222<h4>Documentation comment support</h4>
223<p>Clang now supports documentation comments written in a Doxygen-like syntax.
224Clang parses the comments and can detect syntactic and semantic errors in
225comments. These warnings are off by default. Pass <tt>-Wdocumentation</tt>
226flag to enable warnings about documentation comments.</p>
227
228<p>For example, given:</p>
229
230<pre>/// \param [in] Str the string.
231/// \returns a modified string.
232void do_something(const std::string &amp;str);</pre>
233
234<p><tt>clang -Wdocumentation</tt> will emit two warnings:</p>
235
236<pre><b>doc-test.cc:3:6: <span class="warning">warning:</span></b> '\returns' command used in a comment that is attached to a function returning void [-Wdocumentation]
237/// \returns a modified string.
238 <span class="caret">~^~~~~~~~~~~~~~~~~~~~~~~~~~</span>
239<b>doc-test.cc:2:17: <span class="warning">warning:</span></b> parameter 'Str' not found in the function declaration [-Wdocumentation]
240/// \param [in] Str the string.
241 <span class="caret">^~~</span>
242<b>doc-test.cc:2:17: <span class="note">note:</span></b> did you mean 'str'?
243/// \param [in] Str the string.
244 <span class="caret">^~~</span>
245 <span class="caret">str</span></pre>
246
247<p>libclang includes a new API, <tt>clang_FullComment_getAsXML</tt>, to convert
248comments to XML documents. This API can be used to build documentation
249extraction tools.</p>
250
Alexey Samsonovf7a4c352012-06-22 11:18:10 +0000[diff] [blame]251<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
252<h3 id="newflags">New Compiler Flags</h3>
253<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
254<ul>
255 <li><tt>-gline-tables-only</tt> controls the
256 <a href="http://clang.llvm.org/docs/UsersManual.html#debuginfosize">size of debug information</a>.
257 This flag tells Clang to emit debug info which is just enough to obtain stack traces with
258 function names, file names and line numbers (by such tools as gdb or addr2line).
259 Debug info for variables or function parameters is not produced, which reduces
260 the size of the resulting binary.
Hans Wennborg7bf9d9b2012-07-13 12:47:15 +0000[diff] [blame]261
262 <li><tt>-ftls-model</tt> controls which TLS model to use for thread-local
263 variables. This can be overridden per variable using the
264 <a href="#tlsmodel"><tt>tls_model</tt> attribute</a> mentioned above.
265 For more details, see the <a href="UsersManual.html#opt_ftls-model">User's
266 Manual</a>.</li>
Alexey Samsonovf7a4c352012-06-22 11:18:10 +0000[diff] [blame]267</ul>
Manuel Klimek92f74092012-04-04 12:53:16 +0000[diff] [blame]268
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]269<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
270<h3 id="cchanges">C Language Changes in Clang</h3>
271<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
272
Richard Smith45fb9952012-02-16 00:32:27 +0000[diff] [blame]273<h4 id="c11changes">C11 Feature Support</h4>
Richard Smith62d730f2011-11-28 22:48:25 +0000[diff] [blame]274
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]275<p>...</p>
Richard Smith45fb9952012-02-16 00:32:27 +0000[diff] [blame]276
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]277<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
278<h3 id="cxxchanges">C++ Language Changes in Clang</h3>
279<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
280
Richard Smith855746b2011-11-28 20:02:05 +0000[diff] [blame]281<h4 id="cxx11changes">C++11 Feature Support</h4>
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]282
283<p>...</p>
Richard Smith855746b2011-11-28 20:02:05 +0000[diff] [blame]284
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]285<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
286<h3 id="objcchanges">Objective-C Language Changes in Clang</h3>
287<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
Chandler Carruth4d582122011-11-29 00:15:23 +0000[diff] [blame]288
Jordan Rose6deae7c2012-07-09 16:54:44 +0000[diff] [blame]289<p>...</p>
Chandler Carruth52e375e2011-11-29 00:15:25 +0000[diff] [blame]290
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]291<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
292<h3 id="apichanges">Internal API Changes</h3>
293<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
294
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]295<p>These are major API changes that have happened since the 3.1 release of
296 Clang. If upgrading an external codebase that uses Clang as a library, this
297 section should help get you past the largest hurdles of upgrading.</p>
Chandler Carruthc4dbffa2011-11-28 18:55:47 +0000[diff] [blame]298
Richard Smith45fb9952012-02-16 00:32:27 +0000[diff] [blame]299<h4 id="api1">API change 1</h4>
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]300
301<p>...</p>
Chandler Carruthc4dbffa2011-11-28 18:55:47 +0000[diff] [blame]302
Gregory Szorc63419002012-05-12 20:45:56 +0000[diff] [blame]303<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
304<h3 id="pythonchanges">Python Binding Changes</h3>
305<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
306
307The following methods have been added:
308<ul>
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]309 <li>...</li>
Gregory Szorc63419002012-05-12 20:45:56 +0000[diff] [blame]310</ul>
311
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]312<!-- ======================================================================= -->
313<h2 id="knownproblems">Significant Known Problems</h2>
314<!-- ======================================================================= -->
315
316<!-- ======================================================================= -->
317<h2 id="additionalinfo">Additional Information</h2>
318<!-- ======================================================================= -->
319
320<p>A wide variety of additional information is available on the
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]321 <a href="http://clang.llvm.org/">Clang web page</a>. The web page contains
322 versions of the API documentation which are up-to-date with the Subversion
323 version of the source code. You can access versions of these documents
324 specific to this release by going into the "<tt>clang/doc/</tt>" directory in
325 the Clang tree.</p>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]326
327<p>If you have any questions or comments about Clang, please feel free to
Bill Wendlingc0bb3122012-05-24 06:42:56 +0000[diff] [blame]328 contact us via
329 the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev"> mailing
330 list</a>.</p>
Chandler Carruth59abf062011-11-28 22:12:44 +0000[diff] [blame]331
332<!-- ======================================================================= -->
333<!-- Likely 3.1 release notes -->
334<!-- ======================================================================= -->
335<!--
336This is just a section to hold things that have already gotten started and
337should likely pick up proper release notes in 3.1.
338
339- C1X and C++11 atomics infrastructure and support
340- CUDA support?
341
342-->
343
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame]344</div>
Chandler Carruthc00c0c32011-11-28 07:16:19 +0000[diff] [blame]345</body>
346</html>