6.4.5. Running Analyses

This chapter explains the usage of the tools axivion_ci and axivion_analysis.

axivion_ci does the complete job of updating, building, and analyzing your projects. It stores the resulting data in a database, which can be accessed and queried through the Dashboard and IDE plugins. While processing the source code of the system under analysis, it extracts all the required information from it, producing intermediate representations on which the later stages of the analysis can operate. It then runs these analyses and adds the results to the database.

Starting from the intermediate representation produced by axivion_ci, the tool axivion_analysis can be used to check the software against individually configurable style guides. It covers all stylechecks, metrics, architecture analysis, clone detection, cycle detection, dead code detection, include analysis, fault detection and so on.

One of the stages of axivion_ci performs the job of axivion_analysis, so there is no need to run the latter explicitly when using axivion_ci.

6.4.5.1. axivion_analysis

axivion_analysis is the tool to start analyses using the analysis framework. Violations against the individual rules are output on a per-violation basis and can be further processed. In a CI context with axivion_ci, the analysis tool is called automatically.

axivion_analysis uses the JSON-based configuration introduced in version 7.0.

Command-Line Switches

axivion_analysis [-h] [--ir IR] [--input_rfg RFG]
                    [--unit | --system] [--output FILE] [--brief]
                    [--output_rfg RFG] [--output_csv_av CSV]
                    [--output_csv_cl CSV] [--output_csv_de CSV]
                    [--output_csv_cy CSV] [--output_csv_metric CSV]
                    [--output_csv_mv CSV] [--output_csv_sv CSV]
                    [--csv_delimiter D] [--output_json FILE]
                    [--output_binary FILE] [--rule RULE]
                    [--limit_to LIMIT_TO] [--jobs [N]]
                    [--continue_on_error] [--validate] [--exclude GLOB]
                    [--include GLOB] [--system_headers]
                    [--omit_disabled] [--list_identical_rules]
                    [--quiet] [--verbose] [--output_config CONFIG_PATH]
                    [--config_to FILE]

Description of the arguments:

-h, --help

Shows the help message and exits

Input:

--ir IR

Specifies the file name of the IR to analyze.

--input_rfg RFG

Specifies the file name of the RFG to analyze. If not specified, the RFG will be generated from the IR file, if needed.

--unit

Treat IR as being a single unit rather than a system.

--system

Treat IR as being a system rather than a single unit.

Output:

Specifies the output format and file. Multiple options may be combined. If no options are used, will output in text format to stdout.

--output FILE, -o FILE

Output file (text format).

--brief

For text output, use short format with one violation per line.

--output_rfg RFG

File name of the output RFG. Note: When using the SaveRFG rule, the filename configured in that rule overwrites this parameter

--output_csv_av CSV

Output architecture violations in CSV format.

--output_csv_cl CSV

Output clones in CSV format.

--output_csv_de CSV

Output dead entities in CSV format.

--output_csv_cy CSV

Output cycles in CSV format.

--output_csv_metric CSV

Output metrics in CSV format. Metric values which are not violations are included, if report_all_values=true.

--output_csv_mv CSV

Output metric violations in CSV format. Only metric values which are violations are included.

--output_csv_sv CSV

Output style violations in CSV format.

--csv_delimiter D

CSV delimiter character.

--output_json FILE

Output violations in JSON format. Metric values which are not violations are included, if report_all_values=true.

--output_binary FILE

Output analysis results into a file in an internal binary format. The file format can be read from Python using bauhaus.analysis_results.FileReader. The format is not guaranteed to be stable across different versions of the Axivion Suite. These files can be used with cidbman import or rule ImportAnalysisResults.

Analysis:

--rule RULE

If this option is used, only the rules specified on the command-line will be executed. Can be used multiple times to execute multiple rules. The provided RULE parameter must be the name of a rule or of a group of rules (as shown in the rule tree in the graphical configuration interface). If a group such as Stylechecks is given, all rules in that group will be activated (use --limit_to if you instead want to restrict the active set to those inside a group). For example, --rule MisraC++ will execute all MisraC++ checks. If --rule is used without --limit_to, all rules not listed on the command-line will be disabled, except for those in the AnalysisControl tree. If --rule is combined with --limit_to, the limits will be applied first and then the rules will be activated additionally.

