livery.extensions.cmake._readings¶
livery.extensions.cmake._readings ¶
What a native measurer read of each source file, and the part it becomes.
A measured test run of the gate build is read by its compiler family's
measurer, and each reader here turns that measurer's output into a
Reading per source file: gcov's JSON (from_gcov_json), llvm-cov's
JSON export (from_llvm_json), and the Cobertura report Microsoft's
engine writes (from_cobertura). write_part writes a package's
readings as its part in the coverage extension's line format, under
PARTS, where coverage gathers it.
Each reader keeps the most its measurer gives. gcov gives each line's
count, each line's branches by index with the path an exception takes
tagged, and its functions under their demangled names. llvm-cov gives
each line's count as its own line view counts it, each condition's
true and false branches, its functions, whose names demangle turns
readable, each code region as a range, with a macro counted where it
is called, and the code the preprocessor removed as excluded lines. A
Cobertura report gives each line's count, how many of a line's
branches ran, and its methods. The floors judge the lines alone; the
rest reaches the pages.
Classes:
| Name | Description |
|---|---|
Reading |
What a native measurer read of one source file. |
Functions:
| Name | Description |
|---|---|
from_gcov_json |
What gcov's JSON output names, per file as gcov names it; a non-document refuses. |
from_llvm_json |
What |
line_counts |
Each line's count from a file's segments, as llvm-cov's line view counts it. |
demangle |
Rename every function of readings to its demangled name, in place. |
from_cobertura |
What a Cobertura report names, per file; a report that is not XML refuses. |
relativise |
readings keyed by workspace-relative posix paths; files outside root dropped. |
within |
The files of readings under package, keyed as they are. |
write_part |
Write readings as package_path's part under root; the part's path. |
remove_parts |
Delete package_path's parts of an earlier run under root, any measurer's. |
Attributes:
| Name | Type | Description |
|---|---|---|
PARTS |
|
|
FORMAT |
|
|
THROW |
|
|
MEASURERS |
dict[str, dict[str, Any]]
|
|
CODE_REGION |
|
|
EXPANSION_REGION |
|
|
SKIPPED_REGION |
|
|
CONDITIONS |
|
MEASURERS
module-attribute
¶
MEASURERS: dict[str, dict[str, Any]] = {'gcov': {'name': 'gcov', 'branches': 'indexes', 'columns': False}, 'llvm': {'name': 'llvm-cov', 'branches': 'indexes', 'columns': True}, 'msvc': {'name': 'dotnet-coverage', 'branches': 'none', 'columns': False}}
Reading
dataclass
¶
Reading(lines: dict[int, int] = dict(), excluded: set[int] = set(), branches: dict[tuple[int, int], tuple[int, str]] = dict(), branch_counts: dict[int, tuple[int, int]] = dict(), functions: dict[tuple[str, int], tuple[int, int | None]] = dict(), ranges: dict[tuple[int, int, int, int], int] = dict())
What a native measurer read of one source file.
Attributes:
| Name | Type | Description |
|---|---|---|
lines |
dict[int, int]
|
How many times each line ran, every line the measurer instruments, run or not. |
excluded |
set[int]
|
The lines the preprocessor removed from the build. |
branches |
dict[tuple[int, int], tuple[int, str]]
|
Each branch's runs and tag by its line and its index
among the line's branches; the tag is |
branch_counts |
dict[int, tuple[int, int]]
|
For a measurer that counts a line's branches without naming them: the line's branches, and how many ran. |
functions |
dict[tuple[str, int], tuple[int, int | None]]
|
Each function's last line and calls, by its name and first line; the calls are None for a measurer that counts none. |
ranges |
dict[tuple[int, int, int, int], int]
|
How many times each stretch of code ran, by its start line and column and its end line and the column after its last; columns count bytes from 1. |
Methods:
| Name | Description |
|---|---|
add |
Add other, another counter file's reading of the same source, to this one. |
add_branch |
Count taken runs of branch index of line, tagged tag. |
add_function |
Count calls of the function name from line start to line end. |
branches
class-attribute
instance-attribute
¶
branch_counts
class-attribute
instance-attribute
¶
functions
class-attribute
instance-attribute
¶
ranges
class-attribute
instance-attribute
¶
add ¶
add(other: Reading) -> None
Add other, another counter file's reading of the same source, to this one.
Counts add up; a count of a line's branches keeps the most of each.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
add_branch ¶
Count taken runs of branch index of line, tagged tag.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
add_function ¶
Count calls of the function name from line start to line end.
Calls a measurer counts add up; a function no reading counted the calls of keeps None.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
from_gcov_json ¶
What gcov's JSON output names, per file as gcov names it; a non-document refuses.
gcov prints one document per counter file, one per line, or one
whole. A line gcov names twice, and a file two documents name, has
its counts added. Each line's branches are numbered in gcov's
order, the ones gcov marks as an exception's tagged throw,
when gcov ran with --branch-probabilities; a function is named
as gcov demangles it.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
from_llvm_json ¶
What llvm-cov export -format=text prints, per file as llvm-cov names it.
A line's count is the one llvm-cov's own line view gives, the view
its lcov export prints, read from the file's segments
(line_counts). Each branch region is a condition: its true
branch numbered twice its place among its line's conditions, its
false branch one more. A function's code regions in its own file
give its first and last line, and its calls are its count; its
name is llvm-cov's, a mangled one until demangle reads it. A
function's code regions become ranges, and a macro's call counts
as a range where it is called, never inside the macro; regions of
one stretch, as each instance of a template gives, add their
counts. Its skipped regions, the code the preprocessor removed,
mark their lines excluded.
Raises:
| Type | Description |
|---|---|
Failed
|
when text is not llvm-cov's JSON export, naming why. |
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
line_counts ¶
Each line's count from a file's segments, as llvm-cov's line view counts it.
A segment is [line, column, count, has count, starts a region,
is a gap]. A line is counted when a region with a count starts
on it, or the last segment before it carries a count, unless the
line starts a region the preprocessor skipped; its count is the
most of the carried count and the counts of the regions starting
on it, gaps aside. The lines run from the first to the last line a
segment names.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
demangle ¶
Rename every function of readings to its demangled name, in place.
demangled answers each of the names it is given with the name
to show, in order, as llvm-cxxfilt does on its standard input;
an answer of another length leaves every name as it is.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
from_cobertura ¶
What a Cobertura report names, per file; a report that is not XML refuses.
A class's filename is taken as it is when absolute, else under
the report's first <source>. A line a class names twice, under
one of its methods and again under the class, counts once, at its
most; two classes of one file add their counts. A line's
condition-coverage of (k/n) is how many of its n branches
ran, and each method is a function over the lines it names.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
relativise ¶
readings keyed by workspace-relative posix paths; files outside root dropped.
A measurer names files the way the compiler saw them, absolute and with the host's separators; the row and the floors want the path the repository knows. Two names of one file add up.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
within ¶
The files of readings under package, keyed as they are.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
write_part ¶
Write readings as package_path's part under root; the part's path.
The part names its measurer by the compiler family that read it, counts how many times each line ran, and judges lines alone. Per file: the instrumented lines as its statements and the ones that ran with their counts, the lines the preprocessor removed that are no statement as excluded, the branches by index, the counts of a line's branches, the functions, the ranges for a measurer that reads columns, and the git blob id of the file's text with each CRLF read as LF, so a Windows checkout and a Linux one give one digest. A line number below 1 is no line and is left out.
Source code in packages/extensions/cmake/src/livery/extensions/cmake/_readings.py
remove_parts ¶
Delete package_path's parts of an earlier run under root, any measurer's.