Gcov For Mac

Display gcov command-line options, and then exit.-l or -long-file-names Create long file names for included source files. For example, if x.h was included in a.c, then running gcov -l on a.c will produce a.c##x.h.gcov instead of x.h.gcov. This can be useful if x.h is included in multiple source files.n or -no-output Don't create the output. Its part of the GCC package from gnu. It's a nice Fortran compiler and the best part is it is free. If you've searched the web you know most Fortran compilers are pricey. The link above will let you access precompiled binaries for gfortran. The binaries are packaged as simple to install Mac.dmg files.

This is about how to run your C/C++ code using gcov to gather coverage metrics.

Note

These instructions have been tested on Mac OS X 10.9 (Mavericks).They may or may not work on other OS’s

gcov under Mac OS X¶

Configuring Xcode¶

This document tells you how to configure Xcode for gcov (actually llvm-cov).

Running and Analysing Code Coverage¶

In Xcode select Product->Run then once that has completed note the GCov_build directory in Xcode by selecting Products-><project> in the left hand pane. In the right hand pane under ‘Identity and Type’ you should see ‘Full Path’ of something like:

In the Terminal navigate to the ‘Build’ directory:

Now navigate to the Intermediates/ directory and in there you should find the code coverage data in a path such as this:

In there the interesting file has a .gcno extension. To convert this into something readable we need to run gcov on it. We can use xcrun to find gcov and this gives an overall code coverage number for each file (and its includes):

This has now generated a detailed file TimeBDT.cpp.gcov that contains line by line coverage:

The first snippet shows that line 210 is executed 6000000 times. In the second snippet the ##### shows that lines 290-293 have not executed at all.

Using gcov on CPython Extensions¶

Gcov For C++

Whilst it is common to track code coverage in Python test code it gets a bit more tricky with Cpython extensions as Python code coverage tools can not track C/C++ extension code. The solution is to use gcov and run the tests in a C/C++ process by embedding the Python interpreter.

Next: Gcov and Optimization, Previous: Gcov Intro, Up: Gcov [Contents][Index]

10.2 Invoking `gcov`

gcov accepts the following options:

-a

--all-blocks

Write individual execution counts for every basic block. Normally gcovoutputs execution counts only for the main blocks of a line. With thisoption you can determine if blocks within a single line are not beingexecuted.

-b

--branch-probabilities

Write branch frequencies to the output file, and write branch summaryinfo to the standard output. This option allows you to see how ofteneach branch in your program was taken. Unconditional branches will notbe shown, unless the -u option is given.

-c

--branch-counts

Write branch frequencies as the number of branches taken, rather thanthe percentage of branches taken.

-d

--display-progress

Display the progress on the standard output.

-f

--function-summaries

Output summaries for each function in addition to the file level summary.

-h

--help

Display help about using gcov (on the standard output), andexit without doing any further processing.

-j

--json-format

Output gcov file in an easy-to-parse JSON intermediate formatwhich does not require source code for generation. The JSONfile is compressed with gzip compression algorithmand the files have .gcov.json.gz extension.

Structure of the JSON is following:

Fields of the root element have following semantics:

current_working_directory: working directory wherea compilation unit was compiled
data_file: name of the data file (GCDA)
format_version: semantic version of the format
gcc_version: version of the GCC compiler

Each file has the following form:

Fields of the file element have following semantics:

file_name: name of the source file

Each function has the following form:

Fields of the function element have following semantics:

blocks: number of blocks that are in the function
blocks_executed: number of executed blocks of the function
demangled_name: demangled name of the function
end_column: column in the source file where the function ends
end_line: line in the source file where the function ends
execution_count: number of executions of the function
name: name of the function
start_column: column in the source file where the function begins
start_line: line in the source file where the function begins

Note that line numbers and column numbers number from 1. In the currentimplementation, start_line and start_column do not includeany template parameters and the leading return type but thatthis is likely to be fixed in the future.

Each line has the following form:

Branches are present only with -b option.Fields of the line element have following semantics:

count: number of executions of the line
line_number: line number
unexecuted_block: flag whether the line contains an unexecuted block(not all statements on the line are executed)
function_name: a name of a function this line belongs to(for a line with an inlined statements can be not set)

