A.2.170 -xprofile=p

Use this option to first collect and save execution-frequency data so that you can then use the data in subsequent runs to improve performance. This option is only valid when you specify optimization at level -xO2 or above.

Compiling with high optimization levels (for example -xO5) is enhanced by providing the compiler with runtime-performance feedback. In order to produce runtime-performance feedback, you must compile with -xprofile=collect, run the executable against a typical data set, and then recompile at the highest optimization level and with -xprofile=use.

Profile collection is safe for multithreaded applications. That is, profiling a program that does its own multitasking (-mt) produces accurate results. This option is only valid when you specify optimization at level -xO2 or above.

A.2.170.1 Values

p must be one of the following values.

• collect[:name]

  Collects and saves execution frequency for later use by the optimizer with –xprofile=use. The compiler generates code to measure statement execution frequency.

  The name is the optional name of the directory in which profile data will be stored when the program is executed. If specified, name should be an absolute UNIX pathname. If name is not specified, profile data for a profiled program named program will be stored in a directory named program.profile in the current working directory at the time that program is executed.

  At runtime, a program compiled with –xprofile=collect:name creates the subdirectory name.profile to hold the runtime feedback information. Data is written to the file feedback in this subdirectory. You can use the $SUN_PROFDATA and $SUN_PROFDATA_DIR environment variables to change the location of the feedback information. See the Interactions section for more information.

  If you run the program several times, the execution frequency data accumulates in the feedback file; that is, output from prior runs is not lost.

  If you are compiling and linking in separate steps, make sure that any object files compiled with -xprofile=collect are also linked with -xprofile=collect. See 3.3.3 Compile-Time and Link-Time Options for a complete list of options that must be specified at both compile time and link time.

  The three options -xMerge -ztext -xprofile=collect should not be used together. While -xMerge forces statically initialized data into read-only storage, -ztext prohibits position-dependent symbol relocations in read-only storage, and -xprofile=collect generates statically initialized, position-dependent symbol relocations in writable storage.

• use[:name]

  The program is optimized by using the executions-frequency data generated and saved in the feedback files from a previous execution of the program that was compiled with –xprofile=collect.

  The name is the name of the executable that is being analyzed. The name is optional and, if not specified, is assumed to be a.out.

  Except for the -xprofile option which changes from -xprofile=collect to -xprofile=use, the source files and other compiler options must be exactly the same as those used for the compilation that created the compiled program which in turn generated the feedback file. The same version of the compiler must be used for both the collect build and the use build as well. If compiled with -xprofile=collect:name, the same program name name must appear in the optimizing compilation: -xprofile=use:name.

  The association between an object file and its profile data is based on the UNIX pathname of the object file when it is compiled with -xprofile=collect. In some circumstances, the compiler will not associate an object file with its profile data: the object file has no profile data because it was not previously compiled with -xprofile=collect, the object file is not linked in a program with -xprofile=collect, the program has never been executed.

  The compiler can also become confused if an object file was previously compiled in a different directory with -xprofile=collect and this object file shares a common basename with other object files compiled with -xprofile=collect but they cannot be uniquely identified by the names of their containing directories. In this case, even if the object file has profile data, the compiler will not be able to find it in the feedback directory when the object file is recompiled with -xprofile=use.

  All of these situations cause the compiler to loose the association between an object file and its profile data. Therefor, if an object file has profile data but the compiler is unable to associate it with the object file’s pathname when you specify -xprofile=use, use the -xprofile_pathmap option to identify correct directory. See A.2.172 -xprofile_pathmap

• tcov

  Basic block coverage analysis using the new style tcov.

  This option is the new style of basic block profiling for tcov. It has similar functionality to the– xa option, but correctly collects data for programs that have source code in header files or make use of C++ templates. Code instrumentation is similar to that of the -xa option, but.d files are no longer generated. Instead, a single file is generated, the name of which is based on the final executable. For example, if the program is run out of /foo/bar/myprog.profile, then the data file is stored in /foo/bar/myprog.profile/myprog.tcovd.

  When running tcov, you must pass it the– x option to force it to use the new style of data. If you do not pass -x, tcov uses the old .d files by default, and produces unexpected output.

  Unlike the –xa option, the TCOVDIR environment variable has no effect at compile time. However, its value is used at program runtime.

Interactions

The –xprofile=tcov and the -xa options are compatible in a single executable. That is, you can link a program that contains some files that have been compiled with -xprofile=tcov and other files compiled with -xa. You cannot compile a single file with both options.

The code coverage report produced by -xprofile=tcov can be unreliable if there is inlining of functions due to the use of -xinline or -xO4.

You can set the environment variables $SUN_PROFDATA and $SUN_PROFDATA_DIR to control where a program that is compiled with -xprofile=collect puts the profile data. If these variables are not set, the profile data is written to name.profile/feedback in the current directory (name is the name of the executable or the name specified in the -xprofile=collect:name flag). If these variables are set, the -xprofile=collect data is written to $SUN_PROFDATA_DIR/$SUN_PROFDATA.

The $SUN_PROFDATA and $SUN_PROFDATA_DIR environment variables similarly control the path and names of the profile data files written by tcov. See the tcov(1) man page for more information.

Warnings

If you compile and link in separate steps, the same -xprofile option must appear in both the compile command and the link command. Including -xprofile in one step and excluding it from the other step will not affect the correctness of the program, but you will not be able to do profiling.

-xprofile=collect or -xprofile=tcov should not be used with -G to build shared libraries on Linux platforms.

See also

-xa, tcov(1) man page, Program Performance Analysis Tools.