6.4.5. Inspecting Configurations with axivion_config_tool

The tool axivion_config_tool inspects a layered configuration as specified by BAUHAUS_CONFIG. It has four subcommands:

delta

Prints the difference between two configurations as a JSON configuration file.

locate

Shows in which layers an option, a rule or a rule subtree is set.

show

Prints the effective value of an option as a JSON value.

list

Lists the loaded Python and JSON configuration files in loading order.

To check whether a configuration is complete and consistent enough for an analysis run, use --validate of axivion_ci instead. It schedules the build and analysis steps using the configuration without executing them and reports configuration errors. axivion_config_tool shows the values a configuration contains, where they are set, and how it differs from another configuration.

Every subcommand takes the option --config (-c), which gives the layers in BAUHAUS_CONFIG notation. The empty string means “no layers”, i.e., the default configuration. If the argument is omitted, the current configuration as defined by BAUHAUS_CONFIG is used. Configuration paths have the form described for --output_config in Command-Line Switches, including the shorthand /<aspect_name>//<rule_name> that allows omitting all intermediate hierarchy levels of a deeply nested rule.

6.4.5.1. delta

Compares the configuration defined by BAUHAUS_CONFIG (or, if given, the -c option) against a baseline configuration (which can be the default configuration) and outputs the difference as a JSON layer. Ignoring Python-only options, the resulting JSON layer could be used to turn the baseline into the current configuration by prepending it to the baseline’s layers.

Only rules that are active in the compared configuration are considered. A rule that is active in the baseline but not in the compared configuration is output with "_active": false only; option changes of inactive rules are not shown.

axivion_config_tool delta [-h] [-c CONFIG] [-p PATH] [-j] [-n] [-s] [--rulenames]
                          [--ignore_option IGNORE_OPTION] [-e] [-r]
                          [--abort_on_missing_config | --continue_on_missing_config]
                          [baseline_config]

baseline_config is the configuration to compare against, specified in BAUHAUS_CONFIG notation. If it is omitted or empty, the default configuration is used.

Description of the arguments:
-c CONFIG, --config CONFIG

The configuration to compare.

-p PATH, --path PATH

