diff --git a/clang/docs/OpenCLSupport.rst b/clang/docs/OpenCLSupport.rst --- a/clang/docs/OpenCLSupport.rst +++ b/clang/docs/OpenCLSupport.rst @@ -34,7 +34,7 @@ list `__. -- Command-line flag :ref:`-cl-ext ` (used to override extensions/ +- Command-line flag :option:`-cl-ext` (used to override extensions/ features supported by a target) is missing support of some functionality i.e. that is implemented fully through libraries (see :ref:`library-based features and extensions `). @@ -235,7 +235,7 @@ extensions. For all other targets the configuration has to be made explicitly. Note that the target extension support performed by clang can be overridden -with :ref:`-cl-ext ` command-line flags. +with :option:`-cl-ext` command-line flags. .. _opencl_ext_libs: @@ -345,7 +345,7 @@ OpenCL C 3.0 language standard makes most OpenCL C 2.0 features optional. Optional functionality in OpenCL C 3.0 is indicated with the presence of feature-test macros (list of feature-test macros is `here `__). -Command-line flag :ref:`-cl-ext ` can be used to override features supported by a target. +Command-line flag :option:`-cl-ext` can be used to override features supported by a target. For cases when there is an associated extension for a specific feature (fp64 and 3d image writes) user should specify both (extension and feature) in command-line flag: diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst --- a/clang/docs/UsersManual.rst +++ b/clang/docs/UsersManual.rst @@ -165,7 +165,8 @@ .. _opt_fshow-column: -**-f[no-]show-column** +.. option:: -f[no-]show-column + Print column number in diagnostic. This option, which defaults to on, controls whether or not Clang @@ -187,7 +188,8 @@ .. _opt_fshow-source-location: -**-f[no-]show-source-location** +.. option:: -f[no-]show-source-location + Print source file/line/column information in diagnostic. This option, which defaults to on, controls whether or not Clang @@ -206,7 +208,8 @@ .. _opt_fcaret-diagnostics: -**-f[no-]caret-diagnostics** +.. option:: -f[no-]caret-diagnostics + Print source line and ranges from source code in diagnostic. This option, which defaults to on, controls whether or not Clang prints the source line, source ranges, and caret when emitting a @@ -220,7 +223,8 @@ ^ // -**-f[no-]color-diagnostics** +.. option:: -f[no-]color-diagnostics + This option, which defaults to on when a color-capable terminal is detected, controls whether or not Clang prints diagnostics in color. @@ -247,7 +251,8 @@ ^ // -**-fansi-escape-codes** +.. option:: -fansi-escape-codes + Controls whether ANSI escape codes are used instead of the Windows Console API to output colored diagnostics. This option is only used on Windows and defaults to off. @@ -277,7 +282,8 @@ .. _opt_fdiagnostics-show-option: -**-f[no-]diagnostics-show-option** +.. option:: -f[no-]diagnostics-show-option + Enable ``[-Woption]`` information in diagnostic line. This option, which defaults to on, controls whether or not Clang @@ -293,13 +299,11 @@ // Passing **-fno-diagnostics-show-option** will prevent Clang from - printing the [:ref:`-Wextra-tokens `] information in + printing the [:option:`-Wextra-tokens`] information in the diagnostic. This information tells you the flag needed to enable or disable the diagnostic, either from the command line or through :ref:`#pragma GCC diagnostic `. -.. _opt_fdiagnostics-show-category: - .. option:: -fdiagnostics-show-category=none/id/name Enable printing category information in diagnostic line. @@ -347,7 +351,7 @@ ``-fsave-optimization-record=bitstream``: A binary format based on LLVM Bitstream. - The output file is controlled by :ref:`-foptimization-record-file `. + The output file is controlled by :option:`-foptimization-record-file`. In the absence of an explicit output file, the file is chosen using the following scheme: @@ -395,20 +399,18 @@ ``-.opt.`` Note that this is incompatible with passing the - :ref:`-foptimization-record-file ` option. + :option:`-foptimization-record-file` option. -.. _opt_foptimization-record-file: +.. option:: -foptimization-record-file -**-foptimization-record-file** Control the file to which optimization reports are written. This implies :ref:`-fsave-optimization-record `. On Darwin platforms, this is incompatible with passing multiple ``-arch `` options. -.. _opt_foptimization-record-passes: +.. option:: -foptimization-record-passes -**-foptimization-record-passes** Only include passes which match a specified regular expression. When optimization reports are being output (see @@ -420,7 +422,8 @@ .. _opt_fdiagnostics-show-hotness: -**-f[no-]diagnostics-show-hotness** +.. option:: -f[no-]diagnostics-show-hotness + Enable profile hotness information in diagnostic line. This option controls whether Clang prints the profile hotness associated @@ -443,9 +446,8 @@ :ref:`-fsave-optimization-record ` is used. Otherwise, it defaults to off. -.. _opt_fdiagnostics-hotness-threshold: +.. option:: -fdiagnostics-hotness-threshold -**-fdiagnostics-hotness-threshold** Prevent optimization remarks from being output if they do not have at least this hotness value. @@ -458,7 +460,8 @@ .. _opt_fdiagnostics-fixit-info: -**-f[no-]diagnostics-fixit-info** +.. option:: -f[no-]diagnostics-fixit-info + Enable "FixIt" information in the diagnostics output. This option, which defaults to on, controls whether or not Clang @@ -479,7 +482,8 @@ .. _opt_fdiagnostics-print-source-range-info: -**-fdiagnostics-print-source-range-info** +.. option:: -fdiagnostics-print-source-range-info + Print machine parsable information about source ranges. This option makes Clang print information about source ranges in a machine parsable format after the file/line/column number information. The @@ -577,8 +581,6 @@ TODO: Generate this from tblgen. Define one anchor per warning group. -.. _opt_wextra-tokens: - .. option:: -Wextra-tokens Warn about excess tokens at the end of a preprocessor directive. @@ -1036,7 +1038,7 @@ #. A :ref:`high-level category ` for the diagnostic for clients that want to group diagnostics by class (for diagnostics that support it) - [:ref:`-fdiagnostics-show-category `]. + [:option:`-fdiagnostics-show-category`]. #. The line of source code that the issue occurs on, along with a caret and ranges that indicate the important locations [:ref:`-fcaret-diagnostics `]. @@ -1073,7 +1075,7 @@ grouped way. Categories are not shown by default, but they can be turned on with the -:ref:`-fdiagnostics-show-category ` option. +:option:`-fdiagnostics-show-category` option. When set to "``name``", the category is printed textually in the diagnostic output. When it is set to "``id``", a category number is printed. The mapping of category names to category id's can be obtained @@ -1516,9 +1518,7 @@ Defaults to ``ieee``. -.. _opt_fstrict-float-cast-overflow: - -**-f[no-]strict-float-cast-overflow** +.. option:: -f[no-]strict-float-cast-overflow When a floating-point value is not representable in a destination integer type, the code has undefined behavior according to the language standard. @@ -1526,9 +1526,7 @@ With the 'no-strict' option, Clang will saturate towards the smallest and largest representable integer values instead. NaNs will be converted to zero. -.. _opt_fmath-errno: - -**-f[no-]math-errno** +.. option:: -f[no-]math-errno Require math functions to indicate errors by setting errno. The default varies by ToolChain. ``-fno-math-errno`` allows optimizations @@ -1544,9 +1542,7 @@ ``-fno-math-errno`` is the default. This includes most BSD-derived systems, including Darwin. -.. _opt_ftrapping-math: - -**-f[no-]trapping-math** +.. option:: -f[no-]trapping-math Control floating point exception behavior. ``-fno-trapping-math`` allows optimizations that assume that floating point operations cannot generate traps such as divide-by-zero, overflow and underflow. @@ -1574,23 +1570,17 @@ * ``off`` (never fuse) * ``fast-honor-pragmas`` (fuse across statements unless dictated by pragmas, default for HIP) -.. _opt_fhonor-infinities: - -**-f[no-]honor-infinities** +.. option:: -f[no-]honor-infinities If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used, has the same effect as specifying ``-ffinite-math-only``. -.. _opt_fhonor-nans: - -**-f[no-]honor-nans** +.. option:: -f[no-]honor-nans If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used, has the same effect as specifying ``-ffinite-math-only``. -.. _opt_fapprox-func: - -**-f[no-]approx-func** +.. option:: -f[no-]approx-func Allow certain math function calls (such as ``log``, ``sqrt``, ``pow``, etc) to be replaced with an approximately equivalent set of instructions @@ -1599,32 +1589,24 @@ in cases where ``x`` is ``-0.0`` or ``-inf``. Defaults to ``-fno-approx-func``. -.. _opt_fsigned-zeros: - -**-f[no-]signed-zeros** +.. option:: -f[no-]signed-zeros Allow optimizations that ignore the sign of floating point zeros. Defaults to ``-fno-signed-zeros``. -.. _opt_fassociative-math: - -**-f[no-]associative-math** +.. option:: -f[no-]associative-math Allow floating point operations to be reassociated. Defaults to ``-fno-associative-math``. -.. _opt_freciprocal-math: - -**-f[no-]reciprocal-math** +.. option:: -f[no-]reciprocal-math Allow division operations to be transformed into multiplication by a reciprocal. This can be significantly faster than an ordinary division but can also have significantly less precision. Defaults to ``-fno-reciprocal-math``. -.. _opt_funsafe-math-optimizations: - -**-f[no-]unsafe-math-optimizations** +.. option:: -f[no-]unsafe-math-optimizations Allow unsafe floating-point optimizations. Also implies: @@ -1635,9 +1617,7 @@ Defaults to ``-fno-unsafe-math-optimizations``. -.. _opt_ffinite-math-only: - -**-f[no-]finite-math-only** +.. option:: -f[no-]finite-math-only Allow floating-point optimizations that assume arguments and results are not NaNs or +-Inf. This defines the ``__FINITE_MATH_ONLY__`` preprocessor macro. @@ -1648,9 +1628,7 @@ Defaults to ``-fno-finite-math-only``. -.. _opt_frounding-math: - -**-f[no-]rounding-math** +.. option:: -f[no-]rounding-math Force floating-point operations to honor the dynamically-set rounding mode by default. @@ -1799,7 +1777,8 @@ Clang provides a number of ways to control code generation. The options are listed below. -**-f[no-]sanitize=check1,check2,...** +.. option:: -f[no-]sanitize=check1,check2,... + Turn on runtime checks for various forms of undefined or suspicious behavior. @@ -1847,9 +1826,9 @@ ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same program. -**-f[no-]sanitize-recover=check1,check2,...** +.. option:: -f[no-]sanitize-recover=check1,check2,... -**-f[no-]sanitize-recover[=all]** +.. option:: -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 @@ -1873,9 +1852,9 @@ will have no effect on its own; it will need to be accompanied by ``-fno-sanitize-trap=alignment``. -**-f[no-]sanitize-trap=check1,check2,...** +.. option:: -f[no-]sanitize-trap=check1,check2,... -**-f[no-]sanitize-trap[=all]** +.. option:: -f[no-]sanitize-trap[=all] Controls which checks enabled by the ``-fsanitize=`` flag trap. This option is intended for use in cases where the sanitizer runtime cannot @@ -1898,12 +1877,12 @@ Don't use ignorelist file, if it was specified earlier in the command line. -**-f[no-]sanitize-coverage=[type,features,...]** +.. option:: -f[no-]sanitize-coverage=[type,features,...] Enable simple code coverage in addition to certain sanitizers. See :doc:`SanitizerCoverage` for more details. -**-f[no-]sanitize-address-outline-instrumentation** +.. option:: -f[no-]sanitize-address-outline-instrumentation Controls how address sanitizer code is generated. If enabled will always use a function call instead of inlining the code. Turning this option on could @@ -1911,7 +1890,7 @@ See :doc: `AddressSanitizer` for more details. -**-f[no-]sanitize-stats** +.. option:: -f[no-]sanitize-stats Enable simple statistics gathering for the enabled sanitizers. See :doc:`SanitizerStats` for more details. @@ -2027,7 +2006,8 @@ compact branches and ``always`` generates compact branches whenever possible. -**-f[no-]max-type-align=[number]** +.. option:: -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. This cap is ignored when directly accessing a variable or when the pointee @@ -2068,7 +2048,7 @@ on ELF targets when using the integrated assembler. This flag currently only has an effect on ELF targets. -**-f[no]-unique-internal-linkage-names** +.. option:: -f[no]-unique-internal-linkage-names Controls whether Clang emits a unique (best-effort) symbol name for internal linkage symbols. When this option is set, compiler hashes the main source @@ -2089,7 +2069,7 @@ $ cd $P/bar && clang -c -funique-internal-linkage-names name_conflict.c $ cd $P && clang foo/name_conflict.o && bar/name_conflict.o -**-fbasic-block-sections=[labels, all, list=, none]** +.. option:: -fbasic-block-sections=[labels, all, list=, none] Controls how Clang emits text sections for basic blocks. With values ``all`` and ``list=``, each basic block or a subset of basic blocks can be placed @@ -3295,8 +3275,6 @@ Some extra options are available to support special OpenCL features. -.. _opencl_cl_no_stdinc: - .. option:: -cl-no-stdinc Allows to disable all extra types and functions that are not native to the compiler. @@ -3416,7 +3394,7 @@ By default Clang will include standard headers and therefore most of OpenCL builtin functions and types are available during compilation. The default declarations of non-native compiler types and functions can be disabled -by using flag :ref:`-cl-no-stdinc `. +by using flag :option:`-cl-no-stdinc`. The following example demonstrates that OpenCL kernel sources with various standard builtin functions can be compiled without the need for an explicit