diff options
Diffstat (limited to 'docs/UsersManual.rst')
| -rw-r--r-- | docs/UsersManual.rst | 162 |
1 files changed, 94 insertions, 68 deletions
diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst index 18211e27f5d6..8e591518d54d 100644 --- a/docs/UsersManual.rst +++ b/docs/UsersManual.rst @@ -133,13 +133,13 @@ Options to Control Error and Warning Messages .. 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`. + 20, and the error limit can be disabled with `-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`. + the limit can be disabled with `-ftemplate-backtrace-limit=0`. .. _cl_diag_formatting: @@ -543,15 +543,15 @@ vectorize a loop body. Clang offers a family of flags which the optimizers can use to emit a diagnostic in three cases: -1. When the pass makes a transformation (:option:`-Rpass`). +1. When the pass makes a transformation (`-Rpass`). -2. When the pass fails to make a transformation (:option:`-Rpass-missed`). +2. When the pass fails to make a transformation (`-Rpass-missed`). 3. When the pass determines whether or not to make a transformation - (:option:`-Rpass-analysis`). + (`-Rpass-analysis`). -NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact -same options apply to :option:`-Rpass-missed` and :option:`-Rpass-analysis`. +NOTE: Although the discussion below focuses on `-Rpass`, the exact +same options apply to `-Rpass-missed` and `-Rpass-analysis`. Since there are dozens of passes inside the compiler, each of these flags take a regular expression that identifies the name of the pass which should @@ -567,7 +567,7 @@ compile the code with: Note that remarks from the inliner are identified with `[-Rpass=inline]`. To request a report from every optimization pass, you should use -:option:`-Rpass=.*` (in fact, you can use any valid POSIX regular +`-Rpass=.*` (in fact, you can use any valid POSIX regular expression). However, do not expect a report from every transformation made by the compiler. Optimization remarks do not really make sense outside of the major transformations (e.g., inlining, vectorization, @@ -585,7 +585,7 @@ Current limitations 2. Some source locations are not displayed correctly. The front end has a more detailed source location tracking than the locations included in the debug info (e.g., the front end can locate code inside macro - expansions). However, the locations used by :option:`-Rpass` are + expansions). However, the locations used by `-Rpass` are translated from debug annotations. That translation can be lossy, which results in some remarks having no location information. @@ -711,16 +711,19 @@ also allows you to push and pop the current warning state. This is particularly useful when writing a header file that will be compiled by other people, because you don't know what warning flags they build with. -In the below example :option:`-Wmultichar` is ignored for only a single line of -code, after which the diagnostics return to whatever state had previously +In the below example :option:`-Wextra-tokens` is ignored for only a single line +of code, after which the diagnostics return to whatever state had previously existed. .. code-block:: c - #pragma clang diagnostic push - #pragma clang diagnostic ignored "-Wmultichar" + #if foo + #endif foo // warning: extra tokens at end of #endif directive - char b = 'df'; // no warning. + #pragma clang diagnostic ignored "-Wextra-tokens" + + #if foo + #endif foo // no warning #pragma clang diagnostic pop @@ -772,13 +775,15 @@ the pragma onwards within the same file. .. code-block:: c - char a = 'xy'; // warning + #if foo + #endif foo // warning: extra tokens at end of #endif directive #pragma clang system_header - char b = 'ab'; // no warning + #if foo + #endif foo // no warning -The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=` +The `--system-header-prefix=` and `--no-system-header-prefix=` command-line arguments can be used to override whether subsets of an include path are treated as system headers. When the name in a ``#include`` directive is found within a header search path and starts with a system prefix, the @@ -847,7 +852,7 @@ Generating a PCH File ^^^^^^^^^^^^^^^^^^^^^ To generate a PCH file using Clang, one invokes Clang with the -:option:`-x <language>-header` option. This mirrors the interface in GCC +`-x <language>-header` option. This mirrors the interface in GCC for generating PCH files: .. code-block:: console @@ -910,7 +915,7 @@ location. Building a relocatable precompiled header requires two additional arguments. First, pass the ``--relocatable-pch`` flag to indicate that the resulting PCH file should be relocatable. Second, pass -:option:`-isysroot /path/to/build`, which makes all includes for your library +`-isysroot /path/to/build`, which makes all includes for your library relative to the build directory. For example: .. code-block:: console @@ -920,9 +925,9 @@ relative to the build directory. For example: When loading the relocatable PCH file, the various headers used in the PCH file are found from the system header root. For example, ``mylib.h`` can be found in ``/usr/include/mylib.h``. If the headers are installed -in some other system root, the :option:`-isysroot` option can be used provide +in some other system root, the `-isysroot` option can be used provide a different system root from which the headers will be based. For -example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for +example, `-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``. Relocatable precompiled headers are intended to be used in a limited @@ -986,6 +991,8 @@ are listed below. **-f[no-]sanitize-recover=check1,check2,...** +**-f[no-]sanitize-recover=all** + Controls which checks enabled by ``-fsanitize=`` flag are non-fatal. If the check is fatal, program will halt after the first error of this kind is detected and error report is printed. @@ -1038,6 +1045,11 @@ are listed below. Enable simple code coverage in addition to certain sanitizers. See :doc:`SanitizerCoverage` for more details. +**-f[no-]sanitize-stats** + + Enable simple statistics gathering for the enabled sanitizers. + See :doc:`SanitizerStats` for more details. + .. option:: -fsanitize-undefined-trap-on-error Deprecated alias for ``-fsanitize-trap=undefined``. @@ -1048,6 +1060,25 @@ are listed below. the behavior of sanitizers in the ``cfi`` group to allow checking of cross-DSO virtual and indirect calls. +.. option:: -ffast-math + + Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor + macro, and lets the compiler make aggressive, potentially-lossy assumptions + about floating-point math. These include: + + * Floating-point math obeys regular algebraic rules for real numbers (e.g. + ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and + ``(a + b) * c == a * c + b * c``), + * operands to floating-point operations are not equal to ``NaN`` and + ``Inf``, and + * ``+0`` and ``-0`` are interchangeable. + +.. option:: -fwhole-program-vtables + + Enable whole-program vtable optimizations, such as single-implementation + devirtualization and virtual constant propagation, for classes with + :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``. + .. option:: -fno-assume-sane-operator-new Don't assume that the C++'s new operator is sane. @@ -1114,6 +1145,16 @@ are listed below. This option restricts the generated code to use general registers only. This only applies to the AArch64 architecture. +.. option:: -mcompact-branches=[values] + + Control the usage of compact branches for MIPSR6. + + Valid values are: ``never``, ``optimal`` and ``always``. + The default value is ``optimal`` which generates compact branches + when a delay slot cannot be filled. ``never`` disables the usage of + compact branches and ``always`` generates compact branches whenever + possible. + **-f[no-]max-type-align=[number]** Instruct the code generator to not enforce a higher alignment than the given number (of bytes) when accessing memory via an opaque pointer or reference. @@ -1461,19 +1502,21 @@ instrumentation: profile. As you make changes to your code, clang may no longer be able to use the profile data. It will warn you when this happens. -Profile generation and use can also be controlled by the GCC-compatible flags -``-fprofile-generate`` and ``-fprofile-use``. Although these flags are -semantically equivalent to their GCC counterparts, they *do not* handle -GCC-compatible profiles. They are only meant to implement GCC's semantics -with respect to profile creation and use. +Profile generation using an alternative instrumentation method can be +controlled by the GCC-compatible flags ``-fprofile-generate`` and +``-fprofile-use``. Although these flags are semantically equivalent to +their GCC counterparts, they *do not* handle GCC-compatible profiles. +They are only meant to implement GCC's semantics with respect to +profile creation and use. .. option:: -fprofile-generate[=<dirname>] - Without any other arguments, ``-fprofile-generate`` behaves identically to - ``-fprofile-instr-generate``. When given a directory name, it generates the - profile file ``default.profraw`` in the directory named ``dirname``. If - ``dirname`` does not exist, it will be created at runtime. The environment - variable ``LLVM_PROFILE_FILE`` can be used to override the directory and + The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use + an alterantive instrumentation method for profile generation. When + given a directory name, it generates the profile file + ``default.profraw`` in the directory named ``dirname``. If ``dirname`` + does not exist, it will be created at runtime. The environment variable + ``LLVM_PROFILE_FILE`` can be used to override the directory and filename for the profile file at runtime. For example, .. code-block:: console @@ -1689,10 +1732,6 @@ GCC extensions not implemented yet clang tries to be compatible with gcc as much as possible, but some gcc extensions are not implemented yet: -- clang does not support #pragma weak (`bug - 3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses - described in the bug, this is likely to be implemented at some point, - at least partially. - clang does not support decimal floating point types (``_Decimal32`` and friends) or fixed-point types (``_Fract`` and friends); nobody has expressed interest in these features yet, so it's hard to say when @@ -1710,9 +1749,6 @@ extensions are not implemented yet: ... local_function(1); -- clang does not support global register variables; this is unlikely to - be implemented soon because it requires additional LLVM backend - support. - clang does not support static initialization of flexible array members. This appears to be a rarely used extension, but could be implemented pending user demand. @@ -1757,13 +1793,11 @@ Intentionally unsupported GCC extensions Microsoft extensions -------------------- -clang has some experimental support for extensions from Microsoft Visual -C++; to enable it, use the ``-fms-extensions`` command-line option. This is -the default for Windows targets. Note that the support is incomplete. -Some constructs such as ``dllexport`` on classes are ignored with a warning, -and others such as `Microsoft IDL annotations -<http://msdn.microsoft.com/en-us/library/8tesw2eh.aspx>`_ are silently -ignored. +clang has support for many extensions from Microsoft Visual C++. To enable these +extensions, use the ``-fms-extensions`` command-line option. This is the default +for Windows targets. Clang does not implement every pragma or declspec provided +by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma +comment(lib)`` are well supported. clang has a ``-fms-compatibility`` flag that makes clang accept enough invalid C++ to be able to parse most Microsoft headers. For example, it @@ -1776,23 +1810,14 @@ for Windows targets. definitions until the end of a translation unit. This flag is enabled by default for Windows targets. -- clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to - 1700 which is the same as Visual C/C++ 2012. Any number is supported - and can greatly affect what Windows SDK and c++stdlib headers clang - can compile. -- clang does not support the Microsoft extension where anonymous record - members can be declared using user defined typedefs. -- clang supports the Microsoft ``#pragma pack`` feature for controlling - record layout. GCC also contains support for this feature, however - where MSVC and GCC are incompatible clang follows the MSVC - definition. -- clang supports the Microsoft ``#pragma comment(lib, "foo.lib")`` feature for - automatically linking against the specified library. Currently this feature - only works with the Visual C++ linker. -- clang supports the Microsoft ``#pragma comment(linker, "/flag:foo")`` feature - for adding linker flags to COFF object files. The user is responsible for - ensuring that the linker understands the flags. -- clang defaults to C++11 for Windows targets. +For compatibility with existing code that compiles with MSVC, clang defines the +``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800 +and 180000000 respectively, making clang look like an early release of Visual +C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values. It +accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC +compatibility version makes clang behave more like that version of MSVC. For +example, ``-fms-compatibility-version=19`` will enable C++14 features and define +``char16_t`` and ``char32_t`` as builtin types. .. _cxx: @@ -1849,8 +1874,8 @@ directives, ``depend`` clause for ``#pragma omp task`` directive (except for array sections), ``#pragma omp cancel`` and ``#pragma omp cancellation point`` directives, and ``#pragma omp taskgroup`` directive. -Use :option:`-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with -:option:`-fno-openmp`. +Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with +`-fno-openmp`. Controlling implementation limits --------------------------------- @@ -1859,7 +1884,7 @@ Controlling implementation limits Controls code generation for OpenMP threadprivate variables. In presence of this option all threadprivate variables are generated the same way as thread - local variables, using TLS support. If :option:`-fno-openmp-use-tls` + local variables, using TLS support. If `-fno-openmp-use-tls` is provided or target does not support TLS, code generation for threadprivate variables relies on OpenMP runtime library. @@ -1883,7 +1908,7 @@ On ``x86_64-mingw32``, passing i128(by value) is incompatible with the Microsoft x64 calling convention. You might need to tweak ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp. -For the X86 target, clang supports the :option:`-m16` command line +For the X86 target, clang supports the `-m16` command line argument which enables 16-bit code output. This is broadly similar to using ``asm(".code16gcc")`` with the GNU toolchain. The generated code and the ABI remains 32-bit but the assembler emits instructions @@ -2019,8 +2044,9 @@ with a warning. For example: To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option. -Options that are not known to clang-cl will cause errors. If they are spelled with a -leading ``/``, they will be mistaken for a filename: +Options that are not known to clang-cl will be ignored by default. Use the +``-Werror=unknown-argument`` option in order to treat them as errors. If these +options are spelled with a leading ``/``, they will be mistaken for a filename: :: |