Disclaimer The information provided in this repository is subject to change without notice and does not represent a commitment on any part of IAR. While the information contained herein is useful as reference for DevOps Engineers willing to implement Continuous Integration using IAR Tools, IAR assumes no responsibility for any errors, omissions or particular implementations.
Docker is generally recognized as best practice for achieving automatically reproducible build environments. It provides the means for containerizing self-sufficient build environments that result from the requirements described in a Dockerfile.
This tutorial provides a Dockerfile and helper scripts that provide the means for building embedded applications with the IAR Build Tools from a Linux container.
Tip
We recommended that you initially perform this tutorial within a test environment.
To complete this tutorial you need:
- An understanding of how to use command line tools.
A IAR Build Tools installer package of your choice for Ubuntu(/Debian) in the .deb format, which IAR customers can download it directly from IAR MyPages.
The IAR Build Tools installer packages are delivered using the following name standard:
bx<arch>[fs]-<V.vv.patch[.build]>.deb
where [fs] and [.build] in the package names show up to distinguish tools that are pre-certified for Functional Safety.
A x86_64/amd64 platform supported by the Docker Engine (supported platforms) capable of accessing the Internet for downloading the necessary packages.
Note
In this guide, network node in which the Docker Engine was installed will be referred to as DOCKER_HOST.
- ready to serve, up and running, with activated license(s) for one or more network nodes running the IAR Build Tools of your choice -and-
- reachable from the platform in which the
DOCKER_HOSTis running as described above.
Tip
If you do not have the licenses you need, contact us.
To install the Docker Engine on the DOCKER_HOST, follow the official instructions.
Alternatively, use this procedure that should work for most DOCKER_HOSTs:
| Linux (Bash) | Windows |
|---|---|
curl -fsSL https://get.docker.com -o get-docker.shsh ./get-docker.sh |
Install Docker Desktop |
Note
On Windows hosts, make sure that Docker Desktop is set up to run Linux Containers (default).
To execute Docker commands, the current user ($USER) must be in the docker group. Execute:
| Linux (Bash) | Windows |
|---|---|
sudo usermod -aG docker $USERThen log out and log in again for the changes to take effect. |
N/A |
Before you can run a Docker container, you need a Docker image that contains the required environment. A Dockerfile contains instructions that describe how to build an image .
This Dockerfile was created as a universal template to build images with the IAR Build Tools.
The build script will use the docker build command with the Dockerfile, together with an installer package (bx<package>-<version>.deb), to create one image.
To build the image, clone the bx-docker repository to the user's home directory:
| Linux (Bash) | Windows (PowerShell) |
|---|---|
git clone https://github.com/iarsystems/bx-docker.git ~/bx-docker |
git clone https://github.com/iarsystems/bx-docker.git $home/bx-docker |
Then, invoke the build script that points to the installer package:
| Linux (Bash) | Windows (PowerShell) |
|---|---|
~/bx-docker/build /path/to/bx<package>-<version>.deb |
./bx-docker/build /path/to/bx<package>-<version>.deb |
Depending on your system's properties, it might take a while to build the image. The build time ranges from seconds to a few minutes. In the end, the build script will automatically tag the image as iarsystems/bx<package>:<version>.
Tip
Invoke the build script once for each installer package you have, to get one dedicated image for each package.
Once you have created the image, execute the docker images command to list all created images:
docker images iarsystems/*
The output will be similar to this, depending on which images you have created:
REPOSITORY TAG IMAGE ID CREATED SIZE iarsystems/bxarm 9.40.1 93eb28dd4e65 2 minutes ago 3.17GB iarsystems/bxarmfs 9.20.3.59432 abc420034fcb 8 minutes ago 2.45GB iarsystems/bxriscv 3.20.1 89bd0878856f About an hour ago 1.46GB
The IAR Build Tools require an available network license to operate.
To set up the license for all the containers in the DOCKER_HOST, execute the setup-license script, pointing to the image's <tagname:version> followed by the IAR LMS2 License Server's IP address:
| Linux (Bash) | Windows (PowerShell) |
|---|---|
~/bx-docker/setup-license iarsystems/bx<package>:<version> <lms2-server-ip> |
./bx-docker/setup-license iarsystems/bx<package>:<version> <lms2-server-ip> |
The setup-license script will prepare a Docker volume to be shared by all containers that run on the DOCKER_HOST, for persistent storage of the license configuration.
Tip
This step can only be performed 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 (DOCKER_HOSTs), setup-license must be run individually on all of them.
In this section, you will use the image you created to run a container so that you can build a project later.
The bx-docker repository comes with projects created in the IAR Embedded Workbench IDE for the supported target architectures.
Access the projects subdirectory:
| Linux (Bash) | Windows (PowerShell) |
|---|---|
cd ~/bx-docker/projects |
cd ./bx-docker/projects |
The run script will use the docker run command with all the necessary parameters to run the container. Execute:
| Linux (Bash) | Windows (PowerShell) |
|---|---|
~/bx-docker/run iarsystems/bx<package>:<version>Follow the instructions provided by the run script output, to source the aliases-set script. |
../run iarsystems/bx<package>:<version>The aliases-set script is invoked automatically by the run command and applied to the current shell session. |
Containers spawned by the run script will bind mount the current directory (pwd) to the Docker image's working directory (/build). This 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.
Tip
The docker run --help command provides more information.
The docker exec command can execute a command in a running container. Often, these command lines will get too long to type 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 selected to work with. These aliases encapsulated the required docker exec commands in such a way that the DOCKER_HOST can now execute all the IAR Build Tools seamlessly.
The IAR Command Line Build Utility (iarbuild) can build (or analyze) a <project>.ewp file.
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
Tip
Invoke iarbuild with no parameters for a detailed description.
Static Code Analysis can be performed with IAR C-STAT.
C-STAT is an add-on to the IAR Build Tools that helps you 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.
To perform 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 with 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
Tip
On the Linux Bash shell, you can use lynx hello-world.html to visualize the text contents 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 project are automatically stored in a corresponding <project>.ewt file. If the project is under version control, you are advised to check in this file as well.
Did you find an issue or do you have a suggestion related to the bx-docker tutorial? Please use the public issue tracker.
- Do not forget to take a look at earlier issues.
- If you are reporting a new issue, please describe it in detail.
This tutorial decribes how the IAR Build Tools can run on Linux containers.
From the scripts, the Dockerfile, and the official Docker Documentation —which can form a cornerstone for your organization— you can learn how to use this setup as it is or to customize it so that the containers run in the way you need them to.
