[codelinks_coverage]

Code coverage from the source side: which functions and methods in the codelinks source files trace to no need.

When this table is present (even empty), its settings decide which definitions the coverage report counts and how it judges them. Its keys are inherited one by one: a configuration that extends another, or a -c override, keeps every key it does not set.

Guide: Coverage policy ([codelinks_coverage]).

codelinks_coverage.exclude

Type:

array of strings

Default:

[]

Glob patterns of source files to leave out of the count, relative to the directory of the ubproject.toml that sets them.

The files are still read for markers, so the needs they define are unaffected. An invalid pattern is ignored with a warning. Unset: none.

codelinks_coverage.exclude_generated

Type:

boolean

Default:

true

Leave out the generated files: those whose leading comments, before any code, hold @generated, or a line with generated and do not edit or do not modify, or a line with automatically generated, auto-generated or autogenerated then by, from or file, or this file is / this file was then generated, auto-generated or automatically generated, or a line with changes made in this file will be lost (Qt’s moc and uic), in any case. Unset: true.

codelinks_coverage.exclude_names

Type:

array of strings

Default:

[]

Regular expressions searched in each unit’s qualified name, such as ns::Widget::draw or Shape.area; a unit with a match is left out of the count.

A pattern matches anywhere in the name: anchor it with ^ or a trailing $ to match a prefix or a suffix. An invalid pattern is ignored with a warning. Unset: none.

codelinks_coverage.exclude_tests

Type:

boolean

Default:

true

Leave test code out of the count: test files, and the functions, classes and modules the language marks as tests. Unset: true.

codelinks_coverage.gap

Type:

boolean

Default:

false

Whether ubc agent reports each untraced unit as a code_untraced gap. Unset: false.

codelinks_coverage.inheritance

Type:

string

Default:

"containment"

Whether a marker on a class, module or file traces the units inside it. Unset: containment.

Values:

• "containment": A marker on a class, module or file also traces the units inside it. The report counts those units apart from the units traced by a marker of their own.

• "strict": Only a marker on the unit itself traces it.

codelinks_coverage.justification_markers

Type:

array of strings

Default:

["codelinks-exclude:"]

Comment markers that justify an untraced unit in the source, each followed by a category and a reason: codelinks-exclude: <category>: <reason>.

An empty list turns in-source justifications off; an empty marker is ignored with a warning. Unset: ["codelinks-exclude:"].

codelinks_coverage.kinds

Type:

array of strings

The kinds of definition counted as units: function, method, constructor, destructor and operator. Only a definition with a body is a unit.

Classes, structs, modules and namespaces are never units: they group the units inside them, and a marker on one can trace those units (see inheritance).

Unset: all five. An empty list is reported and counts all five.

Each entry: A kind of definition that can count as a unit.

Values:

• "function": A function that is not a member of a type.

• "method": A function that is a member of a class, struct, trait or impl block.

• "constructor": A constructor.

• "destructor": A destructor.

• "operator": An operator overload.

codelinks_coverage.ledger

Type:

string

A TOML file of justifications keyed by symbol ID, for code that cannot carry a justification comment, relative to the directory of the ubproject.toml that sets it. Unset: no ledger.

codelinks_coverage.projects

Type:

array of strings

The codelinks projects whose source files are counted, by their names under [codelinks.projects].

Unset: every codelinks project. A name that is not a codelinks project is ignored with a warning; an empty list is reported and counts every project.

codelinks_coverage.symbol_fields

Type:

string or array of strings

Need fields whose values name the code the need traces to, so a need can trace code from its own side, without a marker in the source.

Each is a custom need field (declared in [needs.fields] or extra_options) holding a string or an array of strings. Each value names a function by its symbol ID (or by the ID without its signature, for every overload), a class, namespace or module by its ID, a file as <language>:<path>, or functions by a /regular expression/ over their IDs. A name that is not such a field is ignored with a warning. Unset: none.

Forms:

• a string: The name of one need field.

• an array of strings: The names of several need fields.

codelinks_coverage.visibility

Type:

string

Default:

"all"

Which units are counted, by their visibility: all, or only public ones. Unset: all.

Values:

• "all": Every unit counts.

• "public": Only the units visible outside their own file or type count.