PGO Sample

The Profile-guided Optimization (PGO) sample is intended to illustrate how to profile an application and generate PGO reports. This same sample is designed to demonstrate how to use the code-coverage tool and test-prioritization tool.

See Included Samples for other samples included with the compiler.

Sample file and locations

Compile and profile the sample

Create an instrumented executable.

Note the size of the instrumented executable. (You should notice a change in the file size between the instrumented and optimized application, which you will generate in the last step.)

Run the instrumented executable.

Running the instrumented executable generates a dynamic information (.dyn) file each time the application is run. Look in the compilation directory. There should be at least one file with a .dyn file extension.

Run the instrumented executable a second time passing in an argument.

A second .dyn file should have appeared. These contain the dynamic profiling data for the functions that were exercised in the runs shown above.

Run the instrumented a third time passing in two arguments.

Run it again passing in 1 2 3 as the argument. Once you're done there should be many .dyn files in the compilation directory: one for each time you ran the application.

Use the profmerge tool to merge the dynamic information files.

After this step finishes there should be a new file with .dpi as the file extension. (The default is pgopti.dpi.) The .dpi file contains the summary of all of the dynamic data collected during the instrumented runs.

Note

See profmerge and proforder Tools for more information.

Use the profiling data to generate an optimized executable by entering the following commands. (You can combine this last step with compiler report options to generate the PGO report.)

Note the size of the optimized executable. This file should be smaller than the instrumented file. Executing the smaller application should not generate .dyn files.

Use the code-coverage Tool

These procedures demonstrate using the samples to use the code-coverage tool to generate a simple report. See code-coverage tool for detailed information about the tool and the report.

The process for using the tool is the same as shown in the Compile and profile the sample section (above); however, there is one significant difference. You must use the -prof-genx (Linux and Mac OS X) or /Qprof-genx (Windows) option to create the instrumented executable.

1. If you have any existing .dyn or .dpi files from previous runs delete them before moving to the next step.

2. Generate the instrumented executable with prof-genx.
   Notice that compiling the instrumented file generates a .spi file.

3. Run the instrumented executable several time passing new values each time.

4. Merge the .dyn files using profmerge. (The code-coverage tool uses both the .dpi and .spi files to generate coverage reports.)

4. Generate the code-coverage tool report.

After the status indicator reaches 100% you should notice a new code_coverage.html file, and a new codecoverage directory, in the compilation directory. Open the HTML formatted file to view the report.

Use the test-prioritization Tool

These procedures demonstrate using the samples to use the test-prioritization tool to generate sample test results. See test-prioritization tool for detailed information about how to use the tool.

The process for using the tool is the similar as shown in the Compile and profile the sample section (above); however, you must use the -prof-genx (Linux and Mac OS X) or /Qprof-genx (Windows) option to create the instrumented executable.

1. If you have any existing .dyn or .dpi files from previous runs delete them before moving to the next step.

2. Generate the instrumented executable with prof-genx.
   Notice that compiling the instrumented file generates a .spi file. (The test-prioritization tool uses the .spi file.)

3. Run the instrumented executable several times passing unique values for each run.

4. Merge the .dyn files using profmerge and specify a name for the .dpi file.

5. Delete all .dyn files.

6. Run the instrumented executable several times passing unique values for each run.

7. Merge the .dyn files using profmerge and specify a name for the .dpi file.

8. Create a file named testruns.txt. Add the dpi names to the file; insure there is only one name per line. For example, the following example lists the testruns.txt file contents for these runs.

9. Run the test-prioritization tool specifying the .dpi list file name and direct the report results to a report file by entering commands similar to the following. (The report file will be created in the compilation directory.)

10. Open the tselect_report.txt file. The file should contain results similar to the following.