diff options
Diffstat (limited to 'third_party/lcov/man')
| -rw-r--r-- | third_party/lcov/man/gendesc.1 | 78 | ||||
| -rw-r--r-- | third_party/lcov/man/genhtml.1 | 461 | ||||
| -rw-r--r-- | third_party/lcov/man/geninfo.1 | 323 | ||||
| -rw-r--r-- | third_party/lcov/man/genpng.1 | 101 | ||||
| -rw-r--r-- | third_party/lcov/man/lcov.1 | 557 | ||||
| -rw-r--r-- | third_party/lcov/man/lcovrc.5 | 557 |
6 files changed, 2077 insertions, 0 deletions
diff --git a/third_party/lcov/man/gendesc.1 b/third_party/lcov/man/gendesc.1 new file mode 100644 index 0000000..e1fb38a --- /dev/null +++ b/third_party/lcov/man/gendesc.1 @@ -0,0 +1,78 @@ +.TH gendesc 1 "LCOV 1.7" 2008\-11\-17 "User Manuals" +.SH NAME +gendesc \- Generate a test case description file +.SH SYNOPSIS +.B gendesc +.RB [ \-h | \-\-help ] +.RB [ \-v | \-\-version ] +.RS 8 +.br +.RB [ \-o | \-\-output\-filename +.IR filename ] +.br +.I inputfile +.SH DESCRIPTION +Convert plain text test case descriptions into a format as understood by +.BR genhtml . +.I inputfile +needs to observe the following format: + +For each test case: +.IP " \-" +one line containing the test case name beginning at the start of the line +.RE +.IP " \-" +one or more lines containing the test case description indented with at +least one whitespace character (tab or space) +.RE + +.B Example input file: + +test01 +.RS +An example test case description. +.br +Description continued +.RE + +test42 +.RS +Supposedly the answer to most of your questions +.RE + +Note: valid test names can consist of letters, decimal digits and the +underscore character ('_'). +.SH OPTIONS +.B \-h +.br +.B \-\-help +.RS +Print a short help text, then exit. +.RE + +.B \-v +.br +.B \-\-version +.RS +Print version number, then exit. +.RE + + +.BI "\-o " filename +.br +.BI "\-\-output\-filename " filename +.RS +Write description data to +.IR filename . + +By default, output is written to STDOUT. +.RE +.SH AUTHOR +Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com> + +.SH SEE ALSO +.BR lcov (1), +.BR genhtml (1), +.BR geninfo (1), +.BR genpng (1), +.BR gcov (1) diff --git a/third_party/lcov/man/genhtml.1 b/third_party/lcov/man/genhtml.1 new file mode 100644 index 0000000..e99c642 --- /dev/null +++ b/third_party/lcov/man/genhtml.1 @@ -0,0 +1,461 @@ +.TH genhtml 1 "LCOV 1.7" 2008\-11\-17 "User Manuals" +.SH NAME +genhtml \- Generate HTML view from LCOV coverage data files +.SH SYNOPSIS +.B genhtml +.RB [ \-h | \-\-help ] +.RB [ \-v | \-\-version ] +.RS 8 +.br +.RB [ \-q | \-\-quiet ] +.RB [ \-s | \-\-show\-details ] +.RB [ \-f | \-\-frames ] +.br +.RB [ \-b | \-\-baseline\-file ] +.IR baseline\-file +.br +.RB [ \-o | \-\-output\-directory +.IR output\-directory ] +.br +.RB [ \-t | \-\-title +.IR title ] +.br +.RB [ \-d | \-\-description\-file +.IR description\-file ] +.br +.RB [ \-k | \-\-keep\-descriptions ] +.RB [ \-c | \-\-css\-file +.IR css\-file ] +.br +.RB [ \-p | \-\-prefix +.IR prefix ] +.RB [ \-\-no\-prefix ] +.br +.RB [ \-\-no\-source ] +.RB [ \-\-num\-spaces +.IR num ] +.RB [ \-\-highlight ] +.br +.RB [ \-\-legend ] +.RB [ \-\-html\-prolog +.IR prolog\-file ] +.br +.RB [ \-\-html\-epilog +.IR epilog\-file ] +.RB [ \-\-html\-extension +.IR extension ] +.br +.RB [ \-\-html\-gzip ] +.RB [ \-\-sort ] +.RB [ \-\-no\-sort ] +.br +.RB [ \-\-function\-coverage ] +.RB [ \-\-no\-function\-coverage ] +.br +.IR tracefile(s) +.RE +.SH DESCRIPTION +Create an HTML view of coverage data found in +.IR tracefile . +Note that +.I tracefile +may also be a list of filenames. + +HTML output files are created in the current working directory unless the +\-\-output\-directory option is used. If +.I tracefile +ends with ".gz", it is assumed to be GZIP\-compressed and the gunzip tool +will be used to decompress it transparently. + +Note that all source code files have to be present and readable at the +exact file system location they were compiled. + +Use option +.I \--css\-file +to modify layout and colors of the generated HTML output. Files are +marked in different colors depending on the associated coverage rate. By +default, the coverage limits for low, medium and high coverage are set to +0\-15%, 15\-50% and 50\-100% percent respectively. To change these +values, use configuration file options +.IR genhtml_hi_limit " and " genhtml_med_limit . + +.SH OPTIONS +.B \-h +.br +.B \-\-help +.RS +Print a short help text, then exit. + +.RE +.B \-v +.br +.B \-\-version +.RS +Print version number, then exit. + +.RE +.B \-q +.br +.B \-\-quiet +.RS +Do not print progress messages. + +Suppresses all informational progress output. When this switch is enabled, +only error or warning messages are printed. + +.RE +.B \-f +.br +.B \-\-frames +.RS +Use HTML frames for source code view. + +If enabled, a frameset is created for each source code file, providing +an overview of the source code as a "clickable" image. Note that this +option will slow down output creation noticeably because each source +code character has to be inspected once. Note also that the GD.pm PERL +module has to be installed for this option to work (it may be obtained +from http://www.cpan.org). + +.RE +.B \-s +.br +.B \-\-show\-details +.RS +Generate detailed directory view. + +When this option is enabled, +.B genhtml +generates two versions of each +file view. One containing the standard information plus a link to a +"detailed" version. The latter additionally contains information about +which test case covered how many lines of each source file. + +.RE +.BI "\-b " baseline\-file +.br +.BI "\-\-baseline\-file " baseline\-file +.RS +Use data in +.I baseline\-file +as coverage baseline. + +The tracefile specified by +.I baseline\-file +is read and all counts found in the original +.I tracefile +are decremented by the corresponding counts in +.I baseline\-file +before creating any output. + +Note that when a count for a particular line in +.I baseline\-file +is greater than the count in the +.IR tracefile , +the result is zero. + +.RE +.BI "\-o " output\-directory +.br +.BI "\-\-output\-directory " output\-directory +.RS +Create files in +.I output\-directory. + +Use this option to tell +.B genhtml +to write the resulting files to a directory other than +the current one. If +.I output\-directory +does not exist, it will be created. + +It is advisable to use this option since depending on the +project size, a lot of files and subdirectories may be created. + +.RE +.BI "\-t " title +.br +.BI "\-\-title " title +.RS +Display +.I title +in header of all pages. + +.I title +is written to the header portion of each generated HTML page to +identify the context in which a particular output +was created. By default this is the name of the tracefile. + +.RE +.BI "\-d " description\-file +.br +.BI "\-\-description\-file " description\-file +.RS +Read test case descriptions from +.IR description\-file . + +All test case descriptions found in +.I description\-file +and referenced in the input data file are read and written to an extra page +which is then incorporated into the HTML output. + +The file format of +.IR "description\-file " is: + +for each test case: +.RS +TN:<testname> +.br +TD:<test description> + +.RE + +Valid test case names can consist of letters, numbers and the underscore +character ('_'). +.RE +.B \-k +.br +.B \-\-keep\-descriptions +.RS +Do not remove unused test descriptions. + +Keep descriptions found in the description file even if the coverage data +indicates that the associated test case did not cover any lines of code. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_keep_descriptions . + +.RE +.BI "\-c " css\-file +.br +.BI "\-\-css\-file " css\-file +.RS +Use external style sheet file +.IR css\-file . + +Using this option, an extra .css file may be specified which will replace +the default one. This may be helpful if the default colors make your eyes want +to jump out of their sockets :) + +This option can also be configured permanently using the configuration file +option +.IR genhtml_css_file . + +.RE +.BI "\-p " prefix +.br +.BI "\-\-prefix " prefix +.RS +Remove +.I prefix +from all directory names. + +Because lists containing long filenames are difficult to read, there is a +mechanism implemented that will automatically try to shorten all directory +names on the overview page beginning with a common prefix. By default, +this is done using an algorithm that tries to find the prefix which, when +applied, will minimize the resulting sum of characters of all directory +names. + +Use this option to specify the prefix to be removed by yourself. + +.RE +.B \-\-no\-prefix +.RS +Do not remove prefix from directory names. + +This switch will completely disable the prefix mechanism described in the +previous section. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_no_prefix . + +.RE +.B \-\-no\-source +.RS +Do not create source code view. + +Use this switch if you don't want to get a source code view for each file. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_no_source . + +.RE +.BI "\-\-num\-spaces " spaces +.RS +Replace tabs in source view with +.I num +spaces. + +Default value is 8. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_num_spaces . + +.RE +.B \-\-highlight +.RS +Highlight lines with converted\-only coverage data. + +Use this option in conjunction with the \-\-diff option of +.B lcov +to highlight those lines which were only covered in data sets which were +converted from previous source code versions. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_highlight . + +.RE +.B \-\-legend +.RS +Include color legend in HTML output. + +Use this option to include a legend explaining the meaning of color coding +in the resulting HTML output. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_legend . + +.RE +.BI "\-\-html\-prolog " prolog\-file +.RS +Read customized HTML prolog from +.IR prolog\-file . + +Use this option to replace the default HTML prolog (the initial part of the +HTML source code leading up to and including the <body> tag) with the contents +of +.IR prolog\-file . +Within the prolog text, the following words will be replaced when a page is generated: + +.B "@pagetitle@" +.br +The title of the page. + +.B "@basedir@" +.br +A relative path leading to the base directory (e.g. for locating css\-files). + +This option can also be configured permanently using the configuration file +option +.IR genhtml_html_prolog . + +.RE +.BI "\-\-html\-epilog " epilog\-file +.RS +Read customized HTML epilog from +.IR epilog\-file . + +Use this option to replace the default HTML epilog (the final part of the HTML +source including </body>) with the contents of +.IR epilog\-file . + +Within the epilog text, the following words will be replaced when a page is generated: + +.B "@basedir@" +.br +A relative path leading to the base directory (e.g. for locating css\-files). + +This option can also be configured permanently using the configuration file +option +.IR genhtml_html_epilog . + +.RE +.BI "\-\-html\-extension " extension +.RS + +Use customized filename extension for generated HTML pages. + +This option is useful in situations where different filename extensions +are required to render the resulting pages correctly (e.g. php). Note that +a '.' will be inserted between the filename and the extension specified by +this option. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_html_extension . +.RE + +.B \-\-html\-gzip +.RS + +Compress all generated html files with gzip and add a .htaccess file specifying +gzip\-encoding in the root output directory. + +Use this option if you want to save space on your webserver. Requires a +webserver with .htaccess support and a browser with support for gzip +compressed html. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_html_gzip . + +.RE +.B \-\-sort +.br +.B \-\-no\-sort +.RS +Specify whether to include sorted views of file and directory overviews. + +Use \-\-sort to include sorted views or \-\-no\-sort to not include them. +Sorted views are +.B enabled +by default. + +When sorted views are enabled, each overview page will contain links to +views of that page sorted by coverage rate. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_sort . + +.RE +.B \-\-function\-coverage +.br +.B \-\-no\-function\-coverage +.RS +Specify whether to display function coverage summaries in HTML output. + +Use \-\-function\-coverage to enable function coverage summaries or +\-\-no\-function\-coverage to disable it. Function coverage summaries are +.B enabled +by default + +When function coverage summaries are enabled, each overview page will contain +the number of functions found and hit per file or directory, together with +the resulting coverage rate. In addition, each source code view will contain +a link to a page which lists all functions found in that file plus the +respective call count for those functions. + +This option can also be configured permanently using the configuration file +option +.IR genhtml_function_coverage . + +.RE +.SH FILES + +.I /etc/lcovrc +.RS +The system\-wide configuration file. +.RE + +.I ~/.lcovrc +.RS +The per\-user configuration file. +.RE + +.SH AUTHOR +Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com> + +.SH SEE ALSO +.BR lcov (1), +.BR geninfo (1), +.BR genpng (1), +.BR gendesc (1), +.BR gcov (1) diff --git a/third_party/lcov/man/geninfo.1 b/third_party/lcov/man/geninfo.1 new file mode 100644 index 0000000..47fcfa3 --- /dev/null +++ b/third_party/lcov/man/geninfo.1 @@ -0,0 +1,323 @@ +.TH geninfo 1 "LCOV 1.7" 2008\-11\-17 "User Manuals" +.SH NAME +geninfo \- Generate tracefiles from .da files +.SH SYNOPSIS +.B geninfo +.RB [ \-h | \-\-help ] +.RB [ \-v | \-\-version ] +.RB [ \-q | \-\-quiet ] +.br +.RS 8 +.RB [ \-i | \-\-initial ] +.RB [ \-t | \-\-test\-name +.IR test\-name ] +.br +.RB [ \-o | \-\-output\-filename +.IR filename ] +.RB [ \-f | \-\-follow ] +.br +.RB [ \-b | \-\-base\-directory +.IR directory ] +.br +.RB [ \-\-checksum ] +.RB [ \-\-no\-checksum ] +.br +.RB [ \-\-compat\-libtool ] +.RB [ \-\-no\-compat\-libtool ] +.br +.RB [ \-\-gcov\-tool +.IR tool ] +.RB [ \-\-ignore\-errors +.IR errors ] +.br +.RB [ \-\-no\-recursion ] +.I directory +.RE +.SH DESCRIPTION +.B geninfo +converts all GCOV coverage data files found in +.I directory +into tracefiles, which the +.B genhtml +tool can convert to HTML output. + +Unless the \-\-output\-filename option is specified, +.B geninfo +writes its +output to one file per .da file, the name of which is generated by simply +appending ".info" to the respective .da file name. + +Note that the current user needs write access to both +.I directory +as well as to the original source code location. This is necessary because +some temporary files have to be created there during the conversion process. + +Note also that +.B geninfo +is called from within +.BR lcov , +so that there is usually no need to call it directly. +.SH OPTIONS + +.B \-b +.I directory +.br +.B \-\-base\-directory +.I directory +.br +.RS +.RI "Use " directory +as base directory for relative paths. + +Use this option to specify the base directory of a build\-environment +when geninfo produces error messages like: + +.RS +ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c +.RE + +In this example, use /home/user/project as base directory. + +This option is required when using geninfo on projects built with libtool or +similar build environments that work with a base directory, i.e. environments, +where the current working directory when invoking the compiler is not the same +directory in which the source code file is located. + +Note that this option will not work in environments where multiple base +directories are used. In that case repeat the geninfo call for each base +directory while using the \-\-ignore\-errors option to prevent geninfo from +exiting when the first source code file could not be found. This way you can +get partial coverage information for each base directory which can then be +combined using the \-a option. +.RE + +.B \-\-checksum +.br +.B \-\-no\-checksum +.br +.RS +Specify whether to generate checksum data when writing tracefiles. + +Use \-\-checksum to enable checksum generation or \-\-no\-checksum to +disable it. Checksum generation is +.B disabled +by default. + +When checksum generation is enabled, a checksum will be generated for each +source code line and stored along with the coverage data. This checksum will +be used to prevent attempts to combine coverage data from different source +code versions. + +If you don't work with different source code versions, disable this option +to speed up coverage data processing and to reduce the size of tracefiles. +.RE + +.B \-\-compat\-libtool +.br +.B \-\-no\-compat\-libtool +.br +.RS +Specify whether to enable libtool compatibility mode. + +Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-libtool +to disable it. The libtool compatibility mode is +.B enabled +by default. + +When libtool compatibility mode is enabled, geninfo will assume that the source +code relating to a .da file located in a directory named ".libs" can be +found in its parent directory. + +If you have directories named ".libs" in your build environment but don't use +libtool, disable this option to prevent problems when capturing coverage data. +.RE + +.B \-f +.br +.B \-\-follow +.RS +Follow links when searching .da files. +.RE + +.B \-\-gcov\-tool +.I tool +.br +.RS +Specify the location of the gcov tool. +.RE + +.B \-h +.br +.B \-\-help +.RS +Print a short help text, then exit. +.RE + +.B \-\-ignore\-errors +.I errors +.br +.RS +Specify a list of errors after which to continue processing. + +Use this option to specify a list of one or more classes of errors after which +geninfo should continue processing instead of aborting. + +.I errors +can be a comma\-separated list of the following keywords: + +.B gcov: +the gcov tool returned with a non\-zero return code. + +.B source: +the source code file for a data set could not be found. +.RE + +.B \-i +.br +.B \-\-initial +.RS +Capture initial zero coverage data. + +Run geninfo with this option on the directories containing .bb, .bbg or .gcno +files before running any test case. The result is a "baseline" coverage data +file that contains zero coverage for every instrumented line. Combine this +data file (using lcov \-a) with coverage data files captured after a test +run to ensure that the percentage of total lines covered is correct even +when not all source code files were loaded during the test. +.RE + +.B \-\-no\-recursion +.br +.RS +Use this option if you want to get coverage data for the specified directory +only without processing subdirectories. +.RE + +.BI "\-o " output\-filename +.br +.BI "\-\-output\-filename " output\-filename +.RS +Write all data to +.IR output\-filename . + +If you want to have all data written to a single file (for easier +handling), use this option to specify the respective filename. By default, +one tracefile will be created for each processed .da file. +.RE + +.B \-q +.br +.B \-\-quiet +.RS +Do not print progress messages. + +Suppresses all informational progress output. When this switch is enabled, +only error or warning messages are printed. +.RE + +.BI "\-t " testname +.br +.BI "\-\-test\-name " testname +.RS +Use test case name +.I testname +for resulting data. Valid test case names can consist of letters, decimal +digits and the underscore character ('_'). + +This proves useful when data from several test cases is merged (i.e. by +simply concatenating the respective tracefiles) in which case a test +name can be used to differentiate between data from each test case. +.RE + +.B \-v +.br +.B \-\-version +.RS +Print version number, then exit. +.RE + + +.SH FILES + +.I /etc/lcovrc +.RS +The system\-wide configuration file. +.RE + +.I ~/.lcovrc +.RS +The per\-user configuration file. +.RE + +Following is a quick description of the tracefile format as used by +.BR genhtml ", " geninfo " and " lcov . + +A tracefile is made up of several human\-readable lines of text, +divided into sections. If available, a tracefile begins with the +.I testname +which is stored in the following format: + + TN:<test name> + +For each source file referenced in the .da file, there is a section containing +filename and coverage data: + + SF:<absolute path to the source file> + +Following is a list of line numbers for each function name found in the +source file: + + FN:<line number of function start>,<function name> + +Next, there is a list of execution counts for each instrumented function: + + FNDA:<execution count>,<function name> + +This list is followed by two lines containing the number of functions found +and hit: + + FNF:<number of functions found> + FNH:<number of function hit> + +Then there is a list of execution counts for each instrumented line +(i.e. a line which resulted in executable code): + + DA:<line number>,<execution count>[,<checksum>] + +Note that there may be an optional checksum present for each instrumented +line. The current +.B geninfo +implementation uses an MD5 hash as checksumming algorithm. + +At the end of a section, there is a summary about how many lines +were found and how many were actually instrumented: + + LH:<number of lines with a non\-zero execution count> + LF:<number of instrumented lines> + +Each sections ends with: + + end_of_record + +In addition to the main source code file there are sections for all +#included files which also contain executable code. + +Note that the absolute path of a source file is generated by interpreting +the contents of the respective .bb file (see +.BR "gcov " (1) +for more information on this file type). Relative filenames are prefixed +with the directory in which the .bb file is found. + +Note also that symbolic links to the .bb file will be resolved so that the +actual file path is used instead of the path to a link. This approach is +necessary for the mechanism to work with the /proc/gcov files. + +.SH AUTHOR +Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com> + +.SH SEE ALSO +.BR lcov (1), +.BR genhtml (1), +.BR genpng (1), +.BR gendesc (1), +.BR gcov (1) diff --git a/third_party/lcov/man/genpng.1 b/third_party/lcov/man/genpng.1 new file mode 100644 index 0000000..147a25d --- /dev/null +++ b/third_party/lcov/man/genpng.1 @@ -0,0 +1,101 @@ +.TH genpng 1 "LCOV 1.7" 2008\-11\-17 "User Manuals" +.SH NAME +genpng \- Generate an overview image from a source file +.SH SYNOPSIS +.B genpng +.RB [ \-h | \-\-help ] +.RB [ \-v | \-\-version ] +.RS 7 +.br +.RB [ \-t | \-\-tab\-size +.IR tabsize ] +.RB [ \-w | \-\-width +.IR width ] +.br +.RB [ \-o | \-\-output\-filename +.IR output\-filename ] +.br +.IR source\-file +.SH DESCRIPTION +.B genpng +creates an overview image for a given source code file of either +plain text or .gcov file format. + +Note that the +.I GD.pm +PERL module has to be installed for this script to work +(it may be obtained from +.IR http://www.cpan.org ). + +Note also that +.B genpng +is called from within +.B genhtml +so that there is usually no need to call it directly. + +.SH OPTIONS +.B \-h +.br +.B \-\-help +.RS +Print a short help text, then exit. +.RE + +.B \-v +.br +.B \-\-version +.RS +Print version number, then exit. +.RE + +.BI "\-t " tab\-size +.br +.BI "\-\-tab\-size " tab\-size +.RS +Use +.I tab\-size +spaces in place of tab. + +All occurrences of tabulator signs in the source code file will be replaced +by the number of spaces defined by +.I tab\-size +(default is 4). +.RE + +.BI "\-w " width +.br +.BI "\-\-width " width +.RS +Set width of output image to +.I width +pixel. + +The resulting image will be exactly +.I width +pixel wide (default is 80). + +Note that source code lines which are longer than +.I width +will be truncated. +.RE + + +.BI "\-o " filename +.br +.BI "\-\-output\-filename " filename +.RS +Write image to +.IR filename . + +Specify a name for the resulting image file (default is +.IR source\-file .png). +.RE +.SH AUTHOR +Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com> + +.SH SEE ALSO +.BR lcov (1), +.BR genhtml (1), +.BR geninfo (1), +.BR gendesc (1), +.BR gcov (1) diff --git a/third_party/lcov/man/lcov.1 b/third_party/lcov/man/lcov.1 new file mode 100644 index 0000000..aa30fb8 --- /dev/null +++ b/third_party/lcov/man/lcov.1 @@ -0,0 +1,557 @@ +.TH lcov 1 "LCOV 1.7" 2008\-11\-17 "User Manuals" +.SH NAME +lcov \- a graphical GCOV front\-end +.SH SYNOPSIS +.B lcov +.RB [ \-h | \-\-help ] +.RB [ \-v | \-\-version ] +.RB [ \-q | \-\-quiet ] +.RS 5 +.br +.RB [ \-z | \-\-zerocounters ] +.RB [ \-c | \-\-capture ] +.br +.RB [ \-a | \-\-add\-tracefile +.IR tracefile ] +.br +.RB [ \-e | \-\-extract +.IR tracefile ] +.br +.RB [ \-r | \-\-remove +.IR tracefile ] +.br +.RB [ \-l | \-\-list +.IR tracefile ] +.br +.RB [ \-\-diff +.IR "tracefile diff" ] +.br +.RB [ \-i | \-\-initial ] +.RB [ \-t | \-\-test\-name +.IR testname ] +.br +.RB [ \-o | \-\-output\-file +.IR filename ] +.br +.RB [ \-d | \-\-directory +.IR directory ] +.br +.RB [ \-f | \-\-follow ] +.br +.RB [ \-k | \-\-kernel\-directory +.IR directory ] +.br +.RB [ \-b | \-\-base\-directory +.IR directory ] +.br +.RB [ \-\-convert\-filenames ] +.RB [ \-\-strip +.IR depth ] +.RB [ \-\-path +.IR path ] +.br +.RB [ \-\-checksum ] +.RB [ \-\-no\-checksum ] +.br +.RB [ \-\-compat\-libtool ] +.RB [ \-\-no\-compat\-libtool ] +.br +.RB [ \-\-gcov\-tool +.IR tool ] +.RB [ \-\-ignore\-errors +.IR errors ] +.br +.RB [ \-\-no\-recursion ] +.SH DESCRIPTION +.B lcov +is a graphical front\-end for GCC's coverage testing tool gcov. It collects +gcov data for multiple source files and creates HTML pages containing the +source code annotated with coverage information. It also adds overview pages +for easy navigation within the file structure. + +Use +.B lcov +to collect coverage data and +.B genhtml +to create HTML pages. Coverage data can either be collected from the +currently running Linux kernel or from a user space application. To do this, +you have to complete the following preparation steps: + +For Linux kernel coverage: +.RS +Follow the installation instructions for the gcov\-kernel patch: +.I http://ltp.sourceforge.net/coverage/gcov.php + +.RE +For user space application coverage: +.RS +Compile the application with GCC using the options +"\-fprofile\-arcs" and "\-ftest\-coverage". +.RE + +Please note that this man page refers to the output format of +.B lcov +as ".info file" or "tracefile" and that the output of GCOV +is called ".da file". +.SH OPTIONS + + +.B \-a +.I tracefile +.br +.B \-\-add\-tracefile +.I tracefile +.br +.RS +Add contents of +.IR tracefile . + +Specify several tracefiles using the \-a switch to combine the coverage data +contained in these files by adding up execution counts for matching test and +filename combinations. + +The result of the add operation will be written to stdout or the tracefile +specified with \-o. + +Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified +at a time. + +.RE + +.B \-b +.I directory +.br +.B \-\-base\-directory +.I directory +.br +.RS +.RI "Use " directory +as base directory for relative paths. + +Use this option to specify the base directory of a build\-environment +when lcov produces error messages like: + +.RS +ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c +.RE + +In this example, use /home/user/project as base directory. + +This option is required when using lcov on projects built with libtool or +similar build environments that work with a base directory, i.e. environments, +where the current working directory when invoking the compiler is not the same +directory in which the source code file is located. + +Note that this option will not work in environments where multiple base +directories are used. In that case repeat the lcov call for each base directory +while using the \-\-ignore\-errors option to prevent lcov from exiting when the +first source code file could not be found. This way you can get partial coverage +information for each base directory which can then be combined using the \-a +option. +.RE + +.B \-c +.br +.B \-\-capture +.br +.RS +Capture coverage data. + +By default captures the current kernel execution counts and writes the +resulting coverage data to the standard output. Use the \-\-directory +option to capture counts for a user space program. + +The result of the capture operation will be written to stdout or the tracefile +specified with \-o. + +Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified +at a time. +.RE + +.B \-\-checksum +.br +.B \-\-no\-checksum +.br +.RS +Specify whether to generate checksum data when writing tracefiles. + +Use \-\-checksum to enable checksum generation or \-\-no\-checksum to +disable it. Checksum generation is +.B disabled +by default. + +When checksum generation is enabled, a checksum will be generated for each +source code line and stored along with the coverage data. This checksum will +be used to prevent attempts to combine coverage data from different source +code versions. + +If you don't work with different source code versions, disable this option +to speed up coverage data processing and to reduce the size of tracefiles. +.RE + +.B \-\-compat\-libtool +.br +.B \-\-no\-compat\-libtool +.br +.RS +Specify whether to enable libtool compatibility mode. + +Use \-\-compat\-libtool to enable libtool compatibility mode or \-\-no\-compat\-libtool +to disable it. The libtool compatibility mode is +.B enabled +by default. + +When libtool compatibility mode is enabled, lcov will assume that the source +code relating to a .da file located in a directory named ".libs" can be +found in its parent directory. + +If you have directories named ".libs" in your build environment but don't use +libtool, disable this option to prevent problems when capturing coverage data. +.RE + +.B \-\-convert\-filenames +.br +.RS +Convert filenames when applying diff. + +Use this option together with \-\-diff to rename the file names of processed +data sets according to the data provided by the diff. +.RE + +.B \-\-diff +.I tracefile +.I difffile +.br +.RS +Convert coverage data in +.I tracefile +using source code diff file +.IR difffile . + +Use this option if you want to merge coverage data from different source code +levels of a program, e.g. when you have data taken from an older version +and want to combine it with data from a more current version. +.B lcov +will try to map source code lines between those versions and adjust the coverage +data respectively. +.I difffile +needs to be in unified format, i.e. it has to be created using the "\-u" option +of the +.B diff +tool. + +Note that lines which are not present in the old version will not be counted +as instrumented, therefore tracefiles resulting from this operation should +not be interpreted individually but together with other tracefiles taken +from the newer version. Also keep in mind that converted coverage data should +only be used for overview purposes as the process itself introduces a loss +of accuracy. + +The result of the diff operation will be written to stdout or the tracefile +specified with \-o. + +Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified +at a time. +.RE + +.B \-d +.I directory +.br +.B \-\-directory +.I directory +.br +.RS +Use .da files in +.I directory +instead of kernel. + +If you want to work on coverage data for a user space program, use this +option to specify the location where the program was compiled (that's +where the counter files ending with .da will be stored). + +Note that you may specify this option more than once. +.RE + +.B \-e +.I tracefile +.I pattern +.br +.B \-\-extract +.I tracefile +.I pattern +.br +.RS +Extract data from +.IR tracefile . + +Use this switch if you want to extract coverage data for only a particular +set of files from a tracefile. Additional command line parameters will be +interpreted as shell wildcard patterns (note that they may need to be +escaped accordingly to prevent the shell from expanding them first). +Every file entry in +.I tracefile +which matches at least one of those patterns will be extracted. + +The result of the extract operation will be written to stdout or the tracefile +specified with \-o. + +Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified +at a time. +.RE + +.B \-f +.br +.B \-\-follow +.br +.RS +Follow links when searching for .da files. +.RE + +.B \-\-gcov\-tool +.I tool +.br +.RS +Specify the location of the gcov tool. +.RE + +.B \-h +.br +.B \-\-help +.br +.RS +Print a short help text, then exit. +.RE + +.B \-\-ignore\-errors +.I errors +.br +.RS +Specify a list of errors after which to continue processing. + +Use this option to specify a list of one or more classes of errors after which +lcov should continue processing instead of aborting. + +.I errors +can be a comma\-separated list of the following keywords: + +.B gcov: +the gcov tool returned with a non\-zero return code. + +.B source: +the source code file for a data set could not be found. +.RE + +.B \-i +.br +.B \-\-initial +.RS +Capture initial zero coverage data. + +Run lcov with \-c and this option on the directories containing .bb, .bbg +or .gcno files before running any test case. The result is a "baseline" +coverage data file that contains zero coverage for every instrumented line. +Combine this data file (using lcov \-a) with coverage data files captured +after a test run to ensure that the percentage of total lines covered is +correct even when not all source code files were loaded during the test. + +Recommended procedure when capturing data for a test case: + +1. create baseline coverage data file +.RS +# lcov \-c \-i \-d appdir \-o app_base.info +.br + +.RE +2. perform test +.RS +# appdir/test +.br + +.RE +3. create test coverage data file +.RS +# lcov \-c \-d appdir \-o app_test.info +.br + +.RE +4. combine baseline and test coverage data +.RS +# lcov \-a app_base.info \-a app_test.info \-o app_total.info +.br + +.RE +.RE + +.B \-k +.I subdirectory +.br +.B \-\-kernel\-directory +.I subdirectory +.br +.RS +Capture kernel coverage data only from +.IR subdirectory . + +Use this option if you don't want to get coverage data for all of the +kernel, but only for specific subdirectories. + +Note that you may specify this option more than once. +.RE + +.B \-l +.I tracefile +.br +.B \-\-list +.I tracefile +.br +.RS +List the contents of the +.IR tracefile . + +Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified +at a time. +.RE + +.B \-\-no\-recursion +.br +.RS +Use this option if you want to get coverage data for the specified directory +only without processing subdirectories. +.RE + +.B \-o +.I tracefile +.br +.B \-\-output\-file +.I tracefile +.br +.RS +Write data to +.I tracefile +instead of stdout. + +Specify "\-" as a filename to use the standard output. + +By convention, lcov\-generated coverage data files are called "tracefiles" and +should have the filename extension ".info". +.RE + +.B \-\-path +.I path +.br +.RS +Strip path from filenames when applying diff. + +Use this option together with \-\-diff to tell lcov to disregard the specified +initial path component when matching between tracefile and diff filenames. +.RE + +.B \-q +.br +.B \-\-quiet +.br +.RS +Do not print progress messages. + +This option is implied when no output filename is specified to prevent +progress messages to mess with coverage data which is also printed to +the standard output. +.RE + +.B \-r +.I tracefile +.I pattern +.br +.B \-\-remove +.I tracefile +.I pattern +.br +.RS +Remove data from +.IR tracefile . + +Use this switch if you want to remove coverage data for a particular +set of files from a tracefile. Additional command line parameters will be +interpreted as shell wildcard patterns (note that they may need to be +escaped accordingly to prevent the shell from expanding them first). +Every file entry in +.I tracefile +which matches at least one of those patterns will be removed. + +The result of the remove operation will be written to stdout or the tracefile +specified with \-o. + +Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified +at a time. +.RE + +.B \-\-strip +.I depth +.br +.RS +Strip path components when applying diff. + +Use this option together with \-\-diff to tell lcov to disregard the specified +number of initial directories when matching tracefile and diff filenames. +.RE + +.B \-t +.I testname +.br +.B \-\-test\-name +.I testname +.br +.RS +Specify test name to be stored in the tracefile. + +This name identifies a coverage data set when more than one data set is merged +into a combined tracefile (see option \-a). + +Valid test names can consist of letters, decimal digits and the underscore +character ("_"). +.RE + +.B \-v +.br +.B \-\-version +.br +.RS +Print version number, then exit. +.RE + +.B \-z +.br +.B \-\-zerocounters +.br +.RS +Reset all execution counts to zero. + +By default tries to reset kernel execution counts. Use the \-\-directory +option to reset all counters of a user space program. + +Only one of \-z, \-c, \-a, \-e, \-r, \-l and \-\-diff may be specified +at a time. +.RE + +.SH FILES + +.I /etc/lcovrc +.RS +The system\-wide configuration file. +.RE + +.I ~/.lcovrc +.RS +The per\-user configuration file. +.RE + +.SH AUTHOR +Peter Oberparleiter <Peter.Oberparleiter@de.ibm.com> + +.SH SEE ALSO +.BR lcovrc (5), +.BR genhtml (1), +.BR geninfo (1), +.BR genpng (1), +.BR gendesc (1), +.BR gcov (1) diff --git a/third_party/lcov/man/lcovrc.5 b/third_party/lcov/man/lcovrc.5 new file mode 100644 index 0000000..8bb7a63 --- /dev/null +++ b/third_party/lcov/man/lcovrc.5 @@ -0,0 +1,557 @@ +.TH lcovrc 5 "LCOV 1.7" 2008\-11\-17 "User Manuals" + +.SH NAME +lcovrc \- lcov configuration file + +.SH DESCRIPTION +The +.I lcovrc +file contains configuration information for the +.B lcov +code coverage tool (see +.BR lcov (1)). +.br + +The system\-wide configuration file is located at +.IR /etc/lcovrc . +To change settings for a single user, place a customized copy of this file at +location +.IR ~/.lcovrc . +Where available, command\-line options override configuration file settings. + +Lines in a configuration file can either be: +.IP " *" +empty lines or lines consisting only of white space characters. These lines are +ignored. +.IP " *" +comment lines which start with a hash sign ('#'). These are treated like empty +lines and will be ignored. +.IP " *" +statements in the form +.RI ' key " = " value '. +A list of valid statements and their description can be found in +section 'OPTIONS' below. +.PP + +.B Example configuration: +.IP +# +.br +# Example LCOV configuration file +.br +# +.br + +# External style sheet file +.br +#genhtml_css_file = gcov.css +.br + +# Coverage rate limits for line coverage +.br +genhtml_hi_limit = 50 +.br +genhtml_med_limit = 15 +.br + +# Coverage rate limits for function coverage +.br +genhtml_function_hi_limit = 90 +.br +genhtml_function_med_limit = 75 +.br + +# Width of overview image +.br +genhtml_overview_width = 80 +.br + +# Resolution of overview navigation +.br +genhtml_nav_resolution = 4 +.br + +# Offset for source code navigation +.br +genhtml_nav_offset = 10 +.br + +# Do not remove unused test descriptions if non\-zero +.br +genhtml_keep_descriptions = 0 +.br + +# Do not remove prefix from directory names if non\-zero +.br +genhtml_no_prefix = 0 +.br + +# Do not create source code view if non\-zero +.br +genhtml_no_source = 0 +.br + +# Specify size of tabs +.br +genhtml_num_spaces = 8 +.br + +# Highlight lines with converted\-only data if non\-zero +.br +genhtml_highlight = 0 +.br + +# Include color legend in HTML output if non\-zero +.br +genhtml_legend = 0 +.br + +# Include HTML file at start of HTML output +.br +#genhtml_html_prolog = prolog.html +.br + +# Include HTML file at end of HTML output +.br +#genhtml_html_epilog = epilog.html +.br + +# Use custom HTML file extension +.br +#genhtml_html_extension = html +.br + +# Compress all generated html files with gzip. +.br +#genhtml_html_gzip = 1 +.br + +# Include sorted overview pages +.br +genhtml_sort = 1 +.br + +# Include function coverage data display +.br +genhtml_function_coverage = 1 +.br + +# Location of the gcov tool +.br +#geninfo_gcov_tool = gcov +.br + +# Adjust test names if non\-zero +.br +#geninfo_adjust_testname = 0 +.br + +# Calculate a checksum for each line if non\-zero +.br +geninfo_checksum = 0 +.br + +# Enable libtool compatibility mode if non\-zero +.br +geninfo_compat_libtool = 0 +.br + +# Directory containing gcov kernel files +.br +lcov_gcov_dir = /proc/gcov +.br + +# Location of the insmod tool +.br +lcov_insmod_tool = /sbin/insmod +.br + +# Location of the modprobe tool +.br +lcov_modprobe_tool = /sbin/modprobe +.br + +# Location of the rmmod tool +.br +lcov_rmmod_tool = /sbin/rmmod +.br + +# Location for temporary directories +.br +lcov_tmp_dir = /tmp +.br +.PP + +.SH OPTIONS + +.BR genhtml_css_file " =" +.I filename +.IP +Specify an external style sheet file. Use this option to modify the appearance of the HTML output as generated by +.BR genhtml . +During output generation, a copy of this file will be placed in the output +directory. +.br + +This option corresponds to the \-\-css\-file command line option of +.BR genhtml . +.br + +By default, a standard CSS file is generated. +.PP + +.BR genhtml_hi_limit " =" +.I hi_limit +.br +.BR genhtml_med_limit " =" +.I med_limit +.br +.BR genhtml_function_med_limit " =" +.I hi_limit +.br +.BR genhtml_function_med_limit " =" +.I med_limit +.IP +Specify coverage rate limits for classifying file entries. Use this option to +modify the coverage rates (in percent) for line or function coverage at which +a result is classified as high, medium or low coverage. This classification +affects the color of the corresponding entries on the overview pages of the +HTML output: +.br + +High: hi_limit <= rate <= 100 default color: green +.br +Medium: med_limit <= rate < hi_limit default color: orange +.br +Low: 0 <= rate < med_limit default color: red +.br + +Defaults are 50 and 15 percent for line coverage and 90 and 75 percent for +function coverage. +.PP + +.BR genhtml_overview_width " =" +.I pixel_size +.IP +Specify the width (in pixel) of the overview image created when generating HTML +output using the \-\-frames option of +.BR genhtml . +.br + +Default is 80. +.PP + +.BR genhtml_nav_resolution " =" +.I lines +.IP +Specify the resolution of overview navigation when generating HTML output using +the \-\-frames option of +.BR genhtml . +This number specifies the maximum difference in lines between the position a +user selected from the overview and the position the source code window is +scrolled to. +.br + +Default is 4. +.PP + + +.BR genhtml_nav_offset " =" +.I lines +.IP +Specify the overview navigation line offset as applied when generating HTML +output using the \-\-frames option of +.BR genhtml. +.br + +Clicking a line in the overview image should show the source code view at +a position a bit further up, so that the requested line is not the first +line in the window. This number specifies that offset. +.br + +Default is 10. +.PP + + +.BR genhtml_keep_descriptions " =" +.IR 0 | 1 +.IP +If non\-zero, keep unused test descriptions when generating HTML output using +.BR genhtml . +.br + +This option corresponds to the \-\-keep\-descriptions option of +.BR genhtml . +.br + +Default is 0. +.PP + +.BR genhtml_no_prefix " =" +.IR 0 | 1 +.IP +If non\-zero, do not try to find and remove a common prefix from directory names. +.br + +This option corresponds to the \-\-no\-prefix option of +.BR genhtml . +.br + +Default is 0. +.PP + +.BR genhtml_no_source " =" +.IR 0 | 1 +.IP +If non\-zero, do not create a source code view when generating HTML output using +.BR genhtml . +.br + +This option corresponds to the \-\-no\-source option of +.BR genhtml . +.br + +Default is 0. +.PP + +.BR genhtml_num_spaces " =" +.I num +.IP +Specify the number of spaces to use as replacement for tab characters in the +HTML source code view as generated by +.BR genhtml . +.br + +This option corresponds to the \-\-num\-spaces option of +.BR genthml . +.br + +Default is 8. + +.PP + +.BR genhtml_highlight " =" +.IR 0 | 1 +.IP +If non\-zero, highlight lines with converted\-only data in +HTML output as generated by +.BR genhtml . +.br + +This option corresponds to the \-\-highlight option of +.BR genhtml . +.br + +Default is 0. +.PP + +.BR genhtml_legend " =" +.IR 0 | 1 +.IP +If non\-zero, include a legend explaining the meaning of color coding in the HTML +output as generated by +.BR genhtml . +.br + +This option corresponds to the \-\-legend option of +.BR genhtml . +.br + +Default is 0. +.PP + +.BR genhtml_html_prolog " =" +.I filename +.IP +If set, include the contents of the specified file at the beginning of HTML +output. + +This option corresponds to the \-\-html\-prolog option of +.BR genhtml . +.br + +Default is to use no extra prolog. +.PP + +.BR genhtml_html_epilog " =" +.I filename +.IP +If set, include the contents of the specified file at the end of HTML output. + +This option corresponds to the \-\-html\-epilog option of +.BR genhtml . +.br + +Default is to use no extra epilog. +.PP + +.BR genhtml_html_extension " =" +.I extension +.IP +If set, use the specified string as filename extension for generated HTML files. + +This option corresponds to the \-\-html\-extension option of +.BR genhtml . +.br + +Default extension is "html". +.PP + +.BR genhtml_html_gzip " =" +.IR 0 | 1 +.IP +If set, compress all html files using gzip. + +This option corresponds to the \-\-html\-gzip option of +.BR genhtml . +.br + +Default extension is 0. +.PP + +.BR genhtml_sort " =" +.IR 0 | 1 +.IP +If non\-zero, create overview pages sorted by coverage rates when generating +HTML output using +.BR genhtml . +.br + +This option can be set to 0 by using the \-\-no\-sort option of +.BR genhtml . +.br + +Default is 1. +.PP + +.BR genhtml_function_coverage " =" +.IR 0 | 1 +.IP +If non\-zero, include function coverage data when generating HTML output using +.BR genhtml . +.br + +This option can be set to 0 by using the \-\-no\-function\-coverage option of +.BR genhtml . +.br + +Default is 1. +.PP + +.BR geninfo_gcov_tool " =" +.I path_to_gcov +.IP +Specify the location of the gcov tool (see +.BR gcov (1)) +which is used to generate coverage information from data files. +.br + +Default is 'gcov'. +.PP + +.BR geninfo_adjust_testname " =" +.IR 0 | 1 +.IP +If non\-zero, adjust test names to include operating system information +when capturing coverage data. +.br + +Default is 0. +.PP + +.BR geninfo_checksum " =" +.IR 0 | 1 +.IP +If non\-zero, generate source code checksums when capturing coverage data. +Checksums are useful to prevent merging coverage data from incompatible +source code versions but checksum generation increases the size of coverage +files and the time used to generate those files. +.br + +This option corresponds to the \-\-checksum and \-\-no\-checksum command line +option of +.BR geninfo . +.br + +Default is 0. +.PP + +.BR geninfo_compat_libtool " =" +.IR 0 | 1 +.IP +If non\-zero, enable libtool compatibility mode. When libtool compatibility +mode is enabled, lcov will assume that the source code relating to a .da file +located in a directory named ".libs" can be found in its parent directory. +.br + +This option corresponds to the \-\-compat\-libtool and \-\-no\-compat\-libtool +command line option of +.BR geninfo . +.br + +Default is 1. +.PP + +.BR lcov_gcov_dir " =" +.I path_to_kernel_coverage_data +.IP +Specify the path to the directory where kernel coverage data can be found. +.br + +Default is '/proc/gcov'. +.PP + +.BR lcov_insmod_tool " =" +.I path_to_insmod +.IP +Specify the location of the insmod tool used to load kernel modules. +.br + +Default is '/sbin/insmod'. +.PP + +.BR lcov_modprobe_tool " =" +.I path_to_modprobe +.IP +Specify the location of the modprobe tool used to load kernel modules. +.br + +Default is '/sbin/modprobe'. +.PP + +.BR lcov_rmmod_tool " =" +.I path_to_rmmod +.IP +Specify the location of the rmmod tool used to unload kernel modules. +.br + +Default is '/sbin/rmmod'. +.PP + +.BR lcov_tmp_dir " =" +.I temp +.IP +Specify the location of a directory used for temporary files. +.br + +Default is '/tmp'. +.PP + +.SH FILES + +.TP +.I /etc/lcovrc +The system\-wide +.B lcov +configuration file. + +.TP +.I ~/.lcovrc +The individual per\-user configuration file. +.PP + +.SH SEE ALSO +.BR lcov (1), +.BR genhtml (1), +.BR geninfo (1), +.BR gcov (1) |