1.4.65. Migration to new Configuration System

Version 7.0 introduces a new, extended configuration system. Now, besides manually created Python configuration files, you can also use JSON configuration files created using a graphical user interface named axivion_config. Starting from version 7.1, the new system is available for CI/VCS configuration, all kinds of analyses and code annotations (markup comments) used to suppress or justify issues. Version 7.3 introduces support for compiler and UI tool configuration using the new system.

Caution

The steps described in Migration to 7.0.0 need to be done before the steps described here.

Caution

Old-style XML files for configuring the project, analyses, the compiler and code annotations can still be used in 7.3, but they are deprecated, and support for these files will be dropped in a future version. Migration scripts are provided for the transition to the new system.

In case you’ve got additional stylechecks or metrics in place, they also might need some migration to be usable in the new analysis framework which now handles all kinds of analyses in a uniform way.

The new Project Configuration allows a uniform analysis configuration with the new graphical user interface axivion_config and Python files.

In general, you can decide which parts to configure using the GUI, and which parts to configure in Python (some options can only be configured in Python, e.g. when they require a Python function as value).

It is recommended to configure as much as possible with axivion_config unless you have specific reasons to prefer Python. An approach for the migration thus would be:

  1. Use axivion_config and enable the rules which correspond to the CI analysis tools, stylechecks and metrics that your existing configuration activates. You do not have to switch everything at once. For example, you could start by migrating the stylechecks, leaving other analyses in the old form at first.

  2. Also use axivion_config to set rule options where possible in the GUI to the values of your current configuration.

  3. Create a Python configuration file for those parts of the configuration that you cannot do in the GUI.

  4. Create an interface configuration file axivion_config.json and reference the file(s) saved from within the GUI and the Python file(s). This file will be picked up by default as the configuration for your project.

The sections below help you with the details of these steps. The new tool axivion_analysis is used to execute all kinds of analyses. The sections below describe the migration for each erosion kind.

1.4.65.1. Overview of Configuration Files

Mapping of old configuration files to new files

Old file

Migration tool

New file

build.conf

migrate ci

ci_config.json

cafeCC.config

migrate compiler

compiler_config.json

gravis2.config

migrate gravis

gravis_config.json

includes.config

N/A

rule_config.json

ir2rfg.config

migrate config

rule_config.json

iranalysis/externals/c_std_lib.config

migrate config

rule_config.json

iranalysis.config

migrate config

rule_config.json

irclones.config

N/A

rule_config.json

irlink.config

migrate compiler

compiler_config.json

LanguageSupport.config

migrate compiler

compiler_config.json

metric_config.py

migrate config

rule_config.json

Metrics.config

N/A

rule_config.json

predefined_macros.txt

migrate compiler

compiler_config.json

predefined_sizes.txt

migrate compiler

compiler_config.json

Scanner.config

N/A

rule_config.json

stylecheck_config.py

migrate config

rule_config.json

stylecheck.config

migrate config

rule_config.json

Note: the new file names are the output files created by the migration tool. The new configuration system does not require the use of these names, e.g. the complete configuration could be combined in a single axivion_config.json file.

1.4.65.2. Automatic Config Migration

You can use the command migrate config to automatically generate a new JSON configuration from your existing configuration. Note that your existing configuration will first need to be adjusted to 7.0 (as described in Migration to 7.0.0).

To generate the new configuration, set BAUHAUS_CONFIG as during analysis, then run:

migrate config --all_layers

This will write the new configuration files into the existing directories.

If your existing configuration depends on the environment (e.g. because you have code in stylecheck_config.py inspecting os.environ), only the current variant of the configuration will be migrated.

For more complex configurations, the automatic migration can be used to create a starting point for the manual migration.

The migration tool will generate an interface JSON file axivion_config.json, a declarative config rule_config.json, which can be edited with the axivion_config GUI, and a Python script rule_config.py for settings that cannot be configured using the GUI.

Note that XML/Python comments in the existing configuration are ignored by migrate and should be copied to the new configuration manually.

