Tutorial
Building embedded applications with
the IAR Build Tools on Docker Containers

Docker is generally recognized as best practice to achieve automatically reproducible build environments. It provides means for containerizing self-sufficient build environments resulting from the requirements described in a Dockerfile.

This tutorial provides a Dockerfile and helper scripts that provide means for building embedded applications with the IAR Build Tools from a container.

⚠️ It is recommended to follow this tutorial on a test environment.

Disclaimer

The information in this repository is subject to change without notice and does not represent a commitment on any part of IAR Systems. While the information contained herein is assumed to be accurate, IAR Systems assumes no responsibility for any errors or omissions.

Pre-requisites

For completing this tutorial you are going to need:

Understanding on how to use command-line tools.
An IAR Build Tools installer package
- in the .deb format.
- 💡 Feel free to contact us if you would like to learn how to get access to the installers.
A recent x86_64/amd64 Linux machine
- connected to the Internet.
An IAR LMS2 License Server
- with activated license(s) for the product in the .deb package,
- reachable from the Linux machine.

Conventions

The following conventions are going to be used during this tutorial:

Placeholder	Meaning	Valid values
`<arch>`	Architecture	`arm`, `riscv`, `rh850`, `rl78` or `rx`
`<package>`	Product package	`arm`, `armfs`, `riscv`, `riscvfs`, `rh850`, `rh850fs`, `rl78`, `rl78fs`, `rx` or `rxfs`
`<version>`	Package version	`major`.`minor`.`patch` `[.build]`

Consider the following examples:

Installer package	Meaning	Placeholders to be replaced
bxarm-9.20.4.deb	IAR Build Tools for Arm version 9.20.4	`<arch>`=`arm` `<package>`=`arm` `<version>`=`9.20.4`
bxarmfs-8.50.10.35167.deb	IAR Build Tools for Arm Functional Safety Edition version 8.50.10.35167	`<arch>`=`arm` `<package>`=`armfs` `<version>`=`8.50.10.35167`
bxriscv-3.10.1.deb	IAR Build Tools for RISC-V version 3.10.1	`<arch>`=`riscv` `<package>`=`riscv` `<version>`=`3.10.1`

Installing Docker

For installing the Docker Engine on the Linux machine, follow the official instructions.

Alternatively, Docker provides a "convenience shell script" which can automate the process. Launch a bash shell and execute the following commands:

curl -fsSL https://get.docker.com -o get-docker.sh

DRY_RUN=1 sh ./get-docker.sh

💡 Verify the get-docker.sh script commands and, if you are satisfied, execute it once more without DRY_RUN=1 to install the Docker Engine.

In order to execute Docker commands, the current user ($USER) must be in the docker group. Execute:

sudo usermod -aG docker $USER

Then logout and login again for the changes to take effect.

Building a Docker image

Before being able to run a Docker container, we need to have a Docker image containing its required environment. A Dockerfile contains instructions that describe how an image should be built.

This Dockerfile was created as an universal template to build images with the IAR Build Tools.

The build script will use docker build ... with the Dockerfile, alongside an installer package (bx<package>-<version>.deb) to create one image.

In order to build the image, clone the bx-docker repository to the user's home directory (~) by executing the following command:

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

Then, invoke the build script pointing to the installer package:

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

Depending on your system's characteristics, it might take a while to build the image. This process usually might range from seconds to a few minutes. In the end, the build script will automatically tag the image as iarsystems/bx<package>:<version>.

💡 Invoke the build script once for each installer package you have so you will get one dedicated image for each of them.

Once you're done with image creation, execute docker images ... to list all the created images:

docker images iarsystems/*

And you will get an output similar to this, depending on the images you've created:

REPOSITORY                         TAG                 IMAGE ID            CREATED             SIZE
iarsystems/bxarm                   9.20.4              cef45bb09322        5 minutes ago       2.42GB
iarsystems/bxarmfs                 9.20.3.45167        527420cb4fcf        8 minutes ago       2.37GB
iarsystems/bxriscv                 3.30.1              89bd0878856f        About an hour ago   2.25GB

Setting up the license

The IAR Build Tools require an available network license to operate.

In order to set up the license for all the containers in the Linux machine, execute the setup-license script pointing to the image's <tagname:version> followed by the IAR LMS2 License Server's IP:

~/bx-docker/setup-license iarsystems/bx<package>:<version> <lms2-server-ip>

The setup-license script will prepare a Docker volume which can be shared among all the containers running on the Linux machine for persistent storage of the license configuration.

💡 This step must be performed only once. The Docker Engine will never erase this (or any other) named volume, even after the containers which made use of it are stopped or removed.

💡 If your network has multiple build nodes (Linux machines), setup-license must be performed individually on all of them.

Running a container

In this section, we will use the image we created to run a container so that later we can build a project.

The bx-docker repository comes with projects created in the IAR Embedded Workbench for the supported target architectures.

Access the projects sub-directory:

cd ~/bx-docker/projects

The run script will use the docker run ... command with all the necessary parameters to run the container.

Execute:

~/bx-docker/run iarsystems/bx<package>:<version>

Containers spawned by the run script will bind mount the current directory (pwd) to the Docker image's working directory (pwd). That way, these containers cannot access any parent directories. Make sure to always run a container from the project's top-directory from which all the project's files are accessible.

💡 Use docker run --help for more information.

Executing the Build Tools

The docker exec ... command can execute a command in a running container. Oftentimes, these command lines might become too long for typing every single time.

When you spawned the container using the run script, you also got bash aliases set for all the IAR Build Tools from the image you have selected to work with. These aliases encapsulated the required docker exec ... commands in such a way that the Linux machine can now execute all the IAR Build Tools seamlessly.

💡 Use docker exec --help for more information.

Build the project with iarbuild

The IAR Command Line Build Utility (iarbuild) can build (or analyze) a <project>.ewp.

The simplified iarbuild syntax is:

iarbuild relative/path/to/<project>.ewp [command] <build-cfg>

For example, use iarbuild with the -build <build-cfg> command to build the hello-world.ewp project using the build configuration for "Release":

iarbuild <arch>/hello-world.ewp -build Release

💡 Invoke iarbuild with no parameters for detailed description.

Performing static code analysis

Static Code Analysis can be performed with IAR C-STAT.

C-STAT is an add-on to the IAR Build Tools that help you to ensure code quality in your applications. If you have C-STAT, iarbuild can be used with the -cstat_analyze <build-cfg> command to analyze the project.

For performing an analysis using the "Release" configuration for the hello-world.ewp project, execute:

iarbuild <arch>/hello-world.ewp -cstat_analyze Release

The analysis results are stored in an SQLite database named cstat.db. This database can be used for generating an analysis report containing warnings about coding violations for the project's ruleset selection.

Use icstat to display the warnings on the terminal:

icstat load --db <arch>/Release/path/to/cstat.db

And then use ireport to generate an HTML report:

ireport --full --project hello-world --db <arch>/Release/path/to/cstat.db

HTML report generated: hello-world.html

💡 On terminal, you can use lynx hello-world.html to visualize the text content of the HTML report. This report contains graphical elements, so use a Desktop Web Browser to visualize its full contents.

💡 Customized ruleset selections for a <project>.ewp are automatically stored in a corresponding <project>.ewt. If the project is under version control, it is advised to check-in this file as well.

Issues

Found an issue or have a suggestion related to the bx-docker tutorial? Feel free to use the public issue tracker.

Do not forget to take a look at earlier issues.
If creating a new issue, please describe it in detail.

Summary

And that is how the IAR Build Tools can run in containers.

Now you can learn from the scripts, from the Dockerfile and from the official Docker Documentation which together sum up as a cornerstone for your organization to use as it is or to customize them so that the containers run in suitable ways for particular needs.

Here you can find additional resources such as on-demand webinars about the IAR Build Tools within automated workflows scenarios.

controlol/bx-docker

Tutorial Building embedded applications with the IAR Build Tools on Docker Containers