Skip to content
Snippets Groups Projects
Commit 0bd9e727 authored by Dmitri Gribenko's avatar Dmitri Gribenko
Browse files

Documentation: UsersManual.rst: some cleanups after semi-automatic conversion 

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@170590 91177308-0d34-0410-b5e6-96231b3b80d8
parent 277076a4
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 146 additions and 97 deletions
docs/UsersManual.rst
+ 146
− 97
View file @ 0bd9e727
...@@ -80,41 +80,64 @@ Command Line Options ...@@ -80,41 +80,64 @@ Command Line Options
This section is generally an index into other sections. It does not go 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 into depth on the ones that are covered by other sections. However, the
first part introduces the language selection and other high level first part introduces the language selection and other high level
options like -c, -g, etc. options like :option:`-c`, :option:`-g`, etc.
Options to Control Error and Warning Messages Options to Control Error and Warning Messages
--------------------------------------------- ---------------------------------------------
**-Werror**: Turn warnings into errors. .. option:: -Werror
**-Werror=foo**: Turn warning "foo" into an error. Turn warnings into errors.
**-Wno-error=foo**: Turn warning "foo" into an warning even if -Werror .. This is in plain monospaced font because it generates the same label as
is specified. .. -Werror, and Sphinx complains.
**-Wfoo**: Enable warning "foo". ``-Werror=foo``
**-Wno-foo**: Disable warning "foo". Turn warning "foo" into an error.
**-w**: Disable all warnings. .. option:: -Wno-error=foo
**-Weverything**: :ref:`Enable **all** Turn warning "foo" into an warning even if :option:`-Werror` is specified.
warnings. <diagnostics_enable_everything>`
**-pedantic**: Warn on language extensions. .. option:: -Wfoo
**-pedantic-errors**: Error on language extensions. Enable warning "foo".
**-Wsystem-headers**: Enable warnings from system headers. .. option:: -Wno-foo
**-ferror-limit=123**: Stop emitting diagnostics after 123 errors have Disable warning "foo".
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 .. option:: -w
instantiation notes within the template instantiation backtrace for a
single warning or error. The default is 10, and the limit can be Disable all warnings.
disabled with -ftemplate-backtrace-limit=0.
.. option:: -Weverything
:ref:`Enable all warnings. <diagnostics_enable_everything>`
.. option:: -pedantic
Warn on language extensions.
.. option:: -pedantic-errors
Error on language extensions.
.. option:: -Wsystem-headers
Enable warnings from system headers.
.. option:: -ferror-limit=123
Stop emitting diagnostics after 123 errors have been produced. The default is
20, and the error limit can be disabled with :option:`-ferror-limit=0`.
.. option:: -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 :option:`-ftemplate-backtrace-limit=0`.
.. _cl_diag_formatting: .. _cl_diag_formatting:
...@@ -212,7 +235,8 @@ output format of the diagnostics that it generates. ...@@ -212,7 +235,8 @@ output format of the diagnostics that it generates.
^ ^
// //
**-fdiagnostics-format=clang/msvc/vi** .. option:: -fdiagnostics-format=clang/msvc/vi
Changes diagnostic output format to better match IDEs and command line tools. Changes diagnostic output format to better match IDEs and command line tools.
This option controls the output format of the filename, line number, This option controls the output format of the filename, line number,
...@@ -264,7 +288,8 @@ output format of the diagnostics that it generates. ...@@ -264,7 +288,8 @@ output format of the diagnostics that it generates.
.. _opt_fdiagnostics-show-category: .. _opt_fdiagnostics-show-category:
**-fdiagnostics-show-category=none/id/name** .. option:: -fdiagnostics-show-category=none/id/name
Enable printing category information in diagnostic line. Enable printing category information in diagnostic line.
This option, which defaults to "none", controls whether or not Clang This option, which defaults to "none", controls whether or not Clang
...@@ -328,7 +353,8 @@ output format of the diagnostics that it generates. ...@@ -328,7 +353,8 @@ output format of the diagnostics that it generates.
The printed column numbers count bytes from the beginning of the The printed column numbers count bytes from the beginning of the
line; take care if your source contains multibyte characters. line; take care if your source contains multibyte characters.
**-fdiagnostics-parseable-fixits** .. option:: -fdiagnostics-parseable-fixits
Print Fix-Its in a machine parseable form. Print Fix-Its in a machine parseable form.
This option makes Clang print available Fix-Its in a machine This option makes Clang print available Fix-Its in a machine
...@@ -351,7 +377,8 @@ output format of the diagnostics that it generates. ...@@ -351,7 +377,8 @@ output format of the diagnostics that it generates.
The printed column numbers count bytes from the beginning of the The printed column numbers count bytes from the beginning of the
line; take care if your source contains multibyte characters. line; take care if your source contains multibyte characters.
**-fno-elide-type** .. option:: -fno-elide-type
Turns off elision in template type printing. Turns off elision in template type printing.
The default for template type printing is to elide as many template The default for template type printing is to elide as many template
...@@ -372,7 +399,8 @@ output format of the diagnostics that it generates. ...@@ -372,7 +399,8 @@ output format of the diagnostics that it generates.
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; 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** .. option:: -fdiagnostics-show-template-tree
Template type diffing prints a text tree. Template type diffing prints a text tree.
For diffing large templated types, this option will cause Clang to For diffing large templated types, this option will cause Clang to
...@@ -386,7 +414,7 @@ output format of the diagnostics that it generates. ...@@ -386,7 +414,7 @@ output format of the diagnostics that it generates.
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; 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 With :option:`-fdiagnostics-show-template-tree`:
:: ::
...@@ -407,7 +435,8 @@ TODO: Generate this from tblgen. Define one anchor per warning group. ...@@ -407,7 +435,8 @@ TODO: Generate this from tblgen. Define one anchor per warning group.
.. _opt_wextra-tokens: .. _opt_wextra-tokens:
**-Wextra-tokens** .. option:: -Wextra-tokens
Warn about excess tokens at the end of a preprocessor directive. Warn about excess tokens at the end of a preprocessor directive.
This option, which defaults to on, enables warnings about extra This option, which defaults to on, enables warnings about extra
...@@ -422,7 +451,8 @@ TODO: Generate this from tblgen. Define one anchor per warning group. ...@@ -422,7 +451,8 @@ TODO: Generate this from tblgen. Define one anchor per warning group.
These extra tokens are not strictly conforming, and are usually best These extra tokens are not strictly conforming, and are usually best
handled by commenting them out. handled by commenting them out.
**-Wambiguous-member-template** .. option:: -Wambiguous-member-template
Warn about unqualified uses of a member template whose name resolves to Warn about unqualified uses of a member template whose name resolves to
another template at the location of the use. another template at the location of the use.
...@@ -445,7 +475,8 @@ TODO: Generate this from tblgen. Define one anchor per warning group. ...@@ -445,7 +475,8 @@ TODO: Generate this from tblgen. Define one anchor per warning group.
because it's hard to work around, Clang downgrades it to a warning because it's hard to work around, Clang downgrades it to a warning
as an extension. as an extension.
**-Wbind-to-temporary-copy** .. option:: -Wbind-to-temporary-copy
Warn about an unusable copy constructor when binding a reference to a Warn about an unusable copy constructor when binding a reference to a
temporary. temporary.
...@@ -492,8 +523,9 @@ a crash. These files should be attached to a bug report to ease ...@@ -492,8 +523,9 @@ a crash. These files should be attached to a bug report to ease
reproducibility of the failure. Below are the command line options to reproducibility of the failure. Below are the command line options to
control the crash diagnostics. control the crash diagnostics.
**-fno-crash-diagnostics**: Disable auto-generation of preprocessed .. option:: -fno-crash-diagnostics
source files during a clang crash.
Disable auto-generation of preprocessed source files during a clang crash.
The -fno-crash-diagnostics flag can be helpful for speeding the process The -fno-crash-diagnostics flag can be helpful for speeding the process
of generating a delta reduced test case. of generating a delta reduced test case.
...@@ -590,27 +622,27 @@ line. Warnings may be set to ignored, warning, error, or fatal. The ...@@ -590,27 +622,27 @@ line. Warnings may be set to ignored, warning, error, or fatal. The
following example code will tell Clang or GCC to ignore the -Wall following example code will tell Clang or GCC to ignore the -Wall
warnings: warnings:
:: .. code-block:: c
#pragma GCC diagnostic ignored "-Wall" #pragma GCC diagnostic ignored "-Wall"
In addition to all of the functionality provided by GCC's pragma, Clang 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 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 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. 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 In the below example :option:`-Wmultichar` is ignored for only a single line of
code, after which the diagnostics return to whatever state had code, after which the diagnostics return to whatever state had previously
previously existed. existed.
:: .. code-block:: c
#pragma clang diagnostic push #pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wmultichar" #pragma clang diagnostic ignored "-Wmultichar"
char b = 'df'; // no warning. char b = 'df'; // no warning.
#pragma clang diagnostic pop #pragma clang diagnostic pop
The push and pop pragmas will save and restore the full diagnostic state 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 of the compiler, regardless of how it was set. That means that it is
...@@ -633,15 +665,15 @@ The ``system_header`` pragma can be used to mark the current file as ...@@ -633,15 +665,15 @@ 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 being a system header. No warnings will be produced from the location of
the pragma onwards within the same file. the pragma onwards within the same file.
:: .. code-block:: c
char a = 'xy'; // warning char a = 'xy'; // warning
#pragma clang system_header #pragma clang system_header
char b = 'ab'; // no warning char b = 'ab'; // no warning
The ``-isystem-prefix`` and ``-ino-system-prefix`` command-line The :option:`-isystem-prefix` and :option:`-ino-system-prefix` command-line
arguments can be used to override whether subsets of an include path are 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 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 found within a header search path and starts with a system prefix, the
...@@ -649,9 +681,9 @@ header is treated as a system header. The last prefix on the ...@@ -649,9 +681,9 @@ header is treated as a system header. The last prefix on the
command-line which matches the specified header name takes precedence. command-line which matches the specified header name takes precedence.
For instance: For instance:
:: .. code-block:: console
clang -Ifoo -isystem bar -isystem-prefix x/ -ino-system-prefix x/y/ $ 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 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 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
...@@ -668,10 +700,10 @@ Enabling All Warnings ...@@ -668,10 +700,10 @@ Enabling All Warnings
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
In addition to the traditional ``-W`` flags, one can enable **all** In addition to the traditional ``-W`` flags, one can enable **all**
warnings by passing ``-Weverything``. This works as expected with warnings by passing :option:`-Weverything`. This works as expected with
``-Werror``, and also includes the warnings from ``-pedantic``. :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
Note that when combined with ``-w`` (which disables all warnings), that Note that when combined with :option:`-w` (which disables all warnings), that
flag wins. flag wins.
Controlling Static Analyzer Diagnostics Controlling Static Analyzer Diagnostics
...@@ -708,23 +740,23 @@ Generating a PCH File ...@@ -708,23 +740,23 @@ Generating a PCH File
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
To generate a PCH file using Clang, one invokes Clang with the To generate a PCH file using Clang, one invokes Clang with the
**``-x <language>-header``** option. This mirrors the interface in GCC :option:`-x <language>-header` option. This mirrors the interface in GCC
for generating PCH files: for generating PCH files:
:: .. code-block:: console
$ gcc -x c-header test.h -o test.h.gch $ gcc -x c-header test.h -o test.h.gch
$ clang -x c-header test.h -o test.h.pch $ clang -x c-header test.h -o test.h.pch
Using a PCH File Using a PCH File
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
A PCH file can then be used as a prefix header when a **``-include``** A PCH file can then be used as a prefix header when a :option:`-include`
option is passed to ``clang``: option is passed to ``clang``:
:: .. code-block:: console
$ clang -include test.h test.c -o test $ clang -include test.h test.c -o test
The ``clang`` driver will first check if a PCH file for ``test.h`` is 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) available; if so, the contents of ``test.h`` (and the files it includes)
...@@ -733,19 +765,20 @@ directly processing the content of ``test.h``. This mirrors the behavior ...@@ -733,19 +765,20 @@ directly processing the content of ``test.h``. This mirrors the behavior
of GCC. of GCC.
.. note:: .. note::
Clang does *not* automatically use PCH files for headers that are
directly included within a source file. For example:
:: Clang does *not* automatically use PCH files for headers that are directly
included within a source file. For example:
.. code-block:: console
$ clang -x c-header test.h -o test.h.pch $ clang -x c-header test.h -o test.h.pch
$ cat test.c $ cat test.c
#include "test.h" #include "test.h"
$ clang test.c -o test $ clang test.c -o test
In this example, ``clang`` will not automatically use the PCH file for 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 ``test.h`` since ``test.h`` was included directly in the source file and not
not specified on the command line using ``-include``. specified on the command line using :option:`-include`.
Relocatable PCH Files Relocatable PCH Files
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
...@@ -770,19 +803,19 @@ location. ...@@ -770,19 +803,19 @@ location.
Building a relocatable precompiled header requires two additional Building a relocatable precompiled header requires two additional
arguments. First, pass the ``--relocatable-pch`` flag to indicate that arguments. First, pass the ``--relocatable-pch`` flag to indicate that
the resulting PCH file should be relocatable. Second, pass the resulting PCH file should be relocatable. Second, pass
``-isysroot /path/to/build``, which makes all includes for your library :option:`-isysroot /path/to/build`, which makes all includes for your library
relative to the build directory. For example: relative to the build directory. For example:
:: .. code-block:: console
# clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch # 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 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`` 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 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 in some other system root, the :option:`-isysroot` option can be used provide
a different system root from which the headers will be based. For a different system root from which the headers will be based. For
example, ``-isysroot /Developer/SDKs/MacOSX10.4u.sdk`` will look for example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``. ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
Relocatable precompiled headers are intended to be used in a limited Relocatable precompiled headers are intended to be used in a limited
...@@ -896,17 +929,22 @@ are listed below. ...@@ -896,17 +929,22 @@ are listed below.
**-f[no-]thread-sanitizer** **-f[no-]thread-sanitizer**
Deprecated synonym for :ref:`-f[no-]sanitize=thread Deprecated synonym for :ref:`-f[no-]sanitize=thread
<opt_fsanitize_thread>`. <opt_fsanitize_thread>`.
**-fcatch-undefined-behavior**
.. option:: -fcatch-undefined-behavior
Deprecated synonym for :ref:`-fsanitize=undefined Deprecated synonym for :ref:`-fsanitize=undefined
<opt_fsanitize_undefined>`. <opt_fsanitize_undefined>`.
**-fno-assume-sane-operator-new**
.. option:: -fno-assume-sane-operator-new
Don't assume that the C++'s new operator is sane. Don't assume that the C++'s new operator is sane.
This option tells the compiler to do not assume that C++'s global 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 new operator will always return a pointer that does not alias any
other pointer when the function returns. other pointer when the function returns.
**-ftrap-function=[name]** .. option:: -ftrap-function=[name]
Instruct code generator to emit a function call to the specified Instruct code generator to emit a function call to the specified
function name for ``__builtin_trap()``. function name for ``__builtin_trap()``.
...@@ -919,7 +957,8 @@ are listed below. ...@@ -919,7 +957,8 @@ are listed below.
deeply embedded) where a trap cannot be properly handled, or when deeply embedded) where a trap cannot be properly handled, or when
some custom behavior is desired. some custom behavior is desired.
**-ftls-model=[model]** .. option:: -ftls-model=[model]
Select which TLS model to use. Select which TLS model to use.
Valid values are: ``global-dynamic``, ``local-dynamic``, Valid values are: ``global-dynamic``, ``local-dynamic``,
...@@ -935,16 +974,22 @@ Controlling Size of Debug Information ...@@ -935,16 +974,22 @@ Controlling Size of Debug Information
Debug info kind generated by Clang can be set by one of the flags listed 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. below. If multiple flags are present, the last one is used.
**-g0**: Don't generate any debug info (default). .. option:: -g0
Don't generate any debug info (default).
.. option:: -gline-tables-only
Generate line number tables only.
**-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).
This kind of debug info allows to obtain stack traces with function .. option:: -g
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. Generate complete debug info.
.. _c: .. _c:
...@@ -957,7 +1002,7 @@ C99 floating-point pragmas. ...@@ -957,7 +1002,7 @@ C99 floating-point pragmas.
Extensions supported by clang Extensions supported by clang
----------------------------- -----------------------------
See `clang language extensions <LanguageExtensions.html>`_. See :doc:`LanguageExtensions`.
Differences between various standard modes Differences between various standard modes
------------------------------------------ ------------------------------------------
...@@ -1025,13 +1070,13 @@ extensions are not implemented yet: ...@@ -1025,13 +1070,13 @@ extensions are not implemented yet:
anytime soon. In C++11 it can be emulated by assigning lambda anytime soon. In C++11 it can be emulated by assigning lambda
functions to local variables, e.g: functions to local variables, e.g:
:: .. code-block:: cpp
auto const local_function = [&](int parameter) { auto const local_function = [&](int parameter) {
// Do something // Do something
}; };
... ...
local_function(1); local_function(1);
- clang does not support global register variables; this is unlikely to - clang does not support global register variables; this is unlikely to
be implemented soon because it requires additional LLVM backend be implemented soon because it requires additional LLVM backend
...@@ -1119,11 +1164,15 @@ features <http://clang.llvm.org/cxx_status.html>`_ are also implemented. ...@@ -1119,11 +1164,15 @@ features <http://clang.llvm.org/cxx_status.html>`_ are also implemented.
Controlling implementation limits Controlling implementation limits
--------------------------------- ---------------------------------
**-fconstexpr-depth=N**: Sets the limit for recursive constexpr function .. option:: -fconstexpr-depth=N
invocations to N. The default is 512.
Sets the limit for recursive constexpr function invocations to N. The
default is 512.
.. option:: -ftemplate-depth=N
**-ftemplate-depth=N**: Sets the limit for recursively nested template Sets the limit for recursively nested template instantiations to N. The
instantiations to N. The default is 1024. default is 1024.
.. _objc: .. _objc:
...@@ -1178,10 +1227,10 @@ experimental. ...@@ -1178,10 +1227,10 @@ experimental.
Other platforms are completely unsupported at the moment. Adding the Other platforms are completely unsupported at the moment. Adding the
minimal support needed for parsing and semantic analysis on a new minimal support needed for parsing and semantic analysis on a new
platform is quite easy; see lib/Basic/Targets.cpp in the clang source 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 tree. This level of support is also sufficient for conversion to LLVM IR
for simple programs. Proper support for conversion to LLVM IR requires 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 adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
change soon, though. Generating assembly requires a suitable LLVM change soon, though. Generating assembly requires a suitable LLVM
backend. backend.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment