5.8. Local Build

5.8.1. Introduction

The Local Build provides the ability to analyze your code changes before committing them to the repository. This can also speed up the “develop – analyze – fix issues” cycle.

Here we give an overview of how the Local Build works, the integration into the plugins, and how to use the Local Build without the plugins.

Despite the possibility to use the Local Build without the plugins, the recommended way is to use the plugins because they hide much of the required magic.

5.8.2. Overview of the Local Build

The Local Build is a special mode of the tool axivion_ci which is intended to use the same configuration as axivion_ci uses for the server analysis.

At the beginning of a Local Build, axivion_ci fetches a reference version of the current issues from the dashboard. This version is used to diff against the issues found by the Local Build. The reference version and the issues found by the Local Build are written into the project database HOME/.bauhaus/localbuild/projects/<project_name>.db. This file is created automatically, so no manual action is needed to create it. After the Local Build, this database contains the version Empty, the reference version, and the Local Build results.

5.8.3. Preparing the Configuration

To build the native object files and the IR incrementally without interfering with each other, the configuration must be prepared accordingly. There is no “one size fits all” solution for this.

In contrast to the CI server build which may just hold the analysis results in its working copy, the analysis results of the Local Build have to co-exist with the native build results in the same working copy. So there are two possible options to solve this problem:

  • Use different output folders for native build and analysis (preferred way).

  • Use different names for the output files (e. g. IR suffix).

In an environment prepared for cross-compilation, a separate platform for the analysis can be used which will lead to a separate output directory for the analysis. A second working copy for the Local Build might be an option, but then there would be two independent copies of the code requiring some kind of synchronization between them. irCC will not work because it cannot do an incremental build independently and so every Local Build run would have to do a clean build (native and analysis). MSBuild can be used with IR suffix without requiring to clean the native build. However, incremental build does not work in this case.

The tool axivion_ci is put into the Local Build mode by the plugins automatically. In case of a manually started Local Build, the Local Build mode is achieved by the environment variable

AXIVION_LOCAL_BUILD=1

5.8.4. Configuring the TLS Certificate

The Local Build needs to fetch a reference analysis from the Axivion Dashboard Server. If the Dashboard connection is transport encrypted (HTTPS), the client has to verify the Dashboards certificate.

Python Requests (used by the CI in Local Build mode), uses a certificate bundle file which is referenced by the environment variable REQUESTS_CA_BUNDLE. This file contains certificates in PEM format (ASCII armored Base64). To trust a servers certificate, the corresponding root certificate has to be placed into the file referenced by REQUESTS_CA_BUNDLE - an intermediate certificate alone or the server certificate (if not self-signed) is not enough.

The root certificate of the Dashboard server can be retrieved with your browser.

In the simplest case, the file content looks similar to this example:

-----BEGIN CERTIFICATE-----
<base64 of root certificate>
-----END CERTIFICATE-----

A more complex example would be:

-----BEGIN CERTIFICATE-----
<base64 of root certificate A>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<base64 of root certificate B>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<base64 of immediate certificate B1>
-----END CERTIFICATE-----

5.8.5. Starting Local Build from within the IDE Plugins

From the plugins, the Local Build can be started with the Local Build button in the toolbar above the issue list.

Local Build Button

Local Build Button

For the Axivion Eclipse Plugin, the Axivion Visual Studio Plugin, and the Axivion CLion Plugin, a dialog box appears which queries the information which is required to run the Local Build: the path to the Axivion Suite installation folder and the command which runs the Local Build. The Axivion Visual Studio Code Plugin is configured via the settings.json as described in Configuration.

This command is usually the build script you are using on your CI server, e. g. start_analysis.bat or axivion_ci. Please make sure though, that a axivion_ci invocation can find the correct configuration. This is achieved by setting BAUHAUS_CONFIG.

The Build Type list can be used to switch between incremental and clean Local Builds. When Clean is selected, the environment variable AXIVION_CLEAN_BUILD=1 is set. Selecting Incremental sets the environment variable AXIVION_INCREMENTAL_BUILD=1 .

The plugin will put axivion_ci into Local Build mode and pass it the username and password required to fetch the reference version from the Axivion Dashboard Server.

The plugin will update the Local Build status of the project automatically when the Local Build finished.

When a local build is available, the View Local Build Results Button becomes active. This button is used to toggle between showing the analysis results from the dashboard and showing the analysis results of the Local Build.

View Local Build Results Button

View Local Build Results Button

Viewing the Local Build results offers three options:

  • All issues found by the Local Build (start version empty, end version Local Build).

  • All newly found issues in the Local Build (start version reference, end version Local Build).

  • All issues of the reference version (start version empty, end version reference).