Starting with version 7.1, there is a further step migrate ci available that can migrate the build.conf contents to the new configuration system. We recommend that you first migrate the stylechecks to the new configuration system before you attempt to migrate build.conf.

Starting with version 7.3, there are two further steps migrate compiler and migrate gravis available. migrate compiler migrates the contents of cafeCC.config, predefined_macros.txt, predefined_sizes.txt, irlink.config and LanguageSupport.config to the new configuration system. migrate gravis migrates the contents of gravis2.config to the new configuration system. We recommend that you first migrate the stylechecks and CI configuration (build.conf) to the new configuration system before attempting to migrate the compiler settings.

Recommended order of migration:

  • migrate config

  • migrate ci

  • migrate compiler

  • migrate gravis

1.4.65.3. Activate the new Analysis Tool

In order to use the new configuration system for analysis configuration, add the following to your build.conf, next to the classic stylecheck tool:

Activate the new analysis tool
<action tool="analysis" name="analysis" />

In this simple form, the default file name axivion_config.json is looked up in your project configuration. The easiest approach is to create this file in the following steps using the GUI. If you want to split the configuration into different files, or if you require Python configuration files besides the part done with the GUI, then this can also be an interface JSON file (see Configuration Files). Now start axivion_config in order to create the file with contents as described in the next sections.

1.4.65.4. Migrate Clone Detection

If you’ve got clone detection via irclones enabled, perform the following steps:

  1. In the GUI, select the rule CloneDetection

  2. If your irclones entry in build.conf listed some options for the analysis, or if you had special settings in your irclones.config, set them now in the GUI to the same values

  3. Save the configuration in the GUI

  4. Remove the irclones configuration in your build.conf and delete any project-specific file irclones.config

1.4.65.5. Migrate Cycle Detection

If you’ve got cycle detection via cycles enabled, perform the following steps:

  1. In the GUI, select the corresponding rule depending on the view on which the analysis was executed:

    • CycleDetection-CallgraphCycles if you used the default settings (operating on the Call view)

    • CycleDetection-IncludeCycles if you configured the analysis

      to use the Include view

    • Architecture-CycleDetection in all other cases (don’t forget to set the view there)

  2. If your cycles entry in build.conf listed some options for the analysis, set them now in the GUI to the same values

  3. If you also want the number of strongly connected components as a metric, activate the rule Metric-Number_Of_SCCs (in the GUI, you find this in the path Metrics/CallgraphMetrics) and set its options

  4. Save the configuration in the GUI

  5. Remove the cycles configuration in your build.conf

1.4.65.6. Migrate Dead Code Detection

If you’ve got dead code detection via deadcode enabled, perform the following steps:

  1. In the GUI, select the rule DeadCodeDetection

  2. If your deadcode entry in build.conf listed some options for the analysis, set them now in the GUI to the same values

  3. If you also want to configure additional entry points, activate the corresponding rules in rulegroup AnalysisControl/Environment/EntryPoints and set their options

  4. Save the configuration in the GUI

  5. Remove the deadcode configuration in your build.conf

1.4.65.7. Migrate ir2rfg

If you’ve got ir2rfg enabled, perform the following steps:

  1. If your ir2rfg entry in build.conf listed some options, or if you had special settings in your ir2rfg.config, set them now in the GUI to the same values. The former options are now available in different places:

    • Most options are present in rule Architecture-Dependencies (which is activated automatically when an RFG is needed)

    • Metric options have been moved to the metric rules (for example, former command-line option --consider_dynamic_calls_in_metrics is now an option of the affected rules in rulegroup Metrics/CallgraphMetrics); former command-line option --his_metrics_aliases is not needed any more as it is inferred automatically

    • Configuration of additional entry points as previously possible in the build.conf tool ir2rfg with options interrupt_keywords and animating_attributes is now handled by the rules EntryPoints-EntriesByKeyword and EntryPoints-EntriesByAttribute

    • If you did not use option --no_dllexport_entries and you require functions being marked as dllexport as additional entry points (e.g., when analysing a library instead of a tool), then activate EntryPoints-EntriesByDLLExport

  2. Save the configuration in the GUI

  3. Remove the ir2rfg configuration in your build.conf and delete any project-specific file ir2rfg.config

