| ------------------------------------------------- |
| - README file for the LTP GCOV extension (LCOV) - |
| - Last changes: 2012-10-10 - |
| ------------------------------------------------- |
| |
| Description |
| ----------- |
| LCOV is an extension of GCOV, a GNU tool which provides information about |
| what parts of a program are actually executed (i.e. "covered") while running |
| a particular test case. The extension consists of a set of Perl scripts |
| which build on the textual GCOV output to implement the following enhanced |
| functionality: |
| |
| * HTML based output: coverage rates are additionally indicated using bar |
| graphs and specific colors. |
| |
| * Support for large projects: overview pages allow quick browsing of |
| coverage data by providing three levels of detail: directory view, |
| file view and source code view. |
| |
| LCOV was initially designed to support Linux kernel coverage measurements, |
| but works as well for coverage measurements on standard user space |
| applications. |
| |
| |
| Further README contents |
| ----------------------- |
| 1. Included files |
| 2. Installing LCOV |
| 3. An example of how to access kernel coverage data |
| 4. An example of how to access coverage data for a user space program |
| 5. Questions and Comments |
| |
| |
| |
| 1. Important files |
| ------------------ |
| README - This README file |
| CHANGES - List of changes between releases |
| bin/lcov - Tool for capturing LCOV coverage data |
| bin/genhtml - Tool for creating HTML output from LCOV data |
| bin/gendesc - Tool for creating description files as used by genhtml |
| bin/geninfo - Internal tool (creates LCOV data files) |
| bin/genpng - Internal tool (creates png overviews of source files) |
| bin/install.sh - Internal tool (takes care of un-/installing) |
| descriptions.tests - Test descriptions for the LTP suite, use with gendesc |
| man - Directory containing man pages for included tools |
| example - Directory containing an example to demonstrate LCOV |
| lcovrc - LCOV configuration file |
| Makefile - Makefile providing 'install' and 'uninstall' targets |
| |
| |
| 2. Installing LCOV |
| ------------------ |
| The LCOV package is available as either RPM or tarball from: |
| |
| http://ltp.sourceforge.net/coverage/lcov.php |
| |
| To install the tarball, unpack it to a directory and run: |
| |
| make install |
| |
| Use anonymous CVS for the most recent (but possibly unstable) version: |
| |
| cvs -d:pserver:anonymous@ltp.cvs.sourceforge.net:/cvsroot/ltp login |
| |
| (simply press the ENTER key when asked for a password) |
| |
| cvs -z3 -d:pserver:anonymous@ltp.cvs.sourceforge.net:/cvsroot/ltp export -D now utils |
| |
| Change to the utils/analysis/lcov directory and type: |
| |
| make install |
| |
| |
| 3. An example of how to access kernel coverage data |
| --------------------------------------------------- |
| Requirements: get and install the gcov-kernel package from |
| |
| http://sourceforge.net/projects/ltp |
| |
| Copy the resulting gcov kernel module file to either the system wide modules |
| directory or the same directory as the Perl scripts. As root, do the following: |
| |
| a) Resetting counters |
| |
| lcov --zerocounters |
| |
| b) Capturing the current coverage state to a file |
| |
| lcov --capture --output-file kernel.info |
| |
| c) Getting HTML output |
| |
| genhtml kernel.info |
| |
| Point the web browser of your choice to the resulting index.html file. |
| |
| |
| 4. An example of how to access coverage data for a user space program |
| --------------------------------------------------------------------- |
| Requirements: compile the program in question using GCC with the options |
| -fprofile-arcs and -ftest-coverage. During linking, make sure to specify |
| -lgcov or -coverage. |
| |
| Assuming the compile directory is called "appdir", do the following: |
| |
| a) Resetting counters |
| |
| lcov --directory appdir --zerocounters |
| |
| b) Capturing the current coverage state to a file (works only after the |
| application has been started and stopped at least once) |
| |
| lcov --directory appdir --capture --output-file app.info |
| |
| c) Getting HTML output |
| |
| genhtml app.info |
| |
| Point the web browser of your choice to the resulting index.html file. |
| |
| Please note that independently of where the application is installed or |
| from which directory it is run, the --directory statement needs to |
| point to the directory in which the application was compiled. |
| |
| For further information on the gcc profiling mechanism, please also |
| consult the gcov man page. |
| |
| |
| 5. Questions and comments |
| ------------------------- |
| See the included man pages for more information on how to use the LCOV tools. |
| |
| Please email further questions or comments regarding this tool to the |
| LTP Mailing list at ltp-coverage@lists.sourceforge.net |
| |