Profmerge and Proforder Tools

Intel® C++ Compiler Classic Developer Guide and Reference

Download PDF

ID 767249

Date 12/16/2022

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-9E804DFC-FA37-402C-BD54-856965D1A8BF

View Details

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 usage for profmerge is as follows:

Syntax
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 variable`PROF_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

Weighting 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.

Relocating 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:

Example: relocation command syntax
`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. For example, you may need to do this if the source files are located in multiple directories:

Operating System	Command Examples
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

Operating System

Command Examples

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:

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:

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_dir`dir`		Specifies the directory where the .spi and .dpi file reside.
-prof_dpi`file`		Specifies the name of the .dpi file.
-prof_file`string`		Selects the .dpi and .spi files that include the substring value in the file name matching the values passed as string.
-prof_spi`file`		Specifies the name of the .spi file.
-o`file`	proford.txt	Specifies an alternate name for the output file.

Parent topic: PGO Tools

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® C++ Compiler Classic Developer Guide and Reference

Profmerge and Proforder Tools

Profmerge Tool

Proforder Tool

See Also