diff options
Diffstat (limited to 'clang')
23 files changed, 3249 insertions, 3425 deletions
diff --git a/clang/docs/AddressSanitizer.html b/clang/docs/AddressSanitizer.html deleted file mode 100644 index 397eafc2d51..00000000000 --- a/clang/docs/AddressSanitizer.html +++ /dev/null @@ -1,171 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ --> -<html> -<head> - <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> - <title>AddressSanitizer, a fast memory error detector</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>AddressSanitizer</h1> -<ul> - <li> <a href="#intro">Introduction</a> - <li> <a href="#howtobuild">How to Build</a> - <li> <a href="#usage">Usage</a> - <ul><li> <a href="#has_feature">__has_feature(address_sanitizer)</a></ul> - <ul><li> <a href="#no_address_safety_analysis"> - __attribute__((no_address_safety_analysis))</a></ul> - <li> <a href="#platforms">Supported Platforms</a> - <li> <a href="#limitations">Limitations</a> - <li> <a href="#status">Current Status</a> - <li> <a href="#moreinfo">More Information</a> -</ul> - -<h2 id="intro">Introduction</h2> -AddressSanitizer is a fast memory error detector. -It consists of a compiler instrumentation module and a run-time library. -The tool can detect the following types of bugs: -<ul> <li> Out-of-bounds accesses to heap, stack and globals - <li> Use-after-free - <li> Use-after-return (to some extent) - <li> Double-free, invalid free -</ul> -Typical slowdown introduced by AddressSanitizer is <b>2x</b>. - -<h2 id="howtobuild">How to build</h2> -Follow the <a href="../get_started.html">clang build instructions</a>. -CMake build is supported.<BR> - -<h2 id="usage">Usage</h2> -Simply compile and link your program with <tt>-fsanitize=address</tt> flag. <BR> -The AddressSanitizer run-time library should be linked to the final executable, -so make sure to use <tt>clang</tt> (not <tt>ld</tt>) for the final link step.<BR> -When linking shared libraries, the AddressSanitizer run-time is not linked, -so <tt>-Wl,-z,defs</tt> may cause link errors (don't use it with AddressSanitizer). <BR> - -To get a reasonable performance add <tt>-O1</tt> or higher. <BR> -To get nicer stack traces in error messages add -<tt>-fno-omit-frame-pointer</tt>. <BR> -To get perfect stack traces you may need to disable inlining (just use <tt>-O1</tt>) and tail call -elimination (<tt>-fno-optimize-sibling-calls</tt>). - -<pre> -% cat example_UseAfterFree.cc -int main(int argc, char **argv) { - int *array = new int[100]; - delete [] array; - return array[argc]; // BOOM -} -</pre> - -<pre> -# Compile and link -% clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc -</pre> -OR -<pre> -# Compile -% clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc -# Link -% clang -g -fsanitize=address example_UseAfterFree.o -</pre> - -If a bug is detected, the program will print an error message to stderr and exit with a -non-zero exit code. -Currently, AddressSanitizer does not symbolize its output, so you may need to use a -separate script to symbolize the result offline (this will be fixed in future). -<pre> -% ./a.out 2> log -% projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt -==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 -READ of size 4 at 0x7f7ddab8c084 thread T0 - #0 0x403c8c in main example_UseAfterFree.cc:4 - #1 0x7f7ddabcac4d in __libc_start_main ??:0 -0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) -freed by thread T0 here: - #0 0x404704 in operator delete[](void*) ??:0 - #1 0x403c53 in main example_UseAfterFree.cc:4 - #2 0x7f7ddabcac4d in __libc_start_main ??:0 -previously allocated by thread T0 here: - #0 0x404544 in operator new[](unsigned long) ??:0 - #1 0x403c43 in main example_UseAfterFree.cc:2 - #2 0x7f7ddabcac4d in __libc_start_main ??:0 -==9442== ABORTING -</pre> - -AddressSanitizer exits on the first detected error. This is by design. -One reason: it makes the generated code smaller and faster (both by ~5%). -Another reason: this makes fixing bugs unavoidable. With Valgrind, it is often -the case that users treat Valgrind warnings as false positives -(which they are not) and don't fix them. - - -<h3 id="has_feature">__has_feature(address_sanitizer)</h3> -In some cases one may need to execute different code depending on whether -AddressSanitizer is enabled. -<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a> -can be used for this purpose. -<pre> -#if defined(__has_feature) -# if __has_feature(address_sanitizer) - code that builds only under AddressSanitizer -# endif -#endif -</pre> - -<h3 id="no_address_safety_analysis">__attribute__((no_address_safety_analysis))</h3> -Some code should not be instrumented by AddressSanitizer. -One may use the function attribute -<a href="LanguageExtensions.html#address_sanitizer"> - <tt>no_address_safety_analysis</tt></a> -to disable instrumentation of a particular function. -This attribute may not be supported by other compilers, so we suggest to -use it together with <tt>__has_feature(address_sanitizer)</tt>. -Note: currently, this attribute will be lost if the function is inlined. - -<h2 id="platforms">Supported Platforms</h2> -AddressSanitizer is supported on -<ul><li>Linux i386/x86_64 (tested on Ubuntu 10.04 and 12.04). -<li>MacOS 10.6, 10.7 and 10.8 (i386/x86_64). -</ul> -Support for Linux ARM (and Android ARM) is in progress -(it may work, but is not guaranteed too). - - -<h2 id="limitations">Limitations</h2> -<ul> -<li> AddressSanitizer uses more real memory than a native run. -Exact overhead depends on the allocations sizes. The smaller the -allocations you make the bigger the overhead is. -<li> AddressSanitizer uses more stack memory. We have seen up to 3x increase. -<li> On 64-bit platforms AddressSanitizer maps (but not reserves) -16+ Terabytes of virtual address space. -This means that tools like <tt>ulimit</tt> may not work as usually expected. -<li> Static linking is not supported. -</ul> - - -<h2 id="status">Current Status</h2> -AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1. -The test suite is integrated into CMake build and can be run with -<tt>make check-asan</tt> command. - -<h2 id="moreinfo">More Information</h2> -<a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>. - - -</div> -</body> -</html> diff --git a/clang/docs/AddressSanitizer.rst b/clang/docs/AddressSanitizer.rst new file mode 100644 index 00000000000..0ee108bd9e4 --- /dev/null +++ b/clang/docs/AddressSanitizer.rst @@ -0,0 +1,158 @@ +================ +AddressSanitizer +================ + +.. contents:: + :local: + +Introduction +============ + +AddressSanitizer is a fast memory error detector. It consists of a +compiler instrumentation module and a run-time library. The tool can +detect the following types of bugs: + +- Out-of-bounds accesses to heap, stack and globals +- Use-after-free +- Use-after-return (to some extent) +- Double-free, invalid free + +Typical slowdown introduced by AddressSanitizer is **2x**. + +How to build +============ + +Follow the `clang build instructions <../get_started.html>`_. CMake +build is supported. + +Usage +===== + +Simply compile and link your program with ``-fsanitize=address`` flag. +The AddressSanitizer run-time library should be linked to the final +executable, so make sure to use ``clang`` (not ``ld``) for the final +link step. +When linking shared libraries, the AddressSanitizer run-time is not +linked, so ``-Wl,-z,defs`` may cause link errors (don't use it with +AddressSanitizer). +To get a reasonable performance add ``-O1`` or higher. +To get nicer stack traces in error messages add +``-fno-omit-frame-pointer``. +To get perfect stack traces you may need to disable inlining (just use +``-O1``) and tail call elimination (``-fno-optimize-sibling-calls``). + +:: + + % cat example_UseAfterFree.cc + int main(int argc, char **argv) { + int *array = new int[100]; + delete [] array; + return array[argc]; // BOOM + } + +:: + + # Compile and link + % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc + +OR + +:: + + # Compile + % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc + # Link + % clang -g -fsanitize=address example_UseAfterFree.o + +If a bug is detected, the program will print an error message to stderr +and exit with a non-zero exit code. Currently, AddressSanitizer does not +symbolize its output, so you may need to use a separate script to +symbolize the result offline (this will be fixed in future). + +:: + + % ./a.out 2> log + % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt + ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 + READ of size 4 at 0x7f7ddab8c084 thread T0 + #0 0x403c8c in main example_UseAfterFree.cc:4 + #1 0x7f7ddabcac4d in __libc_start_main ??:0 + 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) + freed by thread T0 here: + #0 0x404704 in operator delete[](void*) ??:0 + #1 0x403c53 in main example_UseAfterFree.cc:4 + #2 0x7f7ddabcac4d in __libc_start_main ??:0 + previously allocated by thread T0 here: + #0 0x404544 in operator new[](unsigned long) ??:0 + #1 0x403c43 in main example_UseAfterFree.cc:2 + #2 0x7f7ddabcac4d in __libc_start_main ??:0 + ==9442== ABORTING + +AddressSanitizer exits on the first detected error. This is by design. +One reason: it makes the generated code smaller and faster (both by +~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind, +it is often the case that users treat Valgrind warnings as false +positives (which they are not) and don't fix them. + +\_\_has\_feature(address\_sanitizer) +------------------------------------ + +In some cases one may need to execute different code depending on +whether AddressSanitizer is enabled. +`\_\_has\_feature <LanguageExtensions.html#__has_feature_extension>`_ +can be used for this purpose. + +:: + + #if defined(__has_feature) + # if __has_feature(address_sanitizer) + code that builds only under AddressSanitizer + # endif + #endif + +``__attribute__((no_address_safety_analysis))`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some code should not be instrumented by AddressSanitizer. One may use +the function attribute +`no_address_safety_analysis <LanguageExtensions.html#address_sanitizer>`_ +to disable instrumentation of a particular function. This attribute may +not be supported by other compilers, so we suggest to use it together +with ``__has_feature(address_sanitizer)``. Note: currently, this +attribute will be lost if the function is inlined. + +Supported Platforms +=================== + +AddressSanitizer is supported on + +- Linux i386/x86\_64 (tested on Ubuntu 10.04 and 12.04). +- MacOS 10.6, 10.7 and 10.8 (i386/x86\_64). + +Support for Linux ARM (and Android ARM) is in progress (it may work, but +is not guaranteed too). + +Limitations +=========== + +- AddressSanitizer uses more real memory than a native run. Exact + overhead depends on the allocations sizes. The smaller the + allocations you make the bigger the overhead is. +- AddressSanitizer uses more stack memory. We have seen up to 3x + increase. +- On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ + Terabytes of virtual address space. This means that tools like + ``ulimit`` may not work as usually expected. +- Static linking is not supported. + +Current Status +============== + +AddressSanitizer is fully functional on supported platforms starting +from LLVM 3.1. The test suite is integrated into CMake build and can be +run with ``make check-asan`` command. + +More Information +================ + +`http://code.google.com/p/address-sanitizer <http://code.google.com/p/address-sanitizer/>`_. diff --git a/clang/docs/AnalyzerRegions.html b/clang/docs/AnalyzerRegions.html deleted file mode 100644 index f9d33379204..00000000000 --- a/clang/docs/AnalyzerRegions.html +++ /dev/null @@ -1,260 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>Static Analyzer Design Document: Memory Regions</title> -</head> -<body> - -<h1>Static Analyzer Design Document: Memory Regions</h1> - -<h3>Authors</h3> - -<p>Ted Kremenek, <tt>kremenek at apple</tt><br> -Zhongxing Xu, <tt>xuzhongzhing at gmail</tt></p> - -<h2 id="intro">Introduction</h2> - -<p>The path-sensitive analysis engine in libAnalysis employs an extensible API -for abstractly modeling the memory of an analyzed program. This API employs the -concept of "memory regions" to abstractly model chunks of program memory such as -program variables and dynamically allocated memory such as those returned from -'malloc' and 'alloca'. Regions are hierarchical, with subregions modeling -subtyping relationships, field and array offsets into larger chunks of memory, -and so on.</p> - -<p>The region API consists of two components:</p> - -<ul> <li>A taxonomy and representation of regions themselves within the analyzer -engine. The primary definitions and interfaces are described in <tt><a -href="http://clang.llvm.org/doxygen/MemRegion_8h-source.html">MemRegion.h</a></tt>. -At the root of the region hierarchy is the class <tt>MemRegion</tt> with -specific subclasses refining the region concept for variables, heap allocated -memory, and so forth.</li> <li>The modeling of binding of values to regions. For -example, modeling the value stored to a local variable <tt>x</tt> consists of -recording the binding between the region for <tt>x</tt> (which represents the -raw memory associated with <tt>x</tt>) and the value stored to <tt>x</tt>. This -binding relationship is captured with the notion of "symbolic -stores."</li> </ul> - -<p>Symbolic stores, which can be thought of as representing the relation -<tt>regions -> values</tt>, are implemented by subclasses of the -<tt>StoreManager</tt> class (<tt><a -href="http://clang.llvm.org/doxygen/Store_8h-source.html">Store.h</a></tt>). A -particular StoreManager implementation has complete flexibility concerning the -following: - -<ul> -<li><em>How</em> to model the binding between regions and values</li> -<li><em>What</em> bindings are recorded -</ul> - -<p>Together, both points allow different StoreManagers to tradeoff between -different levels of analysis precision and scalability concerning the reasoning -of program memory. Meanwhile, the core path-sensitive engine makes no -assumptions about either points, and queries a StoreManager about the bindings -to a memory region through a generic interface that all StoreManagers share. If -a particular StoreManager cannot reason about the potential bindings of a given -memory region (e.g., '<tt>BasicStoreManager</tt>' does not reason about fields -of structures) then the StoreManager can simply return 'unknown' (represented by -'<tt>UnknownVal</tt>') for a particular region-binding. This separation of -concerns not only isolates the core analysis engine from the details of -reasoning about program memory but also facilities the option of a client of the -path-sensitive engine to easily swap in different StoreManager implementations -that internally reason about program memory in very different ways.</p> - -<p>The rest of this document is divided into two parts. We first discuss region -taxonomy and the semantics of regions. We then discuss the StoreManager -interface, and details of how the currently available StoreManager classes -implement region bindings.</p> - -<h2 id="regions">Memory Regions and Region Taxonomy</h2> - -<h3>Pointers</h3> - -<p>Before talking about the memory regions, we would talk about the pointers -since memory regions are essentially used to represent pointer values.</p> - -<p>The pointer is a type of values. Pointer values have two semantic aspects. -One is its physical value, which is an address or location. The other is the -type of the memory object residing in the address.</p> - -<p>Memory regions are designed to abstract these two properties of the pointer. -The physical value of a pointer is represented by MemRegion pointers. The rvalue -type of the region corresponds to the type of the pointee object.</p> - -<p>One complication is that we could have different view regions on the same -memory chunk. They represent the same memory location, but have different -abstract location, i.e., MemRegion pointers. Thus we need to canonicalize the -abstract locations to get a unique abstract location for one physical -location.</p> - -<p>Furthermore, these different view regions may or may not represent memory -objects of different types. Some different types are semantically the same, -for example, 'struct s' and 'my_type' are the same type.</p> - -<pre> -struct s; -typedef struct s my_type; -</pre> - -<p>But <tt>char</tt> and <tt>int</tt> are not the same type in the code below:</p> - -<pre> -void *p; -int *q = (int*) p; -char *r = (char*) p; -</pre> - -<p>Thus we need to canonicalize the MemRegion which is used in binding and -retrieving.</p> - -<h3>Regions</h3> -<p>Region is the entity used to model pointer values. A Region has the following -properties:</p> - -<ul> -<li>Kind</li> - -<li>ObjectType: the type of the object residing on the region.</li> - -<li>LocationType: the type of the pointer value that the region corresponds to. - Usually this is the pointer to the ObjectType. But sometimes we want to cache - this type explicitly, for example, for a CodeTextRegion.</li> - -<li>StartLocation</li> - -<li>EndLocation</li> -</ul> - -<h3>Symbolic Regions</h3> - -<p>A symbolic region is a map of the concept of symbolic values into the domain -of regions. It is the way that we represent symbolic pointers. Whenever a -symbolic pointer value is needed, a symbolic region is created to represent -it.</p> - -<p>A symbolic region has no type. It wraps a SymbolData. But sometimes we have -type information associated with a symbolic region. For this case, a -TypedViewRegion is created to layer the type information on top of the symbolic -region. The reason we do not carry type information with the symbolic region is -that the symbolic regions can have no type. To be consistent, we don't let them -to carry type information.</p> - -<p>Like a symbolic pointer, a symbolic region may be NULL, has unknown extent, -and represents a generic chunk of memory.</p> - -<p><em><b>NOTE</b>: We plan not to use loc::SymbolVal in RegionStore and remove it - gradually.</em></p> - -<p>Symbolic regions get their rvalue types through the following ways:</p> - -<ul> -<li>Through the parameter or global variable that points to it, e.g.: -<pre> -void f(struct s* p) { - ... -} -</pre> - -<p>The symbolic region pointed to by <tt>p</tt> has type <tt>struct -s</tt>.</p></li> - -<li>Through explicit or implicit casts, e.g.: -<pre> -void f(void* p) { - struct s* q = (struct s*) p; - ... -} -</pre> -</li> -</ul> - -<p>We attach the type information to the symbolic region lazily. For the first -case above, we create the <tt>TypedViewRegion</tt> only when the pointer is -actually used to access the pointee memory object, that is when the element or -field region is created. For the cast case, the <tt>TypedViewRegion</tt> is -created when visiting the <tt>CastExpr</tt>.</p> - -<p>The reason for doing lazy typing is that symbolic regions are sometimes only -used to do location comparison.</p> - -<h3>Pointer Casts</h3> - -<p>Pointer casts allow people to impose different 'views' onto a chunk of -memory.</p> - -<p>Usually we have two kinds of casts. One kind of casts cast down with in the -type hierarchy. It imposes more specific views onto more generic memory regions. -The other kind of casts cast up with in the type hierarchy. It strips away more -specific views on top of the more generic memory regions.</p> - -<p>We simulate the down casts by layering another <tt>TypedViewRegion</tt> on -top of the original region. We simulate the up casts by striping away the top -<tt>TypedViewRegion</tt>. Down casts is usually simple. For up casts, if the -there is no <tt>TypedViewRegion</tt> to be stripped, we return the original -region. If the underlying region is of the different type than the cast-to type, -we flag an error state.</p> - -<p>For toll-free bridging casts, we return the original region.</p> - -<p>We can set up a partial order for pointer types, with the most general type -<tt>void*</tt> at the top. The partial order forms a tree with <tt>void*</tt> as -its root node.</p> - -<p>Every <tt>MemRegion</tt> has a root position in the type tree. For example, -the pointee region of <tt>void *p</tt> has its root position at the root node of -the tree. <tt>VarRegion</tt> of <tt>int x</tt> has its root position at the 'int -type' node.</p> - -<p><tt>TypedViewRegion</tt> is used to move the region down or up in the tree. -Moving down in the tree adds a <tt>TypedViewRegion</tt>. Moving up in the tree -removes a <Tt>TypedViewRegion</tt>.</p> - -<p>Do we want to allow moving up beyond the root position? This happens -when:</p> <pre> int x; void *p = &x; </pre> - -<p>The region of <tt>x</tt> has its root position at 'int*' node. the cast to -void* moves that region up to the 'void*' node. I propose to not allow such -casts, and assign the region of <tt>x</tt> for <tt>p</tt>.</p> - -<p>Another non-ideal case is that people might cast to a non-generic pointer -from another non-generic pointer instead of first casting it back to the generic -pointer. Direct handling of this case would result in multiple layers of -TypedViewRegions. This enforces an incorrect semantic view to the region, -because we can only have one typed view on a region at a time. To avoid this -inconsistency, before casting the region, we strip the TypedViewRegion, then do -the cast. In summary, we only allow one layer of TypedViewRegion.</p> - -<h3>Region Bindings</h3> - -<p>The following region kinds are boundable: VarRegion, CompoundLiteralRegion, -StringRegion, ElementRegion, FieldRegion, and ObjCIvarRegion.</p> - -<p>When binding regions, we perform canonicalization on element regions and field -regions. This is because we can have different views on the same region, some -of which are essentially the same view with different sugar type names.</p> - -<p>To canonicalize a region, we get the canonical types for all TypedViewRegions -along the way up to the root region, and make new TypedViewRegions with those -canonical types.</p> - -<p>For Objective-C and C++, perhaps another canonicalization rule should be -added: for FieldRegion, the least derived class that has the field is used as -the type of the super region of the FieldRegion.</p> - -<p>All bindings and retrievings are done on the canonicalized regions.</p> - -<p>Canonicalization is transparent outside the region store manager, and more -specifically, unaware outside the Bind() and Retrieve() method. We don't need to -consider region canonicalization when doing pointer cast.</p> - -<h3>Constraint Manager</h3> - -<p>The constraint manager reasons about the abstract location of memory objects. -We can have different views on a region, but none of these views changes the -location of that object. Thus we should get the same abstract location for those -regions.</p> - -</body> -</html> diff --git a/clang/docs/AnalyzerRegions.rst b/clang/docs/AnalyzerRegions.rst new file mode 100644 index 00000000000..80b3882bc94 --- /dev/null +++ b/clang/docs/AnalyzerRegions.rst @@ -0,0 +1,259 @@ +=============================================== +Static Analyzer Design Document: Memory Regions +=============================================== + +Authors: Ted Kremenek, ``kremenek at apple``, +Zhongxing Xu, ``xuzhongzhing at gmail`` + +Introduction +============ + +The path-sensitive analysis engine in libAnalysis employs an extensible +API for abstractly modeling the memory of an analyzed program. This API +employs the concept of "memory regions" to abstractly model chunks of +program memory such as program variables and dynamically allocated +memory such as those returned from 'malloc' and 'alloca'. Regions are +hierarchical, with subregions modeling subtyping relationships, field +and array offsets into larger chunks of memory, and so on. + +The region API consists of two components: + +- A taxonomy and representation of regions themselves within the + analyzer engine. The primary definitions and interfaces are described + in ``MemRegion.h``. At the root of the region hierarchy is the class + ``MemRegion`` with specific subclasses refining the region concept + for variables, heap allocated memory, and so forth. +- The modeling of binding of values to regions. For example, modeling + the value stored to a local variable ``x`` consists of recording the + binding between the region for ``x`` (which represents the raw memory + associated with ``x``) and the value stored to ``x``. This binding + relationship is captured with the notion of "symbolic stores." + +Symbolic stores, which can be thought of as representing the relation +``regions -> values``, are implemented by subclasses of the +``StoreManager`` class (``Store.h``). A particular StoreManager +implementation has complete flexibility concerning the following: + +- *How* to model the binding between regions and values +- *What* bindings are recorded + +Together, both points allow different StoreManagers to tradeoff between +different levels of analysis precision and scalability concerning the +reasoning of program memory. Meanwhile, the core path-sensitive engine +makes no assumptions about either points, and queries a StoreManager +about the bindings to a memory region through a generic interface that +all StoreManagers share. If a particular StoreManager cannot reason +about the potential bindings of a given memory region (e.g., +'``BasicStoreManager``' does not reason about fields of structures) then +the StoreManager can simply return 'unknown' (represented by +'``UnknownVal``') for a particular region-binding. This separation of +concerns not only isolates the core analysis engine from the details of +reasoning about program memory but also facilities the option of a +client of the path-sensitive engine to easily swap in different +StoreManager implementations that internally reason about program memory +in very different ways. + +The rest of this document is divided into two parts. We first discuss +region taxonomy and the semantics of regions. We then discuss the +StoreManager interface, and details of how the currently available +StoreManager classes implement region bindings. + +Memory Regions and Region Taxonomy +================================== + +Pointers +-------- + +Before talking about the memory regions, we would talk about the +pointers since memory regions are essentially used to represent pointer +values. + +The pointer is a type of values. Pointer values have two semantic +aspects. One is its physical value, which is an address or location. The +other is the type of the memory object residing in the address. + +Memory regions are designed to abstract these two properties of the +pointer. The physical value of a pointer is represented by MemRegion +pointers. The rvalue type of the region corresponds to the type of the +pointee object. + +One complication is that we could have different view regions on the +same memory chunk. They represent the same memory location, but have +different abstract location, i.e., MemRegion pointers. Thus we need to +canonicalize the abstract locations to get a unique abstract location +for one physical location. + +Furthermore, these different view regions may or may not represent +memory objects of different types. Some different types are semantically +the same, for example, 'struct s' and 'my\_type' are the same type. + +:: + + struct s; + typedef struct s my_type; + +But ``char`` and ``int`` are not the same type in the code below: + +:: + + void *p; + int *q = (int*) p; + char *r = (char*) p; + +Thus we need to canonicalize the MemRegion which is used in binding and +retrieving. + +Regions +------- + +Region is the entity used to model pointer values. A Region has the +following properties: + +- Kind +- ObjectType: the type of the object residing on the region. +- LocationType: the type of the pointer value that the region + corresponds to. Usually this is the pointer to the ObjectType. But + sometimes we want to cache this type explicitly, for example, for a + CodeTextRegion. +- StartLocation +- EndLocation + +Symbolic Regions +---------------- + +A symbolic region is a map of the concept of symbolic values into the +domain of regions. It is the way that we represent symbolic pointers. +Whenever a symbolic pointer value is needed, a symbolic region is +created to represent it. + +A symbolic region has no type. It wraps a SymbolData. But sometimes we +have type information associated with a symbolic region. For this case, +a TypedViewRegion is created to layer the type information on top of the +symbolic region. The reason we do not carry type information with the +symbolic region is that the symbolic regions can have no type. To be +consistent, we don't let them to carry type information. + +Like a symbolic pointer, a symbolic region may be NULL, has unknown +extent, and represents a generic chunk of memory. + +.. note:: + We plan not to use loc::SymbolVal in RegionStore and remove it + gradually. + +Symbolic regions get their rvalue types through the following ways: + +- Through the parameter or global variable that points to it, e.g.: + + :: + + void f(struct s* p) { + ... + } + + The symbolic region pointed to by ``p`` has type ``struct s``. + +- Through explicit or implicit casts, e.g.: + + :: + + void f(void* p) { + struct s* q = (struct s*) p; + ... + } + +We attach the type information to the symbolic region lazily. For the +first case above, we create the ``TypedViewRegion`` only when the +pointer is actually used to access the pointee memory object, that is +when the element or field region is created. For the cast case, the +``TypedViewRegion`` is created when visiting the ``CastExpr``. + +The reason for doing lazy typing is that symbolic regions are sometimes +only used to do location comparison. + +Pointer Casts +------------- + +Pointer casts allow people to impose different 'views' onto a chunk of +memory. + +Usually we have two kinds of casts. One kind of casts cast down with in +the type hierarchy. It imposes more specific views onto more generic +memory regions. The other kind of casts cast up with in the type +hierarchy. It strips away more specific views on top of the more generic +memory regions. + +We simulate the down casts by layering another ``TypedViewRegion`` on +top of the original region. We simulate the up casts by striping away +the top ``TypedViewRegion``. Down casts is usually simple. For up casts, +if the there is no ``TypedViewRegion`` to be stripped, we return the +original region. If the underlying region is of the different type than +the cast-to type, we flag an error state. + +For toll-free bridging casts, we return the original region. + +We can set up a partial order for pointer types, with the most general +type ``void*`` at the top. The partial order forms a tree with ``void*`` +as its root node. + +Every ``MemRegion`` has a root position in the type tree. For example, +the pointee region of ``void *p`` has its root position at the root node +of the tree. ``VarRegion`` of ``int x`` has its root position at the +'int type' node. + +``TypedViewRegion`` is used to move the region down or up in the tree. +Moving down in the tree adds a ``TypedViewRegion``. Moving up in the +tree removes a ``TypedViewRegion``. + +Do we want to allow moving up beyond the root position? This happens +when: + +:: + + int x; void *p = &x; + +The region of ``x`` has its root position at 'int\*' node. the cast to +void\* moves that region up to the 'void\*' node. I propose to not allow +such casts, and assign the region of ``x`` for ``p``. + +Another non-ideal case is that people might cast to a non-generic +pointer from another non-generic pointer instead of first casting it +back to the generic pointer. Direct handling of this case would result +in multiple layers of TypedViewRegions. This enforces an incorrect +semantic view to the region, because we can only have one typed view on +a region at a time. To avoid this inconsistency, before casting the +region, we strip the TypedViewRegion, then do the cast. In summary, we +only allow one layer of TypedViewRegion. + +Region Bindings +--------------- + +The following region kinds are boundable: VarRegion, +CompoundLiteralRegion, StringRegion, ElementRegion, FieldRegion, and +ObjCIvarRegion. + +When binding regions, we perform canonicalization on element regions and +field regions. This is because we can have different views on the same +region, some of which are essentially the same view with different sugar +type names. + +To canonicalize a region, we get the canonical types for all +TypedViewRegions along the way up to the root region, and make new +TypedViewRegions with those canonical types. + +For Objective-C and C++, perhaps another canonicalization rule should be +added: for FieldRegion, the least derived class that has the field is +used as the type of the super region of the FieldRegion. + +All bindings and retrievings are done on the canonicalized regions. + +Canonicalization is transparent outside the region store manager, and +more specifically, unaware outside the Bind() and Retrieve() method. We +don't need to consider region canonicalization when doing pointer cast. + +Constraint Manager +------------------ + +The constraint manager reasons about the abstract location of memory +objects. We can have different views on a region, but none of these +views changes the location of that object. Thus we should get the same +abstract location for those regions. diff --git a/clang/docs/ClangPlugins.html b/clang/docs/ClangPlugins.html deleted file mode 100644 index ed560fe840b..00000000000 --- a/clang/docs/ClangPlugins.html +++ /dev/null @@ -1,170 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>Clang Plugins</title> -<link type="text/css" rel="stylesheet" href="../menu.css"> -<link type="text/css" rel="stylesheet" href="../content.css"> -</head> -<body> - -<!--#include virtual="../menu.html.incl"--> - -<div id="content"> - -<h1>Clang Plugins</h1> -<p>Clang Plugins make it possible to run extra user defined actions during -a compilation. This document will provide a basic walkthrough of how to write -and run a Clang Plugin.</p> - -<!-- ======================================================================= --> -<h2 id="intro">Introduction</h2> -<!-- ======================================================================= --> - -<p>Clang Plugins run FrontendActions over code. See the -<a href="RAVFrontendAction.html">FrontendAction tutorial</a> on how to write a -FrontendAction using the RecursiveASTVisitor. In this tutorial, we'll -demonstrate how to write a simple clang plugin. -</p> - -<!-- ======================================================================= --> -<h2 id="pluginactions">Writing a PluginASTAction</h2> -<!-- ======================================================================= --> - -<p>The main difference from writing normal FrontendActions is that you can -handle plugin command line options. The -PluginASTAction base class declares a ParseArgs method which you have to -implement in your plugin. -</p> -<pre> - bool ParseArgs(const CompilerInstance &CI, - const std::vector<std::string>& args) { - for (unsigned i = 0, e = args.size(); i != e; ++i) { - if (args[i] == "-some-arg") { - // Handle the command line argument. - } - } - return true; - } -</pre> - -<!-- ======================================================================= --> -<h2 id="registerplugin">Registering a plugin</h2> -<!-- ======================================================================= --> - -<p>A plugin is loaded from a dynamic library at runtime by the compiler. To register -a plugin in a library, use FrontendPluginRegistry::Add:</p> -<pre> - static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description"); -</pre> - -<!-- ======================================================================= --> -<h2 id="example">Putting it all together</h2> -<!-- ======================================================================= --> - -<p>Let's look at an example plugin that prints top-level function names. -This example is also checked into the clang repository; please also take a look -at the latest <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup">checked in version of PrintFunctionNames.cpp</a>.</p> -<pre> -#include "clang/Frontend/FrontendPluginRegistry.h" -#include "clang/AST/ASTConsumer.h" -#include "clang/AST/AST.h" -#include "clang/Frontend/CompilerInstance.h" -#include "llvm/Support/raw_ostream.h" -using namespace clang; - -namespace { - -class PrintFunctionsConsumer : public ASTConsumer { -public: - virtual bool HandleTopLevelDecl(DeclGroupRef DG) { - for (DeclGroupRef::iterator i = DG.begin(), e = DG.end(); i != e; ++i) { - const Decl *D = *i; - if (const NamedDecl *ND = dyn_cast<NamedDecl>(D)) - llvm::errs() << "top-level-decl: \"" << ND->getNameAsString() << "\"\n"; - } - - return true; - } -}; - -class PrintFunctionNamesAction : public PluginASTAction { -protected: - ASTConsumer *CreateASTConsumer(CompilerInstance &CI, llvm::StringRef) { - return new PrintFunctionsConsumer(); - } - - bool ParseArgs(const CompilerInstance &CI, - const std::vector<std::string>& args) { - for (unsigned i = 0, e = args.size(); i != e; ++i) { - llvm::errs() << "PrintFunctionNames arg = " << args[i] << "\n"; - - // Example error handling. - if (args[i] == "-an-error") { - DiagnosticsEngine &D = CI.getDiagnostics(); - unsigned DiagID = D.getCustomDiagID( - DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'"); - D.Report(DiagID); - return false; - } - } - if (args.size() && args[0] == "help") - PrintHelp(llvm::errs()); - - return true; - } - void PrintHelp(llvm::raw_ostream& ros) { - ros << "Help for PrintFunctionNames plugin goes here\n"; - } - -}; - -} - -static FrontendPluginRegistry::Add<PrintFunctionNamesAction> -X("print-fns", "print function names"); -</pre> - -<!-- ======================================================================= --> -<h2 id="running">Running the plugin</h2> -<!-- ======================================================================= --> - -<p>To run a plugin, the dynamic library containing the plugin registry must be -loaded via the -load command line option. This will load all plugins that are -registered, and you can select the plugins to run by specifying the -plugin -option. Additional parameters for the plugins can be passed with -plugin-arg-<plugin-name>.</p> - -<p>Note that those options must reach clang's cc1 process. There are two -ways to do so:</p> -<ul> -<li> -Directly call the parsing process by using the -cc1 option; this has the -downside of not configuring the default header search paths, so you'll need to -specify the full system path configuration on the command line. -</li> -<li> -Use clang as usual, but prefix all arguments to the cc1 process with -Xclang. -</li> -</ul> -<p>For example, to run the print-function-names plugin over a source file in clang, -first build the plugin, and then call clang with the plugin from the source tree:</p> -<pre> - $ export BD=/path/to/build/directory - $ (cd $BD && make PrintFunctionNames ) - $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \ - -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \ - -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \ - tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \ - -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \ - -plugin -Xclang print-fns -</pre> - -<p>Also see the print-function-name plugin example's -<a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup">README</a></p> - - - -</div> -</body> -</html> - diff --git a/clang/docs/ClangPlugins.rst b/clang/docs/ClangPlugins.rst new file mode 100644 index 00000000000..cf538172298 --- /dev/null +++ b/clang/docs/ClangPlugins.rst @@ -0,0 +1,149 @@ +============= +Clang Plugins +============= + +Clang Plugins make it possible to run extra user defined actions during +a compilation. This document will provide a basic walkthrough of how to +write and run a Clang Plugin. + +Introduction +============ + +Clang Plugins run FrontendActions over code. See the :doc:`FrontendAction +tutorial <RAVFrontendAction>` on how to write a FrontendAction +using the RecursiveASTVisitor. In this tutorial, we'll demonstrate how +to write a simple clang plugin. + +Writing a PluginASTAction +========================= + +The main difference from writing normal FrontendActions is that you can +handle plugin command line options. The PluginASTAction base class +declares a ParseArgs method which you have to implement in your plugin. + +:: + + bool ParseArgs(const CompilerInstance &CI, + const std::vector<std::string>& args) { + for (unsigned i = 0, e = args.size(); i != e; ++i) { + if (args[i] == "-some-arg") { + // Handle the command line argument. + } + } + return true; + } + +Registering a plugin +==================== + +A plugin is loaded from a dynamic library at runtime by the compiler. To +register a plugin in a library, use FrontendPluginRegistry::Add: + +:: + + static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description"); + +Putting it all together +======================= + +Let's look at an example plugin that prints top-level function names. +This example is also checked into the clang repository; please also take +a look at the latest `checked in version of +PrintFunctionNames.cpp <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_. + +:: + + #include "clang/Frontend/FrontendPluginRegistry.h" + #include "clang/AST/ASTConsumer.h" + #include "clang/AST/AST.h" + #include "clang/Frontend/CompilerInstance.h" + #include "llvm/Support/raw_ostream.h" + using namespace clang; + + namespace { + + class PrintFunctionsConsumer : public ASTConsumer { + public: + virtual bool HandleTopLevelDecl(DeclGroupRef DG) { + for (DeclGroupRef::iterator i = DG.begin(), e = DG.end(); i != e; ++i) { + const Decl *D = *i; + if (const NamedDecl *ND = dyn_cast<NamedDecl>(D)) + llvm::errs() << "top-level-decl: \"" << ND->getNameAsString() << "\"\n"; + } + + return true; + } + }; + + class PrintFunctionNamesAction : public PluginASTAction { + protected: + ASTConsumer *CreateASTConsumer(CompilerInstance &CI, llvm::StringRef) { + return new PrintFunctionsConsumer(); + } + + bool ParseArgs(const CompilerInstance &CI, + const std::vector<std::string>& args) { + for (unsigned i = 0, e = args.size(); i != e; ++i) { + llvm::errs() << "PrintFunctionNames arg = " << args[i] << "\n"; + + // Example error handling. + if (args[i] == "-an-error") { + DiagnosticsEngine &D = CI.getDiagnostics(); + unsigned DiagID = D.getCustomDiagID( + DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'"); + D.Report(DiagID); + return false; + } + } + if (args.size() && args[0] == "help") + PrintHelp(llvm::errs()); + + return true; + } + void PrintHelp(llvm::raw_ostream& ros) { + ros << "Help for PrintFunctionNames plugin goes here\n"; + } + + }; + + } + + static FrontendPluginRegistry::Add<PrintFunctionNamesAction> + X("print-fns", "print function names"); + +Running the plugin +================== + +To run a plugin, the dynamic library containing the plugin registry must +be loaded via the -load command line option. This will load all plugins +that are registered, and you can select the plugins to run by specifying +the -plugin option. Additional parameters for the plugins can be passed +with -plugin-arg-<plugin-name>. + +Note that those options must reach clang's cc1 process. There are two +ways to do so: + +- Directly call the parsing process by using the -cc1 option; this has + the downside of not configuring the default header search paths, so + you'll need to specify the full system path configuration on the + command line. +- Use clang as usual, but prefix all arguments to the cc1 process with + -Xclang. + +For example, to run the print-function-names plugin over a source file +in clang, first build the plugin, and then call clang with the plugin +from the source tree: + +:: + + $ export BD=/path/to/build/directory + $ (cd $BD && make PrintFunctionNames ) + $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \ + -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \ + -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \ + tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \ + -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \ + -plugin -Xclang print-fns + +Also see the print-function-name plugin example's +`README <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_ diff --git a/clang/docs/ClangTools.html b/clang/docs/ClangTools.html deleted file mode 100644 index 4de57bd2185..00000000000 --- a/clang/docs/ClangTools.html +++ /dev/null @@ -1,110 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>Clang Tools</title> -<link type="text/css" rel="stylesheet" href="../menu.css"> -<link type="text/css" rel="stylesheet" href="../content.css"> -</head> -<body> - -<!--#include virtual="../menu.html.incl"--> - -<div id="content"> - -<h1>Clang Tools</h1> -<p>Clang Tools are standalone command line (and potentially GUI) tools design -for use by C++ developers who are already using and enjoying Clang as their -compiler. These tools provide developer-oriented functionality such as fast -syntax checking, automatic formatting, refactoring, etc.</p> - -<p>Only a couple of the most basic and fundamental tools are kept in the primary -Clang Subversion project. The rest of the tools are kept in a side-project so -that developers who don't want or need to build them don't. If you want to get -access to the extra Clang Tools repository, simply check it out into the tools -tree of your Clang checkout and follow the usual process for building and -working with a combined LLVM/Clang checkout:</p> -<ul> - <li>With Subversion: - <ul> - <li><tt>cd llvm/tools/clang/tools</tt></li> - <li><tt>svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk - extra</tt></li> - </ul> - </li> - <li>Or with Git: - <ul> - <li><tt>cd llvm/tools/clang/tools</tt></li> - <li><tt>git clone http://llvm.org/git/clang-tools-extra.git extra</tt></li> - </ul> - </li> -</ul> - -<p>This document describes a high-level overview of the organization of Clang -Tools within the project as well as giving an introduction to some of the more -important tools. However, it should be noted that this document is currently -focused on Clang and Clang Tool developers, not on end users of these tools.</p> - -<!-- ======================================================================= --> -<h2 id="org">Clang Tools Organization</h2> -<!-- ======================================================================= --> - -<p>Clang Tools are CLI or GUI programs that are intended to be directly used by -C++ developers. That is they are <em>not</em> primarily for use by Clang -developers, although they are hopefully useful to C++ developers who happen to -work on Clang, and we try to actively dogfood their functionality. They are -developed in three components: the underlying infrastructure for building -a standalone tool based on Clang, core shared logic used by many different tools -in the form of refactoring and rewriting libraries, and the tools -themselves.</p> - -<p>The underlying infrastructure for Clang Tools is the -<a href="LibTooling.html">LibTooling</a> platform. See its documentation for -much more detailed information about how this infrastructure works. The common -refactoring and rewriting toolkit-style library is also part of LibTooling -organizationally.</p> - -<p>A few Clang Tools are developed along side the core Clang libraries as -examples and test cases of fundamental functionality. However, most of the tools -are developed in a side repository to provide easy separation from the core -libraries. We intentionally do not support public libraries in the side -repository, as we want to carefully review and find good APIs for libraries as -they are lifted out of a few tools and into the core Clang library set.</p> - -<p>Regardless of which repository Clang Tools' code resides in, the development -process and practices for all Clang Tools are exactly those of Clang itself. -They are entirely within the Clang <em>project</em>, regardless of the version -control scheme.</p> - - -<!-- ======================================================================= --> -<h2 id="coretools">Core Clang Tools</h2> -<!-- ======================================================================= --> - -<p>The core set of Clang tools that are within the main repository are tools -that very specifically compliment, and allow use and testing of <em>Clang</em> -specific functionality.</p> - -<h3 id="clang-check"><tt>clang-check</tt></h3> -<p>This tool combines the LibTooling framework for running a Clang tool with the -basic Clang diagnostics by syntax checking specific files in a fast, command -line interface. It can also accept flags to re-display the diagnostics in -different formats with different flags, suitable for use driving an IDE or -editor. Furthermore, it can be used in fixit-mode to directly apply fixit-hints -offered by clang.</p> - -<p>FIXME: Link to user-oriented clang-check documentation.</p> - -<!-- ======================================================================= --> -<h2 id="registerplugin">Extra Clang Tools</h2> -<!-- ======================================================================= --> - -<p>As various categories of Clang Tools are added to the extra repository, -they'll be tracked here. The focus of this documentation is on the scope and -features of the tools for other tool developers; each tool should provide its -own user-focused documentation.</p> - -</div> -</body> -</html> - diff --git a/clang/docs/ClangTools.rst b/clang/docs/ClangTools.rst new file mode 100644 index 00000000000..f3bdb0742f3 --- /dev/null +++ b/clang/docs/ClangTools.rst @@ -0,0 +1,91 @@ +=========== +Clang Tools +=========== + +Clang Tools are standalone command line (and potentially GUI) tools +design for use by C++ developers who are already using and enjoying +Clang as their compiler. These tools provide developer-oriented +functionality such as fast syntax checking, automatic formatting, +refactoring, etc. + +Only a couple of the most basic and fundamental tools are kept in the +primary Clang Subversion project. The rest of the tools are kept in a +side-project so that developers who don't want or need to build them +don't. If you want to get access to the extra Clang Tools repository, +simply check it out into the tools tree of your Clang checkout and +follow the usual process for building and working with a combined +LLVM/Clang checkout: + +- With Subversion: + + - ``cd llvm/tools/clang/tools`` + - ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra`` + +- Or with Git: + + - ``cd llvm/tools/clang/tools`` + - ``git clone http://llvm.org/git/clang-tools-extra.git extra`` + +This document describes a high-level overview of the organization of +Clang Tools within the project as well as giving an introduction to some +of the more important tools. However, it should be noted that this +document is currently focused on Clang and Clang Tool developers, not on +end users of these tools. + +Clang Tools Organization +======================== + +Clang Tools are CLI or GUI programs that are intended to be directly +used by C++ developers. That is they are *not* primarily for use by +Clang developers, although they are hopefully useful to C++ developers +who happen to work on Clang, and we try to actively dogfood their +functionality. They are developed in three components: the underlying +infrastructure for building a standalone tool based on Clang, core +shared logic used by many different tools in the form of refactoring and +rewriting libraries, and the tools themselves. + +The underlying infrastructure for Clang Tools is the +:doc:`LibTooling <LibTooling>` platform. See its documentation for much +more detailed information about how this infrastructure works. The +common refactoring and rewriting toolkit-style library is also part of +LibTooling organizationally. + +A few Clang Tools are developed along side the core Clang libraries as +examples and test cases of fundamental functionality. However, most of +the tools are developed in a side repository to provide easy separation +from the core libraries. We intentionally do not support public +libraries in the side repository, as we want to carefully review and +find good APIs for libraries as they are lifted out of a few tools and +into the core Clang library set. + +Regardless of which repository Clang Tools' code resides in, the +development process and practices for all Clang Tools are exactly those +of Clang itself. They are entirely within the Clang *project*, +regardless of the version control scheme. + +Core Clang Tools +================ + +The core set of Clang tools that are within the main repository are +tools that very specifically compliment, and allow use and testing of +*Clang* specific functionality. + +``clang-check`` +~~~~~~~~~~~~~~~ + +This tool combines the LibTooling framework for running a Clang tool +with the basic Clang diagnostics by syntax checking specific files in a +fast, command line interface. It can also accept flags to re-display the +diagnostics in different formats with different flags, suitable for use +driving an IDE or editor. Furthermore, it can be used in fixit-mode to +directly apply fixit-hints offered by clang. + +FIXME: Link to user-oriented clang-check documentation. + +Extra Clang Tools +================= + +As various categories of Clang Tools are added to the extra repository, +they'll be tracked here. The focus of this documentation is on the scope +and features of the tools for other tool developers; each tool should +provide its own user-focused documentation. diff --git a/clang/docs/HowToSetupToolingForLLVM.html b/clang/docs/HowToSetupToolingForLLVM.html deleted file mode 100644 index 022ed9ce9cb..00000000000 --- a/clang/docs/HowToSetupToolingForLLVM.html +++ /dev/null @@ -1,212 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>How To Setup Clang Tooling For LLVM</title> -<link type="text/css" rel="stylesheet" href="../menu.css"> -<link type="text/css" rel="stylesheet" href="../content.css"> -</head> -<body> - -<!--#include virtual="../menu.html.incl"--> - -<div id="content"> - -<h1>How To Setup Clang Tooling For LLVM</h1> -<p>Clang Tooling provides infrastructure to write tools that need syntactic and -semantic infomation about a program. This term also relates to a set of specific -tools using this infrastructure (e.g. <code>clang-check</code>). This document -provides information on how to set up and use Clang Tooling for the LLVM source -code.</p> - - -<!-- ======================================================================= --> -<h2><a name="introduction">Introduction</a></h2> -<!-- ======================================================================= --> - -<p>Clang Tooling needs a compilation database to figure out specific build -options for each file. Currently it can create a compilation database from the -<code>compilation_commands.json</code> file, generated by CMake. When invoking -clang tools, you can either specify a path to a build directory using a command -line parameter <code>-p</code> or let Clang Tooling find this file in your -source tree. In either case you need to configure your build using CMake to use -clang tools.</p> - -<!-- ======================================================================= --> -<h2><a name="using-make">Setup Clang Tooling Using CMake and Make</a></h2> -<!-- ======================================================================= --> - -<p>If you intend to use make to build LLVM, you should have CMake 2.8.6 or later -installed (can be found <a href="http://cmake.org">here</a>).</p> -<p>First, you need to generate Makefiles for LLVM with CMake. You need to make -a build directory and run CMake from it:</p> -<pre> - mkdir your/build/directory - cd your/build/directory - cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources -</pre> - -<p>If you want to use clang instead of GCC, you can add -<code>-DCMAKE_C_COMPILER=/path/to/clang - -DCMAKE_CXX_COMPILER=/path/to/clang++</code>. -You can also use ccmake, which provides a curses interface to configure CMake -variables for lazy people.</p> - -<p>As a result, the new <code>compile_commands.json</code> file should appear in -the current directory. You should link it to the LLVM source tree so that Clang -Tooling is able to use it:</p> -<pre> - ln -s $PWD/compile_commands.json path/to/llvm/source/ -</pre> - -<p>Now you are ready to build and test LLVM using make:</p> -<pre> - make check-all -</pre> - -<!-- ======================================================================= --> -<h2><a name="using-tools">Using Clang Tools</a></h2> -<!-- ======================================================================= --> - -<p>After you completed the previous steps, you are ready to run clang tools. If -you have a recent clang installed, you should have <code>clang-check</code> in -$PATH. Try to run it on any .cpp file inside the LLVM source tree:</p> -<pre> - clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp -</pre> -<p>If you're using vim, it's convenient to have clang-check integrated. Put this -into your .vimrc:</p> -<pre> -function! ClangCheckImpl(cmd) - if &autowrite | wall | endif - echo "Running " . a:cmd . " ..." - let l:output = system(a:cmd) - cexpr l:output - cwindow - let w:quickfix_title = a:cmd - if v:shell_error != 0 - cc - endif - let g:clang_check_last_cmd = a:cmd -endfunction - -function! ClangCheck() - let l:filename = expand('%') - if l:filename =~ '\.\(cpp\|cxx\|cc\|c\)$' - call ClangCheckImpl("clang-check " . l:filename) - elseif exists("g:clang_check_last_cmd") - call ClangCheckImpl(g:clang_check_last_cmd) - else - echo "Can't detect file's compilation arguments and no previous clang-check invocation!" - endif -endfunction - -nmap <silent> <F5> :call ClangCheck()<CR><CR> -</pre> - -<p>When editing a .cpp/.cxx/.cc/.c file, hit F5 to reparse the file. In case -the current file has a different extension (for example, .h), F5 will re-run -the last clang-check invocation made from this vim instance (if any). The -output will go into the error window, which is opened automatically when -clang-check finds errors, and can be re-opened with <code>:cope</code>.</p> - -<p>Other <code>clang-check</code> options that can be useful when working with -clang AST:</p> -<ul> - <li><code>-ast-print</code> - Build ASTs and then pretty-print them.</li> - <li><code>-ast-dump</code> - Build ASTs and then debug dump them.</li> - <li><code>-ast-dump-filter=<string></code> - Use with - <code>-ast-dump</code> or <code>-ast-print</code> to dump/print - only AST declaration nodes having a certain substring in a qualified name. - Use <code>-ast-list</code> to list all filterable declaration node - names.</li> - <li><code>-ast-list</code> - Build ASTs and print the list of declaration - node qualified names.</li> -</ul> -<p>Examples:</p> -<pre> -<b>$ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-dump -ast-dump-filter ActionFactory::newASTConsumer</b> -Processing: tools/clang/tools/clang-check/ClangCheck.cpp. -Dumping <anonymous namespace>::ActionFactory::newASTConsumer: -clang::ASTConsumer *newASTConsumer() (CompoundStmt 0x44da290 </home/alexfh/local/llvm/tools/clang/tools/clang-check/ClangCheck.cpp:64:40, line:72:3> - (IfStmt 0x44d97c8 <line:65:5, line:66:45> - <<<NULL>>> - (ImplicitCastExpr 0x44d96d0 <line:65:9> '_Bool':'_Bool' <UserDefinedConversion> -... -<b>$ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-print -ast-dump-filter ActionFactory::newASTConsumer</b> -Processing: tools/clang/tools/clang-check/ClangCheck.cpp. -Printing <anonymous namespace>::ActionFactory::newASTConsumer: -clang::ASTConsumer *newASTConsumer() { - if (this->ASTList.operator _Bool()) - return clang::CreateASTDeclNodeLister(); - if (this->ASTDump.operator _Bool()) - return clang::CreateASTDumper(this->ASTDumpFilter); - if (this->ASTPrint.operator _Bool()) - return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter); - return new clang::ASTConsumer(); -} -</pre> - -<!-- ======================================================================= --> -<h2><a name="using-ninja">(Experimental) Using Ninja Build System</a></h2> -<!-- ======================================================================= --> - -<p>Optionally you can use the <a - href="https://github.com/martine/ninja">Ninja</a> build system instead of -make. It is aimed at making your builds faster. Currently this step will require -building Ninja from sources and using a development version of CMake.</p> -<p>To take advantage of using Clang Tools along with Ninja build you need at -least CMake 2.8.9. At the moment CMake 2.8.9 is still under development, so you -can get latest development sources and build it yourself:</p> -<pre> - git clone git://cmake.org/cmake.git - cd cmake - ./bootstrap - make - sudo make install -</pre> - -<p>Having the correct version of CMake, you can clone the Ninja git repository -and build Ninja from sources:</p> -<pre> - git clone git://github.com/martine/ninja.git - cd ninja/ - ./bootstrap.py -</pre> -<p>This will result in a single binary <code>ninja</code> in the current -directory. It doesn't require installation and can just be copied to any -location inside <code>$PATH</code>, say <code>/usr/local/bin/</code>:</p> -<pre> - sudo cp ninja /usr/local/bin/ - sudo chmod a+rx /usr/local/bin/ninja -</pre> -<p>After doing all of this, you'll need to generate Ninja build files for LLVM -with CMake. You need to make a build directory and run CMake from it:</p> -<pre> - mkdir your/build/directory - cd your/build/directory - cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources -</pre> - -<p>If you want to use clang instead of GCC, you can add -<code>-DCMAKE_C_COMPILER=/path/to/clang - -DCMAKE_CXX_COMPILER=/path/to/clang++</code>. -You can also use ccmake, which provides a curses interface to configure CMake -variables in an interactive manner.</p> - -<p>As a result, the new <code>compile_commands.json</code> file should appear in -the current directory. You should link it to the LLVM source tree so that Clang -Tooling is able to use it:</p> -<pre> - ln -s $PWD/compile_commands.json path/to/llvm/source/ -</pre> - -<p>Now you are ready to build and test LLVM using Ninja:</p> -<pre> - ninja check-all -</pre> -<p>Other target names can be used in the same way as with make.</p> -</div> -</body> -</html> - diff --git a/clang/docs/HowToSetupToolingForLLVM.rst b/clang/docs/HowToSetupToolingForLLVM.rst new file mode 100644 index 00000000000..0c4cccafca5 --- /dev/null +++ b/clang/docs/HowToSetupToolingForLLVM.rst @@ -0,0 +1,211 @@ +=================================== +How To Setup Clang Tooling For LLVM +=================================== + +Clang Tooling provides infrastructure to write tools that need syntactic +and semantic infomation about a program. This term also relates to a set +of specific tools using this infrastructure (e.g. ``clang-check``). This +document provides information on how to set up and use Clang Tooling for +the LLVM source code. + +Introduction +============ + +Clang Tooling needs a compilation database to figure out specific build +options for each file. Currently it can create a compilation database +from the ``compilation_commands.json`` file, generated by CMake. When +invoking clang tools, you can either specify a path to a build directory +using a command line parameter ``-p`` or let Clang Tooling find this +file in your source tree. In either case you need to configure your +build using CMake to use clang tools. + +Setup Clang Tooling Using CMake and Make +======================================== + +If you intend to use make to build LLVM, you should have CMake 2.8.6 or +later installed (can be found `here <http://cmake.org>`_). + +First, you need to generate Makefiles for LLVM with CMake. You need to +make a build directory and run CMake from it: + +:: + + mkdir your/build/directory + cd your/build/directory + cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources + +If you want to use clang instead of GCC, you can add +``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``. +You can also use ccmake, which provides a curses interface to configure +CMake variables for lazy people. + +As a result, the new ``compile_commands.json`` file should appear in the +current directory. You should link it to the LLVM source tree so that +Clang Tooling is able to use it: + +:: + + ln -s $PWD/compile_commands.json path/to/llvm/source/ + +Now you are ready to build and test LLVM using make: + +:: + + make check-all + +Using Clang Tools +================= + +After you completed the previous steps, you are ready to run clang +tools. If you have a recent clang installed, you should have +``clang-check`` in $PATH. Try to run it on any .cpp file inside the LLVM +source tree: + +:: + + clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp + +If you're using vim, it's convenient to have clang-check integrated. Put +this into your .vimrc: + +:: + + function! ClangCheckImpl(cmd) + if &autowrite | wall | endif + echo "Running " . a:cmd . " ..." + let l:output = system(a:cmd) + cexpr l:output + cwindow + let w:quickfix_title = a:cmd + if v:shell_error != 0 + cc + endif + let g:clang_check_last_cmd = a:cmd + endfunction + + function! ClangCheck() + let l:filename = expand('%') + if l:filename =~ '\.\(cpp\|cxx\|cc\|c\)$' + call ClangCheckImpl("clang-check " . l:filename) + elseif exists("g:clang_check_last_cmd") + call ClangCheckImpl(g:clang_check_last_cmd) + else + echo "Can't detect file's compilation arguments and no previous clang-check invocation!" + endif + endfunction + + nmap <silent> <F5> :call ClangCheck()<CR><CR> + +When editing a .cpp/.cxx/.cc/.c file, hit F5 to reparse the file. In +case the current file has a different extension (for example, .h), F5 +will re-run the last clang-check invocation made from this vim instance +(if any). The output will go into the error window, which is opened +automatically when clang-check finds errors, and can be re-opened with +``:cope``. + +Other ``clang-check`` options that can be useful when working with clang +AST: + +- ``-ast-print`` - Build ASTs and then pretty-print them. +- ``-ast-dump`` - Build ASTs and then debug dump them. +- ``-ast-dump-filter=<string>`` - Use with ``-ast-dump`` or + ``-ast-print`` to dump/print only AST declaration nodes having a + certain substring in a qualified name. Use ``-ast-list`` to list all + filterable declaration node names. +- ``-ast-list`` - Build ASTs and print the list of declaration node + qualified names. + +Examples: + +:: + + $ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-dump -ast-dump-filter ActionFactory::newASTConsumer + Processing: tools/clang/tools/clang-check/ClangCheck.cpp. + Dumping ::ActionFactory::newASTConsumer: + clang::ASTConsumer *newASTConsumer() (CompoundStmt 0x44da290 </home/alexfh/local/llvm/tools/clang/tools/clang-check/ClangCheck.cpp:64:40, line:72:3> + (IfStmt 0x44d97c8 <line:65:5, line:66:45> + <<<NULL>>> + (ImplicitCastExpr 0x44d96d0 <line:65:9> '_Bool':'_Bool' <UserDefinedConversion> + ... + $ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-print -ast-dump-filter ActionFactory::newASTConsumer + Processing: tools/clang/tools/clang-check/ClangCheck.cpp. + Printing <anonymous namespace>::ActionFactory::newASTConsumer: + clang::ASTConsumer *newASTConsumer() { + if (this->ASTList.operator _Bool()) + return clang::CreateASTDeclNodeLister(); + if (this->ASTDump.operator _Bool()) + return clang::CreateASTDumper(this->ASTDumpFilter); + if (this->ASTPrint.operator _Bool()) + return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter); + return new clang::ASTConsumer(); + } + +(Experimental) Using Ninja Build System +======================================= + +Optionally you can use the `Ninja <https://github.com/martine/ninja>`_ +build system instead of make. It is aimed at making your builds faster. +Currently this step will require building Ninja from sources and using a +development version of CMake. + +To take advantage of using Clang Tools along with Ninja build you need +at least CMake 2.8.9. At the moment CMake 2.8.9 is still under +development, so you can get latest development sources and build it +yourself: + +:: + + git clone git://cmake.org/cmake.git + cd cmake + ./bootstrap + make + sudo make install + +Having the correct version of CMake, you can clone the Ninja git +repository and build Ninja from sources: + +:: + + git clone git://github.com/martine/ninja.git + cd ninja/ + ./bootstrap.py + +This will result in a single binary ``ninja`` in the current directory. +It doesn't require installation and can just be copied to any location +inside ``$PATH``, say ``/usr/local/bin/``: + +:: + + sudo cp ninja /usr/local/bin/ + sudo chmod a+rx /usr/local/bin/ninja + +After doing all of this, you'll need to generate Ninja build files for +LLVM with CMake. You need to make a build directory and run CMake from +it: + +:: + + mkdir your/build/directory + cd your/build/directory + cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources + +If you want to use clang instead of GCC, you can add +``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``. +You can also use ccmake, which provides a curses interface to configure +CMake variables in an interactive manner. + +As a result, the new ``compile_commands.json`` file should appear in the +current directory. You should link it to the LLVM source tree so that +Clang Tooling is able to use it: + +:: + + ln -s $PWD/compile_commands.json path/to/llvm/source/ + +Now you are ready to build and test LLVM using Ninja: + +:: + + ninja check-all + +Other target names can be used in the same way as with make. diff --git a/clang/docs/IntroductionToTheClangAST.html b/clang/docs/IntroductionToTheClangAST.html deleted file mode 100644 index 28175dd81bb..00000000000 --- a/clang/docs/IntroductionToTheClangAST.html +++ /dev/null @@ -1,139 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>Introduction to the Clang AST</title> -<link type="text/css" rel="stylesheet" href="../menu.css" /> -<link type="text/css" rel="stylesheet" href="../content.css" /> -</head> -<body> - -<!--#include virtual="../menu.html.incl"--> - -<div id="content"> - -<h1>Introduction to the Clang AST</h1> -<p>This document gives a gentle introduction to the mysteries of the Clang AST. -It is targeted at developers who either want to contribute to Clang, or use -tools that work based on Clang's AST, like the AST matchers.</p> -<!-- FIXME: Add link once we have an AST matcher document --> - -<!-- ======================================================================= --> -<h2 id="intro">Introduction</h2> -<!-- ======================================================================= --> - -<p>Clang's AST is different from ASTs produced by some other compilers in that it closely -resembles both the written C++ code and the C++ standard. For example, -parenthesis expressions and compile time constants are available in an unreduced -form in the AST. This makes Clang's AST a good fit for refactoring tools.</p> - -<p>Documentation for all Clang AST nodes is available via the generated -<a href="http://clang.llvm.org/doxygen">Doxygen</a>. The doxygen online -documentation is also indexed by your favorite search engine, which will make -a search for clang and the AST node's class name usually turn up the doxygen -of the class you're looking for (for example, search for: clang ParenExpr).</p> - -<!-- ======================================================================= --> -<h2 id="examine">Examining the AST</h2> -<!-- ======================================================================= --> - -<p>A good way to familarize yourself with the Clang AST is to actually look -at it on some simple example code. Clang has a builtin AST-dump modes, which -can be enabled with the flags -ast-dump and -ast-dump-xml. Note that -ast-dump-xml -currently only works with debug-builds of clang.</p> - -<p>Let's look at a simple example AST:</p> -<pre> -# cat test.cc -int f(int x) { - int result = (x / 42); - return result; -} - -# Clang by default is a frontend for many tools; -cc1 tells it to directly -# use the C++ compiler mode. -undef leaves out some internal declarations. -$ clang -cc1 -undef -ast-dump-xml test.cc -... cutting out internal declarations of clang ... -<TranslationUnit ptr="0x4871160"> - <Function ptr="0x48a5800" name="f" prototype="true"> - <FunctionProtoType ptr="0x4871de0" canonical="0x4871de0"> - <BuiltinType ptr="0x4871250" canonical="0x4871250"/> - <parameters> - <BuiltinType ptr="0x4871250" canonical="0x4871250"/> - </parameters> - </FunctionProtoType> - <ParmVar ptr="0x4871d80" name="x" initstyle="c"> - <BuiltinType ptr="0x4871250" canonical="0x4871250"/> - </ParmVar> - <Stmt> -(CompoundStmt 0x48a5a38 <t2.cc:1:14, line:4:1> - (DeclStmt 0x48a59c0 <line:2:3, col:24> - 0x48a58c0 "int result = - (ParenExpr 0x48a59a0 <col:16, col:23> 'int' - (BinaryOperator 0x48a5978 <col:17, col:21> 'int' '/' - (ImplicitCastExpr 0x48a5960 <col:17> 'int' <LValueToRValue> - (DeclRefExpr 0x48a5918 <col:17> 'int' lvalue ParmVar 0x4871d80 'x' 'int')) - (IntegerLiteral 0x48a5940 <col:21> 'int' 42)))") - (ReturnStmt 0x48a5a18 <line:3:3, col:10> - (ImplicitCastExpr 0x48a5a00 <col:10> 'int' <LValueToRValue> - (DeclRefExpr 0x48a59d8 <col:10> 'int' lvalue Var 0x48a58c0 'result' 'int')))) - - </Stmt> - </Function> -</TranslationUnit> -</pre> -<p>In general, -ast-dump-xml dumps declarations in an XML-style format and -statements in an S-expression-style format. -The toplevel declaration in a translation unit is always the -<a href="http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html">translation unit declaration</a>. -In this example, our first user written declaration is the -<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">function declaration</a> -of 'f'. The body of 'f' is a <a href="http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">compound statement</a>, -whose child nodes are a <a href="http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html">declaration statement</a> -that declares our result variable, and the -<a href="http://clang.llvm.org/doxygen/classclang_1_1ReturnStmt.html">return statement</a>.</p> - -<!-- ======================================================================= --> -<h2 id="context">AST Context</h2> -<!-- ======================================================================= --> - -<p>All information about the AST for a translation unit is bundled up in the class -<a href="http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html">ASTContext</a>. -It allows traversal of the whole translation unit starting from -<a href="http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#abd909fb01ef10cfd0244832a67b1dd64">getTranslationUnitDecl</a>, -or to access Clang's <a href="http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#a4f95adb9958e22fbe55212ae6482feb4">table of identifiers</a> -for the parsed translation unit.</p> - -<!-- ======================================================================= --> -<h2 id="nodes">AST Nodes</h2> -<!-- ======================================================================= --> - -<p>Clang's AST nodes are modeled on a class hierarchy that does not have a common -ancestor. Instead, there are multiple larger hierarchies for basic node types like -<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a> and -<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>. Many -important AST nodes derive from <a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>, -<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>, -<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclContext.html">DeclContext</a> or -<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>, -with some classes deriving from both Decl and DeclContext.</p> -<p>There are also a multitude of nodes in the AST that are not part of a -larger hierarchy, and are only reachable from specific other nodes, -like <a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html">CXXBaseSpecifier</a>. -</p> - -<p>Thus, to traverse the full AST, one starts from the <a href="http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html">TranslationUnitDecl</a> -and then recursively traverses everything that can be reached from that node -- this information has to be encoded for each specific node type. This algorithm -is encoded in the <a href="http://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html">RecursiveASTVisitor</a>. -See the <a href="http://clang.llvm.org/docs/RAVFrontendAction.html">RecursiveASTVisitor tutorial</a>.</p> - -<p>The two most basic nodes in the Clang AST are statements (<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>) -and declarations (<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>). -Note that expressions (<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>) -are also statements in Clang's AST.</p> - -</div> -</body> -</html> - diff --git a/clang/docs/IntroductionToTheClangAST.rst b/clang/docs/IntroductionToTheClangAST.rst new file mode 100644 index 00000000000..a23fb42b712 --- /dev/null +++ b/clang/docs/IntroductionToTheClangAST.rst @@ -0,0 +1,135 @@ +============================= +Introduction to the Clang AST +============================= + +This document gives a gentle introduction to the mysteries of the Clang +AST. It is targeted at developers who either want to contribute to +Clang, or use tools that work based on Clang's AST, like the AST +matchers. + +Introduction +============ + +Clang's AST is different from ASTs produced by some other compilers in +that it closely resembles both the written C++ code and the C++ +standard. For example, parenthesis expressions and compile time +constants are available in an unreduced form in the AST. This makes +Clang's AST a good fit for refactoring tools. + +Documentation for all Clang AST nodes is available via the generated +`Doxygen <http://clang.llvm.org/doxygen>`_. The doxygen online +documentation is also indexed by your favorite search engine, which will +make a search for clang and the AST node's class name usually turn up +the doxygen of the class you're looking for (for example, search for: +clang ParenExpr). + +Examining the AST +================= + +A good way to familarize yourself with the Clang AST is to actually look +at it on some simple example code. Clang has a builtin AST-dump modes, +which can be enabled with the flags -ast-dump and -ast-dump-xml. Note +that -ast-dump-xml currently only works with debug-builds of clang. + +Let's look at a simple example AST: + +:: + + # cat test.cc + int f(int x) { + int result = (x / 42); + return result; + } + + # Clang by default is a frontend for many tools; -cc1 tells it to directly + # use the C++ compiler mode. -undef leaves out some internal declarations. + $ clang -cc1 -undef -ast-dump-xml test.cc + ... cutting out internal declarations of clang ... + <TranslationUnit ptr="0x4871160"> + <Function ptr="0x48a5800" name="f" prototype="true"> + <FunctionProtoType ptr="0x4871de0" canonical="0x4871de0"> + <BuiltinType ptr="0x4871250" canonical="0x4871250"/> + <parameters> + <BuiltinType ptr="0x4871250" canonical="0x4871250"/> + </parameters> + </FunctionProtoType> + <ParmVar ptr="0x4871d80" name="x" initstyle="c"> + <BuiltinType ptr="0x4871250" canonical="0x4871250"/> + </ParmVar> + <Stmt> + (CompoundStmt 0x48a5a38 <t2.cc:1:14, line:4:1> + (DeclStmt 0x48a59c0 <line:2:3, col:24> + 0x48a58c0 "int result = + (ParenExpr 0x48a59a0 <col:16, col:23> 'int' + (BinaryOperator 0x48a5978 <col:17, col:21> 'int' '/' + (ImplicitCastExpr 0x48a5960 <col:17> 'int' <LValueToRValue> + (DeclRefExpr 0x48a5918 <col:17> 'int' lvalue ParmVar 0x4871d80 'x' 'int')) + (IntegerLiteral 0x48a5940 <col:21> 'int' 42)))") + (ReturnStmt 0x48a5a18 <line:3:3, col:10> + (ImplicitCastExpr 0x48a5a00 <col:10> 'int' <LValueToRValue> + (DeclRefExpr 0x48a59d8 <col:10> 'int' lvalue Var 0x48a58c0 'result' 'int')))) + + </Stmt> + </Function> + </TranslationUnit> + +In general, -ast-dump-xml dumps declarations in an XML-style format and +statements in an S-expression-style format. The toplevel declaration in +a translation unit is always the `translation unit +declaration <http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html>`_. +In this example, our first user written declaration is the `function +declaration <http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html>`_ +of 'f'. The body of 'f' is a `compound +statement <http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html>`_, +whose child nodes are a `declaration +statement <http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html>`_ +that declares our result variable, and the `return +statement <http://clang.llvm.org/doxygen/classclang_1_1ReturnStmt.html>`_. + +AST Context +=========== + +All information about the AST for a translation unit is bundled up in +the class +`ASTContext <http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html>`_. +It allows traversal of the whole translation unit starting from +`getTranslationUnitDecl <http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#abd909fb01ef10cfd0244832a67b1dd64>`_, +or to access Clang's `table of +identifiers <http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#a4f95adb9958e22fbe55212ae6482feb4>`_ +for the parsed translation unit. + +AST Nodes +========= + +Clang's AST nodes are modeled on a class hierarchy that does not have a +common ancestor. Instead, there are multiple larger hierarchies for +basic node types like +`Decl <http://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_ and +`Stmt <http://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_. Many +important AST nodes derive from +`Type <http://clang.llvm.org/doxygen/classclang_1_1Type.html>`_, +`Decl <http://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_, +`DeclContext <http://clang.llvm.org/doxygen/classclang_1_1DeclContext.html>`_ +or `Stmt <http://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_, with +some classes deriving from both Decl and DeclContext. + +There are also a multitude of nodes in the AST that are not part of a +larger hierarchy, and are only reachable from specific other nodes, like +`CXXBaseSpecifier <http://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html>`_. + +Thus, to traverse the full AST, one starts from the +`TranslationUnitDecl <http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html>`_ +and then recursively traverses everything that can be reached from that +node - this information has to be encoded for each specific node type. +This algorithm is encoded in the +`RecursiveASTVisitor <http://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html>`_. +See the `RecursiveASTVisitor +tutorial <http://clang.llvm.org/docs/RAVFrontendAction.html>`_. + +The two most basic nodes in the Clang AST are statements +(`Stmt <http://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_) and +declarations +(`Decl <http://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_). Note +that expressions +(`Expr <http://clang.llvm.org/doxygen/classclang_1_1Expr.html>`_) are +also statements in Clang's AST. diff --git a/clang/docs/JSONCompilationDatabase.html b/clang/docs/JSONCompilationDatabase.html deleted file mode 100644 index 29071947290..00000000000 --- a/clang/docs/JSONCompilationDatabase.html +++ /dev/null @@ -1,89 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>JSON Compilation Database Format Specification</title> -<link type="text/css" rel="stylesheet" href="../menu.css"> -<link type="text/css" rel="stylesheet" href="../content.css"> -</head> -<body> - -<!--#include virtual="../menu.html.incl"--> - -<div id="content"> - -<h1>JSON Compilation Database Format Specification</h1> -<p>This document describes a format for specifying how to replay -single compilations independently of the build system.</p> - -<h2>Background</h2> -<p>Tools based on the C++ Abstract Syntax Tree need full information how to -parse a translation unit. Usually this information is implicitly -available in the build system, but running tools as part of -the build system is not necessarily the best solution: -<ul> -<li>Build systems are inherently change driven, so running multiple -tools over the same code base without changing the code does not fit -into the architecture of many build systems.</li> -<li>Figuring out whether things have changed is often an IO bound -process; this makes it hard to build low latency end user tools based -on the build system.</li> -<li>Build systems are inherently sequential in the build graph, for example -due to generated source code. While tools that run independently of the -build still need the generated source code to exist, running tools multiple -times over unchanging source does not require serialization of the runs -according to the build dependency graph.</li> -</ul> -</p> - -<h2>Supported Systems</h2> -<p>Currently <a href="http://cmake.org">CMake</a> (since 2.8.5) supports generation of compilation -databases for Unix Makefile builds (Ninja builds in the works) with the option -CMAKE_EXPORT_COMPILE_COMMANDS.</p> -<p>Clang's tooling interface supports reading compilation databases; see -the <a href="LibTooling.html">LibTooling documentation</a>. libclang and its -python bindings also support this (since clang 3.2); see -<a href="/doxygen/group__COMPILATIONDB.html">CXCompilationDatabase.h</a>.</p> - -<h2>Format</h2> -<p>A compilation database is a JSON file, which consist of an array of -"command objects", where each command object specifies one way a translation unit -is compiled in the project.</p> -<p>Each command object contains the translation unit's main file, the working -directory of the compile run and the actual compile command.</p> -<p>Example: -<pre> -[ - { "directory": "/home/user/llvm/build", - "command": "/usr/bin/clang++ -Irelative -DSOMEDEF='\"With spaces and quotes.\"' -c -o file.o file.cc", - "file": "file.cc" }, - ... -] -</pre> -The contracts for each field in the command object are: -<ul> -<li><b>directory:</b> The working directory of the compilation. All paths specified -in the <b>command</b> or <b>file</b> fields must be either absolute or relative to -this directory.</li> -<li><b>file:</b> The main translation unit source processed by this compilation step. -This is used by tools as the key into the compilation database. There can be multiple -command objects for the same file, for example if the same source file is -compiled with different configurations.</li> -<li><b>command:</b> The compile command executed. After JSON unescaping, this must -be a valid command to rerun the exact compilation step for the translation unit in -the environment the build system uses. Parameters use shell quoting and shell escaping -of quotes, with '"' and '\' being the only special characters. Shell expansion is -not supported.</li> -</ul> -</p> - -<h2>Build System Integration</h2> -<p>The convention is to name the file compile_commands.json and put it at the top -of the build directory. Clang tools are pointed to the top of the build directory -to detect the file and use the compilation database to parse C++ code in the source -tree.</p> - -</div> -</body> -</html> - diff --git a/clang/docs/JSONCompilationDatabase.rst b/clang/docs/JSONCompilationDatabase.rst new file mode 100644 index 00000000000..502557b50af --- /dev/null +++ b/clang/docs/JSONCompilationDatabase.rst @@ -0,0 +1,85 @@ +============================================== +JSON Compilation Database Format Specification +============================================== + +This document describes a format for specifying how to replay single +compilations independently of the build system. + +Background +========== + +Tools based on the C++ Abstract Syntax Tree need full information how to +parse a translation unit. Usually this information is implicitly +available in the build system, but running tools as part of the build +system is not necessarily the best solution: + +- Build systems are inherently change driven, so running multiple tools + over the same code base without changing the code does not fit into + the architecture of many build systems. +- Figuring out whether things have changed is often an IO bound + process; this makes it hard to build low latency end user tools based + on the build system. +- Build systems are inherently sequential in the build graph, for + example due to generated source code. While tools that run + independently of the build still need the generated source code to + exist, running tools multiple times over unchanging source does not + require serialization of the runs according to the build dependency + graph. + +Supported Systems +================= + +Currently `CMake <http://cmake.org>`_ (since 2.8.5) supports generation +of compilation databases for Unix Makefile builds (Ninja builds in the +works) with the option CMAKE\_EXPORT\_COMPILE\_COMMANDS. + +Clang's tooling interface supports reading compilation databases; see +the `LibTooling documentation <LibTooling.html>`_. libclang and its +python bindings also support this (since clang 3.2); see +`CXCompilationDatabase.h </doxygen/group__COMPILATIONDB.html>`_. + +Format +====== + +A compilation database is a JSON file, which consist of an array of +"command objects", where each command object specifies one way a +translation unit is compiled in the project. + +Each command object contains the translation unit's main file, the +working directory of the compile run and the actual compile command. + +Example: + +:: + + [ + { "directory": "/home/user/llvm/build", + "command": "/usr/bin/clang++ -Irelative -DSOMEDEF='\"With spaces and quotes.\"' -c -o file.o file.cc", + "file": "file.cc" }, + ... + ] + +The contracts for each field in the command object are: + +- **directory:** The working directory of the compilation. All paths + specified in the **command** or **file** fields must be either + absolute or relative to this directory. +- **file:** The main translation unit source processed by this + compilation step. This is used by tools as the key into the + compilation database. There can be multiple command objects for the + same file, for example if the same source file is compiled with + different configurations. +- **command:** The compile command executed. After JSON unescaping, + this must be a valid command to rerun the exact compilation step for + the translation unit in the environment the build system uses. + Parameters use shell quoting and shell escaping of quotes, with '"' + and '\\' being the only special characters. Shell expansion is not + supported. + +Build System Integration +======================== + +The convention is to name the file compile\_commands.json and put it at +the top of the build directory. Clang tools are pointed to the top of +the build directory to detect the file and use the compilation database +to parse C++ code in the source tree. diff --git a/clang/docs/LibASTMatchersTutorial.html b/clang/docs/LibASTMatchersTutorial.html deleted file mode 100644 index 222ce70dfaf..00000000000 --- a/clang/docs/LibASTMatchersTutorial.html +++ /dev/null @@ -1,533 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>Tutorial for building tools using LibTooling and LibASTMatchers</title> -<link type="text/css" rel="stylesheet" href="../menu.css" /> -<link type="text/css" rel="stylesheet" href="../content.css" /> -</head> -<body> - -<!--#include virtual="../menu.html.incl"--> - -<div id="content"> - -<h1>Tutorial for building tools using LibTooling and LibASTMatchers</h1> -<p>This document is intended to show how to build a useful source-to-source -translation tool based on Clang's <a href="LibTooling.html">LibTooling</a>. It -is explicitly aimed at people who are new to Clang, so all you should need is a -working knowledge of C++ and the command line.</p> - -<p>In order to work on the compiler, you need some basic knowledge of the -abstract syntax tree (AST). To this end, the reader is incouraged to skim the -<a href="http://clang.llvm.org/docs/IntroductionToTheClangAST.html">Introduction -to the Clang AST</a></p> - -<!-- ======================================================================= --> -<h2 id="obtainingclang">Step 0: Obtaining Clang</h2> -<!-- ======================================================================= --> -As Clang is part of the LLVM project, you'll need to download LLVM's source code -first. Both Clang and LLVM are maintained as Subversion repositories, but we'll -be accessing them through the git mirror. For further information, see the -<a href="http://llvm.org/docs/GettingStarted.html">getting started guide</a>. - -<pre class="doc_code"> - mkdir ~/clang-llvm && cd ~/clang-llvm - git clone http://llvm.org/git/llvm.git - cd llvm/tools - git clone http://llvm.org/git/clang.git -</pre> - -Next you need to obtain the CMake build system and Ninja build tool. You may -already have CMake installed, but current binary versions of CMake aren't built -with Ninja support. - -<pre class="doc_code"> - cd ~/clang-llvm - git clone https://github.com/martine/ninja.git - cd ninja - git checkout release - ./bootstrap.py - sudo cp ninja /usr/bin/ - - cd ~/clang-llvm - git clone git://cmake.org/stage/cmake.git - cd cmake - git checkout next - ./bootstrap - make - sudo make install -</pre> - -<p>Okay. Now we'll build Clang!</p> - -<pre class="doc_code"> - cd ~/clang-llvm - mkdir build && cd build - cmake -G Ninja ../llvm -DLLVM_BUILD_TESTS=ON # Enable tests; default is off. - ninja - ninja check # Test LLVM only. - ninja clang-test # Test Clang only. - ninja install -</pre> - -<p>And we're live.</p> - -<p>All of the tests should pass, though there is a (very) small chance that you -can catch LLVM and Clang out of sync. Running <tt>'git svn rebase'</tt> in both -the llvm and clang directories should fix any problems.</p> - -<p>Finally, we want to set Clang as its own compiler.</p> - -<pre class="doc_code"> - cd ~/clang-llvm/build - ccmake ../llvm -</pre> - -<p>The second command will bring up a GUI for configuring Clang. You need to set -the entry for <tt>CMAKE_CXX_COMPILER</tt>. Press <tt>'t'</tt> to turn on -advanced mode. Scroll down to <tt>CMAKE_CXX_COMPILER</tt>, and set it to -<tt>/usr/bin/clang++</tt>, or wherever you installed it. Press <tt>'c'</tt> to -configure, then <tt>'g'</tt> to generate CMake's files.</p> - -<p>Finally, run ninja one last time, and you're done.</p> - -<!-- ======================================================================= --> -<h2 id="clangtool">Step 1: Create a ClangTool</h2> -<!-- ======================================================================= --> -<p>Now that we have enough background knowledge, it's time to create the -simplest productive ClangTool in existence: a syntax checker. While this already -exists as <tt>clang-check</tt>, it's important to understand what's going -on.</p> - -<p>First, we'll need to create a new directory for our tool and tell CMake that -it exists. As this is not going to be a core clang tool, it will live in the -<tt>tools/extra</tt> repository.</p> - -<pre class="doc_code"> - cd ~/clang-llvm/llvm/tools/clang - mkdir tools/extra/loop-convert - echo 'add_subdirectory(loop-convert)' >> tools/extra/CMakeLists.txt - vim tools/extra/loop-convert/CMakeLists.txt -</pre> - -CMakeLists.txt should have the following contents: -<pre class="doc_code"> - set(LLVM_LINK_COMPONENTS support) - set(LLVM_USED_LIBS clangTooling clangBasic clangAST) - - add_clang_executable(loop-convert - LoopConvert.cpp - ) - target_link_libraries(loop-convert - clangTooling - clangBasic - clangASTMatchers - ) -</pre> - -<p>With that done, Ninja will be able to compile our tool. Let's give it -something to compile! Put the following into -<tt>tools/extra/loop-convert/LoopConvert.cpp</tt>. A detailed explanation of why -the different parts are needed can be found in the -<a href="LibTooling.html">LibTooling documentation</a>.</p> - -<pre> - // Declares clang::SyntaxOnlyAction. - #include "clang/Frontend/FrontendActions.h" - #include "clang/Tooling/CommonOptionsParser.h" - #include "clang/Tooling/Tooling.h" - // Declares llvm::cl::extrahelp. - #include "llvm/Support/CommandLine.h" - - using namespace clang::tooling; - using namespace llvm; - - // CommonOptionsParser declares HelpMessage with a description of the common - // command-line options related to the compilation database and input files. - // It's nice to have this help message in all tools. - static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage); - - // A help message for this specific tool can be added afterwards. - static cl::extrahelp MoreHelp("\nMore help text..."); - - int main(int argc, const char **argv) { - CommonOptionsParser OptionsParser(argc, argv); - ClangTool Tool(OptionsParser.GetCompilations(), - OptionsParser.GetSourcePathList()); - return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>()); - } -</pre> - -<p>And that's it! You can compile our new tool by running ninja from the -<tt>build</tt> directory.</p> - -<pre class="doc_code"> - cd ~/clang-llvm/build - ninja -</pre> - -<p>You should now be able to run the syntax checker, which is located in -<tt>~/clang-llvm/build/bin</tt>, on any source file. Try it!</p> - -<pre class="doc_code"> - cat "void main() {}" > test.cpp - bin/loop-convert test.cpp -- -</pre> - -<p>Note the two dashes after we specify the source file. The additional options -for the compiler are passed after the dashes rather than loading them from a -compilation database - there just aren't any options needed right now.</p> - -<!-- ======================================================================= --> -<h2 id="learnastmatchers">Intermezzo: Learn AST matcher basics</h2> -<!-- ======================================================================= --> -<p>Clang recently introduced the <a href=LibASTMatchers.html>ASTMatcher -library</a> to provide a simple, powerful, and concise way to describe specific -patterns in the AST. Implemented as a DSL powered by macros and templates (see -<a href="../doxygen/ASTMatchers_8h_source.html">ASTMatchers.h</a> if you're -curious), matchers offer the feel of algebraic data types common to functional -programming languages.</p> - -<p>For example, suppose you wanted to examine only binary operators. There is a -matcher to do exactly that, conveniently named <tt>binaryOperator</tt>. I'll -give you one guess what this matcher does:</p> - -<pre class="doc_code"> - binaryOperator(hasOperatorName("+"), hasLHS(integerLiteral(equals(0)))) -</pre> - -<p>Shockingly, it will match against addition expressions whose left hand side -is exactly the literal 0. It will not match against other forms of 0, such as -<tt>'\0'</tt> or <tt>NULL</tt>, but it will match against macros that expand to -0. The matcher will also not match against calls to the overloaded operator -<tt>'+'</tt>, as there is a separate <tt>operatorCallExpr</tt> matcher to handle -overloaded operators.</p> - -<p>There are AST matchers to match all the different nodes of the AST, narrowing -matchers to only match AST nodes fulfilling specific criteria, and traversal -matchers to get from one kind of AST node to another. For a complete list of AST -matchers, take a look at the <a href="LibASTMatchersReference.html">AST Matcher -References</a></p> - -<p>All matcher that are nouns describe entities in the AST and can be bound, -so that they can be referred to whenever a match is found. To do so, simply call -the method <tt>bind</tt> on these matchers, e.g.:</p> -<pre class="doc_code"> - variable(hasType(isInteger())).bind("intvar") -</pre> - -<!-- ======================================================================= --> -<h2 id="usingastmatchers">Step 2: Using AST matchers</h2> -<!-- ======================================================================= --> -<p>Okay, on to using matchers for real. Let's start by defining a matcher which -will capture all <tt>for</tt> statements that define a new variable -initialized to zero. Let's start with matching all <tt>for</tt> loops:</p> - -<pre class="doc_code"> - forStmt() -</pre> - -<p>Next, we want to specify that a single variable is declared in the first -portion of the loop, so we can extend the matcher to</p> -<pre class="doc_code"> - forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl())))) -</pre> - -<p>Finally, we can add the condition that the variable is initialized to -zero.</p> -<pre class="doc_code"> - forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl( - hasInitializer(integerLiteral(equals(0)))))))) -</pre> - -</p>It is fairly easy to read and understand the matcher definition ("match -loops whose init portion declares a single variable which is initialized to the -integer literal 0"), but deciding that every piece is necessary is more -difficult. Note that this matcher will not match loops whose variables are -initialized to <tt>'\0'</tt>, <tt>0.0</tt>, <tt>NULL</tt>, or any form of zero -besides the integer 0.</p> - -<p>The last step is giving the matcher a name and binding the <tt>ForStmt</tt> -as we will want to do something with it:</p> -<pre class="doc_code"> - StatementMatcher LoopMatcher = - forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl( - hasInitializer(integerLiteral(equals(0)))))))).bind("forLoop"); -</pre> - -<p>Once you have defined your matchers, you will need to add a little more -scaffolding in order to run them. Matchers are paired with a -<tt>MatchCallback</tt> and registered with a <tt>MatchFinder</tt> object, then -run from a <tt>ClangTool</tt>. More code!</p> - -Add the following to <tt>LoopConvert.cpp</tt>: -<pre class="doc_code"> - StatementMatcher LoopMatcher = - forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl( - hasInitializer(integerLiteral(equals(0)))))))).bind("forLoop"); - - class LoopPrinter : public MatchFinder::MatchCallback { - public : - virtual void run(const MatchFinder::MatchResult &Result) { - if (const ForStmt *FS = Result.Nodes.getNodeAs<clang::ForStmt>("forLoop")) - FS->dump(); - }; -</pre> - -And change <tt>main()</tt> to: -<pre class="doc_code"> - int main(int argc, const char **argv) { - CommonOptionsParser OptionsParser(argc, argv); - ClangTool Tool(OptionsParser.GetCompilations(), - OptionsParser.GetSourcePathList()); - - LoopPrinter Printer; - MatchFinder Finder; - Finder.addMatcher(LoopMatcher, &Printer); - - return Tool.run(newFrontendActionFactory(&Finder)); - } -</pre> - -<p>Now, you should be able to recompile and run the code to discover for loops. -Create a new file with a few examples, and test out our new handiwork:</p> - -<pre class="doc_code"> - cd ~/clang-llvm/llvm/llvm_build/ - ninja loop-convert - vim ~/test-files/simple-loops.cc - bin/loop-convert ~/test-files/simple-loops.cc -</pre> - -<!-- FIXME: add example step-2a --> - -<!-- ======================================================================= --> -<h2 id="morematchers">Step 3.5: More Complicated Matchers</h2> -<!-- ======================================================================= --> -<p>Our simple matcher is capable of discovering for loops, but we would still -need to filter out many more ourselves. We can do a good portion of the -remaining work with some cleverly chosen matchers, but first we need to decide -exactly which properties we want to allow.</p> - -<p>How can we characterize for loops over arrays which would be eligible for -translation to range-based syntax? Range based loops over arrays of size -<tt>N</tt> that:</p> -<ul> - <li>start at index <tt>0</tt></li> - <li>iterate consecutively</li> - <li>end at index <tt>N-1</tt></li> -</ul> - -<p>We already check for (1), so all we need to add is a check to the loop's -condition to ensure that the loop's index variable is compared against -<tt>N</tt> and another check to ensure that the increment step just increments -this same variable. The matcher for (2) is straightforward: require a pre- or -post-increment of the same variable declared in the init portion.</p> - -<p>Unfortunately, such a matcher is impossible to write. Matchers contain no -logic for comparing two arbitrary AST nodes and determining whether or not they -are equal, so the best we can do is matching more than we would like to allow, -and punting extra comparisons to the callback.</p> - -<p>In any case, we can start building this sub-matcher. We can require that the -increment step be a unary increment like this:</p> - -<pre class="doc_code"> - hasIncrement(unaryOperator(hasOperatorName("++"))) -</pre> - -<p>Specifying what is incremented introduces another quirk of Clang's AST: -Usages of variables are represented as <tt>DeclRefExpr</tt>'s ("declaration -reference expressions") because they are expressions which refer to variable -declarations. To find a <tt>unaryOperator</tt> that refers to a specific -declaration, we can simply add a second condition to it:</p> -<pre class="doc_code"> - hasIncrement(unaryOperator( - hasOperatorName("++"), - hasUnaryOperand(declRefExpr()))) -</pre> - -<p>Furthermore, we can restrict our matcher to only match if the incremented -variable is an integer:</p> -<pre class="doc_code"> - hasIncrement(unaryOperator( - hasOperatorName("++"), - hasUnaryOperand(declRefExpr(to(varDecl(hasType(isInteger()))))))) -</pre> - -</p>And the last step will be to attach an identifier to this variable, so that -we can retrieve it in the callback:</p> -<pre class="doc_code"> - hasIncrement(unaryOperator( - hasOperatorName("++"), - hasUnaryOperand(declRefExpr(to( - varDecl(hasType(isInteger())).bind("incrementVariable")))))) -</pre> - -<p>We can add this code to the definition of <tt>LoopMatcher</tt> and make sure -that our program, outfitted with the new matcher, only prints out loops that -declare a single variable initialized to zero and have an increment step -consisting of a unary increment of some variable.</p> - -<!-- FIXME: add example step-2b --> - -<p>Now, we just need to add a matcher to check if the condition part of the -<tt>for</tt> loop compares a variable against the size of the array. There is -only one problem - we don't know which array we're iterating over without -looking at the body of the loop! We are again restricted to approximating the -result we want with matchers, filling in the details in the callback. So we -start with:</p> -<pre class="doc_code"> - hasCondition(binaryOperator(hasOperatorName("<")) -</pre> - -<p>It makes sense to ensure that the left-hand side is a reference to a -variable, and that the right-hand side has integer type.</p> -<pre class="doc_code"> - hasCondition(binaryOperator( - hasOperatorName("<"), - hasRHS(expr(hasType(isInteger()))), - hasLHS(declRefExpr(to(varDecl(hasType(isInteger()))))))) -</pre> - -<!-- FIXME: add example step-2c --> - -<p>Why? Because it doesn't work. Of the three loops provided in -<tt>test-files/simple.cpp</tt>, zero of them have a matching condition. A quick -look at the AST dump of the first for loop, produced by the previous iteration -of loop-convert, shows us the answer:</p> - -<pre class="doc_code"> - (ForStmt 0x173b240 - (DeclStmt 0x173afc8 - 0x173af50 "int i = - (IntegerLiteral 0x173afa8 'int' 0)") - <<<NULL>>> - (BinaryOperator 0x173b060 '_Bool' '<' - (ImplicitCastExpr 0x173b030 'int' <LValueToRValue> - (DeclRefExpr 0x173afe0 'int' lvalue Var 0x173af50 'i' 'int')) - (ImplicitCastExpr 0x173b048 'int' <LValueToRValue> - (DeclRefExpr 0x173b008 'const int' lvalue Var 0x170fa80 'N' 'const int'))) - (UnaryOperator 0x173b0b0 'int' lvalue prefix '++' - (DeclRefExpr 0x173b088 'int' lvalue Var 0x173af50 'i' 'int')) - (CompoundStatement … -</pre> - -<p>We already know that the declaration and increments both match, or this loop -wouldn't have been dumped. The culprit lies in the implicit cast applied to the -first operand (i.e. the LHS) of the less-than operator, an L-value to R-value -conversion applied to the expression referencing <tt>i</tt>. Thankfully, the -matcher library offers a solution to this problem in the form of -<tt>ignoringParenImpCasts</tt>, which instructs the matcher to ignore implicit -casts and parentheses before continuing to match. Adjusting the condition -operator will restore the desired match.</p> - -<pre class="doc_code"> - hasCondition(binaryOperator( - hasOperatorName("<"), - hasLHS(expr(hasType(isInteger()))), - hasRHS(ignoringParenImpCasts(declRefExpr( - to(varDecl(hasType(isInteger())))))))) -</pre> - -<p>After adding binds to the expressions we wished to capture and extracting the -identifier strings into variables, we have array-step-2 completed.</p> - -<!-- ======================================================================= --> -<h2 id="usingastmatchers">Step 4: Retrieving Matched Nodes</h2> -<!-- ======================================================================= --> -<p>So far, the matcher callback isn't very interesting: it just dumps the loop's -AST. At some point, we will need to make changes to the input source code. Next, -we'll work on using the nodes we bound in the previous step.</p> - -<p>The <tt>MatchFinder::run()</tt> callback takes a -<tt>MatchFinder::MatchResult&</tt> as its parameter. We're most interested in -its <tt>Context</tt> and <tt>Nodes</tt> members. Clang uses the -<tt>ASTContext</tt> class to represent contextual information about the AST, as -the name implies, though the most functionally important detail is that several -operations require an <tt>ASTContext*</tt> parameter. More immediately useful is -the set of matched nodes, and how we retrieve them.</p> - -<!-- FIXME: Where is this binding described? --> - -<p>Since we bind three variables (identified by ConditionVarName, -InitVarName, and IncrementVarName), we can obtain the matched nodes by using the -<tt>getNodeAs()</tt> member function.</p> - -<p>In <tt>LoopActions.cpp</tt>:</p> -<pre class="doc_code"> - #include "clang/AST/ASTContext.h" - - void LoopPrinter::run(const MatchFinder::MatchResult &Result) { - ASTContext *Context = Result.Context; - const ForStmt *FS = Result.Nodes.getStmtAs<ForStmt>(LoopName); - // We do not want to convert header files! - if (!FS || !Context->getSourceManager().isFromMainFile(FS->getForLoc())) - return; - const VarDecl *IncVar = Result.Nodes.getNodeAs<VarDecl>(IncrementVarName); - const VarDecl *CondVar = Result.Nodes.getNodeAs<VarDecl>(ConditionVarName); - const VarDecl *InitVar = Result.Nodes.getNodeAs<VarDecl>(InitVarName); -</pre> - -<p>Now that we have the three variables, represented by their respective -declarations, let's make sure that they're all the same, using a helper function -I call <tt>areSameVariable()</tt>.</p> -<pre class="doc_code"> - if (!areSameVariable(IncVar, CondVar) || !areSameVariable(IncVar, InitVar)) - return; - llvm::outs() << "Potential array-based loop discovered.\n"; -} -</pre> - -<p>If execution reaches the end of <tt>LoopPrinter::run()</tt>, we know that the -loop shell that looks like</p> -<pre class="doc_code"> - for (int i= 0; i < expr(); ++i) { ... } -</pre> - -<p>For now, we will just print a message explaining that we found a loop. The -next section will deal with recursively traversing the AST to discover all -changes needed.</p> - -<p>As a side note, here is the implementation of <tt>areSameVariable</tt>. Clang -associates a <tt>VarDecl</tt> with each variable to represent the variable's -declaration. Since the "canonical" form of each declaration is unique by -address, all we need to do is make sure neither <tt>ValueDecl</tt> (base class -of <tt>VarDecl</tt>) is <tt>NULL</tt> and compare the canonical Decls.</p> -<pre class="doc_code"> - static bool areSameVariable(const ValueDecl *First, const ValueDecl *Second) { - return First && Second && - First->getCanonicalDecl() == Second->getCanonicalDecl(); - } -</pre> - -<p>It's not as trivial to test if two expressions are the same, though Clang has -already done the hard work for us by providing a way to canonicalize -expressions:</p> -<pre class="doc_code"> - static bool areSameExpr(ASTContext* Context, const Expr *First, - const Expr *Second) { - if (!First || !Second) - return false; - llvm::FoldingSetNodeID FirstID, SecondID; - First->Profile(FirstID, *Context, true); - Second->Profile(SecondID, *Context, true); - return FirstID == SecondID; - } -</pre> - -<!-- FIXME: Add code example. --> - -<p>This code relies on the comparison between two -<tt>llvm::FoldingSetNodeIDs</tt>. As the documentation for -<tt>Stmt::Profile()</tt> indicates, the <tt>Profile()</tt> member function -builds a description of a node in the AST, based on its properties, along with -those of its children. <tt>FoldingSetNodeID</tt> then serves as a hash we can -use to compare expressions. We will need <tt>areSameExpr</tt> later. Before you -run the new code on the additional loops added to test-files/simple.cpp, try to -figure out which ones will be considered potentially convertible.</p> - -</div> -</body> -</html> diff --git a/clang/docs/LibASTMatchersTutorial.rst b/clang/docs/LibASTMatchersTutorial.rst new file mode 100644 index 00000000000..21d26897f35 --- /dev/null +++ b/clang/docs/LibASTMatchersTutorial.rst @@ -0,0 +1,532 @@ +=============================================================== +Tutorial for building tools using LibTooling and LibASTMatchers +=============================================================== + +This document is intended to show how to build a useful source-to-source +translation tool based on Clang's `LibTooling <LibTooling.html>`_. It is +explicitly aimed at people who are new to Clang, so all you should need +is a working knowledge of C++ and the command line. + +In order to work on the compiler, you need some basic knowledge of the +abstract syntax tree (AST). To this end, the reader is incouraged to +skim the :doc:`Introduction to the Clang +AST <IntroductionToTheClangAST>` + +Step 0: Obtaining Clang +======================= + +As Clang is part of the LLVM project, you'll need to download LLVM's +source code first. Both Clang and LLVM are maintained as Subversion +repositories, but we'll be accessing them through the git mirror. For +further information, see the `getting started +guide <http://llvm.org/docs/GettingStarted.html>`_. + +:: + + mkdir ~/clang-llvm && cd ~/clang-llvm + git clone http://llvm.org/git/llvm.git + cd llvm/tools + git clone http://llvm.org/git/clang.git + +Next you need to obtain the CMake build system and Ninja build tool. You +may already have CMake installed, but current binary versions of CMake +aren't built with Ninja support. + +:: + + cd ~/clang-llvm + git clone https://github.com/martine/ninja.git + cd ninja + git checkout release + ./bootstrap.py + sudo cp ninja /usr/bin/ + + cd ~/clang-llvm + git clone git://cmake.org/stage/cmake.git + cd cmake + git checkout next + ./bootstrap + make + sudo make install + +Okay. Now we'll build Clang! + +:: + + cd ~/clang-llvm + mkdir build && cd build + cmake -G Ninja ../llvm -DLLVM_BUILD_TESTS=ON # Enable tests; default is off. + ninja + ninja check # Test LLVM only. + ninja clang-test # Test Clang only. + ninja install + +And we're live. + +All of the tests should pass, though there is a (very) small chance that +you can catch LLVM and Clang out of sync. Running ``'git svn rebase'`` +in both the llvm and clang directories should fix any problems. + +Finally, we want to set Clang as its own compiler. + +:: + + cd ~/clang-llvm/build + ccmake ../llvm + +The second command will bring up a GUI for configuring Clang. You need +to set the entry for ``CMAKE_CXX_COMPILER``. Press ``'t'`` to turn on +advanced mode. Scroll down to ``CMAKE_CXX_COMPILER``, and set it to +``/usr/bin/clang++``, or wherever you installed it. Press ``'c'`` to +configure, then ``'g'`` to generate CMake's files. + +Finally, run ninja one last time, and you're done. + +Step 1: Create a ClangTool +========================== + +Now that we have enough background knowledge, it's time to create the +simplest productive ClangTool in existence: a syntax checker. While this +already exists as ``clang-check``, it's important to understand what's +going on. + +First, we'll need to create a new directory for our tool and tell CMake +that it exists. As this is not going to be a core clang tool, it will +live in the ``tools/extra`` repository. + +:: + + cd ~/clang-llvm/llvm/tools/clang + mkdir tools/extra/loop-convert + echo 'add_subdirectory(loop-convert)' >> tools/extra/CMakeLists.txt + vim tools/extra/loop-convert/CMakeLists.txt + +CMakeLists.txt should have the following contents: + +:: + + set(LLVM_LINK_COMPONENTS support) + set(LLVM_USED_LIBS clangTooling clangBasic clangAST) + + add_clang_executable(loop-convert + LoopConvert.cpp + ) + target_link_libraries(loop-convert + clangTooling + clangBasic + clangASTMatchers + ) + +With that done, Ninja will be able to compile our tool. Let's give it +something to compile! Put the following into +``tools/extra/loop-convert/LoopConvert.cpp``. A detailed explanation of +why the different parts are needed can be found in the `LibTooling +documentation <LibTooling.html>`_. + +:: + + // Declares clang::SyntaxOnlyAction. + #include "clang/Frontend/FrontendActions.h" + #include "clang/Tooling/CommonOptionsParser.h" + #include "clang/Tooling/Tooling.h" + // Declares llvm::cl::extrahelp. + #include "llvm/Support/CommandLine.h" + + using namespace clang::tooling; + using namespace llvm; + + // CommonOptionsParser declares HelpMessage with a description of the common + // command-line options related to the compilation database and input files. + // It's nice to have this help message in all tools. + static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage); + + // A help message for this specific tool can be added afterwards. + static cl::extrahelp MoreHelp("\nMore help text..."); + + int main(int argc, const char **argv) { + CommonOptionsParser OptionsParser(argc, argv); + ClangTool Tool(OptionsParser.GetCompilations(), + OptionsParser.GetSourcePathList()); + return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>()); + } + +And that's it! You can compile our new tool by running ninja from the +``build`` directory. + +:: + + cd ~/clang-llvm/build + ninja + +You should now be able to run the syntax checker, which is located in +``~/clang-llvm/build/bin``, on any source file. Try it! + +:: + + cat "void main() {}" > test.cpp + bin/loop-convert test.cpp -- + +Note the two dashes after we specify the source file. The additional +options for the compiler are passed after the dashes rather than loading +them from a compilation database - there just aren't any options needed +right now. + +Intermezzo: Learn AST matcher basics +==================================== + +Clang recently introduced the :doc:`ASTMatcher +library <LibASTMatchers>` to provide a simple, powerful, and +concise way to describe specific patterns in the AST. Implemented as a +DSL powered by macros and templates (see +`ASTMatchers.h <../doxygen/ASTMatchers_8h_source.html>`_ if you're +curious), matchers offer the feel of algebraic data types common to +functional programming languages. + +For example, suppose you wanted to examine only binary operators. There +is a matcher to do exactly that, conveniently named ``binaryOperator``. +I'll give you one guess what this matcher does: + +:: + + binaryOperator(hasOperatorName("+"), hasLHS(integerLiteral(equals(0)))) + +Shockingly, it will match against addition expressions whose left hand +side is exactly the literal 0. It will not match against other forms of +0, such as ``'\0'`` or ``NULL``, but it will match against macros that +expand to 0. The matcher will also not match against calls to the +overloaded operator ``'+'``, as there is a separate ``operatorCallExpr`` +matcher to handle overloaded operators. + +There are AST matchers to match all the different nodes of the AST, +narrowing matchers to only match AST nodes fulfilling specific criteria, +and traversal matchers to get from one kind of AST node to another. For +a complete list of AST matchers, take a look at the `AST Matcher +References <LibASTMatchersReference.html>`_ + +All matcher that are nouns describe entities in the AST and can be +bound, so that they can be referred to whenever a match is found. To do +so, simply call the method ``bind`` on these matchers, e.g.: + +:: + + variable(hasType(isInteger())).bind("intvar") + +Step 2: Using AST matchers +========================== + +Okay, on to using matchers for real. Let's start by defining a matcher +which will capture all ``for`` statements that define a new variable +initialized to zero. Let's start with matching all ``for`` loops: + +:: + + forStmt() + +Next, we want to specify that a single variable is declared in the first +portion of the loop, so we can extend the matcher to + +:: + + forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl())))) + +Finally, we can add the condition that the variable is initialized to +zero. + +:: + + forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl( + hasInitializer(integerLiteral(equals(0)))))))) + +It is fairly easy to read and understand the matcher definition ("match +loops whose init portion declares a single variable which is initialized +to the integer literal 0"), but deciding that every piece is necessary +is more difficult. Note that this matcher will not match loops whose +variables are initialized to ``'\0'``, ``0.0``, ``NULL``, or any form of +zero besides the integer 0. + +The last step is giving the matcher a name and binding the ``ForStmt`` +as we will want to do something with it: + +:: + + StatementMatcher LoopMatcher = + forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl( + hasInitializer(integerLiteral(equals(0)))))))).bind("forLoop"); + +Once you have defined your matchers, you will need to add a little more +scaffolding in order to run them. Matchers are paired with a +``MatchCallback`` and registered with a ``MatchFinder`` object, then run +from a ``ClangTool``. More code! + +Add the following to ``LoopConvert.cpp``: + +:: + + StatementMatcher LoopMatcher = + forStmt(hasLoopInit(declStmt(hasSingleDecl(varDecl( + hasInitializer(integerLiteral(equals(0)))))))).bind("forLoop"); + + class LoopPrinter : public MatchFinder::MatchCallback { + public : + virtual void run(const MatchFinder::MatchResult &Result) { + if (const ForStmt *FS = Result.Nodes.getNodeAs<clang::ForStmt>("forLoop")) + FS->dump(); + }; + +And change ``main()`` to: + +:: + + int main(int argc, const char **argv) { + CommonOptionsParser OptionsParser(argc, argv); + ClangTool Tool(OptionsParser.GetCompilations(), + OptionsParser.GetSourcePathList()); + + LoopPrinter Printer; + MatchFinder Finder; + Finder.addMatcher(LoopMatcher, &Printer); + + return Tool.run(newFrontendActionFactory(&Finder)); + } + +Now, you should be able to recompile and run the code to discover for +loops. Create a new file with a few examples, and test out our new +handiwork: + +:: + + cd ~/clang-llvm/llvm/llvm_build/ + ninja loop-convert + vim ~/test-files/simple-loops.cc + bin/loop-convert ~/test-files/simple-loops.cc + +Step 3.5: More Complicated Matchers +=================================== + +Our simple matcher is capable of discovering for loops, but we would +still need to filter out many more ourselves. We can do a good portion +of the remaining work with some cleverly chosen matchers, but first we +need to decide exactly which properties we want to allow. + +How can we characterize for loops over arrays which would be eligible +for translation to range-based syntax? Range based loops over arrays of +size ``N`` that: + +- start at index ``0`` +- iterate consecutively +- end at index ``N-1`` + +We already check for (1), so all we need to add is a check to the loop's +condition to ensure that the loop's index variable is compared against +``N`` and another check to ensure that the increment step just +increments this same variable. The matcher for (2) is straightforward: +require a pre- or post-increment of the same variable declared in the +init portion. + +Unfortunately, such a matcher is impossible to write. Matchers contain +no logic for comparing two arbitrary AST nodes and determining whether +or not they are equal, so the best we can do is matching more than we +would like to allow, and punting extra comparisons to the callback. + +In any case, we can start building this sub-matcher. We can require that +the increment step be a unary increment like this: + +:: + + hasIncrement(unaryOperator(hasOperatorName("++"))) + +Specifying what is incremented introduces another quirk of Clang's AST: +Usages of variables are represented as ``DeclRefExpr``'s ("declaration +reference expressions") because they are expressions which refer to +variable declarations. To find a ``unaryOperator`` that refers to a +specific declaration, we can simply add a second condition to it: + +:: + + hasIncrement(unaryOperator( + hasOperatorName("++"), + hasUnaryOperand(declRefExpr()))) + +Furthermore, we can restrict our matcher to only match if the +incremented variable is an integer: + +:: + + hasIncrement(unaryOperator( + hasOperatorName("++"), + hasUnaryOperand(declRefExpr(to(varDecl(hasType(isInteger()))))))) + +And the last step will be to attach an identifier to this variable, so +that we can retrieve it in the callback: + +:: + + hasIncrement(unaryOperator( + hasOperatorName("++"), + hasUnaryOperand(declRefExpr(to( + varDecl(hasType(isInteger())).bind("incrementVariable")))))) + +We can add this code to the definition of ``LoopMatcher`` and make sure +that our program, outfitted with the new matcher, only prints out loops +that declare a single variable initialized to zero and have an increment +step consisting of a unary increment of some variable. + +Now, we just need to add a matcher to check if the condition part of the +``for`` loop compares a variable against the size of the array. There is +only one problem - we don't know which array we're iterating over +without looking at the body of the loop! We are again restricted to +approximating the result we want with matchers, filling in the details +in the callback. So we start with: + +:: + + hasCondition(binaryOperator(hasOperatorName("<")) + +It makes sense to ensure that the left-hand side is a reference to a +variable, and that the right-hand side has integer type. + +:: + + hasCondition(binaryOperator( + hasOperatorName("<"), + hasRHS(expr(hasType(isInteger()))), + hasLHS(declRefExpr(to(varDecl(hasType(isInteger()))))))) + +Why? Because it doesn't work. Of the three loops provided in +``test-files/simple.cpp``, zero of them have a matching condition. A +quick look at the AST dump of the first for loop, produced by the +previous iteration of loop-convert, shows us the answer: + +:: + + (ForStmt 0x173b240 + (DeclStmt 0x173afc8 + 0x173af50 "int i = + (IntegerLiteral 0x173afa8 'int' 0)") + <<>> + (BinaryOperator 0x173b060 '_Bool' '<' + (ImplicitCastExpr 0x173b030 'int' + (DeclRefExpr 0x173afe0 'int' lvalue Var 0x173af50 'i' 'int')) + (ImplicitCastExpr 0x173b048 'int' + (DeclRefExpr 0x173b008 'const int' lvalue Var 0x170fa80 'N' 'const int'))) + (UnaryOperator 0x173b0b0 'int' lvalue prefix '++' + (DeclRefExpr 0x173b088 'int' lvalue Var 0x173af50 'i' 'int')) + (CompoundStatement … + +We already know that the declaration and increments both match, or this +loop wouldn't have been dumped. The culprit lies in the implicit cast +applied to the first operand (i.e. the LHS) of the less-than operator, +an L-value to R-value conversion applied to the expression referencing +``i``. Thankfully, the matcher library offers a solution to this problem +in the form of ``ignoringParenImpCasts``, which instructs the matcher to +ignore implicit casts and parentheses before continuing to match. +Adjusting the condition operator will restore the desired match. + +:: + + hasCondition(binaryOperator( + hasOperatorName("<"), + hasLHS(expr(hasType(isInteger()))), + hasRHS(ignoringParenImpCasts(declRefExpr( + to(varDecl(hasType(isInteger())))))))) + +After adding binds to the expressions we wished to capture and +extracting the identifier strings into variables, we have array-step-2 +completed. + +Step 4: Retrieving Matched Nodes +================================ + +So far, the matcher callback isn't very interesting: it just dumps the +loop's AST. At some point, we will need to make changes to the input +source code. Next, we'll work on using the nodes we bound in the +previous step. + +The ``MatchFinder::run()`` callback takes a +``MatchFinder::MatchResult&`` as its parameter. We're most interested in +its ``Context`` and ``Nodes`` members. Clang uses the ``ASTContext`` +class to represent contextual information about the AST, as the name +implies, though the most functionally important detail is that several +operations require an ``ASTContext*`` parameter. More immediately useful +is the set of matched nodes, and how we retrieve them. + +Since we bind three variables (identified by ConditionVarName, +InitVarName, and IncrementVarName), we can obtain the matched nodes by +using the ``getNodeAs()`` member function. + +In ``LoopActions.cpp``: + +:: + + #include "clang/AST/ASTContext.h" + + void LoopPrinter::run(const MatchFinder::MatchResult &Result) { + ASTContext *Context = Result.Context; + const ForStmt *FS = Result.Nodes.getStmtAs<ForStmt>(LoopName); + // We do not want to convert header files! + if (!FS || !Context->getSourceManager().isFromMainFile(FS->getForLoc())) + return; + const VarDecl *IncVar = Result.Nodes.getNodeAs<VarDecl>(IncrementVarName); + const VarDecl *CondVar = Result.Nodes.getNodeAs<VarDecl>(ConditionVarName); + const VarDecl *InitVar = Result.Nodes.getNodeAs<VarDecl>(InitVarName); + +Now that we have the three variables, represented by their respective +declarations, let's make sure that they're all the same, using a helper +function I call ``areSameVariable()``. + +:: + + if (!areSameVariable(IncVar, CondVar) || !areSameVariable(IncVar, InitVar)) + return; + llvm::outs() << "Potential array-based loop discovered.\n"; + } + +If execution reaches the end of ``LoopPrinter::run()``, we know that the +loop shell that looks like + +:: + + for (int i= 0; i < expr(); ++i) { ... } + +For now, we will just print a message explaining that we found a loop. +The next section will deal with recursively traversing the AST to +discover all changes needed. + +As a side note, here is the implementation of ``areSameVariable``. Clang +associates a ``VarDecl`` with each variable to represent the variable's +declaration. Since the "canonical" form of each declaration is unique by +address, all we need to do is make sure neither ``ValueDecl`` (base +class of ``VarDecl``) is ``NULL`` and compare the canonical Decls. + +:: + + static bool areSameVariable(const ValueDecl *First, const ValueDecl *Second) { + return First && Second && + First->getCanonicalDecl() == Second->getCanonicalDecl(); + } + +It's not as trivial to test if two expressions are the same, though +Clang has already done the hard work for us by providing a way to +canonicalize expressions: + +:: + + static bool areSameExpr(ASTContext* Context, const Expr *First, + const Expr *Second) { + if (!First || !Second) + return false; + llvm::FoldingSetNodeID FirstID, SecondID; + First->Profile(FirstID, *Context, true); + Second->Profile(SecondID, *Context, true); + return FirstID == SecondID; + } + +This code relies on the comparison between two +``llvm::FoldingSetNodeIDs``. As the documentation for +``Stmt::Profile()`` indicates, the ``Profile()`` member function builds +a description of a node in the AST, based on its properties, along with +those of its children. ``FoldingSetNodeID`` then serves as a hash we can +use to compare expressions. We will need ``areSameExpr`` later. Before +you run the new code on the additional loops added to +test-files/simple.cpp, try to figure out which ones will be considered +potentially convertible. diff --git a/clang/docs/PTHInternals.html b/clang/docs/PTHInternals.html deleted file mode 100644 index b15f6816067..00000000000 --- a/clang/docs/PTHInternals.html +++ /dev/null @@ -1,179 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> - <head> - <title>Pretokenized Headers (PTH)</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>Pretokenized Headers (PTH)</h1> - -<p>This document first describes the low-level -interface for using PTH and then briefly elaborates on its design and -implementation. If you are interested in the end-user view, please see the -<a href="UsersManual.html#precompiledheaders">User's Manual</a>.</p> - - -<h2>Using Pretokenized Headers with <tt>clang</tt> (Low-level Interface)</h2> - -<p>The Clang compiler frontend, <tt>clang -cc1</tt>, supports three command line -options for generating and using PTH files.<p> - -<p>To generate PTH files using <tt>clang -cc1</tt>, use the option -<b><tt>-emit-pth</tt></b>: - -<pre> $ clang -cc1 test.h -emit-pth -o test.h.pth </pre> - -<p>This option is transparently used by <tt>clang</tt> when generating PTH -files. Similarly, PTH files can be used as prefix headers using the -<b><tt>-include-pth</tt></b> option:</p> - -<pre> - $ clang -cc1 -include-pth test.h.pth test.c -o test.s -</pre> - -<p>Alternatively, Clang's PTH files can be used as a raw "token-cache" -(or "content" cache) of the source included by the original header -file. This means that the contents of the PTH file are searched as substitutes -for <em>any</em> source files that are used by <tt>clang -cc1</tt> to process a -source file. This is done by specifying the <b><tt>-token-cache</tt></b> -option:</p> - -<pre> - $ cat test.h - #include <stdio.h> - $ clang -cc1 -emit-pth test.h -o test.h.pth - $ cat test.c - #include "test.h" - $ clang -cc1 test.c -o test -token-cache test.h.pth -</pre> - -<p>In this example the contents of <tt>stdio.h</tt> (and the files it includes) -will be retrieved from <tt>test.h.pth</tt>, as the PTH file is being used in -this case as a raw cache of the contents of <tt>test.h</tt>. This is a low-level -interface used to both implement the high-level PTH interface as well as to -provide alternative means to use PTH-style caching.</p> - -<h2>PTH Design and Implementation</h2> - -<p>Unlike GCC's precompiled headers, which cache the full ASTs and preprocessor -state of a header file, Clang's pretokenized header files mainly cache the raw -lexer <em>tokens</em> that are needed to segment the stream of characters in a -source file into keywords, identifiers, and operators. Consequently, PTH serves -to mainly directly speed up the lexing and preprocessing of a source file, while -parsing and type-checking must be completely redone every time a PTH file is -used.</p> - -<h3>Basic Design Tradeoffs</h3> - -<p>In the long term there are plans to provide an alternate PCH implementation -for Clang that also caches the work for parsing and type checking the contents -of header files. The current implementation of PCH in Clang as pretokenized -header files was motivated by the following factors:<p> - -<ul> - -<li><p><b>Language independence</b>: PTH files work with any language that -Clang's lexer can handle, including C, Objective-C, and (in the early stages) -C++. This means development on language features at the parsing level or above -(which is basically almost all interesting pieces) does not require PTH to be -modified.</p></li> - -<li><b>Simple design</b>: Relatively speaking, PTH has a simple design and -implementation, making it easy to test. Further, because the machinery for PTH -resides at the lower-levels of the Clang library stack it is fairly -straightforward to profile and optimize.</li> -</ul> - -<p>Further, compared to GCC's PCH implementation (which is the dominate -precompiled header file implementation that Clang can be directly compared -against) the PTH design in Clang yields several attractive features:</p> - -<ul> - -<li><p><b>Architecture independence</b>: In contrast to GCC's PCH files (and -those of several other compilers), Clang's PTH files are architecture -independent, requiring only a single PTH file when building an program for -multiple architectures.</p> - -<p>For example, on Mac OS X one may wish to -compile a "universal binary" that runs on PowerPC, 32-bit Intel -(i386), and 64-bit Intel architectures. In contrast, GCC requires a PCH file for -each architecture, as the definitions of types in the AST are -architecture-specific. Since a Clang PTH file essentially represents a lexical -cache of header files, a single PTH file can be safely used when compiling for -multiple architectures. This can also reduce compile times because only a single -PTH file needs to be generated during a build instead of several.</p></li> - -<li><p><b>Reduced memory pressure</b>: Similar to GCC, -Clang reads PTH files via the use of memory mapping (i.e., <tt>mmap</tt>). -Clang, however, memory maps PTH files as read-only, meaning that multiple -invocations of <tt>clang -cc1</tt> can share the same pages in memory from a -memory-mapped PTH file. In comparison, GCC also memory maps its PCH files but -also modifies those pages in memory, incurring the copy-on-write costs. The -read-only nature of PTH can greatly reduce memory pressure for builds involving -multiple cores, thus improving overall scalability.</p></li> - -<li><p><b>Fast generation</b>: PTH files can be generated in a small fraction -of the time needed to generate GCC's PCH files. Since PTH/PCH generation is a -serial operation that typically blocks progress during a build, faster -generation time leads to improved processor utilization with parallel builds on -multicore machines.</p></li> - -</ul> - -<p>Despite these strengths, PTH's simple design suffers some algorithmic -handicaps compared to other PCH strategies such as those used by GCC. While PTH -can greatly speed up the processing time of a header file, the amount of work -required to process a header file is still roughly linear in the size of the -header file. In contrast, the amount of work done by GCC to process a -precompiled header is (theoretically) constant (the ASTs for the header are -literally memory mapped into the compiler). This means that only the pieces of -the header file that are referenced by the source file including the header are -the only ones the compiler needs to process during actual compilation. While -GCC's particular implementation of PCH mitigates some of these algorithmic -strengths via the use of copy-on-write pages, the approach itself can -fundamentally dominate at an algorithmic level, especially when one considers -header files of arbitrary size.</p> - -<p>There are plans to potentially implement an complementary PCH implementation -for Clang based on the lazy deserialization of ASTs. This approach would -theoretically have the same constant-time algorithmic advantages just mentioned -but would also retain some of the strengths of PTH such as reduced memory -pressure (ideal for multi-core builds).</p> - -<h3>Internal PTH Optimizations</h3> - -<p>While the main optimization employed by PTH is to reduce lexing time of -header files by caching pre-lexed tokens, PTH also employs several other -optimizations to speed up the processing of header files:</p> - -<ul> - -<li><p><em><tt>stat</tt> caching</em>: PTH files cache information obtained via -calls to <tt>stat</tt> that <tt>clang -cc1</tt> uses to resolve which files are -included by <tt>#include</tt> directives. This greatly reduces the overhead -involved in context-switching to the kernel to resolve included files.</p></li> - -<li><p><em>Fasting skipping of <tt>#ifdef</tt>...<tt>#endif</tt> chains</em>: -PTH files record the basic structure of nested preprocessor blocks. When the -condition of the preprocessor block is false, all of its tokens are immediately -skipped instead of requiring them to be handled by Clang's -preprocessor.</p></li> - -</ul> - -</div> -</body> -</html> diff --git a/clang/docs/PTHInternals.rst b/clang/docs/PTHInternals.rst new file mode 100644 index 00000000000..d37b76736b0 --- /dev/null +++ b/clang/docs/PTHInternals.rst @@ -0,0 +1,164 @@ +========================== +Pretokenized Headers (PTH) +========================== + +This document first describes the low-level interface for using PTH and +then briefly elaborates on its design and implementation. If you are +interested in the end-user view, please see the `User's +Manual <UsersManual.html#precompiledheaders>`_. + +Using Pretokenized Headers with ``clang`` (Low-level Interface) +=============================================================== + +The Clang compiler frontend, ``clang -cc1``, supports three command line +options for generating and using PTH files. + +To generate PTH files using ``clang -cc1``, use the option +``-emit-pth``: + +:: + + $ clang -cc1 test.h -emit-pth -o test.h.pth + +This option is transparently used by ``clang`` when generating PTH +files. Similarly, PTH files can be used as prefix headers using the +``-include-pth`` option: + +:: + + $ clang -cc1 -include-pth test.h.pth test.c -o test.s + +Alternatively, Clang's PTH files can be used as a raw "token-cache" (or +"content" cache) of the source included by the original header file. +This means that the contents of the PTH file are searched as substitutes +for *any* source files that are used by ``clang -cc1`` to process a +source file. This is done by specifying the ``-token-cache`` option: + +:: + + $ cat test.h + #include <stdio.h> + $ clang -cc1 -emit-pth test.h -o test.h.pth + $ cat test.c + #include "test.h" + $ clang -cc1 test.c -o test -token-cache test.h.pth + +In this example the contents of ``stdio.h`` (and the files it includes) +will be retrieved from ``test.h.pth``, as the PTH file is being used in +this case as a raw cache of the contents of ``test.h``. This is a +low-level interface used to both implement the high-level PTH interface +as well as to provide alternative means to use PTH-style caching. + +PTH Design and Implementation +============================= + +Unlike GCC's precompiled headers, which cache the full ASTs and +preprocessor state of a header file, Clang's pretokenized header files +mainly cache the raw lexer *tokens* that are needed to segment the +stream of characters in a source file into keywords, identifiers, and +operators. Consequently, PTH serves to mainly directly speed up the +lexing and preprocessing of a source file, while parsing and +type-checking must be completely redone every time a PTH file is used. + +Basic Design Tradeoffs +~~~~~~~~~~~~~~~~~~~~~~ + +In the long term there are plans to provide an alternate PCH +implementation for Clang that also caches the work for parsing and type +checking the contents of header files. The current implementation of PCH +in Clang as pretokenized header files was motivated by the following +factors: + +**Language independence** + PTH files work with any language that + Clang's lexer can handle, including C, Objective-C, and (in the early + stages) C++. This means development on language features at the + parsing level or above (which is basically almost all interesting + pieces) does not require PTH to be modified. + +**Simple design** + Relatively speaking, PTH has a simple design and + implementation, making it easy to test. Further, because the + machinery for PTH resides at the lower-levels of the Clang library + stack it is fairly straightforward to profile and optimize. + +Further, compared to GCC's PCH implementation (which is the dominate +precompiled header file implementation that Clang can be directly +compared against) the PTH design in Clang yields several attractive +features: + +**Architecture independence** + In contrast to GCC's PCH files (and + those of several other compilers), Clang's PTH files are architecture + independent, requiring only a single PTH file when building an + program for multiple architectures. + + For example, on Mac OS X one may wish to compile a "universal binary" + that runs on PowerPC, 32-bit Intel (i386), and 64-bit Intel + architectures. In contrast, GCC requires a PCH file for each + architecture, as the definitions of types in the AST are + architecture-specific. Since a Clang PTH file essentially represents + a lexical cache of header files, a single PTH file can be safely used + when compiling for multiple architectures. This can also reduce + compile times because only a single PTH file needs to be generated + during a build instead of several. + +**Reduced memory pressure** + Similar to GCC, Clang reads PTH files + via the use of memory mapping (i.e., ``mmap``). Clang, however, + memory maps PTH files as read-only, meaning that multiple invocations + of ``clang -cc1`` can share the same pages in memory from a + memory-mapped PTH file. In comparison, GCC also memory maps its PCH + files but also modifies those pages in memory, incurring the + copy-on-write costs. The read-only nature of PTH can greatly reduce + memory pressure for builds involving multiple cores, thus improving + overall scalability. + +**Fast generation** + PTH files can be generated in a small fraction + of the time needed to generate GCC's PCH files. Since PTH/PCH + generation is a serial operation that typically blocks progress + during a build, faster generation time leads to improved processor + utilization with parallel builds on multicore machines. + +Despite these strengths, PTH's simple design suffers some algorithmic +handicaps compared to other PCH strategies such as those used by GCC. +While PTH can greatly speed up the processing time of a header file, the +amount of work required to process a header file is still roughly linear +in the size of the header file. In contrast, the amount of work done by +GCC to process a precompiled header is (theoretically) constant (the +ASTs for the header are literally memory mapped into the compiler). This +means that only the pieces of the header file that are referenced by the +source file including the header are the only ones the compiler needs to +process during actual compilation. While GCC's particular implementation +of PCH mitigates some of these algorithmic strengths via the use of +copy-on-write pages, the approach itself can fundamentally dominate at +an algorithmic level, especially when one considers header files of +arbitrary size. + +There are plans to potentially implement an complementary PCH +implementation for Clang based on the lazy deserialization of ASTs. This +approach would theoretically have the same constant-time algorithmic +advantages just mentioned but would also retain some of the strengths of +PTH such as reduced memory pressure (ideal for multi-core builds). + +Internal PTH Optimizations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While the main optimization employed by PTH is to reduce lexing time of +header files by caching pre-lexed tokens, PTH also employs several other +optimizations to speed up the processing of header files: + +- ``stat`` caching: PTH files cache information obtained via calls to + ``stat`` that ``clang -cc1`` uses to resolve which files are included + by ``#include`` directives. This greatly reduces the overhead + involved in context-switching to the kernel to resolve included + files. + +- Fasting skipping of ``#ifdef``... ``#endif`` chains: PTH files + record the basic structure of nested preprocessor blocks. When the + condition of the preprocessor block is false, all of its tokens are + immediately skipped instead of requiring them to be handled by + Clang's preprocessor. + + diff --git a/clang/docs/RAVFrontendAction.html b/clang/docs/RAVFrontendAction.html deleted file mode 100644 index b30cd573d93..00000000000 --- a/clang/docs/RAVFrontendAction.html +++ /dev/null @@ -1,224 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>How to write RecursiveASTVisitor based ASTFrontendActions.</title> -<link type="text/css" rel="stylesheet" href="../menu.css"> -<link type="text/css" rel="stylesheet" href="../content.css"> -</head> -<body> - -<!--#include virtual="../menu.html.incl"--> - -<div id="content"> - -<h1>How to write RecursiveASTVisitor based ASTFrontendActions.</h1> - -<!-- ======================================================================= --> -<h2 id="intro">Introduction</h2> -<!-- ======================================================================= --> - -In this tutorial you will learn how to create a FrontendAction that uses -a RecursiveASTVisitor to find CXXRecordDecl AST nodes with a specified name. - -<!-- ======================================================================= --> -<h2 id="action">Creating a FrontendAction</h2> -<!-- ======================================================================= --> - -<p>When writing a clang based tool like a Clang Plugin or a standalone tool -based on LibTooling, the common entry point is the FrontendAction. -FrontendAction is an interface that allows execution of user specific actions -as part of the compilation. To run tools over the AST clang provides the -convenience interface ASTFrontendAction, which takes care of executing the -action. The only part left is to implement the CreateASTConsumer method that -returns an ASTConsumer per translation unit.</p> -<pre> - class FindNamedClassAction : public clang::ASTFrontendAction { - public: - virtual clang::ASTConsumer *CreateASTConsumer( - clang::CompilerInstance &Compiler, llvm::StringRef InFile) { - return new FindNamedClassConsumer; - } - }; -</pre> - -<!-- ======================================================================= --> -<h2 id="consumer">Creating an ASTConsumer</h2> -<!-- ======================================================================= --> - -<p>ASTConsumer is an interface used to write generic actions on an AST, -regardless of how the AST was produced. ASTConsumer provides many different -entry points, but for our use case the only one needed is HandleTranslationUnit, -which is called with the ASTContext for the translation unit.</p> -<pre> - class FindNamedClassConsumer : public clang::ASTConsumer { - public: - virtual void HandleTranslationUnit(clang::ASTContext &Context) { - // Traversing the translation unit decl via a RecursiveASTVisitor - // will visit all nodes in the AST. - Visitor.TraverseDecl(Context.getTranslationUnitDecl()); - } - private: - // A RecursiveASTVisitor implementation. - FindNamedClassVisitor Visitor; - }; -</pre> - -<!-- ======================================================================= --> -<h2 id="rav">Using the RecursiveASTVisitor</h2> -<!-- ======================================================================= --> - -<p>Now that everything is hooked up, the next step is to implement a -RecursiveASTVisitor to extract the relevant information from the AST.</p> -<p>The RecursiveASTVisitor provides hooks of the form -bool VisitNodeType(NodeType *) for most AST nodes; the exception are TypeLoc -nodes, which are passed by-value. We only need to implement the methods for the -relevant node types. -</p> -<p>Let's start by writing a RecursiveASTVisitor that visits all CXXRecordDecl's. -<pre> - class FindNamedClassVisitor - : public RecursiveASTVisitor<FindNamedClassVisitor> { - public: - bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) { - // For debugging, dumping the AST nodes will show which nodes are already - // being visited. - Declaration->dump(); - - // The return value indicates whether we want the visitation to proceed. - // Return false to stop the traversal of the AST. - return true; - } - }; -</pre> -</p> -<p>In the methods of our RecursiveASTVisitor we can now use the full power of -the Clang AST to drill through to the parts that are interesting for us. For -example, to find all class declaration with a certain name, we can check for a -specific qualified name: -<pre> - bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) { - if (Declaration->getQualifiedNameAsString() == "n::m::C") - Declaration->dump(); - return true; - } -</pre> -</p> - -<!-- ======================================================================= --> -<h2 id="context">Accessing the SourceManager and ASTContext</h2> -<!-- ======================================================================= --> - -<p>Some of the information about the AST, like source locations and global -identifier information, are not stored in the AST nodes themselves, but in -the ASTContext and its associated source manager. To retrieve them we need to -hand the ASTContext into our RecursiveASTVisitor implementation.</p> -<p>The ASTContext is available from the CompilerInstance during the call -to CreateASTConsumer. We can thus extract it there and hand it into our -freshly created FindNamedClassConsumer:</p> -<pre> - virtual clang::ASTConsumer *CreateASTConsumer( - clang::CompilerInstance &Compiler, llvm::StringRef InFile) { - return new FindNamedClassConsumer(<b>&Compiler.getASTContext()</b>); - } -</pre> - -<p>Now that the ASTContext is available in the RecursiveASTVisitor, we can do -more interesting things with AST nodes, like looking up their source -locations:</p> -<pre> - bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) { - if (Declaration->getQualifiedNameAsString() == "n::m::C") { - // getFullLoc uses the ASTContext's SourceManager to resolve the source - // location and break it up into its line and column parts. - FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart()); - if (FullLocation.isValid()) - llvm::outs() << "Found declaration at " - << FullLocation.getSpellingLineNumber() << ":" - << FullLocation.getSpellingColumnNumber() << "\n"; - } - return true; - } -</pre> - -<!-- ======================================================================= --> -<h2 id="full">Putting it all together</h2> -<!-- ======================================================================= --> - -<p>Now we can combine all of the above into a small example program:</p> -<pre> - #include "clang/AST/ASTConsumer.h" - #include "clang/AST/RecursiveASTVisitor.h" - #include "clang/Frontend/CompilerInstance.h" - #include "clang/Frontend/FrontendAction.h" - #include "clang/Tooling/Tooling.h" - - using namespace clang; - - class FindNamedClassVisitor - : public RecursiveASTVisitor<FindNamedClassVisitor> { - public: - explicit FindNamedClassVisitor(ASTContext *Context) - : Context(Context) {} - - bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) { - if (Declaration->getQualifiedNameAsString() == "n::m::C") { - FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart()); - if (FullLocation.isValid()) - llvm::outs() << "Found declaration at " - << FullLocation.getSpellingLineNumber() << ":" - << FullLocation.getSpellingColumnNumber() << "\n"; - } - return true; - } - - private: - ASTContext *Context; - }; - - class FindNamedClassConsumer : public clang::ASTConsumer { - public: - explicit FindNamedClassConsumer(ASTContext *Context) - : Visitor(Context) {} - - virtual void HandleTranslationUnit(clang::ASTContext &Context) { - Visitor.TraverseDecl(Context.getTranslationUnitDecl()); - } - private: - FindNamedClassVisitor Visitor; - }; - - class FindNamedClassAction : public clang::ASTFrontendAction { - public: - virtual clang::ASTConsumer *CreateASTConsumer( - clang::CompilerInstance &Compiler, llvm::StringRef InFile) { - return new FindNamedClassConsumer(&Compiler.getASTContext()); - } - }; - - int main(int argc, char **argv) { - if (argc > 1) { - clang::tooling::runToolOnCode(new FindNamedClassAction, argv[1]); - } - } -</pre> - -<p>We store this into a file called FindClassDecls.cpp and create the following -CMakeLists.txt to link it:</p> -<pre> -set(LLVM_USED_LIBS clangTooling) - -add_clang_executable(find-class-decls FindClassDecls.cpp) -</pre> - -<p>When running this tool over a small code snippet it will output all -declarations of a class n::m::C it found:</p> -<pre> - $ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }" - Found declaration at 1:29 -</pre> - -</div> -</body> -</html> - diff --git a/clang/docs/RAVFrontendAction.rst b/clang/docs/RAVFrontendAction.rst new file mode 100644 index 00000000000..2f60ce9e827 --- /dev/null +++ b/clang/docs/RAVFrontendAction.rst @@ -0,0 +1,216 @@ +========================================================== +How to write RecursiveASTVisitor based ASTFrontendActions. +========================================================== + +Introduction +============ + +In this tutorial you will learn how to create a FrontendAction that uses +a RecursiveASTVisitor to find CXXRecordDecl AST nodes with a specified +name. + +Creating a FrontendAction +========================= + +When writing a clang based tool like a Clang Plugin or a standalone tool +based on LibTooling, the common entry point is the FrontendAction. +FrontendAction is an interface that allows execution of user specific +actions as part of the compilation. To run tools over the AST clang +provides the convenience interface ASTFrontendAction, which takes care +of executing the action. The only part left is to implement the +CreateASTConsumer method that returns an ASTConsumer per translation +unit. + +:: + + class FindNamedClassAction : public clang::ASTFrontendAction { + public: + virtual clang::ASTConsumer *CreateASTConsumer( + clang::CompilerInstance &Compiler, llvm::StringRef InFile) { + return new FindNamedClassConsumer; + } + }; + +Creating an ASTConsumer +======================= + +ASTConsumer is an interface used to write generic actions on an AST, +regardless of how the AST was produced. ASTConsumer provides many +different entry points, but for our use case the only one needed is +HandleTranslationUnit, which is called with the ASTContext for the +translation unit. + +:: + + class FindNamedClassConsumer : public clang::ASTConsumer { + public: + virtual void HandleTranslationUnit(clang::ASTContext &Context) { + // Traversing the translation unit decl via a RecursiveASTVisitor + // will visit all nodes in the AST. + Visitor.TraverseDecl(Context.getTranslationUnitDecl()); + } + private: + // A RecursiveASTVisitor implementation. + FindNamedClassVisitor Visitor; + }; + +Using the RecursiveASTVisitor +============================= + +Now that everything is hooked up, the next step is to implement a +RecursiveASTVisitor to extract the relevant information from the AST. + +The RecursiveASTVisitor provides hooks of the form bool +VisitNodeType(NodeType \*) for most AST nodes; the exception are TypeLoc +nodes, which are passed by-value. We only need to implement the methods +for the relevant node types. + +Let's start by writing a RecursiveASTVisitor that visits all +CXXRecordDecl's. + +:: + + class FindNamedClassVisitor + : public RecursiveASTVisitor<FindNamedClassVisitor> { + public: + bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) { + // For debugging, dumping the AST nodes will show which nodes are already + // being visited. + Declaration->dump(); + + // The return value indicates whether we want the visitation to proceed. + // Return false to stop the traversal of the AST. + return true; + } + }; + +In the methods of our RecursiveASTVisitor we can now use the full power +of the Clang AST to drill through to the parts that are interesting for +us. For example, to find all class declaration with a certain name, we +can check for a specific qualified name: + +:: + + bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) { + if (Declaration->getQualifiedNameAsString() == "n::m::C") + Declaration->dump(); + return true; + } + +Accessing the SourceManager and ASTContext +========================================== + +Some of the information about the AST, like source locations and global +identifier information, are not stored in the AST nodes themselves, but +in the ASTContext and its associated source manager. To retrieve them we +need to hand the ASTContext into our RecursiveASTVisitor implementation. + +The ASTContext is available from the CompilerInstance during the call to +CreateASTConsumer. We can thus extract it there and hand it into our +freshly created FindNamedClassConsumer: + +:: + + virtual clang::ASTConsumer *CreateASTConsumer( + clang::CompilerInstance &Compiler, llvm::StringRef InFile) { + return new FindNamedClassConsumer(&Compiler.getASTContext()); + } + +Now that the ASTContext is available in the RecursiveASTVisitor, we can +do more interesting things with AST nodes, like looking up their source +locations: + +:: + + bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) { + if (Declaration->getQualifiedNameAsString() == "n::m::C") { + // getFullLoc uses the ASTContext's SourceManager to resolve the source + // location and break it up into its line and column parts. + FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart()); + if (FullLocation.isValid()) + llvm::outs() << "Found declaration at " + << FullLocation.getSpellingLineNumber() << ":" + << FullLocation.getSpellingColumnNumber() << "\n"; + } + return true; + } + +Putting it all together +======================= + +Now we can combine all of the above into a small example program: + +:: + + #include "clang/AST/ASTConsumer.h" + #include "clang/AST/RecursiveASTVisitor.h" + #include "clang/Frontend/CompilerInstance.h" + #include "clang/Frontend/FrontendAction.h" + #include "clang/Tooling/Tooling.h" + + using namespace clang; + + class FindNamedClassVisitor + : public RecursiveASTVisitor<FindNamedClassVisitor> { + public: + explicit FindNamedClassVisitor(ASTContext *Context) + : Context(Context) {} + + bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) { + if (Declaration->getQualifiedNameAsString() == "n::m::C") { + FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart()); + if (FullLocation.isValid()) + llvm::outs() << "Found declaration at " + << FullLocation.getSpellingLineNumber() << ":" + << FullLocation.getSpellingColumnNumber() << "\n"; + } + return true; + } + + private: + ASTContext *Context; + }; + + class FindNamedClassConsumer : public clang::ASTConsumer { + public: + explicit FindNamedClassConsumer(ASTContext *Context) + : Visitor(Context) {} + + virtual void HandleTranslationUnit(clang::ASTContext &Context) { + Visitor.TraverseDecl(Context.getTranslationUnitDecl()); + } + private: + FindNamedClassVisitor Visitor; + }; + + class FindNamedClassAction : public clang::ASTFrontendAction { + public: + virtual clang::ASTConsumer *CreateASTConsumer( + clang::CompilerInstance &Compiler, llvm::StringRef InFile) { + return new FindNamedClassConsumer(&Compiler.getASTContext()); + } + }; + + int main(int argc, char **argv) { + if (argc > 1) { + clang::tooling::runToolOnCode(new FindNamedClassAction, argv[1]); + } + } + +We store this into a file called FindClassDecls.cpp and create the +following CMakeLists.txt to link it: + +:: + + set(LLVM_USED_LIBS clangTooling) + + add_clang_executable(find-class-decls FindClassDecls.cpp) + +When running this tool over a small code snippet it will output all +declarations of a class n::m::C it found: + +:: + + $ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }" + Found declaration at 1:29 + diff --git a/clang/docs/UsersManual.html b/clang/docs/UsersManual.html deleted file mode 100644 index 4adf0b4dad1..00000000000 --- a/clang/docs/UsersManual.html +++ /dev/null @@ -1,1338 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>Clang Compiler User's Manual</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>Clang Compiler User's Manual</h1> - -<ul> -<li><a href="#intro">Introduction</a> - <ul> - <li><a href="#terminology">Terminology</a></li> - <li><a href="#basicusage">Basic Usage</a></li> - </ul> -</li> -<li><a href="#commandline">Command Line Options</a> - <ul> - <li><a href="#cl_diagnostics">Options to Control Error and Warning - Messages</a></li> - <li><a href="#cl_crash_diagnostics">Options to Control Clang Crash - Diagnostics</a></li> - </ul> -</li> -<li><a href="#general_features">Language and Target-Independent Features</a> - <ul> - <li><a href="#diagnostics">Controlling Errors and Warnings</a> - <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_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> - <ul> - <li><a href="#c_ext">Extensions supported by clang</a></li> - <li><a href="#c_modes">Differences between various standard modes</a></li> - <li><a href="#c_unimpl_gcc">GCC extensions not implemented yet</a></li> - <li><a href="#c_unsupp_gcc">Intentionally unsupported GCC extensions</a></li> - <li><a href="#c_ms">Microsoft extensions</a></li> - </ul> -</li> -<li><a href="#cxx">C++ Language Features</a> - <ul> - <li><a href="#cxx_implimits">Controlling implementation limits</a></li> - </ul> -</li> -<li><a href="#target_features">Target-Specific Features and Limitations</a> - <ul> - <li><a href="#target_arch">CPU Architectures Features and Limitations</a> - <ul> - <li><a href="#target_arch_x86">X86</a></li> - <li><a href="#target_arch_arm">ARM</a></li> - <li><a href="#target_arch_other">Other platforms</a></li> - </ul> - </li> - <li><a href="#target_os">Operating System Features and Limitations</a> - <ul> - <li><a href="#target_os_darwin">Darwin (Mac OS/X)</a></li> - <li>Linux, etc.</li> - <li><a href="#target_os_win32">Windows</a></li> - </ul> - </li> - </ul> -</li> -</ul> - - -<!-- ======================================================================= --> -<h2 id="intro">Introduction</h2> -<!-- ======================================================================= --> - -<p>The Clang Compiler is an open-source compiler for the C family of programming -languages, aiming to be the best in class implementation of these languages. -Clang builds on the LLVM optimizer and code generator, allowing it to provide -high-quality optimization and code generation support for many targets. For -more general information, please see the <a href="http://clang.llvm.org">Clang -Web Site</a> or the <a href="http://llvm.org">LLVM Web Site</a>.</p> - -<p>This document describes important notes about using Clang as a compiler for -an end-user, documenting the supported features, command line options, etc. If -you are interested in using Clang to build a tool that processes code, please -see <a href="InternalsManual.html">the Clang Internals Manual</a>. If you are -interested in the <a href="http://clang-analyzer.llvm.org">Clang -Static Analyzer</a>, please see its web page.</p> - -<p>Clang is designed to support the C family of programming languages, which -includes <a href="#c">C</a>, <a href="#objc">Objective-C</a>, <a -href="#cxx">C++</a>, and <a href="#objcxx">Objective-C++</a> as well as many -dialects of those. For language-specific information, please see the -corresponding language specific section:</p> - -<ul> -<li><a href="#c">C Language</a>: K&R C, ANSI C89, ISO C90, ISO C94 - (C89+AMD1), ISO C99 (+TC1, TC2, TC3). </li> -<li><a href="#objc">Objective-C Language</a>: ObjC 1, ObjC 2, ObjC 2.1, plus - variants depending on base language.</li> -<li><a href="#cxx">C++ Language</a></li> -<li><a href="#objcxx">Objective C++ Language</a></li> -</ul> - -<p>In addition to these base languages and their dialects, Clang supports a -broad variety of language extensions, which are documented in the corresponding -language section. These extensions are provided to be compatible with the GCC, -Microsoft, and other popular compilers as well as to improve functionality -through Clang-specific features. The Clang driver and language features are -intentionally designed to be as compatible with the GNU GCC compiler as -reasonably possible, easing migration from GCC to Clang. In most cases, code -"just works".</p> - -<p>In addition to language specific features, Clang has a variety of features -that depend on what CPU architecture or operating system is being compiled for. -Please see the <a href="#target_features">Target-Specific Features and -Limitations</a> section for more details.</p> - -<p>The rest of the introduction introduces some basic <a -href="#terminology">compiler terminology</a> that is used throughout this manual -and contains a basic <a href="#basicusage">introduction to using Clang</a> -as a command line compiler.</p> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="terminology">Terminology</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p>Front end, parser, backend, preprocessor, undefined behavior, diagnostic, - optimizer</p> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="basicusage">Basic Usage</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p>Intro to how to use a C compiler for newbies.</p> -<p> -compile + link - -compile then link - -debug info - -enabling optimizations - -picking a language to use, defaults to C99 by default. Autosenses based on -extension. - -using a makefile -</p> - - -<!-- ======================================================================= --> -<h2 id="commandline">Command Line Options</h2> -<!-- ======================================================================= --> - -<p> -This section is generally an index into other sections. It does not go into -depth on the ones that are covered by other sections. However, the first part -introduces the language selection and other high level options like -c, -g, etc. -</p> - - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="cl_diagnostics">Options to Control Error and Warning Messages</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p><b>-Werror</b>: Turn warnings into errors.</p> -<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>-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> - -<p><b>-ferror-limit=123</b>: Stop emitting diagnostics after 123 errors have - been produced. The default is 20, and the error limit can be disabled with - -ferror-limit=0.</p> - -<p><b>-ftemplate-backtrace-limit=123</b>: Only emit up to 123 template instantiation notes within the template instantiation backtrace for a single warning or error. The default is 10, and the limit can be disabled with -ftemplate-backtrace-limit=0.</p> - -<!-- ================================================= --> -<h4 id="cl_diag_formatting">Formatting of Diagnostics</h4> -<!-- ================================================= --> - -<p>Clang aims to produce beautiful diagnostics by default, particularly for new -users that first come to Clang. However, different people have different -preferences, and sometimes Clang is driven by another program that wants to -parse simple and consistent output, not a person. For these cases, Clang -provides a wide range of options to control the exact output format of the -diagnostics that it generates.</p> - -<dl> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fshow-column"><b>-f[no-]show-column</b>: Print column number in -diagnostic.</dt> -<dd>This option, which defaults to on, controls whether or not Clang prints the -column number of a diagnostic. For example, when this is enabled, Clang will -print something like: - -<pre> - test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] - #endif bad - ^ - // -</pre> - -<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> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fshow-source-location"><b>-f[no-]show-source-location</b>: Print -source file/line/column information in diagnostic.</dt> -<dd>This option, which defaults to on, controls whether or not Clang prints the -filename, line number and column number of a diagnostic. For example, -when this is enabled, Clang will print something like: - -<pre> - test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] - #endif bad - ^ - // -</pre> - -<p>When this is disabled, Clang will not print the "test.c:28:8: " part.</p> -</dd> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fcaret-diagnostics"><b>-f[no-]caret-diagnostics</b>: Print source -line and ranges from source code in diagnostic.</dt> -<dd>This option, which defaults to on, controls whether or not Clang prints the -source line, source ranges, and caret when emitting a diagnostic. For example, -when this is enabled, Clang will print something like: - -<pre> - test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] - #endif bad - ^ - // -</pre> -</dd> -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fcolor_diagnostics"><b>-f[no-]color-diagnostics</b>: </dt> -<dd>This option, which defaults to on when a color-capable terminal is - detected, controls whether or not Clang prints diagnostics in color. - When this option is enabled, Clang will use colors to highlight - specific parts of the diagnostic, e.g., - <pre> - <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b> - #endif bad - <span style="color:green">^</span> - <span style="color:green">//</span> -</pre> - -<p>When this is disabled, Clang will just print:</p> - -<pre> - test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] - #endif bad - ^ - // -</pre> -</dd> -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fdiagnostics-format"><b>-fdiagnostics-format=clang/msvc/vi</b>: -Changes diagnostic output format to better match IDEs and command line tools.</dt> -<dd>This option controls the output format of the filename, line number, and column printed in diagnostic messages. The options, and their affect on formatting a simple conversion diagnostic, follow: - - <dl> - <dt><b>clang</b> (default)</dt> - <dd> - <pre>t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'</pre> - </dd> - - <dt><b>msvc</b></dt> - <dd> - <pre>t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'</pre> - </dd> - - <dt><b>vi</b></dt> - <dd> - <pre>t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'</pre> - </dd> - </dl> -</dd> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fdiagnostics-show-name"><b>-f[no-]diagnostics-show-name</b>: -Enable the display of the diagnostic name.</dt> -<dd>This option, which defaults to off, controls whether or not -Clang prints the associated name.<p></p></dd> -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fdiagnostics-show-option"><b>-f[no-]diagnostics-show-option</b>: -Enable <tt>[-Woption]</tt> information in diagnostic line.</dt> -<dd>This option, which defaults to on, -controls whether or not Clang prints the associated <A -href="#cl_diag_warning_groups">warning group</a> option name when outputting -a warning diagnostic. For example, in this output: - -<pre> - test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] - #endif bad - ^ - // -</pre> - -<p>Passing <b>-fno-diagnostics-show-option</b> will prevent Clang from printing -the [<a href="#opt_Wextra-tokens">-Wextra-tokens</a>] information in the -diagnostic. This information tells you the flag needed to enable or disable the -diagnostic, either from the command line or through <a -href="#pragma_GCC_diagnostic">#pragma GCC diagnostic</a>.</dd> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fdiagnostics-show-category"><b>-fdiagnostics-show-category=none/id/name</b>: -Enable printing category information in diagnostic line.</dt> -<dd>This option, which defaults to "none", -controls whether or not Clang prints the category associated with a diagnostic -when emitting it. Each diagnostic may or many not have an associated category, -if it has one, it is listed in the diagnostic categorization field of the -diagnostic line (in the []'s). - -<p>For example, a format string warning will produce these three renditions -based on the setting of this option:</p> - -<pre> - t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat] - t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat<b>,1</b>] - t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat<b>,Format String</b>] -</pre> - -<p>This category can be used by clients that want to group diagnostics by -category, so it should be a high level category. We want dozens of these, not -hundreds or thousands of them.</p> -</dd> - - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fdiagnostics-fixit-info"><b>-f[no-]diagnostics-fixit-info</b>: -Enable "FixIt" information in the diagnostics output.</dt> -<dd>This option, which defaults to on, controls whether or not Clang prints the -information on how to fix a specific diagnostic underneath it when it knows. -For example, in this output: - -<pre> - test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] - #endif bad - ^ - // -</pre> - -<p>Passing <b>-fno-diagnostics-fixit-info</b> will prevent Clang from printing -the "//" line at the end of the message. This information is useful for users -who may not understand what is wrong, but can be confusing for machine -parsing.</p> -</dd> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fdiagnostics-print-source-range-info"> -<b>-f[no-]diagnostics-print-source-range-info</b>: -Print machine parsable information about source ranges.</dt> -<dd>This option, which defaults to off, controls whether or not Clang prints -information about source ranges in a machine parsable format after the -file/line/column number information. The information is a simple sequence of -brace enclosed ranges, where each range lists the start and end line/column -locations. For example, in this output: - -<pre> -exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float') - P = (P-42) + Gamma*4; - ~~~~~~ ^ ~~~~~~~ -</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> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_fdiagnostics-parseable-fixits"> -<b>-fdiagnostics-parseable-fixits</b>: -Print Fix-Its in a machine parseable form.</dt> -<dd><p>This option makes Clang print available Fix-Its in a machine parseable format at the end of diagnostics. The following example illustrates the format:</p> - -<pre> - fix-it:"t.cpp":{7:25-7:29}:"Gamma" -</pre> - -<p>The range printed is a half-open range, so in this example the characters at -column 25 up to but not including column 29 on line 7 in t.cpp should be -replaced with the string "Gamma". Either the range or the replacement -string may be empty (representing strict insertions and strict erasures, -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> - - - -<!-- ===================================================== --> -<h4 id="cl_diag_warning_groups">Individual Warning Groups</h4> -<!-- ===================================================== --> - -<p>TODO: Generate this from tblgen. Define one anchor per warning group.</p> - - -<dl> - - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_Wextra-tokens"><b>-Wextra-tokens</b>: Warn about excess tokens at - the end of a preprocessor directive.</dt> -<dd>This option, which defaults to on, enables warnings about extra tokens at -the end of preprocessor directives. For example: - -<pre> - test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] - #endif bad - ^ -</pre> - -<p>These extra tokens are not strictly conforming, and are usually best handled -by commenting them out.</p> -</dd> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_Wambiguous-member-template"><b>-Wambiguous-member-template</b>: -Warn about unqualified uses of a member template whose name resolves -to another template at the location of the use.</dt> -<dd>This option, which defaults to on, enables a warning in the -following code: - -<pre> -template<typename T> struct set{}; -template<typename T> struct trait { typedef const T& type; }; -struct Value { - template<typename T> void set(typename trait<T>::type value) {} -}; -void foo() { - Value v; - v.set<double>(3.2); -} -</pre> - -<p>C++ [basic.lookup.classref] requires this to be an error, but, -because it's hard to work around, Clang downgrades it to a warning as -an extension.</p> -</dd> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dt id="opt_Wbind-to-temporary-copy"><b>-Wbind-to-temporary-copy</b>: Warn about -an unusable copy constructor when binding a reference to a temporary.</dt> -<dd>This option, which defaults to on, enables warnings about binding a -reference to a temporary when the temporary doesn't have a usable copy -constructor. For example: - -<pre> - struct NonCopyable { - NonCopyable(); - private: - NonCopyable(const NonCopyable&); - }; - void foo(const NonCopyable&); - void bar() { - foo(NonCopyable()); // Disallowed in C++98; allowed in C++11. - } -</pre> -<pre> - struct NonCopyable2 { - NonCopyable2(); - NonCopyable2(NonCopyable2&); - }; - void foo(const NonCopyable2&); - void bar() { - foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11. - } -</pre> - -<p>Note that if <tt>NonCopyable2::NonCopyable2()</tt> has a default -argument whose instantiation produces a compile error, that error will -still be a hard error in C++98 mode even if this warning is turned -off.</p> - -</dd> - -</dl> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="cl_crash_diagnostics">Options to Control Clang Crash Diagnostics</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p>As unbelievable as it may sound, Clang does crash from time to time. -Generally, this only occurs to those living on the -<a href="http://llvm.org/releases/download.html#svn">bleeding edge</a>. Clang -goes to great lengths to assist you in filing a bug report. Specifically, Clang -generates preprocessed source file(s) and associated run script(s) upon a -crash. These files should be attached to a bug report to ease reproducibility -of the failure. Below are the command line options to control the crash -diagnostics. -</p> - -<p><b>-fno-crash-diagnostics</b>: Disable auto-generation of preprocessed -source files during a clang crash.</p> - -<p>The -fno-crash-diagnostics flag can be helpful for speeding the process of -generating a delta reduced test case.</p> - - -<!-- ======================================================================= --> -<h2 id="general_features">Language and Target-Independent Features</h2> -<!-- ======================================================================= --> - - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="diagnostics">Controlling Errors and Warnings</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<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 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 -the ability to print this information, and these are the options that control -it:</p> - -<ol> -<li>A file/line/column indicator that shows exactly where the diagnostic occurs - in your code [<a href="#opt_fshow-column">-fshow-column</a>, <a - href="#opt_fshow-source-location">-fshow-source-location</a>].</li> -<li>A categorization of the diagnostic as a note, warning, error, or fatal - error.</li> -<li>A text string that describes what the problem is.</li> -<li>An option that indicates how to control the diagnostic (for diagnostics that - support it) [<a - href="#opt_fdiagnostics-show-option">-fdiagnostics-show-option</a>].</li> -<li>A <a href="#diagnostics_categories">high-level category</a> for the - diagnostic for clients that want to group diagnostics by class (for - diagnostics that support it) [<a - href="#opt_fdiagnostics-show-category">-fdiagnostics-show-category</a>].</li> -<li>The line of source code that the issue occurs on, along with a caret and - ranges that indicate the important locations [<a - href="opt_fcaret-diagnostics">-fcaret-diagnostics</a>].</li> -<li>"FixIt" information, which is a concise explanation of how to fix the - problem (when Clang is certain it knows) [<a - href="opt_fdiagnostics-fixit-info">-fdiagnostics-fixit-info</a>].</li> -<li>A machine-parsable representation of the ranges involved (off by - default) [<a - href="opt_fdiagnostics-print-source-range-info">-fdiagnostics-print-source-range-info</a>].</li> -</ol> - -<p>For more information please see <a href="#cl_diag_formatting">Formatting of -Diagnostics</a>.</p> - - -<h4 id="diagnostics_mappings">Diagnostic Mappings</h4> - -<p>All diagnostics are mapped into one of these 5 classes:</p> - -<ul> -<li>Ignored</li> -<li>Note</li> -<li>Warning</li> -<li>Error</li> -<li>Fatal</li> -</ul> - -<h4 id="diagnostics_categories">Diagnostic Categories</h4> - -<p>Though not shown by default, diagnostics may each be associated with a - high-level category. This category is intended to make it possible to triage - builds that produce a large number of errors or warnings in a grouped way. -</p> - -<p>Categories are not shown by default, but they can be turned on with the -<a href="#opt_fdiagnostics-show-category">-fdiagnostics-show-category</a> option. -When set to "<tt>name</tt>", the category is printed textually in the diagnostic -output. When it is set to "<tt>id</tt>", a category number is printed. The -mapping of category names to category id's can be obtained by running '<tt>clang - --print-diagnostic-categories</tt>'. -</p> - -<h4 id="diagnostics_commandline">Controlling Diagnostics via Command Line - Flags</h4> - -<p>TODO: -W flags, -pedantic, etc</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 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> - -<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> - warnings by passing <tt>-Weverything</tt>. - This works as expected with <tt>-Werror</tt>, - and also includes the warnings from <tt>-pedantic</tt>.</p> - -<p>Note that when combined with <tt>-w</tt> (which disables all warnings), that - flag wins.</p> - -<h4 id="analyzer_diagnositics">Controlling Static Analyzer Diagnostics</h4> - -<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. 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> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p><a href="http://en.wikipedia.org/wiki/Precompiled_header">Precompiled -headers</a> are a general approach employed by many compilers to reduce -compilation time. The underlying motivation of the approach is that it is -common for the same (and often large) header files to be included by -multiple source files. Consequently, compile times can often be greatly improved -by caching some of the (redundant) work done by a compiler to process headers. -Precompiled header files, which represent one of many ways to implement -this optimization, are literally files that represent an on-disk cache that -contains the vital information necessary to reduce some of the work -needed to process a corresponding header file. While details of precompiled -headers vary between compilers, precompiled headers have been shown to be -highly effective at speeding up program compilation on systems with very large -system headers (e.g., Mac OS/X).</p> - -<h4>Generating a PCH File</h4> - -<p>To generate a PCH file using Clang, one invokes Clang with -the <b><tt>-x <i><language></i>-header</tt></b> option. This mirrors the -interface in GCC for generating PCH files:</p> - -<pre> - $ gcc -x c-header test.h -o test.h.gch - $ clang -x c-header test.h -o test.h.pch -</pre> - -<h4>Using a PCH File</h4> - -<p>A PCH file can then be used as a prefix header when a -<b><tt>-include</tt></b> option is passed to <tt>clang</tt>:</p> - -<pre> - $ clang -include test.h test.c -o test -</pre> - -<p>The <tt>clang</tt> driver will first check if a PCH file for <tt>test.h</tt> -is available; if so, the contents of <tt>test.h</tt> (and the files it includes) -will be processed from the PCH file. Otherwise, Clang falls back to -directly processing the content of <tt>test.h</tt>. This mirrors the behavior of -GCC.</p> - -<p><b>NOTE:</b> Clang does <em>not</em> automatically use PCH files -for headers that are directly included within a source file. For example:</p> - -<pre> - $ clang -x c-header test.h -o test.h.pch - $ cat test.c - #include "test.h" - $ clang test.c -o test -</pre> - -<p>In this example, <tt>clang</tt> will not automatically use the PCH file for -<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> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="codegen">Controlling Code Generation</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p>Clang provides a number of ways to control code generation. The options are listed below.</p> - -<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> -<dl> -<dt id="opt_fsanitize"><b>-fsanitize=check1,check2</b>: Turn on runtime checks -for various forms of undefined or suspicious behavior.</dt> - -<dd>This option controls whether Clang adds runtime checks for various forms of -undefined or suspicious behavior, and is disabled by default. If a check -fails, a diagnostic message is produced at runtime explaining the problem. The -main checks are: - -<ul> -<li id="opt_fsanitize_address"><tt>-fsanitize=address</tt>: - <a href="AddressSanitizer.html">AddressSanitizer</a>, a memory error - detector.</li> -<li id="opt_fsanitize_address_full"><tt>-fsanitize=address-full</tt>: - AddressSanitizer with all the experimental features listed below. -<li id="opt_fsanitize_integer"><tt>-fsanitize=integer</tt>: - Enables checks for undefined or suspicious integer behavior.</li> -<li id="opt_fsanitize_thread"><tt>-fsanitize=thread</tt>: - <a href="ThreadSanitizer.html">ThreadSanitizer</a>, an <em>experimental</em> - data race detector. Not ready for widespread use.</li> -<li id="opt_fsanitize_undefined"><tt>-fsanitize=undefined</tt>: - Fast and compatible undefined behavior checker. Enables the undefined behavior - checks that have small runtime cost and no impact on address space layout - or ABI. This includes all of the checks listed below other than - <tt>unsigned-integer-overflow</tt>.</li> -</ul> - -The following more fine-grained checks are also available: - -<ul> -<li id="opt_fsanitize_alignment"><tt>-fsanitize=alignment</tt>: - Use of a misaligned pointer or creation of a misaligned reference.</li> -<li id="opt_fsanitize_bounds"><tt>-fsanitize=bounds</tt>: - Out of bounds array indexing, in cases where the array bound can be - statically determined.</li> -<li id="opt_fsanitize_float-cast-overflow"><tt>-fsanitize=float-cast-overflow</tt>: - Conversion to, from, or between floating-point types which would overflow - the destination.</li> -<li id="opt_fsanitize_float-divide-by-zero"><tt>-fsanitize=float-divide-by-zero</tt>: - Floating point division by zero.</li> -<li id="opt_fsanitize_integer-divide-by-zero"><tt>-fsanitize=integer-divide-by-zero</tt>: - Integer division by zero.</li> -<li id="opt_fsanitize_null"><tt>-fsanitize=null</tt>: - Use of a null pointer or creation of a null reference.</li> -<li id="opt_fsanitize_object-size"><tt>-fsanitize=object-size</tt>: - An attempt to use bytes which the optimizer can determine are not part of - the object being accessed. - The sizes of objects are determined using <tt>__builtin_object_size</tt>, and - consequently may be able to detect more problems at higher optimization - levels.</li> -<li id="opt_fsanitize_return"><tt>-fsanitize=return</tt>: - In C++, reaching the end of a value-returning function without returning a - value.</li> -<li id="opt_fsanitize_shift"><tt>-fsanitize=shift</tt>: - Shift operators where the amount shifted is greater or equal to the - promoted bit-width of the left hand side or less than zero, or where - the left hand side is negative. For a signed left shift, also checks - for signed overflow in C, and for unsigned overflow in C++.</li> -<li id="opt_fsanitize_signed-integer-overflow"><tt>-fsanitize=signed-integer-overflow</tt>: - Signed integer overflow, including all the checks added by <tt>-ftrapv</tt>, - and checking for overflow in signed division (<tt>INT_MIN / -1</tt>).</li> -<li id="opt_fsanitize_unreachable"><tt>-fsanitize=unreachable</tt>: - If control flow reaches __builtin_unreachable.</li> -<li id="opt_fsanitize_unsigned-integer-overflow"><tt>-fsanitize=unsigned-integer-overflow</tt>: - Unsigned integer overflows.</li> -<li id="opt_fsanitize_vla-bound"><tt>-fsanitize=vla-bound</tt>: - A variable-length array whose bound does not evaluate to a positive value.</li> -<li id="opt_fsanitize_vptr"><tt>-fsanitize=vptr</tt>: - Use of an object whose vptr indicates that it is of the wrong dynamic type, - or that its lifetime has not begun or has ended. Incompatible with - <tt>-fno-rtti</tt>.</li> -</ul> - -Experimental features of AddressSanitizer (not ready for widespread use, -require explicit <tt>-fsanitize=address</tt>): - -<ul> -<li id="opt_fsanitize_init_order"><tt>-fsanitize=init-order</tt>: -Check for dynamic initialization order problems.</li> -<li id="opt_fsanitize_use_after_return"><tt>-fsanitize=use-after-return</tt>: -Check for use-after-return errors (accessing local variable after the function -exit). -<li id="opt_fsanitize_use_after_scope"><tt>-fsanitize=use-after-scope</tt>: -Check for use-after-scope errors (accesing local variable after it went out of -scope). -</ul> - -The <tt>-fsanitize=</tt> argument must also be provided when linking, in order -to link to the appropriate runtime library. It is not possible to combine the -<tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> checkers in the same -program. -</dd> - -<dt id="opt_faddress-sanitizer"><b>-f[no-]address-sanitizer</b>: -Deprecated synonym for <a href="#opt_fsanitize_address"><tt>-f[no-]sanitize=address</tt></a>. - -<dt id="opt_fthread-sanitizer"><b>-f[no-]thread-sanitizer</b>: -Deprecated synonym for <a href="#opt_fsanitize_address"><tt>-f[no-]sanitize=thread</tt></a>. - -<dt id="opt_fcatch-undefined-behavior"><b>-fcatch-undefined-behavior</b>: -Deprecated synonym for <a href="#opt_fsanitize_undefined"><tt>-fsanitize=undefined</tt></a>. - -<dt id="opt_fno-assume-sane-operator-new"><b>-fno-assume-sane-operator-new</b>: -Don't assume that the C++'s new operator is sane.</dt> -<dd>This option tells the compiler to do not assume that C++'s global new -operator will always return a pointer that does not -alias any other pointer when the function returns.</dd> - -<dt id="opt_ftrap-function"><b>-ftrap-function=[name]</b>: Instruct code -generator to emit a function call to the specified function name for -<tt>__builtin_trap()</tt>.</dt> - -<dd>LLVM code generator translates <tt>__builtin_trap()</tt> to a trap -instruction if it is supported by the target ISA. Otherwise, the builtin is -translated into a call to <tt>abort</tt>. If this option is set, then the code -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> - -<!-- ======================================================================= --> -<h2 id="c">C Language Features</h2> -<!-- ======================================================================= --> - -<p>The support for standard C in clang is feature-complete except for the C99 -floating-point pragmas.</p> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="c_ext">Extensions supported by clang</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p>See <a href="LanguageExtensions.html">clang language extensions</a>.</p> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="c_modes">Differences between various standard modes</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p>clang supports the -std option, which changes what language mode clang uses. -The supported modes for C are c89, gnu89, c94, c99, gnu99 and various aliases -for those modes. If no -std option is specified, clang defaults to gnu99 mode. -</p> - -<p>Differences between all c* and gnu* modes:</p> -<ul> -<li>c* modes define "__STRICT_ANSI__".</li> -<li>Target-specific defines not prefixed by underscores, like "linux", are -defined in gnu* modes.</li> -<li>Trigraphs default to being off in gnu* modes; they can be enabled by the --trigraphs option.</li> -<li>The parser recognizes "asm" and "typeof" as keywords in gnu* modes; the -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>Arrays that are VLA's according to the standard, but which can be constant - folded by the frontend are treated as fixed size arrays. This occurs for - things like "int X[(1, 2)];", which is technically a VLA. c* modes are - strictly compliant and treat these as VLAs.</li> -</ul> - -<p>Differences between *89 and *99 modes:</p> -<ul> -<li>The *99 modes default to implementing "inline" as specified in C99, while -the *89 modes implement the GNU version. This can be overridden for individual -functions with the __gnu_inline__ attribute.</li> -<li>Digraphs are not recognized in c89 mode.</li> -<li>The scope of names defined inside a "for", "if", "switch", "while", or "do" -statement is different. (example: "if ((struct x {int x;}*)0) {}".)</li> -<li>__STDC_VERSION__ is not defined in *89 modes.</li> -<li>"inline" is not recognized as a keyword in c89 mode.</li> -<li>"restrict" is not recognized as a keyword in *89 modes.</li> -<li>Commas are allowed in integer constant expressions in *99 modes.</li> -<li>Arrays which are not lvalues are not implicitly promoted to pointers in -*89 modes.</li> -<li>Some warnings are different.</li> -</ul> - -<p>c94 mode is identical to c89 mode except that digraphs are enabled in -c94 mode (FIXME: And __STDC_VERSION__ should be defined!).</p> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="c_unimpl_gcc">GCC extensions not implemented yet</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p>clang tries to be compatible with gcc as much as possible, but some gcc -extensions are not implemented yet:</p> - -<ul> - -<li>clang does not support #pragma weak -(<a href="http://llvm.org/bugs/show_bug.cgi?id=3679">bug 3679</a>). Due to -the uses described in the bug, this is likely to be implemented at some -point, at least partially.</li> - -<li>clang does not support decimal floating point types (_Decimal32 and -friends) or fixed-point types (_Fract and friends); nobody has expressed -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. 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 -to be implemented soon because it requires additional LLVM backend support. -</li> - -<li>clang does not support static initialization of flexible array -members. This appears to be a rarely used extension, but could be -implemented pending user demand.</li> - -<li>clang does not support __builtin_va_arg_pack/__builtin_va_arg_pack_len. -This is used rarely, but in some potentially interesting places, like the -glibc headers, so it may be implemented pending user demand. Note that -because clang pretends to be like GCC 4.2, and this extension was introduced -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 shown up in any real-world code yet, though, so it -might never be implemented.</li> - -</ul> - -<p>This is not a complete list; if you find an unsupported extension -missing from this list, please send an e-mail to cfe-dev. This list -currently excludes C++; see <a href="#cxx">C++ Language Features</a>. -Also, this list does not include bugs in mostly-implemented features; please -see the <a href="http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer"> -bug tracker</a> for known existing bugs (FIXME: Is there a section for -bug-reporting guidelines somewhere?).</p> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="c_unsupp_gcc">Intentionally unsupported GCC extensions</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<ul> - -<li>clang does not support the gcc extension that allows variable-length arrays -in structures. This is for a few reasons: one, it is tricky -to implement, two, the extension is completely undocumented, and three, the -extension appears to be rarely used. Note that clang <em>does</em> support -flexible array members (arrays with a zero or unspecified size at the end of -a structure).</li> - -<li>clang does not have an equivalent to gcc's "fold"; this means that -clang doesn't accept some constructs gcc might accept in contexts where a -constant expression is required, like "x-x" where x is a variable.</li> - -<li>clang does not support __builtin_apply and friends; this extension is -extremely obscure and difficult to implement reliably.</li> - -</ul> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="c_ms">Microsoft extensions</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p>clang has some experimental support for extensions from -Microsoft Visual C++; to enable it, use the -fms-extensions command-line -option. This is the default for Windows targets. Note that the -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 -what Windows SDK and c++stdlib headers clang can compile. This option will be -removed when clang supports the full set of MS extensions required for these -headers.</li> - -<li>clang does not support the Microsoft extension where anonymous -record members can be declared using user defined typedefs.</li> - -<li>clang supports the Microsoft "#pragma pack" feature for -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> - -<!-- ======================================================================= --> -<h2 id="cxx">C++ Language Features</h2> -<!-- ======================================================================= --> - -<p>clang fully implements all of standard C++98 except for exported templates -(which were removed in C++11), and -<a href="http://clang.llvm.org/cxx_status.html">many C++11 features</a> are also -implemented.</p> - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="cxx_implimits">Controlling implementation limits</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<p><b>-fconstexpr-depth=N</b>: Sets the limit for recursive constexpr function -invocations to N. The default is 512.</p> - -<p><b>-ftemplate-depth=N</b>: Sets the limit for recursively nested template -instantiations to N. The default is 1024.</p> - -<!-- ======================================================================= --> -<h2 id="target_features">Target-Specific Features and Limitations</h2> -<!-- ======================================================================= --> - - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="target_arch">CPU Architectures Features and Limitations</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<!-- ======================== --> -<h4 id="target_arch_x86">X86</h4> -<!-- ======================== --> - -<p>The support for X86 (both 32-bit and 64-bit) is considered stable on Darwin -(Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested to correctly -compile many large C, C++, Objective-C, and Objective-C++ codebases.</p> - -<p>On x86_64-mingw32, passing i128(by value) is incompatible to Microsoft x64 -calling conversion. You might need to tweak WinX86_64ABIInfo::classify() -in lib/CodeGen/TargetInfo.cpp.</p> - -<!-- ======================== --> -<h4 id="target_arch_arm">ARM</h4> -<!-- ======================== --> - -<p>The support for ARM (specifically ARMv6 and ARMv7) is considered stable on -Darwin (iOS): it has been tested to correctly compile many large C, C++, -Objective-C, and Objective-C++ codebases. Clang only supports a limited number -of ARM architectures. It does not yet fully support ARMv5, for example.</p> - -<!-- ======================== --> -<h4 id="target_arch_other">Other platforms</h4> -<!-- ======================== --> -clang currently contains some support for PPC and Sparc; however, significant -pieces of code generation are still missing, and they haven't undergone -significant testing. - -<p>clang contains limited support for the MSP430 embedded processor, but both -the clang support and the LLVM backend support are highly experimental. - -<p>Other platforms are completely unsupported at the moment. Adding the -minimal support needed for parsing and semantic analysis on a new platform -is quite easy; see lib/Basic/Targets.cpp in the clang source tree. This level -of support is also sufficient for conversion to LLVM IR for simple programs. -Proper support for conversion to LLVM IR requires adding code to -lib/CodeGen/CGCall.cpp at the moment; this is likely to change soon, though. -Generating assembly requires a suitable LLVM backend. - -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> -<h3 id="target_os">Operating System Features and Limitations</h3> -<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> - -<!-- ======================================= --> -<h4 id="target_os_darwin">Darwin (Mac OS/X)</h4> -<!-- ======================================= --> - -<p>None</p> - -<!-- ======================================= --> -<h4 id="target_os_win32">Windows</h4> -<!-- ======================================= --> - -<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> - -<h5>MinGW32</h5> - -<p>Clang works on some mingw32 distributions. -Clang assumes directories as below;</p> - -<ul> -<li><tt>C:/mingw/include</tt></li> -<li><tt>C:/mingw/lib</tt></li> -<li><tt>C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++</tt></li> -</ul> - -<p>On MSYS, a few tests might fail.</p> - -<h5>MinGW-w64</h5> - -<p>For 32-bit (i686-w64-mingw32), and 64-bit (x86_64-w64-mingw32), Clang assumes as below;<p> - -<ul> -<li><tt>GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)</tt></li> -<li><tt>some_directory/bin/gcc.exe</tt></li> -<li><tt>some_directory/bin/clang.exe</tt></li> -<li><tt>some_directory/bin/clang++.exe</tt></li> -<li><tt>some_directory/bin/../include/c++/GCC_version</tt></li> -<li><tt>some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32</tt></li> -<li><tt>some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32</tt></li> -<li><tt>some_directory/bin/../include/c++/GCC_version/backward</tt></li> -<li><tt>some_directory/bin/../x86_64-w64-mingw32/include</tt></li> -<li><tt>some_directory/bin/../i686-w64-mingw32/include</tt></li> -<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="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> - -<p><a href="http://llvm.org/bugs/show_bug.cgi?id=9072">Some tests might fail</a> -on x86_64-w64-mingw32.</p> - -</div> -</body> -</html> diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst new file mode 100644 index 00000000000..6284255f87f --- /dev/null +++ b/clang/docs/UsersManual.rst @@ -0,0 +1,1238 @@ +============================ +Clang Compiler User's Manual +============================ + +.. contents:: + :local: + +Introduction +============ + +The Clang Compiler is an open-source compiler for the C family of +programming languages, aiming to be the best in class implementation of +these languages. Clang builds on the LLVM optimizer and code generator, +allowing it to provide high-quality optimization and code generation +support for many targets. For more general information, please see the +`Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web +Site <http://llvm.org>`_. + +This document describes important notes about using Clang as a compiler +for an end-user, documenting the supported features, command line +options, etc. If you are interested in using Clang to build a tool that +processes code, please see `the Clang Internals +Manual <InternalsManual.html>`_. If you are interested in the `Clang +Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web +page. + +Clang is designed to support the C family of programming languages, +which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and +:ref:`Objective-C++ <objcxx>` as well as many dialects of those. For +language-specific information, please see the corresponding language +specific section: + +- :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO + C99 (+TC1, TC2, TC3). +- :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus + variants depending on base language. +- :ref:`C++ Language <cxx>` +- :ref:`Objective C++ Language <objcxx>` + +In addition to these base languages and their dialects, Clang supports a +broad variety of language extensions, which are documented in the +corresponding language section. These extensions are provided to be +compatible with the GCC, Microsoft, and other popular compilers as well +as to improve functionality through Clang-specific features. The Clang +driver and language features are intentionally designed to be as +compatible with the GNU GCC compiler as reasonably possible, easing +migration from GCC to Clang. In most cases, code "just works". + +In addition to language specific features, Clang has a variety of +features that depend on what CPU architecture or operating system is +being compiled for. Please see the :ref:`Target-Specific Features and +Limitations <target_features>` section for more details. + +The rest of the introduction introduces some basic :ref:`compiler +terminology <terminology>` that is used throughout this manual and +contains a basic :ref:`introduction to using Clang <basicusage>` as a +command line compiler. + +.. _terminology: + +Terminology +----------- + +Front end, parser, backend, preprocessor, undefined behavior, +diagnostic, optimizer + +.. _basicusage: + +Basic Usage +----------- + +Intro to how to use a C compiler for newbies. + +compile + link compile then link debug info enabling optimizations +picking a language to use, defaults to C99 by default. Autosenses based +on extension. using a makefile + +Command Line Options +==================== + +This section is generally an index into other sections. It does not go +into depth on the ones that are covered by other sections. However, the +first part introduces the language selection and other high level +options like -c, -g, etc. + +Options to Control Error and Warning Messages +--------------------------------------------- + +**-Werror**: Turn warnings into errors. + +**-Werror=foo**: Turn warning "foo" into an error. + +**-Wno-error=foo**: Turn warning "foo" into an warning even if -Werror +is specified. + +**-Wfoo**: Enable warning "foo". + +**-Wno-foo**: Disable warning "foo". + +**-w**: Disable all warnings. + +**-Weverything**: :ref:`Enable **all** +warnings. <diagnostics_enable_everything>` + +**-pedantic**: Warn on language extensions. + +**-pedantic-errors**: Error on language extensions. + +**-Wsystem-headers**: Enable warnings from system headers. + +**-ferror-limit=123**: Stop emitting diagnostics after 123 errors have +been produced. The default is 20, and the error limit can be disabled +with -ferror-limit=0. + +**-ftemplate-backtrace-limit=123**: Only emit up to 123 template +instantiation notes within the template instantiation backtrace for a +single warning or error. The default is 10, and the limit can be +disabled with -ftemplate-backtrace-limit=0. + +.. _cl_diag_formatting: + +Formatting of Diagnostics +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Clang aims to produce beautiful diagnostics by default, particularly for +new users that first come to Clang. However, different people have +different preferences, and sometimes Clang is driven by another program +that wants to parse simple and consistent output, not a person. For +these cases, Clang provides a wide range of options to control the exact +output format of the diagnostics that it generates. + +.. _opt_fshow-column: + +**-f[no-]show-column** + Print column number in diagnostic. + + This option, which defaults to on, controls whether or not Clang + prints the column number of a diagnostic. For example, when this is + enabled, Clang will print something like: + + :: + + test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] + #endif bad + ^ + // + + When this is disabled, Clang will print "test.c:28: warning..." with + no column number. + + The printed column numbers count bytes from the beginning of the + line; take care if your source contains multibyte characters. + +.. _opt_fshow-source-location: + +**-f[no-]show-source-location** + Print source file/line/column information in diagnostic. + + This option, which defaults to on, controls whether or not Clang + prints the filename, line number and column number of a diagnostic. + For example, when this is enabled, Clang will print something like: + + :: + + test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] + #endif bad + ^ + // + + When this is disabled, Clang will not print the "test.c:28:8: " + part. + +.. _opt_fcaret-diagnostics: + +**-f[no-]caret-diagnostics** + Print source line and ranges from source code in diagnostic. + This option, which defaults to on, controls whether or not Clang + prints the source line, source ranges, and caret when emitting a + diagnostic. For example, when this is enabled, Clang will print + something like: + + :: + + test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] + #endif bad + ^ + // + +**-f[no-]color-diagnostics** + This option, which defaults to on when a color-capable terminal is + detected, controls whether or not Clang prints diagnostics in color. + + When this option is enabled, Clang will use colors to highlight + specific parts of the diagnostic, e.g., + + .. nasty hack to not lose our dignity + + .. raw:: html + + <pre> + <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b> + #endif bad + <span style="color:green">^</span> + <span style="color:green">//</span> + </pre> + + When this is disabled, Clang will just print: + + :: + + test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] + #endif bad + ^ + // + +**-fdiagnostics-format=clang/msvc/vi** + Changes diagnostic output format to better match IDEs and command line tools. + + This option controls the output format of the filename, line number, + and column printed in diagnostic messages. The options, and their + affect on formatting a simple conversion diagnostic, follow: + + **clang** (default) + :: + + t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' + + **msvc** + :: + + t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int' + + **vi** + :: + + t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int' + +**-f[no-]diagnostics-show-name** + Enable the display of the diagnostic name. + This option, which defaults to off, controls whether or not Clang + prints the associated name. + +.. _opt_fdiagnostics-show-option: + +**-f[no-]diagnostics-show-option** + Enable ``[-Woption]`` information in diagnostic line. + + This option, which defaults to on, controls whether or not Clang + prints the associated :ref:`warning group <cl_diag_warning_groups>` + option name when outputting a warning diagnostic. For example, in + this output: + + :: + + test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] + #endif bad + ^ + // + + Passing **-fno-diagnostics-show-option** will prevent Clang from + printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in + the diagnostic. This information tells you the flag needed to enable + or disable the diagnostic, either from the command line or through + :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`. + +.. _opt_fdiagnostics-show-category: + +**-fdiagnostics-show-category=none/id/name** + Enable printing category information in diagnostic line. + + This option, which defaults to "none", controls whether or not Clang + prints the category associated with a diagnostic when emitting it. + Each diagnostic may or many not have an associated category, if it + has one, it is listed in the diagnostic categorization field of the + diagnostic line (in the []'s). + + For example, a format string warning will produce these three + renditions based on the setting of this option: + + :: + + t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat] + t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1] + t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String] + + This category can be used by clients that want to group diagnostics + by category, so it should be a high level category. We want dozens + of these, not hundreds or thousands of them. + +.. _opt_fdiagnostics-fixit-info: + +**-f[no-]diagnostics-fixit-info** + Enable "FixIt" information in the diagnostics output. + + This option, which defaults to on, controls whether or not Clang + prints the information on how to fix a specific diagnostic + underneath it when it knows. For example, in this output: + + :: + + test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] + #endif bad + ^ + // + + Passing **-fno-diagnostics-fixit-info** will prevent Clang from + printing the "//" line at the end of the message. This information + is useful for users who may not understand what is wrong, but can be + confusing for machine parsing. + +.. _opt_fdiagnostics-print-source-range-info: + +**-f[no-]diagnostics-print-source-range-info** + Print machine parsable information about source ranges. + This option, which defaults to off, controls whether or not Clang + prints information about source ranges in a machine parsable format + after the file/line/column number information. The information is a + simple sequence of brace enclosed ranges, where each range lists the + start and end line/column locations. For example, in this output: + + :: + + exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float') + P = (P-42) + Gamma*4; + ~~~~~~ ^ ~~~~~~~ + + The {}'s are generated by -fdiagnostics-print-source-range-info. + + The printed column numbers count bytes from the beginning of the + line; take care if your source contains multibyte characters. + +**-fdiagnostics-parseable-fixits** + Print Fix-Its in a machine parseable form. + + This option makes Clang print available Fix-Its in a machine + parseable format at the end of diagnostics. The following example + illustrates the format: + + :: + + fix-it:"t.cpp":{7:25-7:29}:"Gamma" + + The range printed is a half-open range, so in this example the + characters at column 25 up to but not including column 29 on line 7 + in t.cpp should be replaced with the string "Gamma". Either the + range or the replacement string may be empty (representing strict + insertions and strict erasures, 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"). + + The printed column numbers count bytes from the beginning of the + line; take care if your source contains multibyte characters. + +**-fno-elide-type** + Turns off elision in template type printing. + + 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. + + Default: + + :: + + t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument; + + -fno-elide-type: + + :: + + t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument; + +**-fdiagnostics-show-template-tree** + Template type diffing prints a text tree. + + 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. + + Default: + + :: + + t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument; + + -fdiagnostics-show-template-tree + + :: + + t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument; + vector< + map< + [...], + map< + [float != float], + [...]>>> + +.. _cl_diag_warning_groups: + +Individual Warning Groups +^^^^^^^^^^^^^^^^^^^^^^^^^ + +TODO: Generate this from tblgen. Define one anchor per warning group. + +.. _opt_wextra-tokens: + +**-Wextra-tokens** + Warn about excess tokens at the end of a preprocessor directive. + + This option, which defaults to on, enables warnings about extra + tokens at the end of preprocessor directives. For example: + + :: + + test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] + #endif bad + ^ + + These extra tokens are not strictly conforming, and are usually best + handled by commenting them out. + +**-Wambiguous-member-template** + Warn about unqualified uses of a member template whose name resolves to + another template at the location of the use. + + This option, which defaults to on, enables a warning in the + following code: + + :: + + template<typename T> struct set{}; + template<typename T> struct trait { typedef const T& type; }; + struct Value { + template<typename T> void set(typename trait<T>::type value) {} + }; + void foo() { + Value v; + v.set<double>(3.2); + } + + C++ [basic.lookup.classref] requires this to be an error, but, + because it's hard to work around, Clang downgrades it to a warning + as an extension. + +**-Wbind-to-temporary-copy** + Warn about an unusable copy constructor when binding a reference to a + temporary. + + This option, which defaults to on, enables warnings about binding a + reference to a temporary when the temporary doesn't have a usable + copy constructor. For example: + + :: + + struct NonCopyable { + NonCopyable(); + private: + NonCopyable(const NonCopyable&); + }; + void foo(const NonCopyable&); + void bar() { + foo(NonCopyable()); // Disallowed in C++98; allowed in C++11. + } + + :: + + struct NonCopyable2 { + NonCopyable2(); + NonCopyable2(NonCopyable2&); + }; + void foo(const NonCopyable2&); + void bar() { + foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11. + } + + Note that if ``NonCopyable2::NonCopyable2()`` has a default argument + whose instantiation produces a compile error, that error will still + be a hard error in C++98 mode even if this warning is turned off. + +Options to Control Clang Crash Diagnostics +------------------------------------------ + +As unbelievable as it may sound, Clang does crash from time to time. +Generally, this only occurs to those living on the `bleeding +edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great +lengths to assist you in filing a bug report. Specifically, Clang +generates preprocessed source file(s) and associated run script(s) upon +a crash. These files should be attached to a bug report to ease +reproducibility of the failure. Below are the command line options to +control the crash diagnostics. + +**-fno-crash-diagnostics**: Disable auto-generation of preprocessed +source files during a clang crash. + +The -fno-crash-diagnostics flag can be helpful for speeding the process +of generating a delta reduced test case. + +Language and Target-Independent Features +======================================== + +Controlling Errors and Warnings +------------------------------- + +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. + +Controlling How Clang Displays Diagnostics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 the ability to print this information, and these are +the options that control it: + +#. A file/line/column indicator that shows exactly where the diagnostic + occurs in your code [:ref:`-fshow-column <opt_fshow-column>`, + :ref:`-fshow-source-location <opt_fshow-source-location>`]. +#. A categorization of the diagnostic as a note, warning, error, or + fatal error. +#. A text string that describes what the problem is. +#. An option that indicates how to control the diagnostic (for + diagnostics that support it) + [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`]. +#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic + for clients that want to group diagnostics by class (for diagnostics + that support it) + [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`]. +#. The line of source code that the issue occurs on, along with a caret + and ranges that indicate the important locations + [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`]. +#. "FixIt" information, which is a concise explanation of how to fix the + problem (when Clang is certain it knows) + [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`]. +#. A machine-parsable representation of the ranges involved (off by + default) + [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`]. + +For more information please see :ref:`Formatting of +Diagnostics <cl_diag_formatting>`. + +Diagnostic Mappings +^^^^^^^^^^^^^^^^^^^ + +All diagnostics are mapped into one of these 5 classes: + +- Ignored +- Note +- Warning +- Error +- Fatal + +.. _diagnostics_categories: + +Diagnostic Categories +^^^^^^^^^^^^^^^^^^^^^ + +Though not shown by default, diagnostics may each be associated with a +high-level category. This category is intended to make it possible to +triage builds that produce a large number of errors or warnings in a +grouped way. + +Categories are not shown by default, but they can be turned on with the +:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option. +When set to "``name``", the category is printed textually in the +diagnostic output. When it is set to "``id``", a category number is +printed. The mapping of category names to category id's can be obtained +by running '``clang --print-diagnostic-categories``'. + +Controlling Diagnostics via Command Line Flags +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TODO: -W flags, -pedantic, etc + +.. _pragma_gcc_diagnostic: + +Controlling Diagnostics via Pragmas +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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. + +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: + +:: + + #pragma GCC diagnostic ignored "-Wall" + +In addition to all of the functionality 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. + +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. + +:: + + #pragma clang diagnostic push + #pragma clang diagnostic ignored "-Wmultichar" + + char b = 'df'; // no warning. + + #pragma clang diagnostic pop + +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. + +Controlling Diagnostics in System Headers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 ``-isystem``, but this can be overridden in +several ways. + +The ``system_header`` 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. + +:: + + char a = 'xy'; // warning + + #pragma clang system_header + + char b = 'ab'; // no warning + +The ``-isystem-prefix`` and ``-ino-system-prefix`` command-line +arguments can be used to override whether subsets of an include path are +treated as system headers. When the name in a ``#include`` 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: + +:: + + clang -Ifoo -isystem bar -isystem-prefix x/ -ino-system-prefix x/y/ + +Here, ``#include "x/a.h"`` is treated as including a system header, even +if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated +as not including a system header, even if the header is found in +``bar``. + +A ``#include`` 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. + +.. _diagnostics_enable_everything: + +Enabling All Warnings +^^^^^^^^^^^^^^^^^^^^^ + +In addition to the traditional ``-W`` flags, one can enable **all** +warnings by passing ``-Weverything``. This works as expected with +``-Werror``, and also includes the warnings from ``-pedantic``. + +Note that when combined with ``-w`` (which disables all warnings), that +flag wins. + +Controlling Static Analyzer Diagnostics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +While not strictly part of the compiler, the diagnostics from Clang's +`static analyzer <http://clang-analyzer.llvm.org>`_ can also be +influenced by the user via changes to the source code. See the available +`annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the +analyzer's `FAQ +page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more +information. + +Precompiled Headers +------------------- + +`Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__ +are a general approach employed by many compilers to reduce compilation +time. The underlying motivation of the approach is that it is common for +the same (and often large) header files to be included by multiple +source files. Consequently, compile times can often be greatly improved +by caching some of the (redundant) work done by a compiler to process +headers. Precompiled header files, which represent one of many ways to +implement this optimization, are literally files that represent an +on-disk cache that contains the vital information necessary to reduce +some of the work needed to process a corresponding header file. While +details of precompiled headers vary between compilers, precompiled +headers have been shown to be highly effective at speeding up program +compilation on systems with very large system headers (e.g., Mac OS/X). + +Generating a PCH File +^^^^^^^^^^^^^^^^^^^^^ + +To generate a PCH file using Clang, one invokes Clang with the +**``-x <language>-header``** option. This mirrors the interface in GCC +for generating PCH files: + +:: + + $ gcc -x c-header test.h -o test.h.gch + $ clang -x c-header test.h -o test.h.pch + +Using a PCH File +^^^^^^^^^^^^^^^^ + +A PCH file can then be used as a prefix header when a **``-include``** +option is passed to ``clang``: + +:: + + $ clang -include test.h test.c -o test + +The ``clang`` driver will first check if a PCH file for ``test.h`` is +available; if so, the contents of ``test.h`` (and the files it includes) +will be processed from the PCH file. Otherwise, Clang falls back to +directly processing the content of ``test.h``. This mirrors the behavior +of GCC. + +.. note:: + Clang does *not* automatically use PCH files for headers that are + directly included within a source file. For example: + +:: + + $ clang -x c-header test.h -o test.h.pch + $ cat test.c + #include "test.h" + $ clang test.c -o test + +In this example, ``clang`` will not automatically use the PCH file for +``test.h`` since ``test.h`` was included directly in the source file and +not specified on the command line using ``-include``. + +Relocatable PCH Files +^^^^^^^^^^^^^^^^^^^^^ + +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. + +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 ``mylib.h`` +that will be installed into ``/usr/include``, create a subdirectory +``build/usr/include`` and place the header ``mylib.h`` into that +subdirectory. If ``mylib.h`` depends on other headers, then they can be +stored within ``build/usr/include`` in a way that mimics the installed +location. + +Building a relocatable precompiled header requires two additional +arguments. First, pass the ``--relocatable-pch`` flag to indicate that +the resulting PCH file should be relocatable. Second, pass +``-isysroot /path/to/build``, which makes all includes for your library +relative to the build directory. For example: + +:: + + # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch + +When loading the relocatable PCH file, the various headers used in the +PCH file are found from the system header root. For example, ``mylib.h`` +can be found in ``/usr/include/mylib.h``. If the headers are installed +in some other system root, the ``-isysroot`` option can be used provide +a different system root from which the headers will be based. For +example, ``-isysroot /Developer/SDKs/MacOSX10.4u.sdk`` will look for +``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``. + +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, ``stat()`` caching, to be disabled. However, this change +is only likely to affect PCH files that reference a large number of +headers. + +Controlling Code Generation +--------------------------- + +Clang provides a number of ways to control code generation. The options +are listed below. + +**-fsanitize=check1,check2** + Turn on runtime checks for various forms of undefined or suspicious + behavior. + + This option controls whether Clang adds runtime checks for various + forms of undefined or suspicious behavior, and is disabled by + default. If a check fails, a diagnostic message is produced at + runtime explaining the problem. The main checks are: + + .. _opt_fsanitize_address: + + - ``-fsanitize=address``: + :doc:`AddressSanitizer`, a memory error + detector. + - ``-fsanitize=address-full``: AddressSanitizer with all the + experimental features listed below. + - ``-fsanitize=integer``: Enables checks for undefined or + suspicious integer behavior. + - ``-fsanitize=thread``: :doc:`ThreadSanitizer`, + an *experimental* data race detector. Not ready for widespread + use. + + .. _opt_fsanitize_undefined: + + - ``-fsanitize=undefined``: Fast and compatible undefined behavior + checker. Enables the undefined behavior checks that have small + runtime cost and no impact on address space layout or ABI. This + includes all of the checks listed below other than + ``unsigned-integer-overflow``. + + The following more fine-grained checks are also available: + + - ``-fsanitize=alignment``: Use of a misaligned pointer or creation + of a misaligned reference. + - ``-fsanitize=bounds``: Out of bounds array indexing, in cases + where the array bound can be statically determined. + - ``-fsanitize=float-cast-overflow``: Conversion to, from, or + between floating-point types which would overflow the + destination. + - ``-fsanitize=float-divide-by-zero``: Floating point division by + zero. + - ``-fsanitize=integer-divide-by-zero``: Integer division by zero. + - ``-fsanitize=null``: Use of a null pointer or creation of a null + reference. + - ``-fsanitize=object-size``: An attempt to use bytes which the + optimizer can determine are not part of the object being + accessed. The sizes of objects are determined using + ``__builtin_object_size``, and consequently may be able to detect + more problems at higher optimization levels. + - ``-fsanitize=return``: In C++, reaching the end of a + value-returning function without returning a value. + - ``-fsanitize=shift``: Shift operators where the amount shifted is + greater or equal to the promoted bit-width of the left hand side + or less than zero, or where the left hand side is negative. For a + signed left shift, also checks for signed overflow in C, and for + unsigned overflow in C++. + - ``-fsanitize=signed-integer-overflow``: Signed integer overflow, + including all the checks added by ``-ftrapv``, and checking for + overflow in signed division (``INT_MIN / -1``). + - ``-fsanitize=unreachable``: If control flow reaches + ``__builtin_unreachable``. + - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer + overflows. + - ``-fsanitize=vla-bound``: A variable-length array whose bound + does not evaluate to a positive value. + - ``-fsanitize=vptr``: Use of an object whose vptr indicates that + it is of the wrong dynamic type, or that its lifetime has not + begun or has ended. Incompatible with ``-fno-rtti``. + + Experimental features of AddressSanitizer (not ready for widespread + use, require explicit ``-fsanitize=address``): + + - ``-fsanitize=init-order``: Check for dynamic initialization order + problems. + - ``-fsanitize=use-after-return``: Check for use-after-return + errors (accessing local variable after the function exit). + - ``-fsanitize=use-after-scope``: Check for use-after-scope errors + (accesing local variable after it went out of scope). + + The ``-fsanitize=`` argument must also be provided when linking, in + order to link to the appropriate runtime library. It is not possible + to combine the ``-fsanitize=address`` and ``-fsanitize=thread`` + checkers in the same program. +**-f[no-]address-sanitizer** + Deprecated synonym for :ref:`-f[no-]sanitize=address + <opt_fsanitize_address>`. +**-f[no-]thread-sanitizer** + Deprecated synonym for :ref:`-f[no-]sanitize=thread + <opt_fsanitize_address>`. +**-fcatch-undefined-behavior** + Deprecated synonym for :ref:`-fsanitize=undefined + <opt_fsanitize_undefined>`. +**-fno-assume-sane-operator-new** + Don't assume that the C++'s new operator is sane. + + This option tells the compiler to do not assume that C++'s global + new operator will always return a pointer that does not alias any + other pointer when the function returns. + +**-ftrap-function=[name]** + Instruct code generator to emit a function call to the specified + function name for ``__builtin_trap()``. + + LLVM code generator translates ``__builtin_trap()`` to a trap + instruction if it is supported by the target ISA. Otherwise, the + builtin is translated into a call to ``abort``. If this option is + set, then the code 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. + +**-ftls-model=[model]** + Select which TLS model to use. + + Valid values are: ``global-dynamic``, ``local-dynamic``, + ``initial-exec`` and ``local-exec``. The default value is + ``global-dynamic``. 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 ``tls_model`` attribute. + +Controlling Size of Debug Information +------------------------------------- + +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. + +**-g0**: Don't generate any debug info (default). + +**-gline-tables-only**: Generate line number tables only. + +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). + +**-g**: Generate complete debug info. + +.. _c: + +C Language Features +=================== + +The support for standard C in clang is feature-complete except for the +C99 floating-point pragmas. + +Extensions supported by clang +----------------------------- + +See `clang language extensions <LanguageExtensions.html>`_. + +Differences between various standard modes +------------------------------------------ + +clang supports the -std option, which changes what language mode clang +uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and +various aliases for those modes. If no -std option is specified, clang +defaults to gnu99 mode. + +Differences between all ``c*`` and ``gnu*`` modes: + +- ``c*`` modes define "``__STRICT_ANSI__``". +- Target-specific defines not prefixed by underscores, like "linux", + are defined in ``gnu*`` modes. +- Trigraphs default to being off in ``gnu*`` modes; they can be enabled by + the -trigraphs option. +- The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes; + the variants "``__asm__``" and "``__typeof__``" are recognized in all + modes. +- 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. +- Arrays that are VLA's according to the standard, but which can be + constant folded by the frontend are treated as fixed size arrays. + This occurs for things like "int X[(1, 2)];", which is technically a + VLA. ``c*`` modes are strictly compliant and treat these as VLAs. + +Differences between ``*89`` and ``*99`` modes: + +- The ``*99`` modes default to implementing "inline" as specified in C99, + while the ``*89`` modes implement the GNU version. This can be + overridden for individual functions with the ``__gnu_inline__`` + attribute. +- Digraphs are not recognized in c89 mode. +- The scope of names defined inside a "for", "if", "switch", "while", + or "do" statement is different. (example: "``if ((struct x {int + x;}*)0) {}``".) +- ``__STDC_VERSION__`` is not defined in ``*89`` modes. +- "inline" is not recognized as a keyword in c89 mode. +- "restrict" is not recognized as a keyword in ``*89`` modes. +- Commas are allowed in integer constant expressions in ``*99`` modes. +- Arrays which are not lvalues are not implicitly promoted to pointers + in ``*89`` modes. +- Some warnings are different. + +c94 mode is identical to c89 mode except that digraphs are enabled in +c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!). + +GCC extensions not implemented yet +---------------------------------- + +clang tries to be compatible with gcc as much as possible, but some gcc +extensions are not implemented yet: + +- clang does not support #pragma weak (`bug + 3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses + described in the bug, this is likely to be implemented at some point, + at least partially. +- clang does not support decimal floating point types (``_Decimal32`` and + friends) or fixed-point types (``_Fract`` and friends); nobody has + expressed interest in these features yet, so it's hard to say when + they will be implemented. +- clang does not support nested functions; this is a complex feature + which 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: + + :: + + auto const local_function = [&](int parameter) { + // Do something + }; + ... + local_function(1); + +- clang does not support global register variables; this is unlikely to + be implemented soon because it requires additional LLVM backend + support. +- clang does not support static initialization of flexible array + members. This appears to be a rarely used extension, but could be + implemented pending user demand. +- clang does not support + ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is + used rarely, but in some potentially interesting places, like the + glibc headers, so it may be implemented pending user demand. Note + that because clang pretends to be like GCC 4.2, and this extension + was introduced in 4.3, the glibc headers will not try to use this + extension with clang at the moment. +- clang does not support the gcc extension for forward-declaring + function parameters; this has not shown up in any real-world code + yet, though, so it might never be implemented. + +This is not a complete list; if you find an unsupported extension +missing from this list, please send an e-mail to cfe-dev. This list +currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this +list does not include bugs in mostly-implemented features; please see +the `bug +tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_ +for known existing bugs (FIXME: Is there a section for bug-reporting +guidelines somewhere?). + +Intentionally unsupported GCC extensions +---------------------------------------- + +- clang does not support the gcc extension that allows variable-length + arrays in structures. This is for a few reasons: one, it is tricky to + implement, two, the extension is completely undocumented, and three, + the extension appears to be rarely used. Note that clang *does* + support flexible array members (arrays with a zero or unspecified + size at the end of a structure). +- clang does not have an equivalent to gcc's "fold"; this means that + clang doesn't accept some constructs gcc might accept in contexts + where a constant expression is required, like "x-x" where x is a + variable. +- clang does not support ``__builtin_apply`` and friends; this extension + is extremely obscure and difficult to implement reliably. + +.. _c_ms: + +Microsoft extensions +-------------------- + +clang has some experimental support for extensions from Microsoft Visual +C++; to enable it, use the -fms-extensions command-line option. This is +the default for Windows targets. Note that the support is incomplete; +enabling Microsoft extensions will silently drop certain constructs +(including ``__declspec`` and Microsoft-style asm statements). + +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. + +-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. + +- 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 what Windows SDK and c++stdlib headers clang + can compile. This option will be removed when clang supports the full + set of MS extensions required for these headers. +- clang does not support the Microsoft extension where anonymous record + members can be declared using user defined typedefs. +- clang supports the Microsoft "#pragma pack" feature for controlling + record layout. GCC also contains support for this feature, however + where MSVC and GCC are incompatible clang follows the MSVC + definition. +- clang defaults to C++11 for Windows targets. + +.. _cxx: + +C++ Language Features +===================== + +clang fully implements all of standard C++98 except for exported +templates (which were removed in C++11), and `many C++11 +features <http://clang.llvm.org/cxx_status.html>`_ are also implemented. + +Controlling implementation limits +--------------------------------- + +**-fconstexpr-depth=N**: Sets the limit for recursive constexpr function +invocations to N. The default is 512. + +**-ftemplate-depth=N**: Sets the limit for recursively nested template +instantiations to N. The default is 1024. + +.. _objc: + +Objective-C Language Features +============================= + +.. _objcxx: + +Objective-C++ Language Features +=============================== + + +.. _target_features: + +Target-Specific Features and Limitations +======================================== + +CPU Architectures Features and Limitations +------------------------------------------ + +X86 +^^^ + +The support for X86 (both 32-bit and 64-bit) is considered stable on +Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested +to correctly compile many large C, C++, Objective-C, and Objective-C++ +codebases. + +On ``x86_64-mingw32``, passing i128(by value) is incompatible to Microsoft +x64 calling conversion. You might need to tweak +``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp. + +ARM +^^^ + +The support for ARM (specifically ARMv6 and ARMv7) is considered stable +on Darwin (iOS): it has been tested to correctly compile many large C, +C++, Objective-C, and Objective-C++ codebases. Clang only supports a +limited number of ARM architectures. It does not yet fully support +ARMv5, for example. + +Other platforms +^^^^^^^^^^^^^^^ + +clang currently contains some support for PPC and Sparc; however, +significant pieces of code generation are still missing, and they +haven't undergone significant testing. + +clang contains limited support for the MSP430 embedded processor, but +both the clang support and the LLVM backend support are highly +experimental. + +Other platforms are completely unsupported at the moment. Adding the +minimal support needed for parsing and semantic analysis on a new +platform is quite easy; see lib/Basic/Targets.cpp in the clang source +tree. This level of support is also sufficient for conversion to LLVM IR +for simple programs. Proper support for conversion to LLVM IR requires +adding code to lib/CodeGen/CGCall.cpp at the moment; this is likely to +change soon, though. Generating assembly requires a suitable LLVM +backend. + +Operating System Features and Limitations +----------------------------------------- + +Darwin (Mac OS/X) +^^^^^^^^^^^^^^^^^ + +None + +Windows +^^^^^^^ + +Experimental supports are on Cygming. + +See also `Microsoft Extensions <c_ms>`. + +Cygwin +"""""" + +Clang works on Cygwin-1.7. + +MinGW32 +""""""" + +Clang works on some mingw32 distributions. Clang assumes directories as +below; + +- ``C:/mingw/include`` +- ``C:/mingw/lib`` +- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++`` + +On MSYS, a few tests might fail. + +MinGW-w64 +""""""""" + +For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang +assumes as below; + +- ``GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)`` +- ``some_directory/bin/gcc.exe`` +- ``some_directory/bin/clang.exe`` +- ``some_directory/bin/clang++.exe`` +- ``some_directory/bin/../include/c++/GCC_version`` +- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32`` +- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32`` +- ``some_directory/bin/../include/c++/GCC_version/backward`` +- ``some_directory/bin/../x86_64-w64-mingw32/include`` +- ``some_directory/bin/../i686-w64-mingw32/include`` +- ``some_directory/bin/../include`` + +This directory layout is standard for any toolchain you will find on the +official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_. + +Clang expects the GCC executable "gcc.exe" compiled for +``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH. + +`Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on +``x86_64-w64-mingw32``. diff --git a/clang/docs/index.rst b/clang/docs/index.rst index fab47916b43..05947feebb6 100644 --- a/clang/docs/index.rst +++ b/clang/docs/index.rst @@ -18,6 +18,17 @@ progress. This page will get filled out with docs soon... PCHInternals ThreadSanitizer Tooling + AddressSanitizer + AnalyzerRegions + ClangPlugins + ClangTools + HowToSetupToolingForLLVM + IntroductionToTheClangAST + JSONCompilationDatabase + LibASTMatchersTutorial + PTHInternals + RAVFrontendAction + UsersManual Indices and tables |