diff options
Diffstat (limited to 'docs/UsersManual.rst')
| -rw-r--r-- | docs/UsersManual.rst | 62 |
1 files changed, 51 insertions, 11 deletions
diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst index 7634d24eb5..88cb72c9b6 100644 --- a/docs/UsersManual.rst +++ b/docs/UsersManual.rst @@ -15,8 +15,8 @@ programming languages, aiming to be the best in class implementation of these languages. Clang builds on the LLVM optimizer and code generator, allowing it to provide high-quality optimization and code generation support for many targets. For more general information, please see the -`Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web -Site <http://llvm.org>`_. +`Clang Web Site <https://clang.llvm.org>`_ or the `LLVM Web +Site <https://llvm.org>`_. This document describes important notes about using Clang as a compiler for an end-user, documenting the supported features, command line @@ -994,7 +994,7 @@ information. Precompiled Headers ------------------- -`Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__ +`Precompiled headers <https://en.wikipedia.org/wiki/Precompiled_header>`_ are a general approach employed by many compilers to reduce compilation time. The underlying motivation of the approach is that it is common for the same (and often large) header files to be included by multiple @@ -1482,7 +1482,7 @@ usual build cycle when using sample profilers for optimization: 3. Convert the collected profile data to LLVM's sample profile format. This is currently supported via the AutoFDO converter ``create_llvm_prof``. - It is available at http://github.com/google/autofdo. Once built and + It is available at https://github.com/google/autofdo. Once built and installed, you can convert the ``perf.data`` file to LLVM using the command: @@ -1521,12 +1521,12 @@ read by the backend. LLVM supports three different sample profile formats: 2. Binary encoding. This uses a more efficient encoding that yields smaller profile files. This is the format generated by the ``create_llvm_prof`` tool - in http://github.com/google/autofdo. + in https://github.com/google/autofdo. 3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It is only interesting in environments where GCC and Clang co-exist. This encoding is only generated by the ``create_gcov`` tool in - http://github.com/google/autofdo. It can be read by LLVM and + https://github.com/google/autofdo. It can be read by LLVM and ``llvm-profdata``, but it cannot be generated by either. If you are using Linux Perf to generate sampling profiles, you can use the @@ -1745,7 +1745,8 @@ 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 creation and use. Flag ``-fcs-profile-generate`` also instruments +programs using the same instrumentation method as ``-fprofile-generate``. .. option:: -fprofile-generate[=<dirname>] @@ -1778,6 +1779,45 @@ profile creation and use. ``LLVM_PROFILE_FILE`` can still be used to override the directory and filename for the profile file at runtime. +.. option:: -fcs-profile-generate[=<dirname>] + + The ``-fcs-profile-generate`` and ``-fcs-profile-generate=`` flags will use + the same instrumentation method, and generate the same profile as in the + ``-fprofile-generate`` and ``-fprofile-generate=`` flags. The difference is + that the instrumentation is performed after inlining so that the resulted + profile has a better context sensitive information. They cannot be used + together with ``-fprofile-generate`` and ``-fprofile-generate=`` flags. + They are typically used in conjunction with ``-fprofile-use`` flag. + The profile generated by ``-fcs-profile-generate`` and ``-fprofile-generate`` + can be merged by llvm-profdata. A use example: + + .. code-block:: console + + $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code + $ ./code + $ llvm-profdata merge -output=code.profdata yyy/zzz/ + + The first few steps are the same as that in ``-fprofile-generate`` + compilation. Then perform a second round of instrumentation. + + .. code-block:: console + + $ clang++ -O2 -fprofile-use=code.profdata -fcs-profile-generate=sss/ttt \ + -o cs_code + $ ./cs_code + $ llvm-profdata merge -output=cs_code.profdata sss/ttt code.profdata + + The resulted ``cs_code.prodata`` combines ``code.profdata`` and the profile + generated from binary ``cs_code``. Profile ``cs_code.profata`` can be used by + ``-fprofile-use`` compilaton. + + .. code-block:: console + + $ clang++ -O2 -fprofile-use=cs_code.profdata + + The above command will read both profiles to the compiler at the identical + point of instrumenations. + .. option:: -fprofile-use[=<pathname>] Without any other arguments, ``-fprofile-use`` behaves identically to @@ -1831,9 +1871,9 @@ The profile remapping file is a text file containing lines of the form where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``, indicating whether the following mangled name fragments are -<`name <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s, -<`type <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or -<`encoding <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s, +<`name <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s, +<`type <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or +<`encoding <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s, respectively. Blank lines and lines starting with ``#`` are ignored. @@ -2829,7 +2869,7 @@ compatibility with the Visual C++ compiler, cl.exe. To enable clang-cl to find system headers, libraries, and the linker when run from the command-line, it should be executed inside a Visual Studio Native Tools Command Prompt or a regular Command Prompt where the environment has been set -up using e.g. `vcvarsall.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. +up using e.g. `vcvarsall.bat <https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. clang-cl can also be used from inside Visual Studio by selecting the LLVM Platform Toolset. The toolset is not part of the installer, but may be installed |