{"id":13463271,"url":"https://github.com/linux-test-project/lcov","last_synced_at":"2025-05-14T00:07:27.028Z","repository":{"id":17449463,"uuid":"20223305","full_name":"linux-test-project/lcov","owner":"linux-test-project","description":"LCOV","archived":false,"fork":false,"pushed_at":"2025-04-30T15:12:44.000Z","size":3411,"stargazers_count":977,"open_issues_count":14,"forks_count":244,"subscribers_count":43,"default_branch":"master","last_synced_at":"2025-04-30T16:26:08.760Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linux-test-project.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":"CONTRIBUTING","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-05-27T14:38:58.000Z","updated_at":"2025-04-30T15:12:50.000Z","dependencies_parsed_at":"2023-01-14T12:47:14.196Z","dependency_job_id":"54bfa37a-af04-485a-909c-5d7c944f2ea7","html_url":"https://github.com/linux-test-project/lcov","commit_stats":{"total_commits":798,"total_committers":56,"mean_commits":14.25,"dds":0.5614035087719298,"last_synced_commit":"3b6caeb9bc12b1e3fc7da07117cdb3f4a84aacdc"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-test-project%2Flcov","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-test-project%2Flcov/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-test-project%2Flcov/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-test-project%2Flcov/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linux-test-project","download_url":"https://codeload.github.com/linux-test-project/lcov/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254043762,"owners_count":22005012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T13:00:49.401Z","updated_at":"2025-05-14T00:07:26.994Z","avatar_url":"https://github.com/linux-test-project.png","language":"Perl","funding_links":[],"categories":["Running Tests 🧪","Perl"],"sub_categories":[],"readme":"-------------------------------------------------\n- README file for the LTP GCOV extension (LCOV) -\n- Last changes: 2024-12-25\n-------------------------------------------------\n\nDescription\n-----------\n  LCOV is a tool to manipulate and display information about what parts of a\n  program are actually executed (i.e. \"covered\") while running a particular test\n  case or set of testcases. LCOV consists of a set of Perl scripts which build on\n  the text output of various coverage tools - e.g., gcov, llvm-cov, Coverage.py,\n  Cobertura, Devel::Cover, Jacoco, etc. - to implement the following enhanced\n  functionality:\n\n    * HTML based output: coverage rates are indicated using bar\n      graphs and specific colors in a hyperlinked coverage report, intended\n      to enable the user to quickly diagnose and address coverage issues.\n\n    * Support for large projects: overview pages allow quick browsing of\n      coverage data by providing a hierarchical directory structure\n      view, a flat list of all source files in the project, or a three-level\n      detail view: directory, file and source code view.\n\n    * Support for multiple languages - including C/C++, Perl, and Python.\n\n  LCOV was initially designed to support Linux kernel coverage measurements,\n  but works as well for coverage measurements on standard user space\n  applications.\n\n  LCOV supports differential coverage, as well as date- and owner-binning.\n  See:\n      https://arxiv.org/abs/2008.07947\n   or\n      https://ieeexplore.ieee.org/document/9438597\n  for a detailed explanation of the concepts and several possible use models.\n\n  A video presentation of the basic ideas can be found at\n      http://doi.org/10.5281/zenodo.4653252\n\n  In addition, several other features and capabilities are available.  See\n  section 6, below, for a brief description - and also see the man pages and\n  the test cases.\n\n\nFurther README contents\n-----------------------\n  1. Included files\n  2. Installing LCOV\n  3. Dependencies\n  4. An example of how to access kernel coverage data\n  5. An example of how to access coverage data for a user space program\n  6. LCOV features\n  7. Questions and Comments\n  8. Filing a new issue\n\n\n\n1. Important files\n------------------\n  README             - This README file\n  CHANGES            - List of changes between releases\n  bin/lcov           - Tool for capturing LCOV coverage data\n  bin/genhtml        - Tool for creating HTML output from LCOV data\n  bin/gendesc        - Tool for creating description files as used by genhtml\n  bin/perl2lcov      - Tool to translate Perl Devel::Cover data to lcov format\n  bin/llvm2lcov      - Tool to translate LLVM 'llvm-cov' JSON data to LCOV format\n  bin/py2lcov        - Tool to translate Python Coverage.py to lcov format\n  bin/xml2lcov       - Tool to translate Cobertura-like XML coverage data\n                       to lcov format\n  bin/geninfo        - Internal tool (creates LCOV data files)\n  bin/genpng         - Internal tool (creates png overviews of source files)\n  lcovrc             - LCOV configuration file\n  man                - Directory containing man pages for included tools\n  example            - Directory containing an example to demonstrate LCOV\n  tests              - Directory containing lcov regression tests\n  Makefile           - Makefile providing 'install' and 'uninstall' targets\n\n\n2. Installing LCOV\n------------------\nThe LCOV package is available as either RPM or tarball from:\n\n  https://github.com/linux-test-project/lcov/releases\n\nTo install the tarball, unpack it to a directory and run:\n\n  make install\n\nUse Git for the most recent (but possibly unstable) version:\n\n  git clone https://github.com/linux-test-project/lcov.git\n\nChange to the resulting lcov directory and type:\n\n  make install\n\nThe default install location is /usr/local.  Note that you may need to\nhave superuser permissions to write into system directories.\n\nTo install in a different location - for example, your home directory, run:\n\n  make PREFIX=$HOME/my_lcov install\n\nyour PREFIX should be an absolute path.\n\nTo run the LCOV regression test suite on your installation:\n\n  $ cp -r $LCOV_HOME/share/test path/to/myTestDir\n  $ cd path/to/myTestDir\n  $ make [COVERAGE=1]\n\nIf desired, you can collect coverage data for the LCOV module by setting\nthe COVERAGE makefile variable.\nNote that the Devel::Cover package must be installed if COVERAGE is enabled\nor if you want to use the perl2lcov utility.\nTo view the collected coverage information, point your browser to\n.../lcov_coverage/index.html after running the tests.\n\nNote that the testcases are primarily intended to test LCOV functionality\nand not to be easily readable tutorial examples.\n\n3. Dependencies:\n----------------\n\nThe lcov module is implemented primarily in Perl - and requires both a\nmoderately up-to-date Perl installation and multiple Perl packages.\n\nThese perl packages include:\n\n  - Capture::Tiny\n  - DateTime\n  - Devel::Cover\n  - Digest::MD5\n  - File::Spec\n  - at least one flavor of JSON module.\n    In order of performance/preference:\n       - JSON::XS\n       - Cpanel::JSON::XS\n       - JSON::PP\n       - JSON\n  - Memory::Process\n  - Module::Load::Conditional\n  - Scalar::Util\n  - Time::HiRes\n  - TimeDate\n\nIf your system is missing any of these, then you may be able to install them\nvia:\n\n   $ perl -MCPAN -e 'install(\u003cpackageName\u003e)'\n\nYou will very likely need superuser access to be able to install Perl\nmodules.\n\nSome of the applications provided with the lcov module are written\nin Python - and may require additional Python packages.\nIn particular, 'xlsxwriter' is required in order to generate any\nof the spreadsheet reports.\n\nTo measure Python code coverage, users will need Python packages:\n\n  - Coverage.py\n\nIn addition, contributors will need:\n\n  - perltidy\n\nYour platform may support other mechanisms to install and/or update\nrequired packages.\n\n\n\n4. An example of how to access Linux kernel coverage data\n---------------------------------------------------------\nRequirements: Follow the Linux kernel coverage setup instructions at:\n\n  https://docs.kernel.org/dev-tools/gcov.html\n\nAs root, do the following:\n\n  a) Resetting counters\n\n     lcov --zerocounters\n\n  b) Capturing the current coverage state to a file\n\n     lcov --capture --output-file kernel.info\n\n  c) Getting HTML output\n\n     genhtml kernel.info\n\nPoint the web browser of your choice to the resulting index.html file.\n\n\n5. An example of how to access coverage data for a user space program\n---------------------------------------------------------------------\n\n a) Capture current coverage state to a file:\n\n   i) C/C++ code:\n\n      Compile your program using the '--coverage' GCC or LLVM\n      option. During linking, make sure to specify '--coverage':\n\n        $ gcc -o myTest --coverage simple.c\n          OR\n        $ gcc -c file1.c file2.c ... --coverage\n        $ gcc -o myOtherTest --coverage file1.o file2.o ....\n\n      Alternately, LLVM users can use the 'profdata path' (rather than the\n      'gcov path') to collect coverage data from their C/C++ code.  See\n      https://github.com/linux-test-project/lcov/discussions/234 for more\n      information.\n\n       Run your testcase at least once:\n\n        $ path/to/my/testcase/myTest\n\n       Capture the current coverage state to a file:\n\n         $ lcov --directory path/to/my/testcase --capture --output-file app.info\n\n       (LLVM users using the 'profdata path' will use a somewhat different\n       command for this step - see the discussion referenced above.)\n\n       If you want to collect Modified Condition / Decision Coverage (MD/DC)\n       date, then:\n         - you must use gcc/14.2 (or newer), or LLVM/18 (or newer)\n         - your GCC compile- and link command line must include flag\n           '-fcondition-coverage'.\n         - LLVM users must use the 'profdata path' for coverage data collection,\n           and your compile command line must include\n           '-fprofile-inst-generate -fcoverage-mapping -fcoverage-mcdc'.\n           See the above referenced discussion for details.\n         - your lcov and genhtml command line must include flag\n           '--mcdc-coverage'\n       See the '--mcdc-coverage' section in the genhtml and geninfo man pages.\n\n       Note that runtime coverage data exists only after the application has\n       been started and stopped at least once. Otherwise, no data will be found\n       and lcov will abort with an error mentioning that there are no\n       data/.gcda files.\n\n       The coverage runtime emits data (the .gcda files) in an atexit\n       callback.  If your application exits abnormally or crashes before\n       the callback is executed, then no coverage data will be available.\n\n       For further information on the gcc profiling mechanism, please\n       consult the gcov man page.\n\n      See 'man lcov' for more information - especially if your build/test\n      environment is not trivial.\n\n   ii) Python code:\n\n     - install the Coverage.py module\n\n     - execute your testcase to produce python coverage data:\n\n         $ COVERAGE_FILE=./pycov.dat coverage run --append --branch \\\n             myPythonScript [my script args]\n\n     - translate Python coverage data to LCOV format:\n\n         $ py2lcov -o pycov.info [py2lcov_options] pycov.dat [x.dat]+\n\n     See 'py2lcov --help' and the Coverage.py documentation for more\n     information.\n\n   iii) Perl code:\n\n     - install the Devel::Cover module\n\n     - execute your testcase to produce perl coverage data:\n\n         $ perl -MDevel::Cover=-db,perlcov_db,-coverage,statement,branch,condition,subroutine,-silent,1 myPerlTest.pl [my script args]\n\n     - translate Perl coverage data to LCOV format:\n\n         $ perl2lcov --output perlcov.info perlcov_db [perl2lcov options]\n\n     See 'perl2lcov --help' and the Devel::Cover documentation for more\n     information.\n\n   iv) XML data (for example, generated by Cobertura):\n\n     - translate XM coverage data to LCOV format:\n\n         $ xml2lcov --output myData.info coverage.xml [xml2lcov options]\n\n     See 'xml2lcov --help' and the Cobertura documentation for more\n     information.\n\n b) Generate an HTML coverage report:\n\n    Generate an HTML report, combining all of your LCOV data files:\n\n      $ genhtml -o html_report app.info pycov.info perlcov.info\n\n    Point the web browser of your choice to the resulting file:\n    html_report/index.html.\n\n    See 'man genhtml' for more details.\n\n c) Generate a differential coverage report:\n\n    See the example in .../example (run \"make test_differential\")\n    as well as the examples in .../tests/gendiffcov.\n\n\n6. LCOV Features:\n-----------------\n\nLCOV features and capabilities fall into 7 major categories:\n\n  a) Categorization\n\n     This refers primarily to differential coverage categorization as\n     well as date- and owner-binning.  See https://arxiv.org/abs/2008.07947\n     or https://ieeexplore.ieee.org/document/9438597 for a detailed\n     description of the concepts.\n\n     Differential categorization and binning are orthogonal in the sense\n     that you can generate differential report without binning as well\n     as 'vanilla' coverage reports with binning.  See the above papers\n     and the genhtml man page for details.\n\n     Related options:\n        --baseline-file, --diff-file, --annotate-script, --select-script\n        --date-bins, --date-labels --new-file-as-baseline,\n        --elide-path-mismatch\n\n  b) Error handling\n\n     A generic - but very simple - error handler has been added to the\n     lcov tool suite.  The error handler is used to report exceptions,\n     and provides a mechanism for the user to ignore the particular\n     message if desired.  Note that ignoring certain errors can cause\n     subsequent errors and/or can result in inconsistent or confusing\n     coverage reports.\n     See the genhtml/lcov/geninfo man pages for details.\n\n     Note that some errors are unrecoverable - and cannot be suppressed or\n     ignored.\n\n     Related options:\n        --ignore-error, --expect-message-count, --keep-going, --msg-log\n\n  c) Navigation and display:\n\n     Navigation aids such as hyperlinks to the first uncovered region,\n     to the next uncovered region, etc. have been implemented.  Similarly,\n     new tables, new columns, and new links between tables enable the\n     user to identify the author of particular code (covered or not\n     covered), as well as the time period when the code was written.\n\n     Collectively, these features help the user to quickly identify the\n     cause of code coverage issues, and to then decide what to do.\n\n     An option to generate a 'hierarchical' coverage report (which follows\n     the source code directory structure) or 'flat' (all files in top level\n     of two-level report) as well as various other small features (tooltip\n     popups, user-specified HTML header, footer, and table labels, etc.) are\n     also available.\n\n     See the genhtml man page for some details, as well as the\n     'gendiffcov/simple' testcases for some examples.\n\n      Related options:\n          --baseline-title, --baseline-date, --current-date,\n          --flat, --hierarchical,\n          --show-owners, --show-noncode, --show-navigation, --show-proportion,\n          --suppress-aliases\n\n  d) Data manipulation\n\n     Filters are used to suppress or remove certain coverage artifacts -\n     for example, branches generated by the compiler (e.g., for exception\n     handling).  These artifacts can overwhelm the user code and obscure\n     coverage features that are interesting to the user.\n\n     Other options are used to focus on or to exclude certain sections\n     of code, as well as to do regexp replacement of file names - possibly\n     using case-insensitive comparison.\n     (Path munging is useful primarily when the build structure does\n     not exactly match the layout in your revision control system; this\n     is common in large projects with reusable components.)\n\n     During coverage data capture, the --build-directory option can be used\n     to specify a search path, to find the .gcno (compile-time coverage data)\n     file corresponding to a particular .gcda (runtime coverage data) file.\n     Similarly, the --source-directory option can be used to specify a\n     search path for source files.\n\n     See the lcov/geninfo/genhtml man pages for a detailed description of\n     the available filters and manipulation features.\n\n     Related options:\n        --include, --exclude, --erase-functions, --omit-lines,\n        --substitute, --filter\n        --build-directory --source-directory\n\n  e) Callbacks/customization\n\n     The user can supply callbacks which are used to:\n\n        i) interface with the revision control system\n           Sample scripts:\n             - Perforce:  see 'p4diff', 'p4annotate.pm', 'p4annotate'\n             - Git: see 'gitdiff', 'gitblame.pm', 'gitblame'\n        ii) verify that source code versions are compatible, and\n            Sample scripts: see 'get_signature', 'P4version.pm', 'getp4version',\n            'gitversion', 'gitversion.pm', and 'batchGitVersion.pm'\n        iii) enforce a desired code coverage criteria\n             Sample script: criteria.pm/criteria\n        iv) find source files in more complicated environments - where\n            simple substitutions become complicated or unweildy.\n        v) select a subset of coverage data to display - e.g., to\n           use in a code review which wants to concentrate on only\n           the changes caused by a particular commit or range of commits,\n           or to review changes in a particular release.\n           Sample script:  select.pm\n         vi) keep track of environment and other settings - to aid\n            infrastructure debugging in more complicated use cases.\n\n     The callback may be any desired script or executable - but there\n     may be performance advantages if it is written as a Perl module.\n\n     See the genhtml/lcov/geninfo man pages for details.\n\n     Note that the various sample scripts are found in the source code\n     'scripts' directory, but are installed in the\n     $LCOV_HOME/share/lcov/support-scripts directory of the release.\n\n     Related options:\n       --annotate-script, --criteria-script, --version-script\n       --resolve-script, --select-script, --context-script\n\n  f) Performance\n\n     lcov/genhtml/geninfo have been refactored to parallelize computation\n     across multiple cores, if requested.\n     In general, this provides speedup that is nearly linear in the number\n     of cores.\n     There is also an option to throttle parallelism to not exceed peak\n     memory consumption constraints, as well as options to enable simple\n     profile data collection - so you can see where time is going and\n     thus to hint at potential optimizations.  The 'spreadsheet.py'\n     script can be used to view generated profile data.\n\n     There are several configuration file options which can be used to\n     tweak certain parallelization parameters to optimize performance\n     for your environment in cases that the default behaviour is suboptimal.\n     See the lcovrc man page for more information.\n\n     See the genhtml/lcov/geninfo man pages for details\n\n     Related options: --parallel, --memory, --profile\n\n  g) Language/tool support\n\n     Added 'llvm2lcov', 'py2lcov', 'perl2lcov' and 'xml2lcov' scripts.\n\n       - llvm2lcov:\n\n           translates JSON coverage data generated by 'llvm-cov export -format=text ...'\n           to lcov format.\n\n           See \"llvm2lcov --help\" for brief instruction on how to use the\n           translator.  Note that llvm2lcov uses a similar set of command line\n           and configuration file options as lcov, genhtml, and geninfo.\n\n       - py2lcov:\n\n           translates python Coverage.py XML data to lcov format.\n\n           See the Coverage.py documentation at https://coverage.readthedocs.io,\n           as well as \".../py2lcov --help\"\n\n       - perl2lcov\n\n          translates Perl Devel::Cover data to lcov format.\n\n          See the Devel::Cover documentation at\n            https://metacpan.org/pod/Devel::Cover\n          to find out how to generate coverage data for Perl code.\n\n          See \"perl2lcov --help\" for brief instructions on how to\n          use the translator.\n          Note that perl2lcov uses a similar set of command line and\n          config file options as lcov, genhtml, and geninfo.\n\n       - xml2lcov\n\n          translates XML coverage data to lcov format.\n          The XML data may come from Cobertura or similar tools.\n\n          See \"xml2lcov --help\" for brief instructions on how to use\n          the translator.\n          See the Coburtura documentation for directions on how to\n          generate XML data.\n\n     Other languages can be integrated using a similar approach.\n\nIn general, the new features and options are implemented uniformly in lcov,\ngenhtml, and geninfo.  Most of the features can be enabled/disabled\nusing either command line options or by setting defaults in your 'lcovrc'\nfile.  See the lcovrc man page for details.\n\n\n7. Questions and comments\n-------------------------\nSee the included man pages for more information on how to use the LCOV tools.\n\nIn case of further questions, feel free to open a new issue or discussion using\nthe issue tracker on the LCOV code repository site at:\n\n  https://github.com/linux-test-project/lcov\n\n\n8. Filing a new issue\n---------------------\nBefore filing a new issue - and if you are using an LCOV release (as opposed\nto using a clone of the github repo) - please verify whether the issue is\nstill present in the LCOV master version.  See section 2, above for\ndirections on how to clone and install the most up-to-date LCOV version.\n\nIf possible, please include a testcase which illustrates the problem\nwhen you file an issue.\nPlease describe your environment (platform, compiler, perl, and python\nversions,  etc.).  Please include a detailed description of the issue:\nwhat you were trying to do (your goal - not the mechanics of your\nprocedure), what you did (the mechanics of your procedure), the result\nyou wanted to see vs. what actually happened.\nDepending on the issue, your testcase may need to include source code and\ncompile/link command lines, directions for how to run your example, the\ncommand lines used to capture and generate your lcov reports, etc.\nIn other cases, the captured '.info' files may be sufficient to reproduce\nthe issue.\nWhen in doubt: more is better than less.\n\nIf you cannot include a testcase - e.g., because you feel that it is\nsenstitive or proprietary - then your detailed description is even more\nimportant.\nNote that, without an example, it may be difficult or impossible to\ndiagnose or fix the problem.\n\nBear in mind that you are asking for help from volunteers.   Your\npriority might not be their priority. Civility, consideration and politeness\ngo a long way.\n\nPlease check back and to verify the fix and close the issue once it has\nbeen addressed.\nAgain:  remember that you are asking for help from volunteers.\nMake sure that you are doing your part.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-test-project%2Flcov","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinux-test-project%2Flcov","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-test-project%2Flcov/lists"}