1.4.65.8. Migrate iranalysis

If you’ve got iranalysis enabled, perform the following steps:

  1. If your iranalysis entry in build.conf listed some options, or if you had special settings in your iranalysis.config, set them now in the GUI to the same values. The former options are now available in different places:

    • Most options are present in rule AnalysisControl/StaticSemanticAnalysis

    • Configuration of specific checks (as it was possible in iranalysis.config) is now done at the rules for these checks

    • Configuration of the effects of external functions is now done with the rules in rulegroup AnalysisControl/Environment/Externals

    • Configuration of custom resources is now done with the rules in rulegroup AnalysisControl/Environment/Resources, and checks targeting those dynamic resources refer to them by name

    • Configuration of additional entry points as previously possible in iranalysis.config is now handled by the rule EntryPoints-EntriesByName

    • The command-line option --only_control_flow is inferred automatically

  2. If you formerly had CONFIG.Run_IRAnalysis_Checks = True in your stylecheck configuration, activate AnalysisControl/StaticSemanticAnalysis. See below for the general mapping of such global iranalysis options for stylechecks.

  3. If you had the call to iranalysis prior to ir2rfg in your build.conf with the intention to have dynamic call edges in the RFG, then also activate the rule Architecture-AddDynamicCalls

  4. Save the configuration in the GUI

  5. Remove the iranalysis configuration in your build.conf and delete any project-specific file iranalysis.config as well as files in the iranalysis config subfolder

1.4.65.9. Migrate Stylechecks

If you’ve got stylecheck enabled, perform the following steps:

  1. If your stylecheck entry in build.conf listed some options, then add the same options to the analysis entry (command-line options for the tool now use to dashes)

  2. If you had special directories listed in your stylecheck.config, add them in the GUI by right-clicking on the Analysis toplevel node and selecting Additional rules.... Notice that formerly only rules in subdirectories of the listed directories were used; this has been changed: now rules in the given directory itself are also found

  3. Inspect your stylecheck_config.py file and activate the rules put into the ACTIVE set in the GUI. Also set the rule options there to the same values as before.

  4. For cases that still require Python, either adapt stylecheck_config.py to fit into the new configuration system, or create a new Python file for that purpose. List the file in the axivion_config.json interface file.

    Formerly, magic variables RULES and ACTIVE were used in the stylecheck configuration. This is no longer the case, a proper Python API has been created. Activating a rule and setting an option in Python now looks like this:

    Activating rules and setting rule options in Python
    import axivion.config
