diff --git a/clang/docs/AddressSanitizer.rst b/clang/docs/AddressSanitizer.rst index 0ee108bd9e42..357ebd9d93e0 100644 --- a/clang/docs/AddressSanitizer.rst +++ b/clang/docs/AddressSanitizer.rst @@ -8,40 +8,37 @@ AddressSanitizer 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: +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 +* 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 @@ To get perfect stack traces you may need to disable inlining (just use 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 @@ One reason: it makes the generated code smaller and faster (both by 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 `_ -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 ` 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 `_ -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 ` +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 @@ 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. +* 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 `_ + diff --git a/clang/docs/ClangPlugins.rst b/clang/docs/ClangPlugins.rst index cf5381722987..7c5c65ccf1d4 100644 --- a/clang/docs/ClangPlugins.rst +++ b/clang/docs/ClangPlugins.rst @@ -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 ` on how to write a FrontendAction -using the RecursiveASTVisitor. In this tutorial, we'll demonstrate how -to write a simple clang plugin. +tutorial ` 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 -========================= +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. +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& args) { - for (unsigned i = 0, e = args.size(); i != e; ++i) { - if (args[i] == "-some-arg") { - // Handle the command line argument. - } - } - return true; + bool ParseArgs(const CompilerInstance &CI, + const std::vector& 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 X("my-plugin-name", "my plugin description"); + static FrontendPluginRegistry::Add 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 `_. +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 +`_. -:: +.. code-block:: c++ #include "clang/Frontend/FrontendPluginRegistry.h" #include "clang/AST/ASTConsumer.h" @@ -114,31 +114,31 @@ PrintFunctionNames.cpp . +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-`. 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. +* 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: +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 \ + $ 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 @@ from the source tree: Also see the print-function-name plugin example's `README `_ + diff --git a/clang/docs/HowToSetupToolingForLLVM.rst b/clang/docs/HowToSetupToolingForLLVM.rst index 0c4cccafca53..70685f339432 100644 --- a/clang/docs/HowToSetupToolingForLLVM.rst +++ b/clang/docs/HowToSetupToolingForLLVM.rst @@ -28,45 +28,44 @@ later installed (can be found `here `_). 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 @@ automatically when clang-check finds errors, and can be re-opened with 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=`` - 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=`` --- 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 - (IfStmt 0x44d97c8 - <<>> - (ImplicitCastExpr 0x44d96d0 '_Bool':'_Bool' - ... - $ 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 ::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 + (IfStmt 0x44d97c8 + <<>> + (ImplicitCastExpr 0x44d96d0 '_Bool':'_Bool' + ... + $ 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 ::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 @@ 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: -:: +.. 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. + diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst index ccd3ae30382b..bbfcc54b6536 100644 --- a/clang/docs/InternalsManual.rst +++ b/clang/docs/InternalsManual.rst @@ -73,8 +73,8 @@ Getting all of this to happen has several steps and involves many moving 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 diff --git a/clang/docs/IntroductionToTheClangAST.rst b/clang/docs/IntroductionToTheClangAST.rst index a23fb42b7123..81eb7ed0b9ef 100644 --- a/clang/docs/IntroductionToTheClangAST.rst +++ b/clang/docs/IntroductionToTheClangAST.rst @@ -28,14 +28,14 @@ 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. +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 @@ Let's look at a simple example AST: -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 `_. In this example, our first user written declaration is the `function declaration `_ -of 'f'. The body of 'f' is a `compound +of "``f``". The body of "``f``" is a `compound statement `_, whose child nodes are a `declaration statement `_ diff --git a/clang/docs/JSONCompilationDatabase.rst b/clang/docs/JSONCompilationDatabase.rst index 502557b50af5..51482648d5ff 100644 --- a/clang/docs/JSONCompilationDatabase.rst +++ b/clang/docs/JSONCompilationDatabase.rst @@ -31,7 +31,7 @@ Supported Systems Currently `CMake `_ (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 `_. libclang and its @@ -72,8 +72,8 @@ The contracts for each field in the command object are: - **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 diff --git a/clang/docs/PTHInternals.rst b/clang/docs/PTHInternals.rst index d37b76736b0d..55c01928770f 100644 --- a/clang/docs/PTHInternals.rst +++ b/clang/docs/PTHInternals.rst @@ -4,8 +4,8 @@ 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 `_. +interested in the end-user view, please see the :ref:`User's Manual +`. Using Pretokenized Headers with ``clang`` (Low-level Interface) =============================================================== @@ -13,20 +13,19 @@ 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``: +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 @@ 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: -:: +.. code-block:: console - $ cat test.h - #include - $ 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 + $ 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 diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 52afca3d6c5d..5170bfd026f3 100644 --- a/clang/docs/UsersManual.rst +++ b/clang/docs/UsersManual.rst @@ -685,6 +685,8 @@ analyzer's `FAQ page `_ for more information. +.. _usersmanual-precompiled-headers: + Precompiled Headers -------------------