Intel® C++ Compiler Classic Developer Guide and Reference

ID 767249
Date 7/13/2023
Public
Document Table of Contents

Profmerge and Proforder Tools

Profmerge Tool

Use the profmerge tool to merge dynamic profile information (.dyn) files and any specified summary files (.dpi). The compiler executes profmerge automatically during the feedback compilation phase when you specify the [Q]prof-use option.

The command-line syntax for profmerge is as follows:

profmerge [-prof_dir dir_name]

The tool merges all .dyn files in the current directory, or the directory specified by -prof_dir, and produces a summary file: pgopti.dpi.

NOTE:

The spelling of tools options may differ slightly from compiler options. Tools options use an underscore (for example -prof_dir) instead of the hyphen used by compiler options (for example [Q]prof-dir) to join words. Also, on Windows* systems, the tool options are preceded by a hyphen ("-") unlike Windows* compiler options, which are preceded by a forward slash ("/").

You can use profmerge tool to merge .dyn files into a .dpi file without recompiling the application. You can run the instrumented executable file on multiple systems to generate .dyn files, and optionally use profmerge with the -prof_dpi option to name each summary .dpi file created from the multiple .dyn files.

Because the profmerge tool merges all the .dyn files that exist in the given directory, confirm that unrelated .dyn files are not present; otherwise, profile information will be based on invalid profile data, which can negatively impact the performance of optimized code.

Profmerge Options

The profmerge tool supports the following options:

Tool Option

Description

-dump

Displays profile information.

-help

Lists supported options.

-nologo

Disables version information. This option is supported on Windows* only.

-exclude_filesfiles

Excludes functions from the profile if the function comes from one of the listed files. The list items must be separated by a comma (","); you can use a period (".") as a wild card character in function names.

-exclude_funcsfunctions

Excludes functions from the profile. The list items must be separated by a comma (","); you can use a period (".") as a wild card character in function names.

-prof_dirdir

Specifies the directory from which to read .dyn and .dpi files, and write the .dpi file. Alternatively, you can set the environment variablePROF_DIR.

-prof_dpifile

Specifies the name of the .dpi file being generated.

-prof_filefile

Merges information from file matching: dpi_file_and_dyn_tag.

-src_olddir-src_newdir

Changes the directory path stored within the .dpi file.

-no_src_dir

Uses only the file name and not the directory name when reading dyn/dpi records. If you specify -no_src_dir, the directory name of the source file will be ignored when deciding which profile data records correspond to a specific application routine, and the -src-root option is ignored.

-src-rootdir

Specifies a directory path prefix for the root directory where the user's application files are stored. This option is ignored if you specify -no_src_dir.

-afile1.dpi...fileN.dpi

Specifies and merges available .dpi files.

-verbose

Instructs the tool to display full information during merge.

-weighted

Instructs the tool to apply an equal weighting (regardless of execution times) to the .dyn file values to normalize the data counts. This keyword is useful when the execution runs have different time durations and you want them to be treated equally.

-gen_weight_spec file

Instructs the tool to generate a text file containing a list of the .dyn and .dpi file that were merged with default weight=1/run_count.

The text file is created in the directory specified by the prof_dir option.

-weight_spec weight_spec.txt

Instructs the profmerge tool to generate and use the text file, weight_spec.txt, listing individual .dyn/.dpi files or directory names along with weight values for them.

When the -weight_spec option is used:

  • A new .dpi file is always created

  • Only files called out by the specification file are merged

  • .dyn timestamps are ignored and merge always takes place

The prof_dir option controls where the input/output weight_spec.txt is located, and the destination of the .dpi file.

The -weight_spec option overrides:

  • Any values of -a option

  • Any computation from using -weighted option

Weight the Runs

Using the -weight_spec option results in a new .dpi file. Only the files listed in the text file are merged. No files in the current directory are used unless they are included in the text file.

Relocate Source Files Using profmerge

The Intel® C++ Compiler uses the full path to the source file for each routine to look up the profile summary information associated with that routine. By default, this prevents you from:

  • Using the profile summary file (.dpi) if you move your application sources.

  • Sharing the profile summary file with another user who is building identical application sources that are located in a different directory.

You can disable the use of directory names when reading .dyn/.dpi file records by specifying the profmerge option -no_scr_dir. This profmerge option is the same as the compiler option -no-prof-src-dir (Linux* and macOS) and /Qprof-src-dir- (Windows*).

To enable the movement of application sources, as well as the sharing of profile summary files, you can use the profmerge option -src-root to specify a directory path prefix for the root directory where the application files are stored. Alternatively, you can specify the option pair -src_old-src_new to modify the data in an existing summary dpi file. For example:

profmerge -prof_dir <dir1> -src_old <dir2> -src_new <dir3>
where <dir1> is the full path to dynamic information file (.dpi), <dir2> is the old full path to source files, and <dir3> is the new full path to source files. The example command (above) reads the pgopti.dpi file, in the location specified in <dir1>. For each function represented in the pgopti.dpi file, whose source path begins with the <dir2> prefix, profmerge replaces that prefix with <dir3>. The pgopti.dpi file is updated with the new source path information.

You can run profmerge more than once on a given pgopti.dpi file. You may need to do this if the source files are located in multiple directories. For example:

Linux* and macOS

profmerge -prof_dir -src_old /src/prog_1 -src_new /src/prog_2 
profmerge -prof_dir -src_old /proj_1 -src_new /proj_2

Windows*

profmerge -src_old "c:/program files" -src_new "e:/program files"
profmerge -src_old c:/proj/application -src_new d:/app

In the values specified for -src_old and -src_new, uppercase and lowercase characters are treated as identical in Windows. Likewise, forward slash ( /) and backward slash ( \) characters are treated as identical.

NOTE:

Because the source relocation feature of profmerge modifies the pgopti.dpi file, consider making a backup copy of the file before performing the source relocation.

Proforder Tool

The proforder tool is used as part of the feedback compilation phase, to improve program performance. Use proforder to generate a function order list for use with the /ORDER linker option in Windows. The tool uses the following syntax:

proforder [-prof_dir dir] [-o file]

where dir is the directory containing the profile files ( .dpi and .spi), and file is the optional name of the function order list file. The default name is proford.txt .

NOTE:

The spelling of tools options may differ slightly from compiler options. Tools options use an underscore (for example -prof_dir) instead of the hyphen used by compiler options (for example [Q]prof-dir) to join words. Also, on Windows* systems, the tool options are preceded by a hyphen ("-") unlike Windows* compiler options, which are preceded by a forward slash ("/").

Proforder Options

The proforder tool supports the following options:

Tool Option

Default

Description

-help

Lists supported options.

-nologo

Disables version information. This option is supported on Windows* only.

-omit_static

Instructs the tool to omit static functions from function ordering.

-prof_dirdir

Specifies the directory where the .spi and .dpi file reside.

-prof_dpifile

Specifies the name of the .dpi file.

-prof_filestring

Selects the .dpi and .spi files that include the substring value in the file name matching the values passed as string.

-prof_spifile

Specifies the name of the .spi file.

-ofile

proford.txt

Specifies an alternate name for the output file.