analysis = axivion.config.get_analysis()
analysis.activate('MisraC2012-1.1', 'Architecture-ArchitectureCheck')
analysis.activate('MisraC2012-10.3', severity='error')
analysis['MisraC2012-10.3'].provider = 'myself'

  5. Formerly, magic variable CONFIG was used to provide some global options. Set them now in the GUI, or if your prefer, in Python. Some options are still present in the toplevel Analysis node, others have been moved to analysis rules.

    The following table shows the migration of the CONFIG options (the right side here is in Python terms, the GUI of course provides equal access):

    CONFIG.xxx option

    New option

    Additional_Basic_Characters

    analysis.options.scanner.additional_basic_characters

    Allow_Single_Bitfield_As_Bool

    analysis.options.types.allow_single_bitfield_as_bool

    Base_View_Name

    analysis[‘Metrics’].base_view_name

    Effect_Free_Functions

    analysis.options.side_effects.effect_free_functions

    Effect_Free_Volatile_Variables

    analysis.options.side_effects.effect_free_volatile_variables

    Enums_As_Integer_Constants

    analysis.options.types.enums_as_integer_constants

    External_Functions_Returning_Bool

    analysis.options.types.external_functions_returning_bool

    Fixed_Size_Int_Typedefs

    analysis.options.types.fixed_size_int_typedefs

    Hierarchy_Edge_Name

    analysis[‘Metrics’].hierarchy_edge_name

    Hierarchy_View_Name

    analysis[‘Metrics’].hierarchy_view_name

    Ignore_Tokens_In_Disabled_Sections

    analysis.options.scanner.ignore_tokens_in_disabled_sections

    IRAnalysis_Allow_Function_Pointer_Signature_Mismatch
    analysis[‘StaticSemanticAnalysis’].callgraph_options

    .allow_function_pointer_signature_mismatch

    IRAnalysis_Assume_Globals_Are_Initialized
    analysis[‘FaultDetection-UninitializedVariable’]

    .assume_globals_are_initialized

    (also at other rules checking for uninitialized variables:

    MisraC-9.1, MisraC-21.1, MisraC2012Directive-4.1, MisraC2012-9.1, MisraC++-0.3.1, MisraC++-8.5.1, AutosarC++*-M.0.3.1, AutosarC++17_03-M8.5.1, AutosarC++17_10-M8.5.1, CertC-EXP33)

    IRAnalysis_Contexts
    analysis[‘StaticSemanticAnalysis’].global_classic_options

    .routine_context_granularity

    IRAnalysis_Safe_Mode
    analysis[‘StaticSemanticAnalysis’]

    .enable_filtering_heuristics (inverted logic)

    IRAnalysis_Uses_Uncalled_Entries
    analysis[‘StaticSemanticAnalysis’].callgraph_options

    .treat_uncalled_functions_as_alive

    IRAnalysis_With_AbstraIR
    analysis[‘StaticSemanticAnalysis’].global_classic_options

    .abstract_interpretation

    IRAnalysis_With_AbstraIR_Null
    analysis[‘StaticSemanticAnalysis’].global_classic_options

    .use_abstract_interpretation_for_null

    Local_Effect_Functions

    analysis.options.side_effects.local_effect_functions

    Misra_Essential_Types_Treat_Char_As_Integer

    analysis[‘MisraC2012-10’].treat_char_as_integer

    Mixed_Headers_Are_C

    analysis[‘Stylechecks’].mixed_headers_are_c

    Propagate_Metrics

    analysis[‘Metrics’].propagate

    Report_All_Metric_Values

    analysis[‘Metrics’].report_all_values

    Report_Propagated_Metric_Values

    analysis[‘Metrics’].report_propagated_values

    Run_IRAnalysis_Checks

    analysis.activate(‘StaticSemanticAnalysis’)

    Side_Effect_Functions

    analysis.options.side_effects.side_effect_functions

    Use_Bool_Cache

    n/a

    Use_Comment_Cache

    n/a

    Use_ConstValue_Cache

    n/a

    Use_Type_Cache

    n/a

    User_Bool_Type

    analysis.options.types.user_bool_types (is a set now)

  6. Formerly, special flag CONFIG.Run_IRAnalysis_Checks = True was required to activate iranalysis (fault detection). This is now done by activation of the rule StaticSemanticAnalysis.

  7. Save the configuration in the GUI

  8. Remove the stylecheck configuration in your build.conf and delete any project-specific file stylecheck.config (in case there is some metric configuration in that file, only do this after metric migration) as well as stylecheck_config.py if you don’t need it any more

Violations in macros

The configuration option report_at_macro_invocation was renamed to report_at and no longer accepts boolean values.

  • report_at_macro_invocation = False corresponds to report_at = 'macro_definition'

  • report_at_macro_invocation = True corresponds to report_at = 'macro_invocation'

When using the new configuration system, the report_at option has a new default value: 'automatic'. When using the old configuration system, the default value was 'macro_invocation'.

In automatic mode, the rule will automatically detect where to report the violation. Violations that occur for every use of the macro independent of the macro arguments or context in which the macro was used, will now be reported at the macro definition. Because multiple violations in the same line are deduplicated, this tends to reduce the number of violations reported. If the file with the macro definition is excluded from analysis (e.g. system header), violations in these macros will not be reported anymore.

Note

If you leave the report_at option at its default value, it is possible that you once get a large set of added/removed issues when migrating.

1.4.65.10. Migrate Metrics

If you’ve got metric enabled, perform the following steps:

  1. Perform the steps shown above for stylecheck migration, this time for metric_config.py and rule directories listed in stylecheck.config under the Metric key

  2. Activate and configure the token metrics formerly listed in Metrics.config in the rules in rulegroup Metrics/TokenMetrics

  3. Remove the metric configuration in your build.conf and delete any project-specific file Metrics.config

1.4.65.11. Migrate Architecture Check and Processline

If you’ve got architecture_check and/or processline enabled, perform the following steps:

  1. In the GUI, select the rule Architecture-ArchitectureCheck and set its options to the same values as before. There are specific rules now for the import of the architecture specification and to perform certain mappings; activate and configure those rules in group Architecture as needed

  2. For the former processline, an intermediate step is possible: You can activate the rule Architecture-ProcessLine which directly corresponds to the processline framework. However, this is just a wrapper to temporarily simplify the migration to version 7.0 and will be dropped some time in the future

  3. If needed, reorder the activated analyses in group Architecture (the order is important here as these rules might modify the underlying RFG)

  4. Save the configuration in the GUI

  5. Remove the architecture_check and/or processline configuration in your build.conf and delete any project-specific file processline_config.py once you’ve fully migrated the contents to the new rules (not using the Architecture-ProcessLine wrapper)

1.4.65.12. Migrate teecap

If you’ve got teecap enabled, perform the following steps:

  1. If you had special teecap formats defined in XML files inside the teecap config subfolder, recreate corresponding format definitions with the rules under the rulegroup AnalysisControl/ExternalAnalysisFormats

  2. In the GUI, select the rule ImportExternalAnalysisOutput and set its options to run the external tool of which the output should be captured. You may want to rename the rule (see next point below) as the name will appear as the rule name for the issues produced with this rule. The format of the output can be configured as well (the rule selects the desired format which is defined under the rulegroup AnalysisControl/ExternalAnalysisFormats)

  3. If you want to capture the output of more than one external tool, create as many copies of the rule as needed and configure them. Creating copies in the GUI is done by right-clicking on the rule ImportExternalAnalysisOutput and choosing Copy...

  4. Save the configuration in the GUI

  5. Remove the teecap configuration in your build.conf and delete any project-specific XML files inside the teecap config subfolder

1.4.65.13. Migrate Code Annotations

If you are using code annotations (typically through a custom analysis_config.py), perform the following steps:

  1. Version 7.0.0 allows to reuse a 6.9-style analysis_config.py with axivion_analysis, but this is deprecated. In order to reuse it, set the option AnalysisControl/CodeAnnotations.use_analysis_config_py. This may be used for a quick initial migration (but follow the note in the chapter above regarding minimal migration, the transition to Python 3 may require updates to the import statements).

  2. Otherwise, select and activate the desired comment formats under AnalysisControl/CodeAnnotations. As with other rules, you can copy and rename such formats to create independent copies that have independent configurations. Set the options to match your previous settings. Also use this approach to define your own comment formats.

  3. Formats activated in this way are automatically active for all files in the project; the former initial_formats is not necessary any more.

  4. The former initial_comments dictionary is now represented by rule InitialExternalAnnotations (under AnalysisControl/CodeAnnotations/ExternalCodeAnnotations).

  5. The former project_comments list is now represented by rule ProjectWideExternalAnnotations (under AnalysisControl/CodeAnnotations/ExternalCodeAnnotations).

  6. The former lint_rule_mapping_filename is now represented by the option rule_mapping_file in all formats under AnalysisControl/CodeAnnotations/LegacyFormats/LintFormats. Likewise, prqa_rule_mapping_filename is now option rule_mapping_file in all formats under AnalysisControl/CodeAnnotations/LegacyFormats/PRQAFormats.

  7. If you had defined a custom parser function to extract the justification, and if that parser used the four-argument version taking not only the comment and the group text, but also the erosion kind and rule name, you should transition to the new form taking three arguments: def my_parser(comment, text, issue). The issue has fields kind (an enumerator value of type code_annotations.IssueKind) and rule_name (a string).

  8. Replace the old analysis_config.py with the new configuration created above.

