[clang] 3bd7cbb - [Remarks][Docs] Enhance documentation for opt-remarks driver options
Francis Visoiu Mistrih via cfe-commits
cfe-commits at lists.llvm.org
Tue Dec 10 13:22:03 PST 2019
Author: Francis Visoiu Mistrih
Date: 2019-12-10T13:19:49-08:00
New Revision: 3bd7cbb90cdb9cf2ca481107ec66a75d9c885782
URL: https://github.com/llvm/llvm-project/commit/3bd7cbb90cdb9cf2ca481107ec66a75d9c885782
DIFF: https://github.com/llvm/llvm-project/commit/3bd7cbb90cdb9cf2ca481107ec66a75d9c885782.diff
LOG: [Remarks][Docs] Enhance documentation for opt-remarks driver options
Add better documentation about the naming scheme, add a few more
explicit descriptions and make the sphinx look better.
Added:
Modified:
clang/docs/ClangCommandLineReference.rst
clang/docs/UsersManual.rst
clang/include/clang/Driver/Options.td
Removed:
################################################################################
diff --git a/clang/docs/ClangCommandLineReference.rst b/clang/docs/ClangCommandLineReference.rst
index 7047cd9bb7b3..5b8a96b61b3d 100644
--- a/clang/docs/ClangCommandLineReference.rst
+++ b/clang/docs/ClangCommandLineReference.rst
@@ -1699,9 +1699,14 @@ Emit OpenMP code only for SIMD-based constructs.
.. option:: -foperator-arrow-depth=<arg>
-.. option:: -foptimization-record-file=<arg>
+.. option:: -foptimization-record-file=<file>
-Specify the output name of the file containing the optimization remarks. Implies -fsave-optimization-record. On Darwin platforms, this cannot be used with multiple -arch <arch> options.
+Implies -fsave-optimization-record. On Darwin platforms, this
+ cannot be used with multiple -arch <arch> options.
+
+.. option:: -foptimization-record-passes=<regex>
+
+Only include passes which match a specified regular expression in the generated optimization record (by default, include all passes)
.. option:: -foptimize-sibling-calls, -fno-optimize-sibling-calls
@@ -1834,6 +1839,12 @@ Turn on loop reroller
Generate a YAML optimization record file
+.. program:: clang1
+.. option:: -fsave-optimization-record=<format>
+.. program:: clang
+
+Generate an optimization record file in a specific format.
+
.. option:: -fseh-exceptions
Use SEH style exceptions
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 62e2575c6b26..87434200e777 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -324,9 +324,10 @@ output format of the diagnostics that it generates.
.. _opt_fsave-optimization-record:
-.. option:: -fsave-optimization-record[=<format>]
+.. option:: -f[no-]save-optimization-record[=<format>]
- Write optimization remarks to a separate file.
+ Enable optimization remarks during compilation and write them to a separate
+ file.
This option, which defaults to off, controls whether Clang writes
optimization reports to a separate file. By recording diagnostics in a file,
@@ -345,20 +346,45 @@ output format of the diagnostics that it generates.
``-fsave-optimization-record=bitstream``: A binary format based on LLVM
Bitstream.
+ The output file is controlled by :ref:`-foptimization-record-file <opt_foptimization-record-file>`.
+
+ In the absence of an explicit output file, the file is chosen using the
+ following scheme:
+
+ ``<base>.opt.<format>``
+
+ where ``<base>`` is based on the output file of the compilation (whether
+ it's explicitly specified through `-o` or not) when used with `-c` or `-S`.
+ In other cases, it's based on the input file's stem. For example:
+
+ * ``clang -fsave-optimization-record -c in.c -o out.o`` will generate
+ ``out.opt.yaml``
+
+ * ``clang -fsave-optimization-record in.c -o out`` will generate
+ ``in.opt.yaml``
+
+ Compiling for multiple architectures will use the following scheme:
+
+ ``<base>-<arch>.opt.<format>``
+
+ Note that this is only allowed on Darwin platforms and is incompatible with
+ passing multiple ``-arch <arch>`` options.
+
+ When targeting (Thin)LTO, the base is derived from the output filename, and
+ the extension is not dropped.
+
+ When targeting ThinLTO, the following scheme is used:
+
+ ``<base>.opt.<format>.thin.<num>.<format>``
+
.. _opt_foptimization-record-file:
**-foptimization-record-file**
- Control the file to which optimization reports are written.
-
- When optimization reports are being output (see
- :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`), this
- option controls the file to which those reports are written.
+ Control the file to which optimization reports are written. This implies
+ :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`.
- If this option is not used, optimization records are output to a file named
- after the primary file being compiled. If that's "foo.c", for example,
- optimization records are output to "foo.opt.yaml". If a specific
- serialization format is specified, the file will be named
- "foo.opt.<format>".
+ On Darwin platforms, this is incompatible with passing multiple
+ ``-arch <arch>`` options.
.. _opt_foptimization-record-passes:
diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index 8965131b9001..6f404d1f2ea5 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -1800,16 +1800,18 @@ def foperator_arrow_depth_EQ : Joined<["-"], "foperator-arrow-depth=">,
def fsave_optimization_record : Flag<["-"], "fsave-optimization-record">,
Group<f_Group>, HelpText<"Generate a YAML optimization record file">;
def fsave_optimization_record_EQ : Joined<["-"], "fsave-optimization-record=">,
- Group<f_Group>, HelpText<"Generate an optimization record file in a specific format (default: YAML)">;
+ Group<f_Group>, HelpText<"Generate an optimization record file in a specific format">,
+ MetaVarName<"<format>">;
def fno_save_optimization_record : Flag<["-"], "fno-save-optimization-record">,
Group<f_Group>, Flags<[NoArgumentUnused]>;
def foptimization_record_file_EQ : Joined<["-"], "foptimization-record-file=">,
Group<f_Group>,
- HelpText<"Specify the file name of any generated YAML optimization record">;
+ HelpText<"Specify the output name of the file containing the optimization remarks. Implies -fsave-optimization-record. On Darwin platforms, this cannot be used with multiple -arch <arch> options.">,
+ MetaVarName<"<file>">;
def foptimization_record_passes_EQ : Joined<["-"], "foptimization-record-passes=">,
Group<f_Group>,
- HelpText<"Only include passes which match a specified regular expression in the generated optimization record (by default, include all passes)">;
-
+ HelpText<"Only include passes which match a specified regular expression in the generated optimization record (by default, include all passes)">,
+ MetaVarName<"<regex>">;
def ftest_coverage : Flag<["-"], "ftest-coverage">, Group<f_Group>;
def fvectorize : Flag<["-"], "fvectorize">, Group<f_Group>,
More information about the cfe-commits
mailing list