10.2 Вызов gcov

gcov [options] files

gcov принимает следующие параметры:

-h

--help

Отобразить справку по использованию gcov (в стандартном выводе) и завершить работу без дальнейшей обработки.

-v

--version

Отобразить номер версии gcov (в стандартном выводе) и завершить работу без дальнейшей обработки.

-a

--all-blocks

Записать отдельные счетчики выполнения для каждого базового блока. Обычно gcov выводит счетчики выполнения только для основных блоков строки. С этим параметром можно определить, если блоки в одной строке не выполняются.

-b

--branch-probabilities

Записать частоты ветвлений в выходной файл и информацию о сводке ветвлений в стандартный вывод. Этот параметр позволяет увидеть, насколько часто каждая ветвь в вашей программе проходила. Неусловные ветви не будут отображаться, если не задан параметр -u.

-c

--branch-counts

Записывать частоты ветвлений в виде количества пройденных ветвей, а не процента пройденных ветвей.

-n

--no-output

Не создавать выходной файл gcov.

-l

--long-file-names

Создавать длинные имена файлов для включенных исходных файлов. Например, если заголовочный файл x.h содержит код и был включен в файл a.c, то запуск gcov на файле a.c создаст выходной файл, названный a.c##x.h.gcov, а не x.h.gcov. Это может быть полезно, если x.h включен в несколько исходных файлов, и вы хотите видеть отдельные вклады. Если вы используете параметр ‘-p’, имена как включающего, так и включаемого файла будут полными путями.

-p

--preserve-paths

Сохранять полную информацию о пути в именах сгенерированных файлов .gcov. Без этого параметра используется только имя файла. С этим параметром используются все каталоги, при этом символы ‘/’ переводятся в символы ‘#’, компоненты каталогов ‘.’ удаляются, а неудаляемые компоненты каталогов .. переименовываются в ‘^’. Это полезно, если исходные файлы находятся в нескольких разных каталогах.

-r

--relative-only

Выводить информацию только об исходных файлах с относительным путем (после удаления префикса исходного каталога). Абсолютные пути обычно используются для системных заголовочных файлов, и покрытие любых встроенных функций в них обычно не представляет интереса.

-f

--function-summaries

Выводить сводки для каждой функции в дополнение к сводке по файлу.

-o directory|file

--object-directory directory

--object-file file

Укажите либо каталог, содержащий файлы данных gcov, либо имя объекта. Файлы данных .gcno, и .gcda ищутся с помощью этого параметра. Если указан каталог, файлы данных находятся в этом каталоге и имеют имя, соответствующее имени входного файла без расширения. Если здесь указан файл, файлы данных имеют имя, соответствующее этому файлу без расширения.

-s directory

--source-prefix directory

Префикс для имен исходных файлов, который нужно удалить при создании выходных файлов покрытия. Этот параметр полезен при сборке в отдельном каталоге, и путь к исходному каталогу не требуется при определении имен выходных файлов. Обратите внимание, что этот префикс обнаруживается до определения, является ли исходный файл абсолютным.

-u

--unconditional-branches

При указании вероятностей ветвления включать вероятности безусловных ветвлений. Безусловные ветви обычно не представляют интереса.

-d

--display-progress

Отображать ход выполнения в стандартном выводе.

-i

--intermediate-format

Выходной файл gcov в легко анализируемом промежуточном текстовом формате, который может использоваться lcov или другими инструментами. Вывод — это один файл .gcov на каждый файл .gcda. Исходный код не требуется.

Формат промежуточного файла .gcov — это обычный текст с одной записью на строку

file:source_file_name
function:line_number,execution_count,function_name
lcount:line number,execution_count
branch:line_number,branch_coverage_type

Where the branch_coverage_type is
   notexec (Branch not executed)
   taken (Branch executed and taken)
   nottaken (Branch executed, but not taken)

There can be multiple file entries in an intermediate gcov
file. All entries following a file pertain to that source file
until the next file entry.

Вот пример, когда -i используется вместе с параметром -b:

file:array.cc
function:11,1,_Z3sumRKSt6vectorIPiSaIS0_EE
function:22,1,main
lcount:11,1
lcount:12,1
lcount:14,1
branch:14,taken
lcount:26,1
branch:28,nottaken

-m

--demangled-names

Отображать имена функций без искажений в выводе. По умолчанию отображаются искаженные имена функций.

