SYNOPSIS
^^^^^^^^
-:program:`llvm-profdata merge` [*options*] [*filenames...*]
+:program:`llvm-profdata merge` [*options*] [*filename...*]
DESCRIPTION
^^^^^^^^^^^
generated by PGO instrumentation and merges them together into a single
indexed profile data file.
+By default profile data is merged without modification. This means that the
+relative importance of each input file is proportional to the number of samples
+or counts it contains. In general, the input from a longer training run will be
+interpreted as relatively more important than a shorter run. Depending on the
+nature of the training runs it may be useful to adjust the weight given to each
+input file by using the ``-weighted-input`` option.
+
+
OPTIONS
^^^^^^^
Specify the output file name. *Output* cannot be ``-`` as the resulting
indexed profile data can't be written to standard output.
+.. option:: -weighted-input=weight,filename
+
+ Specify an input file name along with a weight. The profile counts of the input
+ file will be scaled (multiplied) by the supplied ``weight``, where where ``weight``
+ is a decimal integer >= 1. Input files specified without using this option are
+ assigned a default weight of 1. Examples are shown below.
+
.. option:: -instr (default)
Specify that the input profile is an instrumentation-based profile.
.. option:: -sample
- Specify that the input profile is a sample-based profile. When using
- sample-based profiles, the format of the generated file can be generated
- in one of three ways:
+ Specify that the input profile is a sample-based profile.
+
+ The format of the generated file can be generated in one of three ways:
.. option:: -binary (default)
- Emit the profile using a binary encoding.
+ Emit the profile using a binary encoding. For instrumentation-based profile
+ the output format is the indexed binary format.
.. option:: -text
- Emit the profile in text mode.
+ Emit the profile in text mode. This option can also be used with both
+ sample-based and instrumentation-based profile. When this option is used
+ the profile will be dumped in the text format that is parsable by the profile
+ reader.
.. option:: -gcc
Emit the profile using GCC's gcov format (Not yet supported).
+EXAMPLES
+^^^^^^^^
+Basic Usage
++++++++++++
+Merge three profiles:
+
+::
+
+ llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
+
+Weighted Input
+++++++++++++++
+The input file `foo.profdata` is especially important, multiply its counts by 10:
+
+::
+
+ llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
+
+Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
+
+::
+
+ llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
+
.. program:: llvm-profdata show
.. _profdata-show:
Specify that the input profile is an instrumentation-based profile.
+.. option:: -text
+
+ Instruct the profile dumper to show profile counts in the text format of the
+ instrumentation-based profile data representation. By default, the profile
+ information is dumped in a more human readable form (also in text) with
+ annotations.
+
.. option:: -sample
Specify that the input profile is a sample-based profile.