Whether you're debugging, trouble-shooting, designing, or optimizing, there may be occasions where you might want to quickly and easily view your profile information in a visual format. With Surveyor, this is a very simple process, as illustrated by the instructions below.

Profile Data - tcov, gprof, and profiler

While much of the information collected and displayed by Surveyor is based on static analysis of your source code, the tool can also collect and display certain information about the runtime performance of your software. Collected from profile data sources, these runtime performance measurements can be displayed as separate, individual metrics associated with the functions in your code. They can also be viewed collectively in the Graph window under Structure mode, so you can see the run-time performance of each function and call within the context of your program's overall calling structure. The process of importing profile data sources into your project consists of determining what data sources you need, appropriately compiling your source code, running your executable(s), and loading in the data sources. Optionally, you may use Surveyor to manage the profile data sources, thereby supporting incremental measurements.

Sources of Profile Data

Surveyor supports several sources of run-time profile data. For Unix executables, the tcov and the gprof databases can be generated using most native Unix compilers. For Windows executables, Surveyor accepts the profiler databases generated through the Microsoft Visual C++ compilers. Once the databases have been populated by running the executable, and some initial post-processing has been done on the platform where the executable runs, Surveyor is able to load tcov, gprof or profiler data regardless of which whether Surveyor itself is running under Unix or Windows. Your choice of which data source to generate and load will depend upon which metric you want to see:

Coverage shows how completely each function has been exercised.

Time shows how much time was spent in each function.

Frequency shows how often each function was executed.

Compiling to Enable Profile Data for Unix Executables

For both the tcov and gprof data sources, you need to set the appropriate flags when you compile your source code. This causes your compiler to prepare to capture profile data by instrumenting the executable code and by creating files to capture the profile results. For tcov, there is a different result (.d) file for each source file, while for gprof there is a single file (gmon.out) for the entire executable.

Normally, the corresponding flags you'll use are:

Certain of these compiler flags can not be set if you have set the -g flag. For more information about using the compiler flags, refer to the documentation for your compiler.

Compiling to Enable Profile Data for Windows Executables

To generate profiler information under Microsoft Visual C++, you need to build the project with profiling enabled. This can be done by checking the `Enable Profiling' checkbox on the Project Settings dialog / Link tab / General category.

If you wish to generate either of the two line types of profiler information, the executable must also be built with the appropriate debugging enabled. This can be done by checking the `Generate Debug Info' checkbox on the same Project Settings dialog / Link tab / General category, and then selecting `Line Numbers Only' or `Program Database' as the Debug Info type on the Project Settings dialog / C/C++ tab / General category.

Refer to your Microsoft Visual C++ User Guide for further information.

Generating Profile Data

After you've recompiled with the appropriate flags set, you'll need to exercise your software in order to generate the profile data for Surveyor to examine.

This is done by running your executable, using whatever test cases you wish to examine. As you run your executables, results are automatically captured into the .d and gmon.out files (Unix) or .pbt files (Windows).

If you're running Surveyor on the same platform where you ran your executables, Surveyor can collect the profile data directly from the resulting data files. Surveyor uses the native tools available on the platform, such as gprof or some of the Microsoft Visual C++ utilities, to help process the data files.

If however you wish to perform cross-platform analysis of the profile data, Surveyor is still able to load in the data. In this case, you need to do some initial processing of the run-time data files on the executable's native platform. Surveyor is then able import the intermediate results on whatever platform it is running on.

The post-processing necessary depends on the type of profile data you have generated. The appropriate commands can be issued from the command line.

No post-processing is necessary for tcov data (.d files). Refer to the gprof man page or your Microsoft Visual C++ User Guide for further information.

Importing Profile Data

You can use the "Add Data Source" dialog (MENU [File][Project Data][Add Data Source]) to load the data sources.

There are restrictions on the order in which you load the data sources. The program structure information (source_files, src_files_using_make, or msvc_project) must be added before the profile information. This is because Surveyor builds the Analysis mode information on top of the information it maintains about your software's functions and calling hierarchy. This is how, for example, Surveyor is able to convert tcov's file-related results into more meaningful function-related results. This also enables you to view each function's profile results as values in the Metrics tool.

If you are importing gprof or profiler data, and are running Surveyor on the platform where the executable ran, there are two choices for loading in the profile data. Use gprof_data_files or msvc_profile_data_file is you wish to import the raw data; use gprof_result_file or msvc_profile_result_file if you've already done the post-processing. If you are doing cross-platform development, you choice will be automatically limited to importing the post-processed results.

Invoke Context-Sensitive Help (KEY [F1]) to understand the details of the Add Data Sources dialog.

Managing Profile Data Files

Through the functions of the Manage Profile Data dialog, you're able to profile your executables across a series of test cases, store the results of the each run, and view the results for whichever run or combination of runs you're interested in.

This eliminates some of the complexity of dealing with the various profiling tools. For multiple (or incremental) runs, the tcov, gprof and MSVC profiler data collectors behave differently. With gprof and profiler, the data files are reset each time you run the executable. Therefore, at any point, gmon.out and executable.pdt contain just the profile data for your latest run. With tcov, the .d files are not reset. As you make multiple runs of your executable, the results accumulate.

One of the Manage Profile Data functions enables you to reinitialize all of the tcov data files before executing a test case. This causes the tcov data files to reflect just the results for the subsequent test runs. In this way, you can track and analyze the coverage associated with the individual test cases. Another function in the dialog saves the current contents of profile data or results files.

Using these functions, you can run a series of test cases, reinitializing tcov data before each run and recording the results after each run. Then, you can use the Manage Profile Data dialog to specify which results you want to view. You're able to view the results for any of the stored runs, either individually or in combination.

There are a number of ways that you might use these capabilities. If you wanted to analyze the impact that particular software changes have on the performance of your code, you could compare the results of the same test case on different versions of the software. Alternatively, you might analyze the completeness of your testing by looking at the combined coverage across a whole series of test cases. Or you might optimize your testing by determining the incremental coverage achieved by specific test cases.

For more information on how Surveyor, the automated code analyzer can help you solve your development issues, click on one of the links above or to the left.