gcov должен запускаться в той же текущей директории, что и при вызове компилятора. В противном случае он не сможет найти исходные файлы. gcov создаёт файлы, называемые mangledname.gcov в текущем каталоге. Они содержат информацию о покрытии соответствующего исходного файла. Один файл .gcov создаётся для каждого исходного (или заголовочного) файла, содержащего код, который был скомпилирован для создания файлов данных. Часть mangledname имени выходного файла обычно просто имя исходного файла, но может быть более сложной, если заданы параметры ‘-l’ или ‘-p’. Подробности см. в описании этих параметров.

Если вы вызываете gcov с несколькими входными файлами, contributions от каждого входного файла суммируются. Обычно вы вызываете его с тем же списком файлов, что и при конечном линковании вашего исполняемого файла.

Файлы .gcov содержат поля, разделённые ‘:’, а также исходный код программы. Формат

execution_count:line_number:source line text

Дополнительная информация о блоках может следовать за каждой строкой, если это запрошено параметром командной строки. execution_count равен ‘-’ для строк, не содержащих кода. Невыполненные строки отмечаются как ‘#####’ или ‘====’, в зависимости от того, достижимы ли они по обычным путям или только по исключительным, таким как обработчики исключений в C++, соответственно.

Некоторые строки информации в начале имеют line_number равным нулю. Эти строки преамбулы имеют вид

-:0:tag:value

Порядок и количество этих строк преамбулы будут дополняться по мере развития gcov — не полагайтесь на то, что они останутся неизменными. Используйте tag для поиска определенной строки преамбулы.

Дополнительная информация о блоках имеет вид

tag information

information удобочитаема, но разработана достаточно просто для машинного анализа тоже.

При выводе процентов, 0% и 100% выводятся только тогда, когда значения точно равны 0% и 100% соответственно. Другие значения, которые обычно округлялись до 0% или 100%, вместо этого выводятся как ближайшее не граничное значение.

При использовании gcov, вы должны сначала скомпилировать свою программу с двумя специальными параметрами GCC: ‘-fprofile-arcs -ftest-coverage’. Это сообщает компилятору генерировать дополнительную информацию, необходимую gcov (в основном граф потоков программы), и также включает дополнительный код в объектные файлы для генерации дополнительной информации о профилировании, необходимой gcov. Эти дополнительные файлы размещаются в каталоге, где находится объектный файл.

Запуск программы приведет к генерации профилирующего вывода. Для каждого исходного файла, скомпилированного с -fprofile-arcs, сопутствующий файл .gcda будет размещен в каталоге объектных файлов.

Запуск gcov с именами исходных файлов вашей программы в качестве аргументов теперь выведет список кода вместе с частотой выполнения для каждой строки. Например, если ваша программа называется tmp.c, вот что вы увидите при использовании базовой возможности gcov:

$ gcc -fprofile-arcs -ftest-coverage tmp.c
$ a.out
$ gcov tmp.c
90.00% of 10 source lines executed in file tmp.c
Creating tmp.c.gcov.

Файл tmp.c.gcov содержит вывод из gcov. Вот пример:

-:    0:Source:tmp.c
    -:    0:Graph:tmp.gcno
    -:    0:Data:tmp.gcda
    -:    0:Runs:1
    -:    0:Programs:1
    -:    1:#include <stdio.h>
    -:    2:
    -:    3:int main (void)
    1:    4:{
    1:    5:  int i, total;
    -:    6:
    1:    7:  total = 0;
    -:    8:
   11:    9:  for (i = 0; i < 10; i++)
   10:   10:    total += i;
    -:   11:
    1:   12:  if (total != 45)
#####:   13:    printf ("Failure\n");
    -:   14:  else
    1:   15:    printf ("Success\n");
    1:   16:  return 0;
    -:   17:}

Когда вы используете параметр -a, вы получите количество отдельных блоков, и вывод будет выглядеть так:

-:    0:Source:tmp.c
    -:    0:Graph:tmp.gcno
    -:    0:Data:tmp.gcda
    -:    0:Runs:1
    -:    0:Programs:1
    -:    1:#include <stdio.h>
    -:    2:
    -:    3:int main (void)
    1:    4:{
    1:    4-block  0
    1:    5:  int i, total;
    -:    6:
    1:    7:  total = 0;
    -:    8:
   11:    9:  for (i = 0; i < 10; i++)
   11:    9-block  0
   10:   10:    total += i;
   10:   10-block  0
    -:   11:
    1:   12:  if (total != 45)
    1:   12-block  0
#####:   13:    printf ("Failure\n");
$$$$$:   13-block  0
    -:   14:  else
    1:   15:    printf ("Success\n");
    1:   15-block  0
    1:   16:  return 0;
    1:   16-block  0
    -:   17:}

