diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/DriverInternals.html | 18 | ||||
| -rw-r--r-- | docs/InternalsManual.html | 7 | ||||
| -rw-r--r-- | docs/LanguageExtensions.html | 44 | ||||
| -rw-r--r-- | docs/UsersManual.html | 109 | ||||
| -rw-r--r-- | docs/libIndex.html | 267 | ||||
| -rw-r--r-- | docs/tools/Makefile | 5 | ||||
| -rw-r--r-- | docs/tools/clang.pod | 48 |
7 files changed, 450 insertions, 48 deletions
diff --git a/docs/DriverInternals.html b/docs/DriverInternals.html index a99d72cd4eb2..a7d2da37711e 100644 --- a/docs/DriverInternals.html +++ b/docs/DriverInternals.html @@ -240,7 +240,7 @@ <p>Once the arguments are parsed, the tree of subprocess jobs needed for the desired compilation sequence are - constructed. This involves determing the input files and + constructed. This involves determining the input files and their types, what work is to be done on them (preprocess, compile, assemble, link, etc.), and constructing a list of Action instances for each task. The result is a list of @@ -312,7 +312,7 @@ to run. Conceptually, the driver performs a top down matching to assign Action(s) to Tools. The ToolChain is responsible for selecting the tool to perform a particular - action; once seleected the driver interacts with the tool + action; once selected the driver interacts with the tool to see if it can match additional actions (for example, by having an integrated preprocessor). @@ -397,7 +397,7 @@ <p>The driver constructs a Compilation object for each set of command line arguments. The Driver itself is intended to be - invariant during construct of a Compilation; an IDE should be + invariant during construction of a Compilation; an IDE should be able to construct a single long lived driver instance to use for an entire build, for example.</p> @@ -409,7 +409,7 @@ <h4 id="int_unified_parsing">Unified Parsing & Pipelining</h4> - <p>Parsing and pipeling both occur without reference to a + <p>Parsing and pipelining both occur without reference to a Compilation instance. This is by design; the driver expects that both of these phases are platform neutral, with a few very well defined exceptions such as whether the platform uses a driver @@ -425,11 +425,11 @@ stop seeing some arguments the user provided, and see new ones instead).</p> - <p>For example, on Darwin <tt>-gfull</tt> gets translated into - two separate arguments, <tt>-g</tt> - and <tt>-fno-eliminate-unused-debug-symbols</tt>. Trying to - write Tool logic to do something with <tt>-gfull</tt> will not - work, because at Tools run after the arguments have been + <p>For example, on Darwin <tt>-gfull</tt> gets translated into two + separate arguments, <tt>-g</tt> + and <tt>-fno-eliminate-unused-debug-symbols</tt>. Trying to write Tool + logic to do something with <tt>-gfull</tt> will not work, because Tool + argument translation is done after the arguments have been translated.</p> <p>A long term goal is to remove this tool chain specific diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index a4d5a057ebaa..f39224f47dc5 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -67,6 +67,7 @@ td { <li><a href="#Constants">Constant Folding in the Clang AST</a></li> </ul> </li> +<li><a href="libIndex.html">The Index Library</a></li> </ul> @@ -528,12 +529,6 @@ describe the location of the characters corresponding to the token and the location where the token was used (i.e. the macro instantiation point or the location of the _Pragma itself).</p> -<p>For efficiency, we only track one level of macro instantiations: if a token was -produced by multiple instantiations, we only track the source and ultimate -destination. Though we could track the intermediate instantiation points, this -would require extra bookkeeping and no known client would benefit substantially -from this.</p> - <p>The Clang front-end inherently depends on the location of a token being tracked correctly. If it is ever incorrect, the front-end may get confused and die. The reason for this is that the notion of the 'spelling' of a Token in diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html index c855a5057a62..9ac35e1dc2dc 100644 --- a/docs/LanguageExtensions.html +++ b/docs/LanguageExtensions.html @@ -27,6 +27,7 @@ td { <li><a href="#builtins">Builtin Functions</a> <ul> <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li> + <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li> </ul> </li> <li><a href="#targetspecific">Target-Specific Extensions</a> @@ -264,7 +265,7 @@ builtins that we need to implement.</p> <h3 id="__builtin_shufflevector">__builtin_shufflevector</h3> <!-- ======================================================================= --> -<p><tt>__builtin_shufflevector</tt> is used to expression generic vector +<p><tt>__builtin_shufflevector</tt> is used to express generic vector permutation/shuffle/swizzle operations. This builtin is also very important for the implementation of various target-specific header files like <tt><xmmintrin.h></tt>. @@ -310,6 +311,47 @@ with the same element type as vec1/vec2 but that has an element count equal to the number of indices specified. </p> +<p>Query for this feature with __has_builtin(__builtin_shufflevector).</p> + +<!-- ======================================================================= --> +<h3 id="__builtin_unreachable">__builtin_unreachable</h3> +<!-- ======================================================================= --> + +<p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in +the program cannot be reached, even if the compiler might otherwise think it +can. This is useful to improve optimization and eliminates certain warnings. +For example, without the <tt>__builtin_unreachable</tt> in the example below, +the compiler assumes that the inline asm can fall through and prints a "function +declared 'noreturn' should not return" warning. +</p> + +<p><b>Syntax:</b></p> + +<pre> +__builtin_unreachable() +</pre> + +<p><b>Example of Use:</b></p> + +<pre> +void myabort(void) __attribute__((noreturn)); +void myabort(void) { + asm("int3"); + __builtin_unreachable(); +} +</pre> + +<p><b>Description:</b></p> + +<p>The __builtin_unreachable() builtin has completely undefined behavior. Since +it has undefined behavior, it is a statement that it is never reached and the +optimizer can take advantage of this to produce better code. This builtin takes +no arguments and produces a void result. +</p> + +<p>Query for this feature with __has_builtin(__builtin_unreachable).</p> + + <!-- ======================================================================= --> <h2 id="targetspecific">Target-Specific Extensions</h2> <!-- ======================================================================= --> diff --git a/docs/UsersManual.html b/docs/UsersManual.html index 65415eea48d5..20fdda72dced 100644 --- a/docs/UsersManual.html +++ b/docs/UsersManual.html @@ -33,6 +33,12 @@ td { <li><a href="#general_features">Language and Target-Independent Features</a> <ul> <li><a href="#diagnostics">Controlling Errors and Warnings</a></li> + <ul> + <li><a href="#diagnostics_display">Controlling How Clang Displays Diagnostics</a></li> + <li><a href="#diagnostics_mappings">Diagnostic Mappings</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> + </ul> <li><a href="#precompiledheaders">Precompiled Headers</a></li> </ul> </li> @@ -362,7 +368,7 @@ by commenting them out.</p> <p>Clang provides a number of ways to control which code constructs cause it to emit errors and warning messages, and how they are displayed to the console.</p> -<h4>Controlling How Clang Displays Diagnostics</h4> +<h4 id="diagnostics_display">Controlling How Clang Displays Diagnostics</h4> <p>When Clang emits a diagnostic, it includes rich information in the output, and gives you fine-grain control over which information is printed. Clang has @@ -394,18 +400,64 @@ it:</p> <p>For more information please see <a href="#cl_diag_formatting">Formatting of Diagnostics</a>.</p> -<h4>Controlling Which Diagnostics Clang Generates</h4> +<h4 id="diagnostics_mappings">Diagnostic Mappings</h4> -<p>mappings: ignore, note, warning, error, fatal</p> +<p>All diagnostics are mapped into one of these 5 classes:</p> <p> -The two major classes are control from the command line and control via pragmas -in your code.</p> +<ul> +<li>Ignored</li> +<li>Note</li> +<li>Warning</li> +<li>Error</li> +<li>Fatal</li> +</ul></p> +<h4 id="diagnostics_commandline">Controlling Diagnostics via Command Line Flags</h4> <p>-W flags, -pedantic, etc</p> -<p>pragma GCC diagnostic</p> +<h4 id="diagnostics_pragmas">Controlling Diagnostics via Pragmas</h4> + +<p>Clang can also control what diagnostics are enabled through the use of +pragmas in the source code. This is useful for turning off specific warnings +in a section of source code. Clang supports GCC's pragma for compatibility +with existing source code, as well as several extensions. </p> + +<p>The pragma may control any warning that can be used from the command line. +Warnings may be set to ignored, warning, error, or fatal. The following +example code will tell Clang or GCC to ignore the -Wall warnings:</p> + +<pre> +#pragma GCC diagnostic ignored "-Wall" +</pre> + +<p>In addition to all of the functionality of provided by GCC's pragma, Clang +also allows you to push and pop the current warning state. This is particularly +useful when writing a header file that will be compiled by other people, because +you don't know what warning flags they build with.</p> + +<p>In the below example +-Wmultichar is ignored for only a single line of code, after which the +diagnostics return to whatever state had previously existed.</p> + +<pre> +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wmultichar" + +char b = 'df'; // no warning. + +#pragma clang diagnostic pop +</pre> + +<p>The push and pop pragmas will save and restore the full diagnostic state of +the compiler, regardless of how it was set. That means that it is possible to +use push and pop around GCC compatible diagnostics and Clang will push and pop +them appropriately, while GCC will ignore the pushes and pops as unknown +pragmas. It should be noted that while Clang supports the GCC pragma, Clang and +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> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <h3 id="precompiledheaders">Precompiled Headers</h3> @@ -465,6 +517,50 @@ for headers that are directly included within a source file. For example:</p> <tt>test.h</tt> since <tt>test.h</tt> was included directly in the source file and not specified on the command line using <tt>-include</tt>.</p> +<h4>Relocatable PCH Files</h4> +<p>It is sometimes necessary to build a precompiled header from headers that +are not yet in their final, installed locations. For example, one might build a +precompiled header within the build tree that is then meant to be installed +alongside the headers. Clang permits the creation of "relocatable" precompiled +headers, which are built with a given path (into the build directory) and can +later be used from an installed location.</p> + +<p>To build a relocatable precompiled header, place your headers into a +subdirectory whose structure mimics the installed location. For example, if you +want to build a precompiled header for the header <code>mylib.h</code> that +will be installed into <code>/usr/include</code>, create a subdirectory +<code>build/usr/include</code> and place the header <code>mylib.h</code> into +that subdirectory. If <code>mylib.h</code> depends on other headers, then +they can be stored within <code>build/usr/include</code> in a way that mimics +the installed location.</p> + +<p>Building a relocatable precompiled header requires two additional arguments. +First, pass the <code>--relocatable-pch</code> flag to indicate that the +resulting PCH file should be relocatable. Second, pass +<code>-isysroot /path/to/build</code>, which makes all includes for your +library relative to the build directory. For example:</p> + +<pre> + # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch +</pre> + +<p>When loading the relocatable PCH file, the various headers used in the PCH +file are found from the system header root. For example, <code>mylib.h</code> +can be found in <code>/usr/include/mylib.h</code>. If the headers are installed +in some other system root, the <code>-isysroot</code> option can be used provide +a different system root from which the headers will be based. For example, +<code>-isysroot /Developer/SDKs/MacOSX10.4u.sdk</code> will look for +<code>mylib.h</code> in +<code>/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h</code>.</p> + +<p>Relocatable precompiled headers are intended to be used in a limited number +of cases where the compilation environment is tightly controlled and the +precompiled header cannot be generated after headers have been installed. +Relocatable precompiled headers also have some performance impact, because +the difference in location between the header locations at PCH build time vs. +at the time of PCH use requires one of the PCH optimizations, +<code>stat()</code> caching, to be disabled. However, this change is only +likely to affect PCH files that reference a large number of headers.</p> <!-- ======================================================================= --> <h2 id="c">C Language Features</h2> @@ -500,7 +596,6 @@ variants "__asm__" and "__typeof__" are recognized in all modes.</li> <li>The Apple "blocks" extension is recognized by default in gnu* modes on some platforms; it can be enabled in any mode with the "-fblocks" option.</li> -<li>Some warnings are different.</li> </ul> <p>Differences between *89 and *99 modes:</p> diff --git a/docs/libIndex.html b/docs/libIndex.html new file mode 100644 index 000000000000..5693de80a868 --- /dev/null +++ b/docs/libIndex.html @@ -0,0 +1,267 @@ +<html> +<head> + <title>The Index Library</title> + <link type="text/css" rel="stylesheet" href="../menu.css" /> + <link type="text/css" rel="stylesheet" href="../content.css" /> + <style type="text/css"> + td { + vertical-align: top; + } + </style> +</head> + +<body> + +<!--#include virtual="../menu.html.incl"--> + +<div id="content"> + +<h1>The Index Library</h1> + + <p><b>Table of Contents</b></p> + <ul> + <li><a href="#philosophy">Design Philosophy</a></li> + <li><a href="#classes">Classes</a> + <ul> + <li><a href="#entity">Entity</a></li> + <li><a href="#astlocation">ASTLocation</a></li> + <li><a href="#declreferencemap">DeclReferenceMap</a></li> + </ul> + </li> + <li><a href="#functions">Functions</a> + <ul> + <li><a href="#resolveloc">ResolveLocationInAST</a></li> + </ul> + </li> + <li><a href="#astfiles">AST Files</a></li> + <li><a href="#indextest">index-test tool</a> + <ul> + <li><a href="#indextestusage">Usage</a></li> + <li><a href="#indextestexamples">Examples</a></li> + </ul> + </li> +</ul> + +<h2 id="philosophy">Design Philosophy</h2> + +<p> The Index library is meant to provide the basic infrastructure for + cross-translation-unit analysis and is primarily focused on indexing + related functionality. It provides an API for clients that need to + accurately map the AST nodes of the ASTContext to the locations in the source files. +It also allows them to analyze information across multiple translation units.</p> + +<p>As a "general rule", ASTContexts are considered the primary source of +information that a client wants about a translation unit. There will be no such class as an + "indexing database" that stores, for example, source locations of identifiers separately from ASTContext. +All the information that a client needs from a translation unit will be extracted from the ASTContext.</p> + +<h2 id="classes">Classes</h2> + +<h3 id="entity">Entity</h3> + +<p>To be able to reason about semantically the same Decls that are contained in multiple ASTContexts, the 'Entity' class was introduced. +An Entity is an ASTContext-independent "token" that can be created from a Decl (and a typename in the future) with +the purpose to "resolve" it into a Decl belonging to another ASTContext. Some examples to make the concept of Entities more clear:</p> + +<p> +t1.c: +<pre class="code_example"> +void foo(void); +void bar(void); +</pre> +</p> + +<p> +t2.c: +<pre class="code_example"> +void foo(void) { +} +</pre> +</p> + +<p> +Translation unit <code>t1.c</code> contains 2 Entities <code>foo</code> and <code>bar</code>, while <code>t2.c</code> contains 1 Entity <code>foo</code>. +Entities are uniqued in such a way that the Entity* pointer for <code>t1.c/foo</code> is the same as the Entity* pointer for <code>t2.c/foo</code>. +An Entity doesn't convey any information about the declaration, it is more like an opaque pointer used only to get the +associated Decl out of an ASTContext so that the actual information for the declaration can be accessed. +Another important aspect of Entities is that they can only be created/associated for declarations that are visible outside the +translation unit. This means that for: +</p> +<p> +t3.c: +<pre class="code_example"> +static void foo(void); +</pre> +</p> +<p> +there can be no Entity (if you ask for the Entity* of the static function <code>foo</code> you'll get a null pointer). +This is for 2 reasons: +<ul> +<li>To preserve the invariant that the same Entity* pointers refer to the same semantic Decls. + In the above example <code>t1.c/foo</code> and <code>t2.c/foo</code> are the same, while <code>t3.c/foo</code> is different.</li> +<li>The purpose of Entity is to get the same semantic Decl from multiple ASTContexts. For a Decl that is not visible + outside of its own translation unit, you don't need an Entity since it won't appear in another ASTContext.</li> +</ul> +</p> + +<h3 id="astlocation">ASTLocation</h3> + +Encapsulates a "point" in the AST tree of the ASTContext. +It represents either a Decl*, or a Stmt* along with its immediate Decl* parent. +An example for its usage is that libIndex will provide the references of <code>foo</code> in the form of ASTLocations, +"pointing" at the expressions that reference <code>foo</code>. + +<h3 id="declreferencemap">DeclReferenceMap</h3> + +Accepts an ASTContext and creates a mapping from NamedDecls to the ASTLocations that reference them (in the same ASTContext). + +<h2 id="functions">Functions</h2> + +<h3 id="resolveloc">ResolveLocationInAST</h3> + +A function that accepts an ASTContext and a SourceLocation which it resolves into an ASTLocation. + +<h2 id="astfiles">AST Files</h2> + +The precompiled headers implementation of clang (<a href="http://clang.llvm.org/docs/PCHInternals.html">PCH</a>) is ideal for storing an ASTContext in a compact form that +will be loaded later for AST analysis. An "AST file" refers to a translation unit that was "compiled" into a precompiled header file. + +<h2 id="indextest">index-test tool</h2> + +<h3 id="indextestusage">Usage</h3> + +A command-line tool that exercises the libIndex API, useful for testing its features. +As input it accepts multiple AST files (representing multiple translation units) and a few options: + +<p> +<pre class="code_example"> + -point-at [file:line:column] +</pre> +Resolves a [file:line:column] triplet into a ASTLocation from the first AST file. If no other option is specified, it prints the ASTLocation. +It also prints a declaration's associated doxygen comment, if one is available. +</p> + +<p> +<pre class="code_example"> + -print-refs +</pre> +Prints the ASTLocations that reference the declaration that was resolved out of the [file:line:column] triplet +</p> + +<p> +<pre class="code_example"> + -print-defs +</pre> +Prints the ASTLocations that define the resolved declaration +</p> + +<p> +<pre class="code_example"> + -print-decls +</pre> +Prints the ASTLocations that declare the resolved declaration +</p> + +<h3 id="indextestexamples">Examples</h3> + +<p> +Here's an example of using index-test: +</p> + +<p> +We have 3 files, +</p> + +<p> +foo.h: +<pre class="code_example"> +extern int global_var; + +void foo_func(int param1); +void bar_func(void); +</pre> + +t1.c: +<pre class="code_example"> +#include "foo.h" + +void foo_func(int param1) { + int local_var = global_var; + for (int for_var = 100; for_var < 500; ++for_var) { + local_var = param1 + for_var; + } + bar_func(); +} +</pre> + +t2.c: +<pre class="code_example"> +#include "foo.h" + +int global_var = 10; + +void bar_func(void) { + global_var += 100; + foo_func(global_var); +} +</pre> +</p> + +<p> +You first get AST files out of <code>t1.c</code> and <code>t2.c</code>: + +<pre class="code_example"> +$ clang-cc -emit-pch t1.c -o t1.ast +$ clang-cc -emit-pch t2.c -o t2.ast +</pre> +</p> + +<p> +Find the ASTLocation under this position of <code>t1.c</code>: +<pre class="code_example"> +[...] +void foo_func(int param1) { + int local_var = global_var; + ^ +[...] +</pre> + +<pre class="code_example"> +$ index-test t1.ast -point-at t1.c:4:23 +> [Decl: Var local_var | Stmt: DeclRefExpr global_var] <t1.c:4:19, t1.c:4:19> +</pre> +</p> + +<p> +Find the declaration: + +<pre class="code_example"> +$ index-test t1.ast -point-at t1.c:4:23 -print-decls +> [Decl: Var global_var] <foo.h:1:12, foo.h:1:12> +</pre> +</p> + +<p> +Find the references: + +<pre class="code_example"> +$ index-test t1.ast t2.ast -point-at t1.c:4:23 -print-refs +> [Decl: Var local_var | Stmt: DeclRefExpr global_var] <t1.c:4:19, t1.c:4:19> +> [Decl: Function bar_func | Stmt: DeclRefExpr global_var] <t2.c:6:3, t2.c:6:3> +> [Decl: Function bar_func | Stmt: DeclRefExpr global_var] <t2.c:7:12, t2.c:7:12> +</pre> +</p> + +<p> +Find definitions: + +<pre class="code_example"> +$ index-test t1.ast t2.ast -point-at t1.c:4:23 -print-defs +> [Decl: Var global_var] <t2.c:3:5, t2.c:3:18> +</pre> +</p> + +</div> + +</body> +</html> diff --git a/docs/tools/Makefile b/docs/tools/Makefile index 90eb7768f531..12696ef0b659 100644 --- a/docs/tools/Makefile +++ b/docs/tools/Makefile @@ -21,6 +21,7 @@ SRC_DOC_DIR= DST_HTML_DIR=html/ DST_MAN_DIR=man/man1/ DST_PS_DIR=ps/ +CLANG_VERSION := trunk # If we are in BUILD_FOR_WEBSITE mode, default to the all target. all:: html man ps @@ -39,6 +40,8 @@ else LEVEL := ../../../.. include $(LEVEL)/Makefile.common +CLANG_VERSION := $(shell cat $(PROJ_SRC_DIR)/../../VER) + SRC_DOC_DIR=$(PROJ_SRC_DIR)/ DST_HTML_DIR=$(PROJ_OBJ_DIR)/ DST_MAN_DIR=$(PROJ_OBJ_DIR)/ @@ -66,7 +69,7 @@ $(DST_HTML_DIR)%.html: %.pod $(DST_HTML_DIR)/.dir --podpath=. --infile=$< --outfile=$@ --title=$* $(DST_MAN_DIR)%.1: %.pod $(DST_MAN_DIR)/.dir - pod2man --release "clang 1.0" --center="Clang Tools Documentation" $< $@ + pod2man --release "clang $(CLANG_VERSION)" --center="Clang Tools Documentation" $< $@ $(DST_PS_DIR)%.ps: $(DST_MAN_DIR)%.1 $(DST_PS_DIR)/.dir groff -Tps -man $< > $@ diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod index c520f93997e5..daa738798930 100644 --- a/docs/tools/clang.pod +++ b/docs/tools/clang.pod @@ -378,8 +378,7 @@ Show commands to run and use verbose output. =over -=item -B<-fshow-column> +=item B<-fshow-column> B<-fshow-source-location> B<-fcaret-diagnostics> B<-fdiagnostics-fixit-info> @@ -428,13 +427,14 @@ Do not search the standard system directories for include files. =cut ## TODO, but do we really want people using this stuff? -=item B<-idirafter>I<directory> -=item B<-iquote>I<directory> -=item B<-isystem>I<directory> -=item B<-iprefix>I<directory> -=item B<-iwithprefix>I<directory> -=item B<-iwithprefixbefore>I<directory> -=item B<-isysroot> +#=item B<-idirafter>I<directory> +#=item B<-iquote>I<directory> +#=item B<-isystem>I<directory> +#=item B<-iprefix>I<directory> +#=item B<-iwithprefix>I<directory> +#=item B<-iwithprefixbefore>I<directory> +#=item B<-isysroot> + =pod @@ -445,21 +445,21 @@ Do not search the standard system directories for include files. =cut ### TODO someday. -=head2 Warning Control Options -=over -=back -=head2 Code Generation and Optimization Options -=over -=back -=head2 Assembler Options -=over -=back -=head2 Linker Options -=over -=back -=head2 Static Analyzer Options -=over -=back +#=head2 Warning Control Options +#=over +#=back +#=head2 Code Generation and Optimization Options +#=over +#=back +#=head2 Assembler Options +#=over +#=back +#=head2 Linker Options +#=over +#=back +#=head2 Static Analyzer Options +#=over +#=back =pod |