Tutorial
Building Docker images
for IAR Build Tools on Linux

This tutorial provides guidance on how to build Docker images containing one of the IAR Build Tools packages using Ubuntu Linux as host OS. From these images, the tools run inside Docker containers. This repository is a revamped version of the earlier bxarm-docker tutorial.

Each of the IAR Build Tools packages requires its specific license. Please feel free to contact us if you would like to learn how to get access to them.

If you have a question specifically related to this tutorial, you might be interested in verifying if it was already answered from earlier questions. Or, ask a new question if you could not find any answer for your question.

Important:

Before you start the walkthrough, make sure you have a non-root super user account - a user with sudo privileges - if you need to install the Docker Engine on the Ubuntu host. If you already have the Docker Engine in place, the standard user account has to belong to the docker group.

IAR Systems only provides what is considered to be the bare essential information for the completion of this tutorial when it comes to Ubuntu, Linux, Docker, Bash and Git in general. That way, it becomes straightforward for any user willing to follow the steps until the end. Beyond this point, as in production, a proper level of familiarity with these platforms becomes a self-evident pre-requisite.

Conventions
Installing Docker
Build a Docker image with the IAR Build Tools
Setup host environment
Host license configuration
Using the IAR Build Tools from a Docker container
Additional resources
Summary

Conventions

As we are going to be dealing with different packages, for different architectures and their respective versions, it unfolds many different possibilites for this tutorial. Establishing some useful conventions becomes convenient.

The following conventions are going to be used:

Placeholder	Meaning
`<arch>`	Architecture Valid: `arm`, `riscv`, `rh850`, `rx`
`<package>`	Product package Valid: `arm`, `armfs`, `riscv`, `rh850`, `rh850fs`, `rx`
`<version>`	Package version Valid: `major`.`minor`.`patch` `[.build]`

Examples:

Package/Version	Meaning
BXARM 9.10.1	IAR Build Tools for Arm version 9.10.1 `<arch>`=`arm` `<package>`=`arm` `<version>`=`9.10.1`
BXARMFS 8.50.10.35167	IAR Build Tools for Arm, Functional Safety Edition, version 8.50.10 `<arch>`=`arm` `<package>`=`armfs` `<version>`=`8.50.10.35167`
BXRISCV 1.40.1	IAR Build Tools for RISC-V version 1.40.1 `<arch>`=`riscv` `<package>`=`riscv` `<version>`=`1.40.1`

Installing Docker

The following steps are the typical ones needed to make Docker ready to be used on the Ubuntu host which will hold the Docker images and run the containers. These installation instructions are based on the official ones available in the Docker Documentation.

Setup the Official Docker Repository

Update the apt package database cache and install packages that allow apt to use a repository over HTTPS:

$ sudo apt-get update

$ sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

Launch a bash shell and add Docker's official repository GPG key to the package management keyring.

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

Use the following command to set up the stable repository.

$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

Install the Docker Engine

Update the apt package index, and install the latest version of Docker Engine and containerd.

$ sudo apt update && sudo apt -y install docker-ce docker-ce-cli containerd.io

In order to use Docker as a non-root user, add the user (referred by the $USER environment variable) to the "docker" group.

$ sudo usermod -aG docker $USER

Now log out and log back in so thay your group membership is re-evaluated.

As in many Linux distributions using systemd to manage which services to start when the system boots, the Docker service can be configured with systemctl to start on boot. To automatically start Docker with the system, enable the service.

$ sudo systemctl enable docker && sudo systemctl start docker

Verify that your user can run docker commands without requiring sudo powers.

$ docker run hello-world

This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits.

Build a Docker image with the IAR Build Tools

The commands in this section are for building a Docker image containing one IAR Build Tools package. It uses an universal Dockerfile template to cover different packages, architectures and versions.

In order to simplify the process of building these Docker images, a build script is offered. The script will create one Docker image per <package>-<version>.

An IAR Build Tools installer package is required for the build script to operate over the Dockerfile. The IAR Build Tools installer packages are prefixed with bx and packaged in the .deb format.

The general package naming will follow this format: bx<package>-<version>.deb.

The table below lists the IAR Build Tools installer packages that have been successfully used for building Docker images with this current solution.