--limit_to LIMIT_TO

If this option is used, the rules activated in the configuration will be limited to those matching the given argument. This is especially useful in single-file analysis if you want to limit the executed rules to those in the Stylechecks group, for example; that can be achieved with --limit_to Stylechecks. Can be used multiple times to form a logical OR over the given rules. The provided LIMIT_TO parameter must be the name of a rule or of a group of rules (as shown in the rule tree in the graphical configuration interface). For example, --limit_to MisraC++ --limit_to AnalysisControl limits the rules being activated in your configuration to those from the MisraC++ checks, while also keeping the configuration from the AnalysisControl tree (such as static semantic analysis) enabled.

--jobs N, -j N

Execute with N processes in parallel. If N or the whole switch is omitted, use the Default Parallelism logic.

--continue_on_error

Ignore when a rule crashes with a Python exception.

--validate

Validate configuration, but do not execute the analyses.

Filtering:

--exclude GLOB

Ignore messages in files matching the given file-globbing pattern. Can be used multiple times.

--include GLOB

Limit messages to files matching the given file-globbing pattern. Can be used multiple times.

--system_headers

Don’t ignore messages from system headers.

--omit_disabled FORMAT

Omit messages suppressed by control comments (e.g., AXIVION_DISABLE) in the specified output format. The optional FORMAT argument can be one of: text, csv, json, sarif, or binary. If used without specifying an output format, applies to text output. Can be used multiple times to specify multiple output formats.

Rules List:

If any option in this group is used, the requested list of rules is written to stdout. No analysis will be performed.

--list

List all available rules.

--list_active

List all rules that are enabled in the current configuration.

--list_identical_rules

List rules that are enabled in the current configuration and are similar/identical to each other.

Logging:

--quiet, -q

Suppress progress messages on stderr.

--verbose, -v

Enable extra debug output on stderr.

Config Output:

--output_config CONFIG_PATH