Each branch has the following form:

Fields of the branch element have following semantics:

count: number of executions of the branch
fallthrough: true when the branch is a fall through branch
throw: true when the branch is an exceptional branch

-H

--human-readable

Write counts in human readable format (like 24.6k).

-k

--use-colors

Use colors for lines of code that have zero coverage. We use red color fornon-exceptional lines and cyan for exceptional. Same colors are used forbasic blocks with -a option.

-l

--long-file-names

Create long file names for included source files. For example, if theheader file x.h contains code, and was included in the filea.c, then running gcov on the file a.c willproduce an output file called a.c##x.h.gcov instead ofx.h.gcov. This can be useful if x.h is included inmultiple source files and you want to see the individualcontributions. If you use the ‘-p’ option, both the includingand included file names will be complete path names.

-m

--demangled-names

Display demangled function names in output. The default is to showmangled function names.

-n

--no-output

Do not create the gcov output file.

-o directory|file

--object-directory directory

--object-file file

Specify either the directory containing the gcov data files, or theobject path name. The .gcno, and.gcda data files are searched for using this option. If a directoryis specified, the data files are in that directory and named after theinput file name, without its extension. If a file is specified here,the data files are named after that file, without its extension.

-p

--preserve-paths

Preserve complete path information in the names of generated.gcov files. Without this option, just the filename component isused. With this option, all directories are used, with ‘/’ characterstranslated to ‘#’ characters, . directory componentsremoved and unremoveable ..components renamed to ‘^’. This is useful if sourcefiles are in severaldifferent directories.

-q

--use-hotness-colors

Emit perf-like colored output for hot lines. Legend of the color scaleis printed at the very beginning of the output file.

-r

--relative-only

Only output information about source files with a relative pathname(after source prefix elision). Absolute paths are usually systemheader files and coverage of any inline functions therein is normallyuninteresting.

-s directory

--source-prefix directory

A prefix for source file names to remove when generating the outputcoverage files. This option is useful when building in a separatedirectory, and the pathname to the source directory is not wanted whendetermining the output file names. Note that this prefix detection isapplied before determining whether the source file is absolute.

-t

--stdout

Output to standard output instead of output files.

-u

--unconditional-branches

When branch probabilities are given, include those of unconditional branches.Unconditional branches are normally not interesting.

-v

--version

Display the gcov version number (on the standard output),and exit without doing any further processing.

-w

--verbose

Print verbose informations related to basic blocks and arcs.

-x

--hash-filenames

When using –preserve-paths,gcov uses the full pathname of the source files to createan output filename. This can lead to long filenames that can overflowfilesystem limits. This option creates names of the formsource-file##md5.gcov,where the source-file component is the final filename part andthe md5 component is calculated from the full mangled name thatwould have been used otherwise. The option is an alternativeto the –preserve-paths on systems which have a filesystem limit.

gcov should be run with the current directory the same as thatwhen you invoked the compiler. Otherwise it will not be able to locatethe source files. gcov produces files calledmangledname.gcov in the current directory. These containthe coverage information of the source file they correspond to.One .gcov file is produced for each source (or header) filecontaining code,which was compiled to produce the data files. The mangledname partof the output file name is usually simply the source file name, but canbe something more complicated if the ‘-l’ or ‘-p’ options aregiven. Refer to those options for details.

Gcov For Macbook

If you invoke gcov with multiple input files, thecontributions from each input file are summed. Typically you wouldinvoke it with the same list of files as the final link of your executable.

The .gcov files contain the ‘:’ separated fields along withprogram source code. The format is

Additional block information may succeed each line, when requested bycommand line option. The execution_count is ‘-’ for linescontaining no code. Unexecuted lines are marked ‘#####’ or‘’, depending on whether they are reachable bynon-exceptional paths or only exceptional paths such as C++ exceptionhandlers, respectively. Given the ‘-a’ option, unexecuted blocks aremarked ‘$$$$$’ or ‘%%%%%’, depending on whether a basic blockis reachable via non-exceptional or exceptional paths.Executed basic blocks having a statement with zero execution_countend with ‘*’ character and are colored with magenta color withthe -k option. This functionality is not supported in Ada.

