Documentation: random cleanups. Use monospaced font where appropriate,
highlight console output with "code-block:: console", etc. llvm-svn: 170276
This commit is contained in:
Dmitri Gribenko
parent
d9d26072d6
commit
7ac0cc3698
|
|
@ -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 <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 @@ 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/>`_.
|
||||
`http://code.google.com/p/address-sanitizer <http://code.google.com/p/address-sanitizer/>`_
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
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
|
||||
=========================
|
||||
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<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;
|
||||
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 @@ PrintFunctionNames.cpp <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/P
|
|||
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.
|
||||
* 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 <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_
|
||||
|
||||
|
|
|
|||
|
|
@ -28,45 +28,44 @@ 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:
|
||||
|
||||
::
|
||||
.. 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=<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 @@ 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
|||
</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>`_
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ 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.
|
||||
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 @@ 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
|
||||
|
|
|
|||
|
|
@ -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 <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 @@ 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 <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
|
||||
|
|
|
|||
|
|
@ -685,6 +685,8 @@ analyzer's `FAQ
|
|||
page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
|
||||
information.
|
||||
|
||||
.. _usersmanual-precompiled-headers:
|
||||
|
||||
Precompiled Headers
|
||||
-------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue