Lcov plugin¶

Description¶

The lcov plugin is used for executing code coverage analysis using lcov.

Mandatory settings¶

The configuration of the lcov plugin must contain the following settings:

run-command: The exec-helper command or plugin to use for running the binaries for which the coverage needs to be analyzed.

Optional settings¶

The configuration of the lcov plugin may contain the following settings:

patterns: A list of patterns to apply on the command line. See Patterns (5).

command-line: Additional command line parameters to pass as a list of separate arguments. By default no additional arguments are added.

info-file: The lcov .info file to use for the analysis. Default: lcov-plugin.info.

base-directory: The base directory to use for the lcov analysis. Check the lcov documentation on the --base-directory option for more information. Default: . (the current working directory).

directory: Use the coverage data files in the given directory. Check the lcov documentation on the --directory option for more information. Default: . (the current working directory).

zero-counters: Set this option to yes to reset the coverage counters before starting the analysis. All other values are threated as no. Default: no.

gen-html: Set this option to yes to enable HTML report generation of the coverage data. Default: no.

gen-html-output: Set the output directory of the generated HTML report. Does nothing if gen-html is not enabled. Default: . (the current working directory).

gen-html-title: Set the title of the generated HTML report. Does nothing if gen-html is not enabled. Default: Hello.

gen-html-command-line: Set additional command line options for the gen html stage. Default: no additional command line options.

excludes: A list of directories and files to excluse from the coverage report. The paths are relative to the current working directory. Default: an empty list.

Example¶

Configuration¶

commands:                       # Define the commands that can be run
    example: Run the lcov example
    build: Build the files
    clean: Clean the build
    run: Run the built binaries

patterns:                       # Define the patterns that can be used
    MAKE_TARGET:                # Define make targets for building
        default-values:         # Only define the default value
            - hello
            - world

example:
    - build
    - lcov                      # Use the lcov plugin when running the 'example' command

build:
    - make

clean:
    - make
    - command-line-command

run:
    command-line-command

lcov:                           # Configure lcov
    run-command: run            # Execute the 'build' command for building, running and analyzing the project
    info-file: build/coverage.info  # Create and use the coverage.info file in the build dir
    base-directory: .           # LCOV's base-directory functionality
    directory: .                # LCOV's directory functionality
    zero-counters: yes          # Zero the counters before executing the analysis
    gen-html: yes               # Generate a HTML coverage report
    gen-html-output: build/coverage # Output the HTML coverage report to build/coverage
    gen-html-title: "LCOV-example" # Set the title of the HTML coverage report
    excludes:                    # Set which entries to exclude from the report
        - /usr/include/*

make:
    build:
        patterns:
            - MAKE_TARGET
        command-line:
            - "{MAKE_TARGET}"
    clean:
        command-line:
            - clean

command-line-command:
    patterns:
        - MAKE_TARGET
    run:
        command-line: ["build/{MAKE_TARGET}"]
    clean:
        command-line:    
            remote-gcda-file: [ rm, -rf, "{MAKE_TARGET}.gcda"]
            remote-gcno-file: [ rm, -rf, "{MAKE_TARGET}.gcno"]

Additional files¶

In order for the above example to work, the following file hierarchy needs to be created in the directory:

Makefile:

CXX=g++
CXXFLAGS+=-O0 -g --coverage
LDFLAGS+=
SRC_DIR=src
BUILD_DIR=build

hello:
	mkdir -p $(BUILD_DIR)
	$(CXX) $(CXXFLAGS) $(LDFLAGS) -o $(BUILD_DIR)/hello $(SRC_DIR)/hello.cpp

world:
	mkdir -p $(BUILD_DIR)
	$(CXX) $(CXXFLAGS) $(LDFLAGS) -o $(BUILD_DIR)/world $(SRC_DIR)/world.cpp

clean:
	rm -rf $(BUILD_DIR)

.PHONY: clean

hello.cpp:

#include <cstdlib>
#include <iostream>

auto main() -> int {
    std::cout << "Hello" << std::endl;
    return EXIT_SUCCESS;
}

world.cpp:

#include <cstdlib>
#include <iostream>

auto main() -> int {
    std::cout << "World!" << std::endl;
    return EXIT_SUCCESS;
}

Usage¶

Save the example to an exec-helper configuration file and execute in the same directory:

eh example