1.4.65.14. Migrating additional stylechecks and metrics

Version 7.0.0 also includes a new analysis framework which now handles all kinds of analyses in a uniform way. If you’ve got stylechecks or metrics in place which are not part of the standard installation (e.g. self-written rules), then they must be updated to fit into this new framework.

A major change in the analysis framework (compared to the former stylecheck framework) is the use of instances of Python classes as rules where the old framework used classes instead. This means there can be multiple instances of a rule now, each with their own, independent configuration.

The migrate tool can migrate Python code from the old framework to the new framework. Run it with the -w switch (to write the changes back into the input files) on the whole directory containing your rules:

migrate 7_0 -w .../your_rules

Please review the code changes made by the tool. In some cases it can be necessary to manually make further adjustments to the rules.

An example for a composite rule (combining multiple existing rules) is the following:

Composite rule to combine different rules under the same name
# Copyright (C) 2025 Axivion GmbH
# Copyright (C) 2025 The Qt Company GmbH, a subsidiary of The Qt Group
# https://www.qt.io


from rule1location import rule1  # replace with the proper Python module/package
from rule2location import rule2  # replace with the proper Python module/package

from axivion import analysis


@analysis.rule('SecondName', options={'my_option': True})
@analysis.rule('CommonName')
class CommonNameRule(analysis.CompositeRule):  # choose a class name
    _parts = [rule1.Rule1Rule, rule2.Rule2Rule]  # use the Python class names
    title = '''The title for the composite rule'''

    my_option: bool = False
    '''Description of the option.'''

Here, the Python class is instantiated by the decorator @analysis.rule, and the resulting instances are usable as new rules. The decorator can pass in values for all constructor parameters, and the instance SecondName shows how to redefine the default value of an option in this way.

For a self-written IR-based rule with its own logic you would typically inherit from the new class analysis.AnalysisRule and implement at least the execute method. An example is provided here:

Minimal self-written rule
# Copyright (C) 2025 Axivion GmbH
# Copyright (C) 2025 The Qt Company GmbH, a subsidiary of The Qt Group
# https://www.qt.io


from axivion import analysis

# other imports as required, e.g. from bauhaus.ir.common.output import unparse


@analysis.rule('AnotherCopy', options={'some_option': 17})
@analysis.rule('MyRule')
class MyRule(analysis.AnalysisRule):  # choose a class name
    title = '''The title for the composite rule'''

    some_option: int = 42
    '''Description of the option.'''

    _message_descriptions = {'my_message_key': 'This text will be shown'}

    def execute(self, ir_graph):
        # ... replace with your logic referencing self.some_option
        # report your findings one by one as style issues with
        # self.add_message(node, 'my_message_key', entity=unparse.entity(node))
        # you can also report all other kinds of issues with functions
        # like add_metric_issue, add_cycle_issue etc.
        pass

Note

Beginning with version 7.0.0, the public API that can be used inside custom extensions like additional stylechecks will be defined more precisely. For this, the affected functions, classes etc. are migrated step-by-step from the bauhaus package into the axivion package. The axivion package forms the public API. During the transition phase, you can still access the old entry points which have not yet been migrated, but the access to bauhaus is deprecated from now on.

1.4.65.15. Migrating Gravis

The configuration of gravis differs from that of other parts of the Axivion Suite in that gravis not only finds configuration files via BAUHAUS_CONFIG, but also looks for a file gravis2.config in the .bauhaus directory inside your home directory. This allows user-specific settings without having to set BAUHAUS_CONFIG to a user-specific value.

The automatic migration migrate gravis behaves like gravis: It first processes all configuration files referenced via BAUHAUS_CONFIG and writes a single output file (called gravis_config.json by default, but this can be overridden) that combines all the settings found via BAUHAUS_CONFIG. Then, it processes the gravis configuration file in the .bauhaus directory inside your home directory, if present, and writes a file called gravis.json to the same location. Like the old XML file gravis2.config, this new file is found automatically by gravis.