The information in this repository is subject to change without notice and does not constitute a commitment by IAR. While it serves as a 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.
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. 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. If you do not have the licenses you need, contact us.
To install the Docker Engine on the DOCKER_HOST, follow the official instructions. If you want to use Docker Desktop on Windows, refer to the wiki.
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 - $USERBefore you can run a container, you need a image containing the required environment. A Dockerfile is a text file that describe how to build a container image.
The build script in this repository works as a frontend for building a container image based on this Dockerfile and requires an installer package (bx<package>-<version>.deb).
$ build -h
IAR Container Image Build Utility V2025.02
Copyright 2020-2025 IAR Systems AB.
Usage:
build -m /path/to/bx<package>.deb [options]
build -u https://url.to.iar.com/.../bx<package>.deb [options]
Parameter: Description:
-m, --main-package <file> The main package.
(ex: /path/to/bxarm-9.60.3.deb)
-u, --url <URL> Download package.
(ex: https://url.to/.../bxarm-9.60.3.deb)
-h, --help Show help information.
-v, --version Show utility version.
Option: Description:
-p, --device-package <file> The C-SPY device support package.
(ex: /path/to/bxarm-cspy-device-support-9.60.3.deb)
-b, --base [18|20|22|24] Choose Ubuntu Linux base image LTS version.
(Default: 20)
-t, --tag <name:version> Create an image with customized tag.
(Default: iarsystems/bx<package>:<version>)
-z, --no-cache Build a container image from scratch.
Experimental: Description:
-c, --with-cmake Include `cmake` in the container image.
-g, --with-git Include `git` in the container image.
-r, --with-sudo Include `sudo` in the container image.
-q, --no-cmsis Exclude `arm/CMSIS` from the container image (up to -129M).
-n, --no-docs Exclude `<target>/doc` from the container image (up to -64M).
-s, --no-source Exclude `<target>/src` from the container image (up to -318M).
-o, --no-translation Exclude localization files from the container image (up to -20M).The build script requires at least one of the following parameters:
- the
--main-package /path/to/bx<package>.debpointing to a local copy of the*.debinstaller which was already downloaded -or- - the
--url https://url.to/.../bx<package>.debpointing to the download link of the*.debinstaller.
Depending on your system specifications, chosen options and installer size, it might take a little while to build an image. In the end, the build script will automatically tag the image as iarsystems/bx<package>:<version> unless specified otherwise.
Note
When building an image, it is safe to ignore eventual debconf: delaying package configuration, since apt-utils is not installed warning messages.
The 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.Important
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>.
Though this is not the way a container image is intended to be used, let's build a project locally and interactively with the container image you have just created.
The following command line will bind the home directory ($HOME) to the "my-iar-bx-container" container's working directory (/workdir) 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:/workdir \
iarsystems/bx<image>:<tag>Enter the container:
$ docker exec -it my-iar-bx-container bash
root@<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.6.958
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.6.958
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 succeededAdditionally, 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.6.958
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:/workdir parameter, all existing files from the home directory and below are bound to the container's /workdir working directory. In this case, once you exit the container, any files within the /workdir 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.