Output the configuration of a rule or rulegroup or the complete configuration. CONFIG_PATH is specified as a path in the rule hierarchy as shown in the graphical configuration interface, e.g., /Analysis/Stylechecks/CodingStyle. Use /path/to/rulegroup/* to output the given group including its complete hierarchy of rule and rulegroup members, use /* to output the complete configuration. Instead of specifying the whole path to a rule or group, the shorthand /<aspect_name>//<rule_name> may be used, e.g., /Analysis//CodingStyle-LineBreaks. By default, the output is written to stdout, use --config_to to redirect it to a file.

--config_to FILE

The file name to which the output of --output_config is written. If used without --output_config, the complete configuration is output to FILE, as if --output_config /* was specified.

The specified IR and/or RFG files are checked for violations against the configured rules and violations are reported on a per-violation basis either on stdout or into the specified output file.

The tool reads in the analysis selection and configuration as created with the configuration system (see Project Configuration). It supports both configuration files created with the graphical user interface and custom Python files. The available analyses can be seen in the graphical user interface and in Analysis Configuration Reference.

Additional Rules

You can also install additional rules, e.g. self-written ones or additional packages bought from Axivion, and these additional rules are then executed as well if selected in your configuration. Installation of additional rules is done in the graphical user interface by adding the directory containing the rules, or in Python by calling the corresponding API function as described in section Python API.

Environment

The builtin configuration variables listed in Builtin Variables are available as environment variables to all code that runs in the context of an axivion_analysis execution, e.g., custom rules.

Output format

The format for outputs to stdout can be configured with options at the analysis aspect. The default format corresponds to

analysis.options.message_format.style.primary_line = '%(filename)s:%(line)d:%(column)d: %(severity)s:' \
               ' %(message)s (Rule %(rulegroup)s-%(rulename)s)'

There are similar options for the format of other kinds of violations, see their documentation in Analysis Configuration Reference.

6.4.5.2. axivion_ci

axivion_ci is the Continuous Integration tool of the Axivion Suite. Typically, this tool is started at regular intervals on a server in order to update the database with the analysis results from the current state of the software project under analysis, but it can also be started manually to perform a complete analysis run and add the results to the database, e.g. to perform a “Local Build” on the developer’s machine using the --local option.

If the source code has not changed since the previous run, axivion_ci --skip_build can be used to re-run the analysis, possibly with different settings, on the existing intermediate representation, without having to repeat the time-consuming initial stage of processing the source code.

axivion_ci uses the JSON-based configuration introduced in version 7.0. It replaces the tool cibuild which was configured using XML files (most notably a file called build.conf). For more details on the migration from cibuild to axivion_ci, see Migration to new Configuration System.

The configuration of the CI system involves specifying

• the version control system (VCS) used to manage the source code of your project,

• the build steps needed in order to build your project,

• the analyses to be performed on your project,

• the target database for the Dashboard use.

All steps can be configured and adapted to your needs. It is even possible to run your own tools and scripts, 3rd party tools (e.g., to include compiler warnings of your target compiler) and import the resulting data in order to monitor the evolution and stop the erosion of your project.

The available options are found in the Project and Results aspects in the graphical configuration interface and are described in the sections Project Configuration Reference and Results Configuration Reference.

Command-Line Switches

axivion_ci [-h] [--local] [--continue_on_error] [--abort_on_missing_config]
           [--validate] [--jobs [N]] [--skip_build] [--only_build]
           [--quiet] [--verbose]
           [--output_config CONFIG_PATH] [--config_to FILE]

Description of the arguments:

-h, --help

show this help message and exit

CI:

--local

Switch from the configuration as given by the /Project/ci_mode to a configuration as given by the /Project/local_mode. That is, run the build and analysis locally and compare to a remote reference version. Setting the environment variable AXIVION_LOCAL_BUILD to any value has the same effect.

--continue_on_error

Ignore when a build step crashes with a Python exception.

--abort_on_missing_config

Abort if a configuration file is missing.

--validate

Validate configuration, but do not execute the build steps.

--jobs N, -j N

Execute with N processes in parallel. If N or the whole switch is omitted, use the Default Parallelism logic. Note: This only applies to analysis jobs and does not affect the build system.

--skip_build

Skip all BuildSystemIntegration steps. This can be used to test changes to the analysis configuration without having to rebuild the IR.

--only_build

Perform only all BuildSystemIntegration steps and exit. This is the inverse of --skip_build.

Logging:

--quiet, -q

Suppress progress messages on stderr.

--verbose, -v

Enable extra debug output on stderr.

Config Output:

--output_config CONFIG_PATH

Output the configuration of a rule or rulegroup or the complete configuration. CONFIG_PATH is specified as a path in the rule hierarchy as shown in the graphical configuration interface, e.g., /Analysis/Stylechecks/CodingStyle. Use /path/to/rulegroup/* to output the given group including its complete hierarchy of rule and rulegroup members, use /* to output the complete configuration. Instead of specifying the whole path to a rule or group, the shorthand /<aspect_name>//<rule_name> may be used, e.g., /Analysis//CodingStyle-LineBreaks. By default, the output is written to stdout, use --config_to to redirect it to a file.

--config_to FILE

The file name to which the output of --output_config is written. If used without --output_config, the complete configuration is output to FILE, as if --output_config /* was specified.

6.4.5.3. Exit Code

axivion_ci returns with exit code zero whenever the analysis completed successfully, even if new issues have been found.

If you want axivion_ci to return with non-zero exit code in case new issues have been detected, you can configure this behavior via option /Results/Dashboard/limit_violations.failure_exit_code and by also configuring appropriate limits at /Results/Dashboard/limit_violations.

All other exit codes indicate unspecified errors during the build/analysis run and you may want to handle them in the calling process accordingly.

6.4.5.4. Default Parallelism

If parallel execution is requested (or enabled by default) without specifying the number of jobs, the system determines it automatically as follows:

• Start with the total number of available CPU cores (respecting container or system limits).

• Reduce that number so that each job has at least 2 GB of memory available.

You can change the 2 GB per job limit by setting the environment variable AXIVION_MIN_MEM_PER_CORE (in bytes, default is 2147483648).