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>, _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits