diff options
Diffstat (limited to 'docs/UsersManual.html')
| -rw-r--r-- | docs/UsersManual.html | 202 |
1 files changed, 160 insertions, 42 deletions
diff --git a/docs/UsersManual.html b/docs/UsersManual.html index b33ed61..69f916c 100644 --- a/docs/UsersManual.html +++ b/docs/UsersManual.html @@ -43,12 +43,14 @@ td { <li><a href="#diagnostics_categories">Diagnostic Categories</a></li> <li><a href="#diagnostics_commandline">Controlling Diagnostics via Command Line Flags</a></li> <li><a href="#diagnostics_pragmas">Controlling Diagnostics via Pragmas</a></li> + <li><a href="#diagnostics_systemheader">Controlling Diagnostics in System Headers</a></li> <li><a href="#diagnostics_enable_everything">Enabling All Warnings</a></li> <li><a href="#analyzer_diagnositics">Controlling Static Analyzer Diagnostics</a></li> </ul> </li> <li><a href="#precompiledheaders">Precompiled Headers</a></li> <li><a href="#codegen">Controlling Code Generation</a></li> + <li><a href="#debuginfosize">Controlling Size of Debug Information</a></li> </ul> </li> <li><a href="#c">C Language Features</a> @@ -185,9 +187,10 @@ introduces the language selection and other high level options like -c, -g, etc. <p><b>-Werror=foo</b>: Turn warning "foo" into an error.</p> <p><b>-Wno-error=foo</b>: Turn warning "foo" into an warning even if -Werror is specified.</p> -<p><b>-Wfoo</b>: Enable warning foo</p> -<p><b>-Wno-foo</b>: Disable warning foo</p> +<p><b>-Wfoo</b>: Enable warning "foo".</p> +<p><b>-Wno-foo</b>: Disable warning "foo".</p> <p><b>-w</b>: Disable all warnings.</p> +<p><b>-Weverything</b>: <a href="#diagnostics_enable_everything">Enable <b>all</b> warnings.</a></p> <p><b>-pedantic</b>: Warn on language extensions.</p> <p><b>-pedantic-errors</b>: Error on language extensions.</p> <p><b>-Wsystem-headers</b>: Enable warnings from system headers.</p> @@ -227,6 +230,9 @@ print something like: <p>When this is disabled, Clang will print "test.c:28: warning..." with no column number.</p> + +<p>The printed column numbers count bytes from the beginning of the line; take +care if your source contains multibyte characters.</p> </dd> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> @@ -393,6 +399,9 @@ exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expre </pre> <p>The {}'s are generated by -fdiagnostics-print-source-range-info.</p> + +<p>The printed column numbers count bytes from the beginning of the line; take +care if your source contains multibyte characters.</p> </dd> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> @@ -413,6 +422,51 @@ respectively). Both the file name and the insertion string escape backslash (as "\\"), tabs (as "\t"), newlines (as "\n"), double quotes(as "\"") and non-printable characters (as octal "\xxx").</p> + +<p>The printed column numbers count bytes from the beginning of the line; take +care if your source contains multibyte characters.</p> +</dd> + +<dt id="opt_fno-elide-type"> +<b>-fno-elide-type</b>: +Turns off elision in template type printing.</dt> +<dd><p>The default for template type printing is to elide as many template +arguments as possible, removing those which are the same in both template types, +leaving only the differences. Adding this flag will print all the template +arguments. If supported by the terminal, highlighting will still appear on +differing arguments.</p> + +Default: +<pre> +t.cc:4:5: <span class="note">note</span>: candidate function not viable: no known conversion from 'vector<map<[...], map<<span class="template-highlight">float</span>, [...]>>>' to 'vector<map<[...], map<<span class="template-highlight">double</span>, [...]>>>' for 1st argument; +</pre> +-fno-elide-type: +<pre> +t.cc:4:5: <span class="note">note</span>: candidate function not viable: no known conversion from 'vector<map<int, map<<span class="template-highlight">float</span>, int>>>' to 'vector<map<int, map<<span class="template-highlight">double</span>, int>>>' for 1st argument; +</pre> +</dd> + +<dt id="opt_fdiagnostics-show-template-tree"> +<b>-fdiagnostics-show-template-tree</b>: +Template type diffing prints a text tree.</dt> +<dd><p>For diffing large templated types, this option will cause Clang to +display the templates as an indented text tree, one argument per line, with +differences marked inline. This is compatible with -fno-elide-type.</p> + +Default: +<pre> +t.cc:4:5: <span class="note">note</span>: candidate function not viable: no known conversion from 'vector<map<[...], map<<span class="template-highlight">float</span>, [...]>>>' to 'vector<map<[...], map<<span class="template-highlight">double</span>, [...]>>>' for 1st argument; +</pre> +-fdiagnostics-show-template-tree +<pre> +t.cc:4:5: <span class="note">note</span>: candidate function not viable: no known conversion for 1st argument; + vector< + map< + [...], + map< + [<span class="template-highlight">float</span> != <span class="template-highlight">float</span>], + [...]>>> +</pre> </dd> </dl> @@ -443,9 +497,6 @@ the end of preprocessor directives. For example: <p>These extra tokens are not strictly conforming, and are usually best handled by commenting them out.</p> - -<p>This option is also enabled by <a href="">-Wfoo</a>, <a href="">-Wbar</a>, - and <a href="">-Wbaz</a>.</p> </dd> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> @@ -609,7 +660,7 @@ mapping of category names to category id's can be obtained by running '<tt>clang <h4 id="diagnostics_commandline">Controlling Diagnostics via Command Line Flags</h4> -<p>-W flags, -pedantic, etc</p> +<p>TODO: -W flags, -pedantic, etc</p> <h4 id="diagnostics_pragmas">Controlling Diagnostics via Pragmas</h4> @@ -653,6 +704,45 @@ GCC do not support the exact same set of warnings, so even when using GCC compatible #pragmas there is no guarantee that they will have identical behaviour on both compilers. </p> +<h4 id="diagnostics_systemheader">Controlling Diagnostics in System Headers</h4> + +<p>Warnings are suppressed when they occur in system headers. By default, an +included file is treated as a system header if it is found in an include path +specified by <tt>-isystem</tt>, but this can be overridden in several ways.</p> + +<p>The <tt>system_header</tt> pragma can be used to mark the current file as +being a system header. No warnings will be produced from the location of the +pragma onwards within the same file.</p> + +<pre> +char a = 'xy'; // warning + +#pragma clang system_header + +char b = 'ab'; // no warning +</pre> + +<p>The <tt>-isystem-prefix</tt> and <tt>-ino-system-prefix</tt> command-line +arguments can be used to override whether subsets of an include path are treated +as system headers. When the name in a <tt>#include</tt> directive is found +within a header search path and starts with a system prefix, the header is +treated as a system header. The last prefix on the command-line which matches +the specified header name takes precedence. For instance:</p> + +<pre> +clang -Ifoo -isystem bar -isystem-prefix x/ -ino-system-prefix x/y/ +</pre> + +<p>Here, <tt>#include "x/a.h"</tt> is treated as including a system header, even +if the header is found in <tt>foo</tt>, and <tt>#include "x/y/b.h"</tt> is +treated as not including a system header, even if the header is found in +<tt>bar</tt>. +</p> + +<p>A <tt>#include</tt> directive which finds a file relative to the current +directory is treated as including a system header if the including file is +treated as a system header.</p> + <h4 id="diagnostics_enable_everything">Enabling All Warnings</h4> <p>In addition to the traditional <tt>-W</tt> flags, one can enable <b>all</b> @@ -667,37 +757,11 @@ on both compilers. </p> <p>While not strictly part of the compiler, the diagnostics from Clang's <a href="http://clang-analyzer.llvm.org">static analyzer</a> can also be influenced -by the user via changes to the source code. This can be done in two ways: - -<ul> - -<li id="analyzer_annotations"><b>Annotations</b>: The static analyzer recognizes various GCC-style -attributes (e.g., <tt>__attribute__((nonnull)))</tt>) that can either suppress -static analyzer warnings or teach the analyzer about code invariants which -enable it to find more bugs. While many of these attributes are standard GCC -attributes, additional ones have been added to Clang to specifically support the -static analyzer. Detailed information on these annotations can be found in the -<a href="http://clang-analyzer.llvm.org/annotations.html">analyzer's -documentation</a>.</li> - -<li><b><tt>__clang_analyzer__</tt></b>: When the static analyzer is using Clang -to parse source files, it implicitly defines the preprocessor macro -<tt>__clang_analyzer__</tt>. While discouraged, code can use this macro to -selectively exclude code the analyzer examines. Here is an example: - -<pre> -#ifndef __clang_analyzer__ -// Code not to be analyzed -#endif -</pre> - -In general, this usage is discouraged. Instead, we prefer that users file bugs -against the analyzer when it flags false positives. There is also active -discussion of allowing users in the future to selectively silence specific -analyzer warnings (some of which can already be done using <a -href="#analyzer_annotations">annotations</a>).</li> - -</ul> +by the user via changes to the source code. See the available +<a href = "http://clang-analyzer.llvm.org/annotations.html" >annotations</a> and +the analyzer's +<a href= "http://clang-analyzer.llvm.org/faq.html#exclude_code" >FAQ page</a> for +more information. <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <h3 id="precompiledheaders">Precompiled Headers</h3> @@ -855,6 +919,39 @@ generator will always lower the builtin to a call to the specified function regardless of whether the target ISA has a trap instruction. This option is useful for environments (e.g. deeply embedded) where a trap cannot be properly handled, or when some custom behavior is desired.</dd> + +<dt id="opt_ftls-model"><b>-ftls-model=[model]</b>: Select which TLS model to +use.</dt> +<dd>Valid values are: <tt>global-dynamic</tt>, <tt>local-dynamic</tt>, +<tt>initial-exec</tt> and <tt>local-exec</tt>. The default value is +<tt>global-dynamic</tt>. The compiler may use a different model if the selected +model is not supported by the target, or if a more efficient model can be used. +The TLS model can be overridden per variable using the <tt>tls_model</tt> +attribute. +</dd> +</dl> + +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> +<h3 id="debuginfosize">Controlling Size of Debug Information</h3> +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> + +<p>Debug info kind generated by Clang can be set by one of the flags listed +below. If multiple flags are present, the last one is used.</p> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> +<dl> +<dt id="opt_g0"><b>-g0</b>: Don't generate any debug info (default). + +<dt id="opt_gline-tables-only"><b>-gline-tables-only</b>: +Generate line number tables only. +<dd> +This kind of debug info allows to obtain stack traces with function +names, file names and line numbers (by such tools as +gdb or addr2line). It doesn't contain any other data (e.g. +description of local variables or function parameters). +</dd> + +<dt id="opt_g"><b>-g</b>: Generate complete debug info. </dl> <!-- ======================================================================= --> @@ -937,9 +1034,18 @@ interest in these features yet, so it's hard to say when they will be implemented.</li> <li>clang does not support nested functions; this is a complex feature which -is infrequently used, so it is unlikely to be implemented anytime soon.</li> +is infrequently used, so it is unlikely to be implemented anytime soon. In C++11 +it can be emulated by assigning lambda functions to local variables, e.g: +<pre> + auto const local_function = [&](int parameter) { + // Do something + }; + ... + local_function(1); +</pre> +</li> -<li>clang does not support global register variables, this is unlikely +<li>clang does not support global register variables; this is unlikely to be implemented soon because it requires additional LLVM backend support. </li> @@ -955,7 +1061,7 @@ in 4.3, the glibc headers will not try to use this extension with clang at the moment.</li> <li>clang does not support the gcc extension for forward-declaring function -parameters; this has not showed up in any real-world code yet, though, so it +parameters; this has not shown up in any real-world code yet, though, so it might never be implemented.</li> </ul> @@ -1001,6 +1107,14 @@ support is incomplete; enabling Microsoft extensions will silently drop certain constructs (including __declspec and Microsoft-style asm statements). </p> +<p>clang has a -fms-compatibility flag that makes clang accept enough +invalid C++ to be able to parse most Microsoft headers. This flag is enabled by +default for Windows targets.</p> + +<p>-fdelayed-template-parsing lets clang delay all template instantiation until +the end of a translation unit. This flag is enabled by default for Windows +targets.</p> + <ul> <li>clang allows setting _MSC_VER with -fmsc-version=. It defaults to 1300 which is the same as Visual C/C++ 2003. Any number is supported and can greatly affect @@ -1015,6 +1129,8 @@ record members can be declared using user defined typedefs.</li> controlling record layout. GCC also contains support for this feature, however where MSVC and GCC are incompatible clang follows the MSVC definition.</li> + +<li>clang defaults to C++11 for Windows targets.</li> </ul> <!-- ======================================================================= --> @@ -1092,7 +1208,7 @@ Generating assembly requires a suitable LLVM backend. <h4 id="target_os_darwin">Darwin (Mac OS/X)</h4> <!-- ======================================= --> -<p>No __thread support, 64-bit ObjC support requires SL tools.</p> +<p>None</p> <!-- ======================================= --> <h4 id="target_os_win32">Windows</h4> @@ -1100,6 +1216,8 @@ Generating assembly requires a suitable LLVM backend. <p>Experimental supports are on Cygming.</p> +<p>See also <a href="#c_ms">Microsoft Extensions</a>.</p> + <h5>Cygwin</h5> <p>Clang works on Cygwin-1.7.</p> @@ -1135,7 +1253,7 @@ Clang assumes directories as below;</p> <li><tt>some_directory/bin/../include</tt></li> </ul> -<p>This directory layout is standard for any toolchain you will find on the official <a href="mingw-w64.sourceforge.net">MinGW-w64 website</a>. +<p>This directory layout is standard for any toolchain you will find on the official <a href="http://mingw-w64.sourceforge.net">MinGW-w64 website</a>. <p>Clang expects the GCC executable "gcc.exe" compiled for i686-w64-mingw32 (or x86_64-w64-mingw32) to be present on PATH.</p> |
