10.2 Вызов gcov

gcov [options] files

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

-a

--all-blocks

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

-b

--branch-probabilities

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

-c

--branch-counts

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

-d

--display-progress

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

-f

--function-summaries

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

-h

--help

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

-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

-l

--long-file-names

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

-m

--demangled-names

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

-n

--no-output

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

-o directory|file

--object-directory directory

--object-file file

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

-p

--preserve-paths

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

-r

--relative-only

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

-s directory

--source-prefix directory

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

-u

--unconditional-branches

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

-v

--version

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

-w

--verbose

Выводить подробную информацию, связанную с базовыми блоками и дугами.

-x

--hash-filenames

По умолчанию gcov использует полный путь к исходным файлам для создания имени выходного файла. Это может привести к длинным именам файлов, которые могут превышать ограничения файловой системы. Этот параметр создаёт имена вида исходный-файл##md5.gcov, где исходный-файл — конечная часть имени файла, а md5 — вычислен из полного именованного имени, которое использовалось бы в противном случае.

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

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

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

execution_count:line_number:source line text

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

Обратите внимание, что GCC может полностью удалить тела функций, которые не нужны — например, если они встроены повсюду. Такие функции отмечаются ‘-’, что может быть запутанным. Используйте параметры -fkeep-inline-functions и -fkeep-static-functions, чтобы сохранить эти функции и позволить gcov правильно отобразить их execution_count.

Некоторые строки информации в начале имеют 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; если файл не соответствует исполняемому файлу (отличающееся число базовых блоков), он проигнорирует содержимое файла. Затем он добавляет новые счетчики выполнения и, наконец, записывает данные в файл.

Далее: Gcov и оптимизация, Предыдущее: Введение в Gcov, Выше: Gcov [Содержание][Индекс]