CbC/CbC_gcc: gcc/doc/gcov.texi comparison

comparison gcc/doc/gcov.texi @ 145:1830386684a0

gcc-9.2.0

author	anatofuz
date	Thu, 13 Feb 2020 11:34:05 +0900
parents	84e7813d76e9
children

comparison

equal deleted inserted replaced

-:84e7813d76e9
+:1830386684a0
-@c Copyright (C) 1996-2018 Free Software Foundation, Inc.
+@c Copyright (C) 1996-2020 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 @ignore
 @c man begin COPYRIGHT
-Copyright @copyright{} 1996-2018 Free Software Foundation, Inc.
+Copyright @copyright{} 1996-2020 Free Software Foundation, Inc.
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with the
 Invariant Sections being ``GNU General Public License'' and ``Funding
 [@option{-a}|@option{--all-blocks}]
 [@option{-b}|@option{--branch-probabilities}]
 [@option{-c}|@option{--branch-counts}]
 [@option{-d}|@option{--display-progress}]
 [@option{-f}|@option{--function-summaries}]
-[@option{-i}|@option{--intermediate-format}]
+[@option{-i}|@option{--json-format}]
 [@option{-j}|@option{--human-readable}]
 [@option{-k}|@option{--use-colors}]
 [@option{-l}|@option{--long-file-names}]
 [@option{-m}|@option{--demangled-names}]
 [@option{-n}|@option{--no-output}]
 @itemx --help
 Display help about using @command{gcov} (on the standard output), and
 exit without doing any further processing.
 @item -i
-@itemx --intermediate-format
+@itemx --json-format
-Output gcov file in an easy-to-parse intermediate text format that can
+Output gcov file in an easy-to-parse JSON intermediate format
-be used by @command{lcov} or other tools. The output is a single
+which does not require source code for generation.  The JSON
-@file{.gcov} file per @file{.gcda} file. No source code is required.
+file is compressed with gzip compression algorithm
+and the files have @file{.gcov.json.gz} extension.
-The format of the intermediate @file{.gcov} file is plain text with
-one entry per line
+Structure of the JSON is following:
 @smallexample
-version:@var{gcc_version}
+@{
-cwd:@var{working_directory}
+"current_working_directory": @var{current_working_directory},
-file:@var{source_file_name}
+"data_file": @var{data_file},
-function:@var{start_line_number},@var{end_line_number},@var{execution_count},@var{function_name}
+"format_version": @var{format_version},
-lcount:@var{line number},@var{execution_count},@var{has_unexecuted_block}
+"gcc_version": @var{gcc_version}
-branch:@var{line_number},@var{branch_coverage_type}
+"files": [@var{file}]
+@}
-Where the @var{branch_coverage_type} is
+@end smallexample
-notexec (Branch not executed)
-taken (Branch executed and taken)
+Fields of the root element have following semantics:
-nottaken (Branch executed, but not taken)
-@end smallexample
+@itemize @bullet
+@item
-There can be multiple @var{file} entries in an intermediate gcov
+@var{current_working_directory}: working directory where
-file. All entries following a @var{file} pertain to that source file
+a compilation unit was compiled
-until the next @var{file} entry.  If there are multiple functions that
-start on a single line, then corresponding lcount is repeated multiple
+@item
-times.
+@var{data_file}: name of the data file (GCDA)
-Here is a sample when @option{-i} is used in conjunction with @option{-b} option:
+@item
+@var{format_version}: semantic version of the format
-@smallexample
-version: 8.1.0 20180103
+@item
-cwd:/home/gcc/testcase
+@var{gcc_version}: version of the GCC compiler
-file:tmp.cpp
+@end itemize
-function:7,7,0,_ZN3FooIcEC2Ev
-function:7,7,1,_ZN3FooIiEC2Ev
+Each @var{file} has the following form:
-function:8,8,0,_ZN3FooIcE3incEv
-function:8,8,2,_ZN3FooIiE3incEv
+@smallexample
-function:18,37,1,main
+@{
-lcount:7,0,1
+"file": @var{file_name},
-lcount:7,1,0
+"functions": [@var{function}],
-lcount:8,0,1
+"lines": [@var{line}]
-lcount:8,2,0
+@}
-lcount:18,1,0
+@end smallexample
-lcount:21,1,0
-branch:21,taken
+Fields of the @var{file} element have following semantics:
-branch:21,nottaken
-lcount:23,1,0
+@itemize @bullet
-branch:23,taken
+@item
-branch:23,nottaken
+@var{file_name}: name of the source file
-lcount:24,1,0
+@end itemize
-branch:24,taken
-branch:24,nottaken
+Each @var{function} has the following form:
-lcount:25,1,0
-lcount:27,11,0
+@smallexample
-branch:27,taken
+@{
-branch:27,taken
+"blocks": @var{blocks},
-lcount:28,10,0
+"blocks_executed": @var{blocks_executed},
-lcount:30,1,1
+"demangled_name": "@var{demangled_name},
-branch:30,nottaken
+"end_column": @var{end_column},
-branch:30,taken
+"end_line": @var{end_line},
-lcount:32,1,0
+"execution_count": @var{execution_count},
-branch:32,nottaken
+"name": @var{name},
-branch:32,taken
+"start_column": @var{start_column}
-lcount:33,0,1
+"start_line": @var{start_line}
-branch:33,notexec
+@}
-branch:33,notexec
+@end smallexample
-lcount:35,1,0
-branch:35,taken
+Fields of the @var{function} element have following semantics:
-branch:35,nottaken
-lcount:36,1,0
+@itemize @bullet
-@end smallexample
+@item
+@var{blocks}: number of blocks that are in the function
+@item
+@var{blocks_executed}: number of executed blocks of the function
+@item
+@var{demangled_name}: demangled name of the function
+@item
+@var{end_column}: column in the source file where the function ends
+@item
+@var{end_line}: line in the source file where the function ends
+@item
+@var{execution_count}: number of executions of the function
+@item
+@var{name}: name of the function
+@item
+@var{start_column}: column in the source file where the function begins
+@item
+@var{start_line}: line in the source file where the function begins
+@end itemize
+Note that line numbers and column numbers number from 1.  In the current
+implementation, @var{start_line} and @var{start_column} do not include
+any template parameters and the leading return type but that
+this is likely to be fixed in the future.
+Each @var{line} has the following form:
+@smallexample
+@{
+"branches": [@var{branch}],
+"count": @var{count},
+"line_number": @var{line_number},
+"unexecuted_block": @var{unexecuted_block}
+"function_name": @var{function_name},
+@}
+@end smallexample
+Branches are present only with @var{-b} option.
+Fields of the @var{line} element have following semantics:
+@itemize @bullet
+@item
+@var{count}: number of executions of the line
+@item
+@var{line_number}: line number
+@item
+@var{unexecuted_block}: flag whether the line contains an unexecuted block
+(not all statements on the line are executed)
+@item
+@var{function_name}: a name of a function this @var{line} belongs to
+(for a line with an inlined statements can be not set)
+@end itemize
+Each @var{branch} has the following form:
+@smallexample
+@{
+"count": @var{count},
+"fallthrough": @var{fallthrough},
+"throw": @var{throw}
+@}
+@end smallexample
+Fields of the @var{branch} element have following semantics:
+@itemize @bullet
+@item
+@var{count}: number of executions of the branch
+@item
+@var{fallthrough}: true when the branch is a fall through branch
+@item
+@var{throw}: true when the branch is an exceptional branch
+@end itemize
 @item -j
 @itemx --human-readable
 Write counts in human readable format (like 24.6k).
 @itemx --verbose
 Print verbose informations related to basic blocks and arcs.
 @item -x
 @itemx --hash-filenames
