30. Code Coverage and Profiling

This chapter describes how to use gcov - coverage testing tool - and gprof - profiler tool - on your Ada programs.

30.1 Code Coverage of Ada Programs using gcov
30.2 Profiling an Ada Program using gprof

30.1 Code Coverage of Ada Programs using gcov

gcov is a test coverage program: it analyzes the execution of a given program on selected tests, to help you determine the portions of the program that are still untested.

gcov is part of the GCC suite, and is described in detail in the GCC User's Guide. You can refer to this documentation for a more complete description.

This chapter provides a quick startup guide, and details some Gnat-specific features.

30.1.1 Quick startup guide
30.1.2 Gnat specifics

30.1.1 Quick startup guide

In order to perform coverage analysis of a program using gcov, 3 steps are needed:

• Code instrumentation during the compilation process
• Execution of the instrumented program
• Execution of the gcov tool to generate the result.

The code instrumentation needed by gcov is created at the object level: The source code is not modified in any way, because the instrumentation code is inserted by gcc during the compilation process. To compile your code with code coverage activated, you need to recompile your whole project using the switches -fprofile-arcs and -ftest-coverage, and link it using -fprofile-arcs.

$ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \ -largs -fprofile-arcs

This compilation process will create `.gcno' files together with the usual object files.

Once the program is compiled with coverage instrumentation, you can run it as many times as needed - on portions of a test suite for example. The first execution will produce `.gcda' files at the same location as the `.gcno' files. The following executions will update those files, so that a cumulative result of the covered portions of the program is generated.

Finally, you need to call the gcov tool. The different options of gcov are available in the GCC User's Guide, section 'Invoking gcov'.

This will create annotated source files with a `.gcov' extension: `my_main.adb' file will be analysed in `my_main.adb.gcov'.

30.1.2 Gnat specifics

Because Ada semantics, portions of the source code may be shared among several object files. This is the case for example when generics are involved, when inlining is active or when declarations generate initialisation calls. In order to take into account this shared code, you need to call gcov on all source files of the tested program at once.

The list of source files might exceed the system's maximum command line length. In order to bypass this limitation, a new mechanism has been implemented in gcov: you can now list all your project's files into a text file, and provide this file to gcov as a parameter, preceded by a @ (e.g. `gcov @mysrclist.txt').

Note that on AIX compiling a static library with -fprofile-arcs is not supported as there can be unresolved symbols during the final link.

30.2 Profiling an Ada Program using gprof

This section is not meant to be an exhaustive documentation of gprof. Full documentation for it can be found in the GNU Profiler User's Guide documentation that is part of this GNAT distribution.

Profiling a program helps determine the parts of a program that are executed most often, and are therefore the most time-consuming.

gprof is the standard GNU profiling tool; it has been enhanced to better handle Ada programs and multitasking. It is currently supported on the following platforms

• linux x86/x86_64
• solaris sparc/sparc64/x86
• windows x86

In order to profile a program using gprof, 3 steps are needed:

• Code instrumentation, requiring a full recompilation of the project with the proper switches.
• Execution of the program under the analysis conditions, i.e. with the desired input.
• Analysis of the results using the gprof tool.

The following sections detail the different steps, and indicate how to interpret the results:

30.2.1 Compilation for profiling
30.2.2 Program execution
30.2.3 Running gprof
30.2.4 Interpretation of profiling results

30.2.1 Compilation for profiling

In order to profile a program the first step is to tell the compiler to generate the necessary profiling information. The compiler switch to be used is -pg, which must be added to other compilation switches. This switch needs to be specified both during compilation and link stages, and can be specified once when using gnatmake:

gnatmake -f -pg -P my_project

Note that only the objects that were compiled with the `-pg' switch will be profiled; if you need to profile your whole project, use the `-f' gnatmake switch to force full recompilation.

30.2.2 Program execution

Once the program has been compiled for profiling, you can run it as usual.

The only constraint imposed by profiling is that the program must terminate normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be properly analyzed.

Once the program completes execution, a data file called `gmon.out' is generated in the directory where the program was launched from. If this file already exists, it will be overwritten.

30.2.3 Running gprof

The gprof tool is called as follow:

gprof my_prog gmon.out

or simpler:

gprof my_prog

The complete form of the gprof command line is the following:

gprof [switches] [executable [data-file]]

gprof supports numerous switch. The order of these switch does not matter. The full list of options can be found in the GNU Profiler User's Guide documentation that comes with this documentation.

The following is the subset of those switches that is most relevant:

`--demangle[=style]'

`--no-demangle'

These options control whether symbol names should be demangled when printing output. The default is to demangle C++ symbols. The --no-demangle option may be used to turn off demangling. Different compilers have different mangling styles. The optional demangling style argument can be used to choose an appropriate demangling style for your compiler, in particular Ada symbols generated by GNAT can be demangled using --demangle=gnat.

`-e function_name'

The `-e function' option tells gprof not to print information about the function function_name (and its children...) in the call graph. The function will still be listed as a child of any functions that call it, but its index number will be shown as `[not printed]'. More than one `-e' option may be given; only one function_name may be indicated with each `-e' option.

`-E function_name'

The -E function option works like the -e option, but execution time spent in the function (and children who were not called from anywhere else), will not be used to compute the percentages-of-time for the call graph. More than one `-E' option may be given; only one function_name may be indicated with each `-E' option.

`-f function_name'

The `-f function' option causes gprof to limit the call graph to the function function_name and its children (and their children...). More than one `-f' option may be given; only one function_name may be indicated with each `-f' option.

`-F function_name'

The `-F function' option works like the -f option, but only time spent in the function and its children (and their children...) will be used to determine total-time and percentages-of-time for the call graph. More than one `-F' option may be given; only one function_name may be indicated with each `-F' option. The `-F' option overrides the `-E' option.

30.2.4 Interpretation of profiling results

The results of the profiling analysis are represented by two arrays: the 'flat profile' and the 'call graph'. Full documentation of those outputs can be found in the GNU Profiler User's Guide.

The flat profile shows the time spent in each function of the program, and how many time it has been called. This allows you to locate easily the most time-consuming functions.

The call graph shows, for each subprogram, the subprograms that call it, and the subprograms that it calls. It also provides an estimate of the time spent in each of those callers/called subprograms.