Note that GCC can completely remove the bodies of functions that arenot needed – for instance if they are inlined everywhere. Such functionsare marked with ‘-’, which can be confusing.Use the -fkeep-inline-functions and -fkeep-static-functionsoptions to retain these functions andallow gcov to properly show their execution_count.

Some lines of information at the start have line_number of zero.These preamble lines are of the form

The ordering and number of these preamble lines will be augmented asgcov development progresses — do not rely on them remainingunchanged. Use tag to locate a particular preamble line.

The additional block information is of the form

The information is human readable, but designed to be simpleenough for machine parsing too.

When printing percentages, 0% and 100% are only printed when the valuesare exactly 0% and 100% respectively. Other values which wouldconventionally be rounded to 0% or 100% are instead printed as thenearest non-boundary value.

Gcov For Macbook Pro

When using gcov, you must first compile your programwith a special GCC option ‘--coverage’.This tells the compiler to generate additional information needed bygcov (basically a flow graph of the program) and also includesadditional code in the object files for generating the extra profilinginformation needed by gcov. These additional files are placed in thedirectory where the object file is located.

Running the program will cause profile output to be generated. For eachsource file compiled with -fprofile-arcs, an accompanying.gcda file will be placed in the object file directory.

Running gcov with your program’s source file names as argumentswill now produce a listing of the code along with frequency of executionfor each line. For example, if your program is called tmp.cpp, thisis what you see when you use the basic gcov facility:

The file tmp.cpp.gcov contains output from gcov.Here is a sample:

Note that line 7 is shown in the report multiple times. First occurrencepresents total number of execution of the line and the next two belongto instances of class Foo constructors. As you can also see, line 30 containssome unexecuted basic blocks and thus execution count has asterisk symbol.

When you use the -a option, you will get individual blockcounts, and the output looks like this:

In this mode, each basic block is only shown on one line – the lastline of the block. A multi-line block will only contribute to theexecution count of that last line, and other lines will not be shownto contain code, unless previous blocks end on those lines.The total execution count of a line is shown and subsequent lines showthe execution counts for individual blocks that end on that line. After eachblock, the branch and call counts of the block will be shown, if the-b option is given.

Because of the way GCC instruments calls, a call count can be shownafter a line with no individual blocks.As you can see, line 33 contains a basic block that was not executed.

When you use the -b option, your output looks like this:

For each function, a line is printed showing how many times the functionis called, how many times it returns and what percentage of thefunction’s blocks were executed.

For each basic block, a line is printed after the last line of the basicblock describing the branch or call that ends the basic block. There canbe multiple branches and calls listed for a single source line if thereare multiple basic blocks that end on that line. In this case, thebranches and calls are each given a number. There is no simple way to mapthese branches and calls back to source constructs. In general, though,the lowest numbered branch or call will correspond to the leftmost constructon the source line.

For a branch, if it was executed at least once, then a percentageindicating the number of times the branch was taken divided by thenumber of times the branch was executed will be printed. Otherwise, themessage “never executed” is printed.

Install Lcov Mac

For a call, if it was executed at least once, then a percentageindicating the number of times the call returned divided by the numberof times the call was executed will be printed. This will usually be100%, but may be less for functions that call exit or longjmp,and thus may not return every time they are called.

Gcov Format

The execution counts are cumulative. If the example program wereexecuted again without removing the .gcda file, the count for thenumber of times each line in the source was executed would be added tothe results of the previous run(s). This is potentially useful inseveral ways. For example, it could be used to accumulate data over anumber of program runs as part of a test verification suite, or toprovide more accurate long-term information over a large number ofprogram runs.

The data in the .gcda files is saved immediately before the programexits. For each source file compiled with -fprofile-arcs, theprofiling code first attempts to read in an existing .gcda file; ifthe file doesn’t match the executable (differing number of basic blockcounts) it will ignore the contents of the file. It then adds in thenew execution counts and finally writes the data to the file.

Gcov For Mac Os