diff options
Diffstat (limited to 'docs/UsersManual.rst')
| -rw-r--r-- | docs/UsersManual.rst | 115 |
1 files changed, 100 insertions, 15 deletions
diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst index 2ebcbdf60317..96b7ac95cb5d 100644 --- a/docs/UsersManual.rst +++ b/docs/UsersManual.rst @@ -2,6 +2,8 @@ Clang Compiler User's Manual ============================ +.. include:: <isonum.txt> + .. contents:: :local: @@ -23,6 +25,10 @@ processes code, please see :doc:`InternalsManual`. If you are interested in the `Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web page. +Clang is one component in a complete toolchain for C family languages. +A separate document describes the other pieces necessary to +:doc:`assemble a complete toolchain <Toolchain>`. + Clang is designed to support the C family of programming languages, which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and :ref:`Objective-C++ <objcxx>` as well as many dialects of those. For @@ -105,6 +111,8 @@ Options to Control Error and Warning Messages .. option:: -Wfoo Enable warning "foo". + See the :doc:`diagnostics reference <DiagnosticsReference>` for a complete + list of the warning flags that can be specified in this way. .. option:: -Wno-foo @@ -313,6 +321,28 @@ output format of the diagnostics that it generates. by category, so it should be a high level category. We want dozens of these, not hundreds or thousands of them. +.. _opt_fdiagnostics-show-hotness: + +**-f[no-]diagnostics-show-hotness** + Enable profile hotness information in diagnostic line. + + This option, which defaults to off, controls whether Clang prints the + profile hotness associated with a diagnostics in the presence of + profile-guided optimization information. This is currently supported with + optimization remarks (see :ref:`Options to Emit Optimization Reports + <rpass>`). The hotness information allows users to focus on the hot + optimization remarks that are likely to be more relevant for run-time + performance. + + For example, in this output, the block containing the callsite of `foo` was + executed 3000 times according to the profile data: + + :: + + s.c:7:10: remark: foo inlined into bar (hotness: 3000) [-Rpass-analysis=inline] + sum += foo(x, x - 2); + ^ + .. _opt_fdiagnostics-fixit-info: **-f[no-]diagnostics-fixit-info** @@ -531,6 +561,8 @@ control the crash diagnostics. The -fno-crash-diagnostics flag can be helpful for speeding the process of generating a delta reduced test case. +.. _rpass: + Options to Emit Optimization Reports ------------------------------------ @@ -574,6 +606,10 @@ outside of the major transformations (e.g., inlining, vectorization, loop optimizations) and not every optimization pass supports this feature. +Note that when using profile-guided optimization information, profile hotness +information can be included in the remarks (see +:ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`). + Current limitations ^^^^^^^^^^^^^^^^^^^ @@ -1073,6 +1109,15 @@ are listed below. ``Inf``, and * ``+0`` and ``-0`` are interchangeable. +.. option:: -fdenormal-fp-math=[values] + + Select which denormal numbers the code is permitted to require. + + Valid values are: ``ieee``, ``preserve-sign``, and ``positive-zero``, + which correspond to IEEE 754 denormal numbers, the sign of a + flushed-to-zero number is preserved in the sign of 0, denormals are + flushed to positive zero, respectively. + .. option:: -fwhole-program-vtables Enable whole-program vtable optimizations, such as single-implementation @@ -1470,8 +1515,13 @@ instrumentation: 2. Run the instrumented executable with inputs that reflect the typical usage. By default, the profile data will be written to a ``default.profraw`` file - in the current directory. You can override that default by setting the - ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file. + in the current directory. You can override that default by using option + ``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE`` + environment variable to specify an alternate file. If non-default file name + is specified by both the environment variable and the command line option, + the environment variable takes precedence. The file name pattern specified + can include different modifiers: ``%p``, ``%h``, and ``%m``. + Any instance of ``%p`` in that file name will be replaced by the process ID, so that you can easily distinguish the profile output from multiple runs. @@ -1480,6 +1530,33 @@ instrumentation: $ LLVM_PROFILE_FILE="code-%p.profraw" ./code + The modifier ``%h`` can be used in scenarios where the same instrumented + binary is run in multiple different host machines dumping profile data + to a shared network based storage. The ``%h`` specifier will be substituted + with the hostname so that profiles collected from different hosts do not + clobber each other. + + While the use of ``%p`` specifier can reduce the likelihood for the profiles + dumped from different processes to clobber each other, such clobbering can still + happen because of the ``pid`` re-use by the OS. Another side-effect of using + ``%p`` is that the storage requirement for raw profile data files is greatly + increased. To avoid issues like this, the ``%m`` specifier can used in the profile + name. When this specifier is used, the profiler runtime will substitute ``%m`` + with a unique integer identifier associated with the instrumented binary. Additionally, + multiple raw profiles dumped from different processes that share a file system (can be + on different hosts) will be automatically merged by the profiler runtime during the + dumping. If the program links in multiple instrumented shared libraries, each library + will dump the profile data into its own profile data file (with its unique integer + id embedded in the profile name). Note that the merging enabled by ``%m`` is for raw + profile data generated by profiler runtime. The resulting merged "raw" profile data + file still needs to be converted to a different format expected by the compiler ( + see step 3 below). + + .. code-block:: console + + $ LLVM_PROFILE_FILE="code-%m.profraw" ./code + + 3. Combine profiles from multiple runs and convert the "raw" profile format to the input expected by clang. Use the ``merge`` command of the ``llvm-profdata`` tool to do this. @@ -1514,27 +1591,31 @@ profile creation and use. 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, + ``default_%m.profraw`` in the directory named ``dirname`` if specified. + If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier + will be substibuted with a unique id documented in step 2 above. In other words, + with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic + merging is turned on by default, so there will no longer any risk of profile + clobbering from different running processes. For example, .. code-block:: console $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code When ``code`` is executed, the profile will be written to the file - ``yyy/zzz/default.profraw``. This can be altered at runtime via the - ``LLVM_PROFILE_FILE`` environment variable: + ``yyy/zzz/default_xxxx.profraw``. - .. code-block:: console + To generate the profile data file with the compiler readable format, the + ``llvm-profdata`` tool can be used with the profile directory as the input: + + .. code-block:: console - $ LLVM_PROFILE_FILE=/tmp/myprofile/code.profraw ./code + $ llvm-profdata merge -output=code.profdata yyy/zzz/ - The above invocation will produce the profile file - ``/tmp/myprofile/code.profraw`` instead of ``yyy/zzz/default.profraw``. - Notice that ``LLVM_PROFILE_FILE`` overrides the directory *and* the file - name for the profile file. + If the user wants to turn off the auto-merging feature, or simply override the + the profile dumping path specified at command line, the environment variable + ``LLVM_PROFILE_FILE`` can still be used to override + the directory and filename for the profile file at runtime. .. option:: -fprofile-use[=<pathname>] @@ -1614,7 +1695,7 @@ features. You can "tune" the debug info for one of several different debuggers. .. option:: -ggdb, -glldb, -gsce - Tune the debug info for the ``gdb``, ``lldb``, or Sony Computer Entertainment + Tune the debug info for the ``gdb``, ``lldb``, or Sony PlayStation\ |reg| debugger, respectively. Each of these options implies **-g**. (Therefore, if you want both **-gline-tables-only** and debugger tuning, the tuning option must come first.) @@ -1749,6 +1830,10 @@ extensions are not implemented yet: ... local_function(1); +- clang only supports global register variables when the register specified + is non-allocatable (e.g. the stack pointer). Support for general global + register variables 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. |