bx`<package>`-`<version>`.deb	`<package>`	`<version>`	`<arch>`
`bxarm-9.10.1.deb` `bxarm-8.50.9.deb` `bxarm-8.50.6.deb`	`arm`	9.10.1 8.50.9 8.50.6	`arm`
`bxarmfs-8.50.10.35167.deb`	`armfs`	8.50.10.35167	`arm`
`bxriscv-1.40.1.deb`	`riscv`	1.40.1	`riscv`
`bxrh850-2.21.1.deb`	`rh850`	2.21.1	`rh850`
`bxrh850fs-2.21.2.1803.deb`	`rh850fs`	2.21.2.1803	`rh850`
`bxrx-4.20.1.deb`	`rx`	4.20.1	`rx`

Launch a bash shell and clone the bx-docker repository to the user's home directory (~).

$ git clone https://github.com/iarsystems/bx-docker.git ~/bx-docker

Build the Docker image for the desired bx<package>-<version>.deb using the following command.

$ ~/bx-docker/scripts/build <path-to>/bx<package>-<version>.deb

The build script will automatically tag the Docker image to be built as iarsystems/bx<package>:<version>.

Multiple images for different packages and their versions can be built in seconds by invoking the build script sucessive times with a corresponding installer package. It is possible to invoke docker images iarsystems/* to list any Docker images which were already built. For example:

REPOSITORY                         TAG                 IMAGE ID            CREATED             SIZE
iarsystems/bxarm                   9.10.1              cef45bb09322        5 minutes ago       2.08GB
iarsystems/bxarmfs                 8.50.10.35167       527420cb4fcf        8 minutes ago       1.96GB
iarsystems/bxriscv                 1.40.1              89bd0878856f        15 minutes ago      2.05GB
iarsystems/bxarm                   8.50.9              ffcfa26ef829        About an hour ago   2GB
iarsystems/bxrx                    4.20.1              ab1b39f07955        About an hour ago   1.4GB
iarsystems/bxrh850fs               2.21.2.1803         735d80b00832        About an hour ago   2.33GB
iarsystems/bxrh850                 2.21.1              d19afbb0a274        About an hour ago   2.32GB
iarsystems/bxarm                   8.50.6              ad9209426630        About an hour ago   2GB

Setup Host environment

In this section, we will take advantage of bash aliases so we can simplify how we run the containerized IAR Build Tools that were installed within the Docker image. Declaring aliases in bash is straightforward. Aliases can last only for the current bash shell session's lifetime.

The general syntax for declaring an alias directly from the command line is:

$ alias <alias-name>='<command-to-run>'

Unsetting previous aliases

In order to avoid potential conflicts between aliases for tools from different images, start with the alias-unset script. The script will quickly unset any aliases for the IAR Build Tools that might have been previously set.

$ source ~/bx-docker/scripts/aliases-unset

Note

It is recommended to invoke aliases-unset before invoking aliases-set for switching from active <package>-<version> to another.

Setting new aliases

The aliases for the IAR Build Tools from existing Docker images are set with the aliases-set script, using the following syntax:

$ source ~/bx-docker/scripts/aliases-set <package> <version>

-- Aliases for IAR Build Tools were set.
   .. Using Docker image: iarsystems/bx<package>:<version>.

The alias-set script will only set the aliases for the IAR Build Tools if the corresponding Docker image can be found in the host.

From this point onwards, when any of the IAR Build Tools is invoked, the aliases will take place. The corresponding Docker container for the iarsystems/bx<package>:<version> image will be spawned, running the selected tool. When the tool operation is completed, the container is destroyed.

It is possible to list all the IAR Build Tools aliases currently set with the following command:

$ alias | grep iarsystems

Sticking with the aliases

Once we have the Docker images built, we have the option to make aliases settings for a single Docker image persistent. In order to achieve that, we need to add the desired command that sources alias-set script into one of the various configuration files that are read when a new bash shell session is launched.

The files that the bash shell reads when a session launches are, in general, ~/.bashrc and ~/.bash_profile. We just need append the command to set the desired aliases for the chosen <package> and <version> in one of them. We can perform this change from an editor, or straight from the command line. For example:

source ~/bx-docker/scripts/aliases-set <package> <version> >> ~/.bashrc

Now, the aliases for running the IAR Build Tools from the chosen Docker Image should always become available when a new bash shell session is launched, unless:

The corresponding iarsystems/bx<package>:<version> Docker image is inaccessible.
The chosen bash configuration file is changed and the command for sourcing the alias is removed.
The alias-unset is invoked during the current bash session.

Notes

The aliases-set script is a general solution to make the usage of the IAR Build Tools seamless.

These aliases bind the host's current directory ($PWD) to the container's /build directory.

It is recommended to invoke the tools from the project's top directory (or any level above). That way, the Docker container will have full visibility over all the project's files.

Ultimately, these aliases are optional as any user can take them as reference for customizing their code to meet particular requirements.

Host license configuration

This section shows how to configure the license on the Host for when using the IAR Build Tools from a Docker container.

The Host license configuration requires an IAR License Server already up, loaded with activated licenses and reachable from the Host.

Executing the build tools prior properly setting up the license will result in a fatal error message: "No license found."

$ icc<arch> --version

   IAR ANSI C/C++ Compiler V<version>/LNX for <arch>
   Copyright 1999-2021 IAR Systems AB.
Fatal error[LMS001]: License check failed. Use the IAR License Manager to
          resolve the problem.
No license found. [LicenseCheck:2.17.3.J190,
          RMS:9.4.0.0023, Feature:<ARCH>BX.EW.COMPILER, Version:1.18]
Fatal error detected, aborting.

The Host license setup is performed with lightlicensemanager as follows:

Override the Host's default license settings directory and make it persistent.

$ echo "export IAR_LMS_SETTINGS_DIR=$HOME/.lms" >> ~/.bashrc && source ~/.bashrc

Make the directory for the license settings.

$ mkdir $IAR_LMS_SETTINGS_DIR

Setup the Host license to point to the IAR License Server (LMS2).

$ lightlicensemanager setup -s <LMS2.server.IP>

Once the license is properly setup, it should be possible to run all the IAR Build Tools.

$ icc<arch> --version

IAR ANSI C/C++ Compiler V<version>/LNX for <arch>

The IAR Build Tools are ready to use.

Notes

Update the <LMS2.server.IP> with the actual IP address to the IAR License Server.

It is possible to customize the IAR_LMS_SETTINGS_DIR environment variable to point a different location. The location does not necessarily need to belong to the build tools user, but requires read/write/execute (rwx) access permissions. If the chosen location is volatile, such as /tmp/.lms, the Host license setup will need to be run every time after the Host reboots.

There are cases where a Firewall could be preventing the Host from reaching the IAR License Server. IAR Systems provides a Tech Note covering such cases.

Access the Installation and Licensing User Guide for Linux for more information.

Using the IAR Build Tools from a Docker container

In this section, we are going to explore some of the IAR Build Tools capabilities using any of the example projects for all the supported <arch>. Each of them was created with its respective IAR Embedded Workbench.

Building a project

With the IAR command line build utility, namely iarbuild, it is straightforward to build a project that was previously created with the IAR Embedded Workbench for <arch>. It enables us to quickly build projects using the same <build-configuration> from the .ewp project file.

Simplified syntax:

iarbuild <relpath-to>/<project>.ewp [command] <build-configuration> [-parallel <cpu-cores>] [other-options]

For example, to build using the "Debug" build configuration from the c-stat.ewp project, paste the corresponding command from the table below for the <arch> in use.

`<arch>`	Command
`arm`	`iarbuild bx-docker/projects/arm/c-stat.ewp "Debug"`
`riscv`	`iarbuild bx-docker/projects/riscv/c-stat.ewp "Debug"`
`rh850`	`iarbuild bx-docker/projects/rh850/c-stat.ewp "Debug"`
`rx`	`iarbuild bx-docker/projects/rx/c-stat.ewp "Debug"`

Notes

The [command] parameter is optional. If ommited, it will default to -make. Other commands commonly used when build projects are -build or -clean.

The <build-configuration> parameter is mandatory. Typically it will be Debug or Release. This parameter accepts multiple comma-separated build configurations such as Debug,Release[,MyAnotherCustomBuildConfiguration,...]. Ultimately this parameter accepts the * as wildcard. The wildcard will address all the build configurations in the <project>.

The -parallel <cpu-cores> parameter is optional. It can significantly reduce the required time for building when the host PC has 2 or more CPU cores.

Invoke iarbuild with no parameters for a more extensive description on its parameter options.

Static Code Analysis

With iarbuild, it is also possible to perform static code analysis with C-STAT on any existing <build-configuration> in an .ewp file.

Simplified syntax:

iarbuild <relpath-to>/<project>.ewp -cstat_analyze <build-configuration> [-parallel <cpu-cores>]

For example, static code analysis with C-STAT using the "Release" build configuration from the c-stat.ewp project can be performed by simply pasting the command from the table below which should point to the project created for the <arch> in use.

`<arch>`	Command
`arm`	`iarbuild bx-docker/projects/arm/c-stat.ewp -cstat_analyze "Release" -parallel $(nproc)`
`riscv`	`iarbuild bx-docker/projects/riscv/c-stat.ewp -cstat_analyze "Release" -parallel $(nproc)`
`rh850`	`iarbuild bx-docker/projects/rh850/c-stat.ewp -cstat_analyze "Release" -parallel $(nproc)`
`rx`	`iarbuild bx-docker/projects/rx/c-stat.ewp -cstat_analyze "Release" -parallel $(nproc)`

By default, the C-STAT static analysis outputs a SQLite database named cstat.db. Then, use ireport to process the database and generate an automatic full HTML report containing all the warnings about coding violations for the <project>'s selected checks:

Simplified syntax:

ireport [--full] --db <relpath-to>/cstat.db --project <relpath-to>/<project>.ewp

For example, to generate a full HTML report from the previous project analysis, we can use the ireport tool pointing to the project for the corresponding <arch> from the table below.

`<arch>`	Command
`arm`	`ireport --full --db bx-docker/projects/arm/Release/Obj/cstat.db --project bx-docker/projects/arm/c-stat.ewp`
`riscv`	`ireport --full --db bx-docker/projects/riscv/Release/Obj/cstat.db --project bx-docker/projects/riscv/c-stat.ewp`
`rh850`	`ireport --full --db bx-docker/projects/rh850/Release/Obj/cstat.db --project bx-docker/projects/rh850/c-stat.ewp`
`rx`	`ireport --full --db bx-docker/projects/rx/Release/Obj/cstat.db --project bx-docker/projects/rx/c-stat.ewp`

The output will be similar to:

HTML report generated: bx-docker/projects/<arch>/c-stat.ewp.html

Note

When used in conjunction with iarbuild, C-STAT will look for a file named <project>.ewt in the <project>'s folder. This file is automatically generated by the IAR Embedded Workbench IDE when rulesets other than its Standard Checks were selected a <build-configuration>.

Running interactive containers

The aliases-set script brings the bx<package>-docker-interactive alias to spawn a container in interactive mode:

$ bx<package>-docker-interactive

To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

iaruser@96a4986f8535:/build$ iarbuild bx-docker/projects/<arch>/c-stat.ewp -build "*" -parallel $(nproc)

...
...
Total number of errors: 0
Total number of warnings: 0

Type exit to exit from the interactive container:

iaruser@96a4986f8535:/build$ exit

Additional Resources

If you are new to CI/CD, Docker, Jenkins and Self-Hosted Runners or just want to learn more and see the IAR tools in action, you can find an useful selection of recorded webinars about automated building and testing in Linux-based environments here!

Summary

And that is how Docker images containing the IAR Build Tools can be made. The ambition is to provide a quick start towards Docker scenarios. It is definitely not the only method, neither a replacement for the extensive Docker Documentation.

The tutorial's sections alongisde the scripts and the universal Dockerfile sum up as a cornerstone for many existing build server topologies. Ultimately, any user can take them as reference for customizing their code to meet particular DevOps requirements.

imrj/bx-docker

Tutorial
Building Docker images
for IAR Build Tools on Linux

Table of Contents

Conventions

Installing Docker

Setup the Official Docker Repository

Install the Docker Engine

Build a Docker image with the IAR Build Tools

Setup Host environment

Unsetting previous aliases

Setting new aliases

Sticking with the aliases

Host license configuration

Using the IAR Build Tools from a Docker container

Building a project

Static Code Analysis

Running interactive containers

Additional Resources

Summary

imrj/bx-docker

TutorialBuilding Docker imagesfor IAR Build Tools on Linux

Table of Contents

Conventions

Installing Docker

Setup the Official Docker Repository

Install the Docker Engine

Build a Docker image with the IAR Build Tools

Setup Host environment

Unsetting previous aliases

Setting new aliases

Sticking with the aliases

Host license configuration

Using the IAR Build Tools from a Docker container

Building a project

Static Code Analysis

Running interactive containers

Additional Resources

Summary

Tutorial
Building Docker images
for IAR Build Tools on Linux