[cfe-commits] r170276 - in /cfe/trunk/docs: AddressSanitizer.rst ClangPlugins.rst HowToSetupToolingForLLVM.rst InternalsManual.rst IntroductionToTheClangAST.rst JSONCompilationDatabase.rst PTHInternals.rst UsersManual.rst
Dmitri Gribenko
gribozavr at gmail.com
Sat Dec 15 13:10:51 PST 2012
Author: gribozavr
Date: Sat Dec 15 15:10:51 2012
New Revision: 170276
URL: http://llvm.org/viewvc/llvm-project?rev=170276&view=rev
Log:
Documentation: random cleanups. Use monospaced font where appropriate,
highlight console output with "code-block:: console", etc.
Modified:
cfe/trunk/docs/AddressSanitizer.rst
cfe/trunk/docs/ClangPlugins.rst
cfe/trunk/docs/HowToSetupToolingForLLVM.rst
cfe/trunk/docs/InternalsManual.rst
cfe/trunk/docs/IntroductionToTheClangAST.rst
cfe/trunk/docs/JSONCompilationDatabase.rst
cfe/trunk/docs/PTHInternals.rst
cfe/trunk/docs/UsersManual.rst
Modified: cfe/trunk/docs/AddressSanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/AddressSanitizer.rst?rev=170276&r1=170275&r2=170276&view=diff
==============================================================================
--- cfe/trunk/docs/AddressSanitizer.rst (original)
+++ cfe/trunk/docs/AddressSanitizer.rst Sat Dec 15 15:10:51 2012
@@ -8,40 +8,37 @@
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
+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.
+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``).
+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``).
-::
+.. code-block:: console
% cat example_UseAfterFree.cc
int main(int argc, char **argv) {
@@ -50,26 +47,24 @@
return array[argc]; // BOOM
}
-::
-
# Compile and link
% clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc
-OR
+or:
-::
+.. code-block:: console
# 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).
+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).
-::
+.. code-block:: console
% ./a.out 2> log
% projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
@@ -94,40 +89,40 @@
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)
+``__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.
+In some cases one may need to execute different code depending on whether
+AddressSanitizer is enabled.
+:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
+this purpose.
-::
+.. code-block:: c
#if defined(__has_feature)
- # if __has_feature(address_sanitizer)
- code that builds only under AddressSanitizer
- # endif
+ # 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.
+Some code should not be instrumented by AddressSanitizer. One may use the
+function attribute
+:ref:`no_address_safety_analysis <langext-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).
+* 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).
@@ -135,24 +130,24 @@
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.
+* 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.
+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/>`_.
+`http://code.google.com/p/address-sanitizer <http://code.google.com/p/address-sanitizer/>`_
+
Modified: cfe/trunk/docs/ClangPlugins.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ClangPlugins.rst?rev=170276&r1=170275&r2=170276&view=diff
==============================================================================
--- cfe/trunk/docs/ClangPlugins.rst (original)
+++ cfe/trunk/docs/ClangPlugins.rst Sat Dec 15 15:10:51 2012
@@ -2,56 +2,56 @@
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.
+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;
+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.
+
+.. code-block:: c++
+
+ 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:
+register a plugin in a library, use ``FrontendPluginRegistry::Add<>``:
-::
+.. code-block:: c++
- static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description");
+ 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>`_.
+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>`_.
-::
+.. code-block:: c++
#include "clang/Frontend/FrontendPluginRegistry.h"
#include "clang/AST/ASTConsumer.h"
@@ -114,31 +114,31 @@
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>.
+To run a plugin, the dynamic library containing the plugin registry must be
+loaded via the :option:`-load` command line option. This will load all plugins
+that are registered, and you can select the plugins to run by specifying the
+:option:`-plugin` option. Additional parameters for the plugins can be passed with
+:option:`-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 \
+* Directly call the parsing process by using the :option:`-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
+ :option:`-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:
+
+.. code-block:: console
+
+ $ 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 \
@@ -147,3 +147,4 @@
Also see the print-function-name plugin example's
`README <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_
+
Modified: cfe/trunk/docs/HowToSetupToolingForLLVM.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/HowToSetupToolingForLLVM.rst?rev=170276&r1=170275&r2=170276&view=diff
==============================================================================
--- cfe/trunk/docs/HowToSetupToolingForLLVM.rst (original)
+++ cfe/trunk/docs/HowToSetupToolingForLLVM.rst Sat Dec 15 15:10:51 2012
@@ -28,45 +28,44 @@
First, you need to generate Makefiles for LLVM with CMake. You need to
make a build directory and run CMake from it:
-::
+.. code-block:: console
- mkdir your/build/directory
- cd your/build/directory
- cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources
+ $ 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
+``-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:
-::
+.. code-block:: console
- ln -s $PWD/compile_commands.json path/to/llvm/source/
+ $ ln -s $PWD/compile_commands.json path/to/llvm/source/
Now you are ready to build and test LLVM using make:
-::
+.. code-block:: console
- make check-all
+ $ 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:
+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:
-::
+.. code-block:: console
- clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp
+ $ 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:
+this into your ``.vimrc``:
::
@@ -106,39 +105,39 @@
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.
+* ``-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:
-::
+.. code-block:: console
- $ 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();
- }
+ $ 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
=======================================
@@ -153,59 +152,60 @@
development, so you can get latest development sources and build it
yourself:
-::
+.. code-block:: console
- git clone git://cmake.org/cmake.git
- cd cmake
- ./bootstrap
- make
- sudo make install
+ $ 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:
-::
+.. code-block:: console
- git clone git://github.com/martine/ninja.git
- cd ninja/
- ./bootstrap.py
+ $ 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/``:
-::
+.. code-block:: console
- sudo cp ninja /usr/local/bin/
- sudo chmod a+rx /usr/local/bin/ninja
+ $ 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:
-::
+.. code-block:: console
- mkdir your/build/directory
- cd your/build/directory
- cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources
+ $ 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
+``-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:
-::
+.. code-block:: console
- ln -s $PWD/compile_commands.json path/to/llvm/source/
+ $ ln -s $PWD/compile_commands.json path/to/llvm/source/
Now you are ready to build and test LLVM using Ninja:
-::
+.. code-block:: console
- ninja check-all
+ $ ninja check-all
Other target names can be used in the same way as with make.
+
Modified: cfe/trunk/docs/InternalsManual.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/InternalsManual.rst?rev=170276&r1=170275&r2=170276&view=diff
==============================================================================
--- cfe/trunk/docs/InternalsManual.rst (original)
+++ cfe/trunk/docs/InternalsManual.rst Sat Dec 15 15:10:51 2012
@@ -73,8 +73,8 @@
pieces, this section describes them and talks about best practices when adding
a new diagnostic.
-The Diagnostic*Kinds.td files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The ``Diagnostic*Kinds.td`` files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Diagnostics are created by adding an entry to one of the
``clang/Basic/Diagnostic*Kinds.td`` files, depending on what library will be
Modified: cfe/trunk/docs/IntroductionToTheClangAST.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/IntroductionToTheClangAST.rst?rev=170276&r1=170275&r2=170276&view=diff
==============================================================================
--- cfe/trunk/docs/IntroductionToTheClangAST.rst (original)
+++ cfe/trunk/docs/IntroductionToTheClangAST.rst Sat Dec 15 15:10:51 2012
@@ -28,14 +28,14 @@
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.
+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
+ $ cat test.cc
int f(int x) {
int result = (x / 42);
return result;
@@ -73,13 +73,13 @@
</Function>
</TranslationUnit>
-In general, -ast-dump-xml dumps declarations in an XML-style format and
+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
+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>`_
Modified: cfe/trunk/docs/JSONCompilationDatabase.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/JSONCompilationDatabase.rst?rev=170276&r1=170275&r2=170276&view=diff
==============================================================================
--- cfe/trunk/docs/JSONCompilationDatabase.rst (original)
+++ cfe/trunk/docs/JSONCompilationDatabase.rst Sat Dec 15 15:10:51 2012
@@ -31,7 +31,7 @@
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.
+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
@@ -72,8 +72,8 @@
- **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
+ Parameters use shell quoting and shell escaping of quotes, with '``"``'
+ and '``\``' being the only special characters. Shell expansion is not
supported.
Build System Integration
Modified: cfe/trunk/docs/PTHInternals.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/PTHInternals.rst?rev=170276&r1=170275&r2=170276&view=diff
==============================================================================
--- cfe/trunk/docs/PTHInternals.rst (original)
+++ cfe/trunk/docs/PTHInternals.rst Sat Dec 15 15:10:51 2012
@@ -4,8 +4,8 @@
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>`_.
+interested in the end-user view, please see the :ref:`User's Manual
+<usersmanual-precompiled-headers>`.
Using Pretokenized Headers with ``clang`` (Low-level Interface)
===============================================================
@@ -13,20 +13,19 @@
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``:
+To generate PTH files using ``clang -cc1``, use the option ``-emit-pth``:
-::
+.. code-block:: console
- $ clang -cc1 test.h -emit-pth -o test.h.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:
-::
+.. code-block:: console
- $ clang -cc1 -include-pth test.h.pth test.c -o test.s
+ $ 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.
@@ -34,14 +33,14 @@
for *any* source files that are used by ``clang -cc1`` to process a
source file. This is done by specifying the ``-token-cache`` option:
-::
+.. code-block:: console
- $ 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
+ $ 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
Modified: cfe/trunk/docs/UsersManual.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=170276&r1=170275&r2=170276&view=diff
==============================================================================
--- cfe/trunk/docs/UsersManual.rst (original)
+++ cfe/trunk/docs/UsersManual.rst Sat Dec 15 15:10:51 2012
@@ -685,6 +685,8 @@
page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
information.
+.. _usersmanual-precompiled-headers:
+
Precompiled Headers
-------------------
More information about the cfe-commits
mailing list