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
File 'tmp.c'
Lines executed:90.00% of 10
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
File 'tmp.c'
Lines executed:90.00% of 10
Branches executed:80.00% of 5
Taken at least once:80.00% of 5
Calls executed:50.00% of 2
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 [Оглавление][Индекс]