В этом режиме каждый базовый блок отображается только на одной строке — на последней строке блока. Многострочный блок будет вносить вклад только в счетчик выполнения последней строки, а другие строки не будут отображаться как содержащие код, если предыдущие блоки не заканчиваются на этих строках. Общее число выполнений строки отображается, а последующие строки отображают число выполнений для отдельных блоков, заканчивающихся на этой строке. После каждого блока будут отображаться счетчики ветвления и вызова блока, если задан параметр -b.

Из-за того, как GCC обрабатывает вызовы, счётчик вызовов может отображаться после строки без отдельных блоков. Как вы можете видеть, строка 13 содержит базовый блок, который не был выполнен.

Когда вы используете параметр -b, ваш вывод выглядит так:

$ gcov -b tmp.c
90.00% of 10 source lines executed in file tmp.c
80.00% of 5 branches executed in file tmp.c
80.00% of 5 branches taken at least once in file tmp.c
50.00% of 2 calls executed in file tmp.c
Creating tmp.c.gcov.

Вот пример результирующего файла tmp.c.gcov:

-:    0:Source:tmp.c
        -:    0:Graph:tmp.gcno
        -:    0:Data:tmp.gcda
        -:    0:Runs:1
        -:    0:Programs:1
        -:    1:#include <stdio.h>
        -:    2:
        -:    3:int main (void)
function main called 1 returned 1 blocks executed 75%
        1:    4:{
        1:    5:  int i, total;
        -:    6:
        1:    7:  total = 0;
        -:    8:
       11:    9:  for (i = 0; i < 10; i++)
branch  0 taken 91% (fallthrough)
branch  1 taken 9%
       10:   10:    total += i;
        -:   11:
        1:   12:  if (total != 45)
branch  0 taken 0% (fallthrough)
branch  1 taken 100%
    #####:   13:    printf ("Failure\n");
call    0 never executed
        -:   14:  else
        1:   15:    printf ("Success\n");
call    0 called 1 returned 100%
        1:   16:  return 0;
        -:   17:}

Для каждой функции выводится строка, показывающая, сколько раз функция вызывается, сколько раз она возвращается и какой процент блоков функции был выполнен.

Для каждого базового блока после последней строки базового блока печатается строка, описывающая ветвление или вызов, который завершает базовый блок. Если на одной строке исходного кода заканчивается несколько базовых блоков, то могут быть перечислены несколько ветвлений и вызовов. В этом случае ветвлениям и вызовам присваивается номер. Нет простого способа связать эти ветвления и вызовы обратно с конструкциями исходного кода. Однако, как правило, ветвление или вызов с наименьшим номером соответствует левой конструкции на строке исходного кода.

Для ветвления, если оно было выполнено хотя бы один раз, то выводится процент, указывающий отношение числа выполнений ветвления к числу выполнений ветвления. В противном случае выводится сообщение «никогда не выполнялось».

Для вызова, если он был выполнен хотя бы один раз, выводится процент, указывающий отношение числа возвратов вызова к числу выполнений вызова. Обычно это будет 100%, но может быть меньше для функций, которые вызывают exit или longjmp, и поэтому могут не возвращаться каждый раз при вызове.

Счетчики выполнения являются кумулятивными. Если пример программы будет запущен снова без удаления файла .gcda, число раз, когда каждая строка в исходном коде была выполнена, будет добавлено к результатам предыдущего запуска(ов). Это потенциально полезно несколькими способами. Например, это можно использовать для накопления данных в течение ряда запусков программы в рамках набора проверочных тестов или для получения более точной долгосрочной информации в течение большого числа запусков программы.

Данные в файлах .gcda сохраняются непосредственно перед завершением работы программы. Для каждого исходного файла, скомпилированного с помощью -fprofile-arcs, код профилирования сначала пытается прочитать существующий файл .gcda; если файл не соответствует исполняемому файлу (отличающееся количество базовых блоков), его содержимое игнорируется. Затем добавляются новые счётчики выполнения, и, наконец, данные записываются в файл.