The configuration path to output, e.g., /Analysis for the global options of the analysis, /Analysis/* for all its rules or /Analysis//MisraC++2023/* for all rules of a rule group. Defaults to /*.

-j, --json_only, --json

Omit the preamble and output only the JSON configuration file.

-n, --show_non_json_options

Include option values that cannot be represented in JSON as comments.

-s, --skip_empty

Produce no output instead of an empty configuration file if there is no difference.

--rulenames

Output only the names of the rules whose configuration differs.

--ignore_option IGNORE_OPTION

Omit the given top-level option from the output. Can be given several times.

-e, --expand_vars

Expand environment variables in rule configurations.

-r, --return_code

Exit with code 0 if there is no difference, 1 if there is a difference and 2 or higher on error.

--abort_on_missing_config

Abort if a configuration file is missing, even if it is optional.

--continue_on_missing_config

Continue without an error if a configuration file is missing, even if it is mandatory.

Examples

Full difference between the configurations of two development branches
axivion_config_tool delta -c D:\dev\master\config D:\dev\release-7\config

After setting BAUHAUS_CONFIG to D:\dev\master\config, this is equivalent to:

Full difference between the current configuration and the configuration of another branch
axivion_config_tool delta D:\dev\release-7\config
Difference for a rule group and its children only
axivion_config_tool delta D:\dev\release-7\config --path /Analysis//MisraC++/*

The empty configuration "" is the configuration after loading no files, i.e., the default configuration of all rules. Comparing against it shows what the current configuration sets.

Current configuration without defaults
axivion_config_tool delta ""
Current configuration without defaults, Results aspect only
axivion_config_tool delta "" --path /Results/*

Use --rulenames to show just the names of the changed rules:

MisraC++ rules whose configuration differs from the baseline
axivion_config_tool delta D:\dev\release-7\config --rulenames --path /Analysis//MisraC++/*

Most rules are inactive by default, so activating a rule counts as a change. Comparing against the default configuration therefore lists every rule that was activated:

All activated MisraC++ rules
axivion_config_tool delta "" --path /Analysis//MisraC++/* --rulenames

To list only the rules with options changed from the default, ignore _active:

MisraC++ rules with options changed from the default
axivion_config_tool delta "" --path /Analysis//MisraC++/* --rulenames --ignore_option=_active

--ignore_option can be given several times to exclude further top-level options:

As above, ignoring further options
axivion_config_tool delta "" --path /Analysis//MisraC++/* --rulenames --ignore_option=_active --ignore_option=exclude_in_macros --ignore_option=report_at

6.4.5.2. locate

Outputs the most local layer or all layers that define a given option or that configure the given rule or rule subtree. Rule copies and imported rules are found as well if the complete configuration defines them.

axivion_config_tool locate [-h] [-c CONFIG] [-r | -g] [-l] [-a] option_path

option_path is the configuration path of an option, e.g., /Analysis//MisraC++-9.3.1/severity, or of a rule or rule group if --rule or --group is specified.

Description of the arguments:
-c CONFIG, --config CONFIG

The configuration to inspect.

-r, --rule

Report the JSON layers that set any option directly on the given rule. Options inherited from rule groups and options of child rules are not considered. Use an aspect such as /Analysis for its global options.

-g, --group

Report the JSON layers that set any option in the given rule subtree. Use an aspect such as /Analysis for the whole aspect.

-l, --layer_only

Omit the preamble and output only the layer file names.

-a, --all

Report all layers that change the option or configure the rule or subtree, not only the most local one.

With --rule or --group, Python layers are not reported.

Examples

Layer that sets an option
> axivion_config_tool locate /Analysis//MisraC++-9.3.1/exclude_in_macros
Option 'Analysis//MisraC++-9.3.1/exclude_in_macros' is set in layer 'D:\dev\rule_config.json'.
Layer that sets a global option, file name only
> axivion_config_tool locate /Project/directory --layer_only
D:\dev\environment_config.json
All layers that change an option’s value
> axivion_config_tool locate /Analysis//MisraC++-9.3.1/severity --all
Option 'Analysis//MisraC++-9.3.1/severity' is set in layers:
D:\dev\global_layer.json (initial)
D:\dev\project_layer.json (override)
D:\dev\local_layer.json (final override)
Most local layer that sets global /Project options
> axivion_config_tool locate --rule /Project
The most local layer configuring rule '/Project' is layer 'D:\dev\environment_config.json'.
All layers that configure the /Project aspect
> axivion_config_tool locate --group /Project --all
Rule subtree '/Project' is configured in layers:
D:\dev\complete_build_config.json
D:\dev\environment_config.json
All layers that configure a rule group, machine-readable
> axivion_config_tool locate --group --all --layer_only /Analysis/AnalysisControl
D:\dev\environment_config.json
D:\dev\static_semantic_analysis.json
D:\dev\rule_config.json

6.4.5.3. show

Prints the effective value of an option as a JSON value.

axivion_config_tool show [-h] [-c CONFIG] [-j] [-e]
                         [--abort_on_missing_config | --continue_on_missing_config]
                         option_path

option_path is the configuration path of an option, e.g., /Analysis//MisraC++-9.3.1/severity.

Description of the arguments:
-c CONFIG, --config CONFIG

The configuration to inspect.

-j, --json_only, --json

Omit the preamble and output only the JSON value.

-e, --expand_vars

Expand environment variables in rule configurations.

--abort_on_missing_config

Abort if a configuration file is missing, even if it is optional.

--continue_on_missing_config

Continue without an error if a configuration file is missing, even if it is mandatory.

Examples

Value of a nested option in dot notation
axivion_config_tool show /Results/Dashboard/ci_mode.directory
Value of an option as JSON only
axivion_config_tool show --json /Analysis/global_excludes

6.4.5.4. list

Lists the loaded Python and JSON configuration files in loading order. Interface layers are resolved recursively, so the output contains the files they refer to instead of the interface layers themselves. Files that do not exist are omitted without an error, even if they are mandatory.

axivion_config_tool list [-h] [-c CONFIG] [-j] [-p]
Description of the arguments:
-c CONFIG, --config CONFIG

The configuration to inspect.

-j, --json

Output a JSON list.

-p, --posix

Output the paths in POSIX notation instead of the notation of the platform.

Examples

Files loaded through an interface layer
> axivion_config_tool list -c D:\dev\axivion_config.json
D:\dev\complete_build_config.json
D:\dev\environment_config.json
D:\dev\rule_config.json
D:\dev\compiler_local.json