-By default, gcov uses the full pathname of the source files to create
+When using @var{--preserve-paths},
+gcov uses the full pathname of the source files to create
 an output filename.  This can lead to long filenames that can overflow
 filesystem limits.  This option creates names of the form
 @file{@var{source-file}##@var{md5}.gcov},
 where the @var{source-file} component is the final filename part and
 the @var{md5} component is calculated from the full mangled name that
-would have been used otherwise.
+would have been used otherwise.  The option is an alternative
+to the @var{--preserve-paths} on systems which have a filesystem limit.
 @end table
 @command{gcov} should be run with the current directory the same as that
 when you invoked the compiler.  Otherwise it will not be able to locate
 When printing percentages, 0% and 100% are only printed when the values
 are @emph{exactly} 0% and 100% respectively.  Other values which would
 conventionally be rounded to 0% or 100% are instead printed as the
 nearest non-boundary value.
-When using @command{gcov}, you must first compile your program with two
+When using @command{gcov}, you must first compile your program
-special GCC options: @samp{-fprofile-arcs -ftest-coverage}.
+with a special GCC option @samp{--coverage}.
 This tells the compiler to generate additional information needed by
 gcov (basically a flow graph of the program) and also includes
 additional code in the object files for generating the extra profiling
 information needed by gcov.  These additional files are placed in the
 directory where the object file is located.
 will now produce a listing of the code along with frequency of execution
 for each line.  For example, if your program is called @file{tmp.cpp}, this
 is what you see when you use the basic @command{gcov} facility:
 @smallexample
-$ g++ -fprofile-arcs -ftest-coverage tmp.cpp
+$ g++ --coverage tmp.cpp
 $ a.out
 $ gcov tmp.cpp -m
 File 'tmp.cpp'
 Lines executed:92.86% of 14
 Creating 'tmp.cpp.gcov'
 @node Gcov and Optimization
 @section Using @command{gcov} with GCC Optimization
 If you plan to use @command{gcov} to help optimize your code, you must
-first compile your program with two special GCC options:
+first compile your program with a special GCC option
-@samp{-fprofile-arcs -ftest-coverage}.  Aside from that, you can use any
+@samp{--coverage}.  Aside from that, you can use any
 other GCC options; but if you want to prove that every single line
 in your program was executed, you should not compile with optimization
 at the same time.  On some machines the optimizer can eliminate some
 simple code lines by combining them with other lines.  For example, code
 like this:
 this option.  It contains arc transition counts, value profile counts, and
 some summary information.
 It is not recommended to access the coverage files directly.
 Consumers should use the intermediate format that is provided
-by @command{gcov} tool via @option{--intermediate-format} option.
+by @command{gcov} tool via @option{--json-format} option.
 @node Cross-profiling
 @section Data File Relocation to Support Cross-Profiling
 Running the program will cause profile output to be generated.  For each

Mercurial > hg > CbC > CbC_gcc

comparison gcc/doc/gcov.texi @ 145:1830386684a0