Disclaimer The information in this repository is subject to change without notice and does not constitute a commitment by IAR. While it serves as a valuable reference for DevOps Engineers implementing Continuous Integration with IAR Tools, IAR assumes no responsibility for any errors, omissions, or specific 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 get the most of this tutorial, you will need a basic understanding on how to use command line tools.
A IAR Build Tools installer package of your choice for Ubuntu(/Debian) in the .deb format. IAR customers with a license can download directly from IAR MyPages. If you do not have a license yet, contact IAR Sales.
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 come 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.
The IAR License Server ready to serve, up and running, with activated license(s) for the network nodes with the IAR Build Tools of your choice -and- reachable from the platform in which the DOCKER_HOST is 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, launch a new bash shell and use the following procedure, known to work for most cases:
sudo apt update
sudo apt install curl
curl -fsSL https://get.docker.com -o get-docker.sh
sh ./get-docker.sh
sudo usermod -aG docker $USER
sudo - $USERTip
If you want to use Docker Desktop on Windows, refer to the wiki.
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, you need to perform these three steps:
- Set
BX_DOWNLOAD_URLwith the download link to the installer package you received from IAR Customer Support during your on-boarding process.
export BX_DOWNLOAD_URL=<fill-with-the-download-URL>- Clone the bx-docker repository to the user's home directory.
sudo apt update
sudo apt install git
git clone https://github.com/iarsystems/bx-docker.git ~/bx-docker- Invoke the
buildscript pointing to the downloaded installer package:
cd ~/bx-docker
curl -fO $BX_DOWNLOAD_URL
./build ${BX_DOWNLOAD_URL##*/}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
The Docker image only needs to be built once. If you use multiple packages for different targets/versions, repeat the process to build a dedicated docker image for each package.
Once you have created your images, execute the docker images iarsystems/* command to list all created images:
$ docker images iarsystems/*
REPOSITORY TAG IMAGE ID CREATED SIZE
iarsystems/bxarm 9.60.2 0f9ce7a7fde4 1 minute ago 4.18GB
iarsystems/bxarmfs 9.50.3.71393 102c086a58df 5 minutes ago 3.75GB
iarsystems/bxarm 9.40.1 93eb28dd4e65 9 days ago 3.17GB
iarsystems/bxarmfs 9.20.3.59432 abc420034fcb 6 weeks ago 2.45GB
iarsystems/bxriscv 3.20.1 89bd0878856f 8 weeks ago 1.46GBThe IAR Build Tools require an available network license to operate.
The setup-license script prepares a named Docker volume for storing persistent license configuration for any containers belonging to the same DOCKER_HOST.
In the bash shell, perform the following step (replace iarsystems/bx<image>:<tag> and <iar-license-server-ip> by the actual ones):
$ ~/bx-docker/setup-license iarsystems/bx<image>:<tag> <iar-license-server-ip>
-- setup-license: Creating a Docker volume for storing persistent license information...
-- setup-license: Running a container for setting up the license...
-- setup-license: Setting up the license with IAR Light License Manager...
-- setup-license: Finished.Tip
Setting up the license for a Docker image in such a way only needs to be performed once per DOCKER_HOST. 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. For manually removing a named volume, remove all containers using it and then use docker volume rm <volume-name>.
In this section, you will run an interactive container locally, clone and build a project with the image you have created.
The following command line will bind the home directory ($HOME) to the "my-iar-bx-container" container's working directory (/build) for the iarsystems/bx<image>:<tag> image.
docker run \
--restart=unless-stopped \
--detach \
--tty \
--name my-iar-bx-container \
--hostname `hostname` \
--volume LMS2:/usr/local/etc/IARSystems \
--volume $HOME:/build \
iarsystems/bx<image>:<tag>Tip
The SHA256 hash number shown in the last line is dynamically attributed by Docker to any new container while uniquely identifying it.
You can check your containers with docker container ls:
$ docker container ls
CONTAINER ID IMAGE COMMAND CREATED STATUS NAMES
dcc6c9f4e104 iarsystems/bxarm:9.60.2 "/bin/bash" 30 seconds ago Up 29 seconds my-iar-bx-containerEnter the container:
$ docker exec -it my-iar-bx-container bash
root@<the-docker_host-hostname>:~# For this example we will clone a public repository with projects created in the IAR Embedded Workbench IDE for the supported target architectures:
# git clone https://github.com/iarsystems/bx-workspaces-ci
Cloning into 'bx-workspaces-ci'...
remote: Enumerating objects: 345, done.
remote: Counting objects: 100% (99/99), done.
remote: Compressing objects: 100% (54/54), done.
remote: Total 345 (delta 44), reused 64 (delta 44), pack-reused 246 (from 1)
Receiving objects: 100% (345/345), 159.12 KiB | 631.00 KiB/s, done.
Resolving deltas: 100% (211/211), done.Finally build the library project for the selected <target> (e.g. arm, avr, riscv, rl78, rx, rh850). In the following example, "arm" was selected and iarbuild was used to build the project:
# /opt/iarsystems/bxarm/common/bin/iarbuild bx-workspaces-ci/targets/arm/library.ewp -build Release
IAR Command Line Build Utility V9.3.5.863
Copyright 2002-2024 IAR Systems AB.
library - Release
Reading project nodes...
Cleaning... 0 files.
crc16.c
crc32.c
library.a
Total number of errors: 0
Total number of warnings: 0
Build succeededNow build the application project that is linked against the library for the same selected target. In this example, targets/arm was selected for demonstration:
# /opt/iarsystems/bxarm/common/bin/iarbuild bx-workspaces-ci/targets/arm/test-crc32.ewp -build Release
IAR Command Line Build Utility V9.3.5.863
Copyright 2002-2024 IAR Systems AB.
test-crc32 - Release
Reading project nodes...
Cleaning... 0 files.
test-crc32.c
test-crc32.out
Total number of errors: 0
Total number of warnings: 0
Build succeededTip
Invoke /opt/iarsystems/bx<target>/common/bin/iarbuild with no parameters for a detailed description of available options.
Additionally, IAR C-STAT is an add-on to the IAR Build Tools that can perform static code analysis. It helps you ensure code quality in your applications. If you have C-STAT, iarbuild can drive the analysis with the -cstat_analyze <build-cfg> command to analyze the project.
Using the library project in bx-workspaces-ci/targets/arm as an example:
# /opt/iarsystems/bxarm/common/bin/iarbuild bx-workspaces-ci/targets/arm/library.ewp -cstat_analyze Release
IAR Command Line Build Utility V9.3.5.863
Copyright 2002-2024 IAR Systems AB.
library - Release
Analysis completed. 8 message(s)The analysis results are stored in an SQLite database named cstat.db. Use icstat to retrieve the warnings and display them on the terminal. For example:
# /opt/iarsystems/bxarm/arm/bin/icstat load --db $(find bx-workspaces-ci -name "cstat.db")
"bx-workspaces-ci/library/source/crc32.c",29 Severity-Medium[ATH-shift-neg]:LHS argument of right shift operator may be negative. Its range is [-INF,INF].
"bx-workspaces-ci/library/source/crc32.c",30 Severity-Medium[ATH-shift-neg]:LHS argument of right shift operator may be negative. Its range is [-INF,INF].
"bx-workspaces-ci/library/source/crc32.c",31 Severity-Medium[ATH-shift-neg]:LHS argument of right shift operator may be negative. Its range is [-INF,INF].
"bx-workspaces-ci/library/source/crc32.c",32 Severity-Medium[ATH-shift-neg]:LHS argument of right shift operator may be negative. Its range is [-INF,INF].
"bx-workspaces-ci/library/source/crc32.c",33 Severity-Medium[ATH-shift-neg]:LHS argument of right shift operator may be negative. Its range is [-INF,INF].
"bx-workspaces-ci/library/source/crc32.c",34 Severity-Medium[ATH-shift-neg]:LHS argument of right shift operator may be negative. Its range is [-INF,INF].
"bx-workspaces-ci/library/source/crc32.c",35 Severity-Medium[ATH-shift-neg]:LHS argument of right shift operator may be negative. Its range is [-INF,INF].
"bx-workspaces-ci/library/source/crc32.c",36 Severity-Medium[ATH-shift-neg]:LHS argument of right shift operator may be negative. Its range is [-INF,INF].The same database can be used for generating an analysis report with warnings about coding violations for the project's ruleset selection. Use ireport to generate an HTML report. In this example:
# /opt/iarsystems/bxarm/arm/bin/ireport --full --project library --db $(find bx-workspaces-ci -name "cstat.db")
HTML report generated: library.htmlNow exit the container:
# exitThanks to running the container with the --volume $HOME:/build parameter, all existing files from the home directory and below are bound to the container's /build working directory. In this case, once you exit the container, any files within the /build directory will remain in their correspondent locations under the home directory.
You will find all your project files generated in this example under ~/bx-workspaces-ci. However they belong to root as it was the default user for the container. In order to get ownership of all generated files, perform:
$ sudo chown -Rv $USER:$USER bx-workspaces-ci/
changed ownership of 'bx-workspaces-ci/LICENSE' from root:root to <user>:<user>
changed ownership of 'bx-workspaces-ci/tests/test-crc32.c' from root:root to <user>:<user>
changed ownership of 'bx-workspaces-ci/tests/test-crc16.c' from root:root to <user>:<user>
...Tip
Since the container was run with the --restart=unless-stopped option, it will remain available for reattaching to it when desired, by using docker exec -it my-iar-bx-container bash, until it is manually stopped with docker stop my-iar-bx-container. The docker run --help command provides more information on different ways of running docker containers.
This tutorial guided you through one way of running the IAR Build Tools on Linux containers.
Using the provided scripts, Dockerfile, and official Docker Documentation, you can either use this setup as-is or customize it to ensure the containers operate according to your specific requirements. This setup can serve as a fundational element for your organization.
Follow us on GitHub to get updates about tutorials like this and more.
For technical support contact IAR Customer Support.
For questions or suggestions related to this tutorial: try the wiki or check earlier issues. If those don't help, create a new issue with detailed information.