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.,
/Analysisfor 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¶
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:
axivion_config_tool delta D:\dev\release-7\config
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.
axivion_config_tool delta ""
axivion_config_tool delta "" --path /Results/*
Use --rulenames to show just the names of the changed rules:
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:
axivion_config_tool delta "" --path /Analysis//MisraC++/* --rulenames
To list only the rules with options changed from the default, ignore _active:
axivion_config_tool delta "" --path /Analysis//MisraC++/* --rulenames --ignore_option=_active
--ignore_option can be given several times to exclude further top-level
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
/Analysisfor its global options.- -g, --group
Report the JSON layers that set any option in the given rule subtree. Use an aspect such as
/Analysisfor 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¶
> 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'.
> axivion_config_tool locate /Project/directory --layer_only
D:\dev\environment_config.json
> 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)
/Project options¶> axivion_config_tool locate --rule /Project
The most local layer configuring rule '/Project' is layer 'D:\dev\environment_config.json'.
/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
> 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¶
axivion_config_tool show /Results/Dashboard/ci_mode.directory
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¶
> 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