Note

The IDE plugins will set these environment variables for the Local Build subprocess:

  • AXIVION_USER_AGENT=<plugin-identifier>/<version> where <plugin-identifier> is

    • AxivionEclipsePlugin or

    • AxivionVisualStudioPlugin or

    • AxivionVsCodePlugin

  • AXIVION_LOCAL_BUILD=1

  • AXIVION_PROJECT_NAME: the name of the project to build in the (global) Dashboard

  • AXIVION_BASE_DIR: the path to the Axivion Suite installation directory if known

Caution

Changing Axivion Dashboard Server related environment variables should not be necessary when the Local Build is started from an Axivion IDE plugin. The plugin already sets the needed variables so that the Axivion CI can connect to the Dashboard.

The plugins are using a two way mechanism to transport the Dashboard password to the CI. This involves the environment variables AXIVION_PASSWORD and AXIVION_PASSFILE. This means that the two variables have to be kept in sync.

So when your start script changes AXIVION_PASSWORD, it has to delete AXIVION_PASSFILE so that the CI uses the correct mode to read the Dashboard password.

Caution

At the time of the local build, the current value of the environment variable BAUHAUS_PYTHON is stored. When a BAUHAUS_PYTHON variable is stored, the plugin will set it for the local Dashboard when the plugin starts the local Dashboard.

When doing an in-place upgrade from e.g. Axivion Suite 6.9 (requires Python 2.7) to Axivion Suite 7.x (requires Python 3), the old value can prevent the start of the local Dashboard. Use local_build_config [--project PROJECT] [--version VERSION] python set "path/to/python.exe" to adjust the local build configuration.

This is only needed for already existing local builds. Another way to fix the local build is to just re-run it with the new Axivion Suite version.

5.8.6. Local Build without Plugins

Depending on whether you have a running dashboard with your project available or not (either because it is not yet set up at all, or because you do not have network connection to your dashboard), you can execute an Online Local Build without Plugins or an Offline Local Build without Plugins.

5.8.6.1. Online Local Build without Plugins

This mode of operation requires a running central dashboard, connects to it - using some way of authentication -, downloads a reference version from it and then does a delta analysis in the local workspace.

To start the Online Local Build manually (without plugins), a few environment variables have to be set:

AXIVION_LOCAL_BUILD=1
AXIVION_DASHBOARD_URL=http://your-dashboard-url.example/axivion
AXIVION_USERNAME=dashboard_username
AXIVION_PASSWORD=dashboard_password_or_token

You can omit the variables AXIVION_USERNAME and/or AXIVION_PASSWORD. When AXIVION_USERNAME is omitted, the user name of your Windows user account is used. When AXIVION_PASSWORD is omitted, the password or token (creatable on the User Preferences Page) is asked for interactively.

After setting the environment variables, start your build script like you do on your CI server or run, e. g. start_analysis.bat or axivion_ci.

To view the Local Build results, you can use the server instance of the dashboard and install the project database mentioned above. The second way is to start/stop a local dashboard as below:

#On Linux
dashserver start --local
  --install_file=$HOME/.bauhaus/localbuild/projects/<project>.db

#On Windows
dashserver start --local
  --install_file=%USERPROFILE%\.bauhaus\localbuild\projects\<project>.db

#Stopping the local dashboard
dashserver stop --local

#Prints further options and description
dashserver start --help
The switch --local has the following effect:
Use the predefined local dashboard configuration. The local dashboard configuration is meant for usage only by a single user and on a single machine. There is only one local dashboard per user and its configuration is stored in a central place in your user/home folder, so you do not need to specify the --confdir option. Its configuration will be deleted automatically when it is stopped, so although it is possible you should not spend effort in configuring it.

Caution

As the Axivion Eclipse Plugin and the Axivion Visual Studio Plugin do not know about manually started Local Build processes, they are unable to update their state automatically after the Local Build finishes.

5.8.6.2. Offline Local Build without Plugins

This mode of operation is completely local without the requirement for a running dashboard. As a consequence, the results cannot be presented as delta against a reference version but always contain the full set of findings from the workspace.

To start the Offline Local Build manually (without plugins), you have to set the environment variable AXIVION_LOCAL_BUILD to 1. Please note that the environment variable AXIVION_DASHBOARD_URL must not be defined, because that would signal an Online Local Build with dashboard connection. Subsequently, also the environment variables AXIVION_USERNAME and AXIVION_PASSWORD do not have to be set.

Starting the analysis and viewing the results is done the same way as an Online Local Build without Plugins.