[cfe-commits] r170590 - /cfe/trunk/docs/UsersManual.rst
Sean Silva
silvas at purdue.edu
Wed Dec 19 17:50:21 PST 2012
+1 for using `.. option::` here.
+.. This is in plain monospaced font because it generates the same label as
+.. -Werror, and Sphinx complains.
-**-Wfoo**: Enable warning "foo".
+``-Werror=foo``
You may want to unify this entry with `-Werror` by doing something like:
.. option:: -Werror[=foo]
Turn warnings into errors. If ``=foo`` is provided, then only turn
warning ``foo`` into an error.
-- Sean Silva
On Wed, Dec 19, 2012 at 3:06 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
> Author: gribozavr
> Date: Wed Dec 19 16:06:59 2012
> New Revision: 170590
>
> URL: http://llvm.org/viewvc/llvm-project?rev=170590&view=rev
> Log:
> Documentation: UsersManual.rst: some cleanups after semi-automatic conversion
>
> Modified:
> cfe/trunk/docs/UsersManual.rst
>
> Modified: cfe/trunk/docs/UsersManual.rst
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=170590&r1=170589&r2=170590&view=diff
> ==============================================================================
> --- cfe/trunk/docs/UsersManual.rst (original)
> +++ cfe/trunk/docs/UsersManual.rst Wed Dec 19 16:06:59 2012
> @@ -80,41 +80,64 @@
> 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
> 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
> ---------------------------------------------
>
> -**-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
> -is specified.
> +.. This is in plain monospaced font because it generates the same label as
> +.. -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**
> -warnings. <diagnostics_enable_everything>`
> + Turn warning "foo" into an warning even if :option:`-Werror` is specified.
>
> -**-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
> -been produced. The default is 20, and the error limit can be disabled
> -with -ferror-limit=0.
> + Disable warning "foo".
>
> -**-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 -ftemplate-backtrace-limit=0.
> +.. option:: -w
> +
> + Disable all warnings.
> +
> +.. 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:
>
> @@ -212,7 +235,8 @@
> ^
> //
>
> -**-fdiagnostics-format=clang/msvc/vi**
> +.. option:: -fdiagnostics-format=clang/msvc/vi
> +
> Changes diagnostic output format to better match IDEs and command line tools.
>
> This option controls the output format of the filename, line number,
> @@ -264,7 +288,8 @@
>
> .. _opt_fdiagnostics-show-category:
>
> -**-fdiagnostics-show-category=none/id/name**
> +.. option:: -fdiagnostics-show-category=none/id/name
> +
> Enable printing category information in diagnostic line.
>
> This option, which defaults to "none", controls whether or not Clang
> @@ -328,7 +353,8 @@
> The printed column numbers count bytes from the beginning of the
> line; take care if your source contains multibyte characters.
>
> -**-fdiagnostics-parseable-fixits**
> +.. option:: -fdiagnostics-parseable-fixits
> +
> Print Fix-Its in a machine parseable form.
>
> This option makes Clang print available Fix-Its in a machine
> @@ -351,7 +377,8 @@
> The printed column numbers count bytes from the beginning of the
> line; take care if your source contains multibyte characters.
>
> -**-fno-elide-type**
> +.. option:: -fno-elide-type
> +
> Turns off elision in template type printing.
>
> The default for template type printing is to elide as many template
> @@ -372,7 +399,8 @@
>
> 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.
>
> For diffing large templated types, this option will cause Clang to
> @@ -386,7 +414,7 @@
>
> 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 @@
>
> .. _opt_wextra-tokens:
>
> -**-Wextra-tokens**
> +.. option:: -Wextra-tokens
> +
> Warn about excess tokens at the end of a preprocessor directive.
>
> This option, which defaults to on, enables warnings about extra
> @@ -422,7 +451,8 @@
> These extra tokens are not strictly conforming, and are usually best
> handled by commenting them out.
>
> -**-Wambiguous-member-template**
> +.. option:: -Wambiguous-member-template
> +
> Warn about unqualified uses of a member template whose name resolves to
> another template at the location of the use.
>
> @@ -445,7 +475,8 @@
> because it's hard to work around, Clang downgrades it to a warning
> as an extension.
>
> -**-Wbind-to-temporary-copy**
> +.. option:: -Wbind-to-temporary-copy
> +
> Warn about an unusable copy constructor when binding a reference to a
> temporary.
>
> @@ -492,8 +523,9 @@
> reproducibility of the failure. Below are the command line options to
> control the crash diagnostics.
>
> -**-fno-crash-diagnostics**: Disable auto-generation of preprocessed
> -source files during a clang crash.
> +.. option:: -fno-crash-diagnostics
> +
> + Disable auto-generation of preprocessed source files during a clang crash.
>
> The -fno-crash-diagnostics flag can be helpful for speeding the process
> of generating a delta reduced test case.
> @@ -590,27 +622,27 @@
> following example code will tell Clang or GCC to ignore the -Wall
> 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
> 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 -Wmultichar is ignored for only a single line of
> -code, after which the diagnostics return to whatever state had
> -previously existed.
> +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
> +existed.
>
> -::
> +.. code-block:: c
>
> - #pragma clang diagnostic push
> - #pragma clang diagnostic ignored "-Wmultichar"
> + #pragma clang diagnostic push
> + #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
> of the compiler, regardless of how it was set. That means that it is
> @@ -633,15 +665,15 @@
> being a system header. No warnings will be produced from the location of
> 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
> 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
> @@ -649,9 +681,9 @@
> command-line which matches the specified header name takes precedence.
> 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
> if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
> @@ -668,10 +700,10 @@
> ^^^^^^^^^^^^^^^^^^^^^
>
> In addition to the traditional ``-W`` flags, one can enable **all**
> -warnings by passing ``-Weverything``. This works as expected with
> -``-Werror``, and also includes the warnings from ``-pedantic``.
> +warnings by passing :option:`-Weverything`. This works as expected with
> +: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.
>
> Controlling Static Analyzer Diagnostics
> @@ -708,23 +740,23 @@
> ^^^^^^^^^^^^^^^^^^^^^
>
> 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:
>
> -::
> +.. code-block:: console
>
> - $ gcc -x c-header test.h -o test.h.gch
> - $ clang -x c-header test.h -o test.h.pch
> + $ gcc -x c-header test.h -o test.h.gch
> + $ clang -x c-header test.h -o test.h.pch
>
> 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``:
>
> -::
> +.. 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
> available; if so, the contents of ``test.h`` (and the files it includes)
> @@ -733,19 +765,20 @@
> of GCC.
>
> .. 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
> - $ cat test.c
> - #include "test.h"
> - $ clang test.c -o test
> -
> -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
> -not specified on the command line using ``-include``.
> + $ clang -x c-header test.h -o test.h.pch
> + $ cat test.c
> + #include "test.h"
> + $ clang test.c -o test
> +
> + 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 not
> + specified on the command line using :option:`-include`.
>
> Relocatable PCH Files
> ^^^^^^^^^^^^^^^^^^^^^
> @@ -770,19 +803,19 @@
> 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
> -``-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:
>
> -::
> +.. 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
> 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 ``-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
> -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``.
>
> Relocatable precompiled headers are intended to be used in a limited
> @@ -896,17 +929,22 @@
> **-f[no-]thread-sanitizer**
> Deprecated synonym for :ref:`-f[no-]sanitize=thread
> <opt_fsanitize_thread>`.
> -**-fcatch-undefined-behavior**
> +
> +.. option:: -fcatch-undefined-behavior
> +
> Deprecated synonym for :ref:`-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.
>
> 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
> other pointer when the function returns.
>
> -**-ftrap-function=[name]**
> +.. option:: -ftrap-function=[name]
> +
> Instruct code generator to emit a function call to the specified
> function name for ``__builtin_trap()``.
>
> @@ -919,7 +957,8 @@
> deeply embedded) where a trap cannot be properly handled, or when
> some custom behavior is desired.
>
> -**-ftls-model=[model]**
> +.. option:: -ftls-model=[model]
> +
> Select which TLS model to use.
>
> Valid values are: ``global-dynamic``, ``local-dynamic``,
> @@ -935,16 +974,22 @@
> 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.
>
> -**-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
> -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).
> +.. option:: -g
>
> -**-g**: Generate complete debug info.
> + Generate complete debug info.
>
> .. _c:
>
> @@ -957,7 +1002,7 @@
> Extensions supported by clang
> -----------------------------
>
> -See `clang language extensions <LanguageExtensions.html>`_.
> +See :doc:`LanguageExtensions`.
>
> Differences between various standard modes
> ------------------------------------------
> @@ -1025,13 +1070,13 @@
> anytime soon. In C++11 it can be emulated by assigning lambda
> functions to local variables, e.g:
>
> - ::
> + .. code-block:: cpp
>
> - auto const local_function = [&](int parameter) {
> - // Do something
> - };
> - ...
> - local_function(1);
> + auto const local_function = [&](int parameter) {
> + // Do something
> + };
> + ...
> + local_function(1);
>
> - clang does not support global register variables; this is unlikely to
> be implemented soon because it requires additional LLVM backend
> @@ -1119,11 +1164,15 @@
> Controlling implementation limits
> ---------------------------------
>
> -**-fconstexpr-depth=N**: Sets the limit for recursive constexpr function
> -invocations to N. The default is 512.
> +.. option:: -fconstexpr-depth=N
> +
> + 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
> -instantiations to N. The default is 1024.
> + Sets the limit for recursively nested template instantiations to N. The
> + default is 1024.
>
> .. _objc:
>
> @@ -1178,10 +1227,10 @@
>
> Other platforms are completely unsupported at the moment. Adding the
> 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
> 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
> backend.
>
>
>
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
More information about the cfe-commits
mailing list