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 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_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, use this procedure that should work for most DOCKER_HOST
s:
Linux (Bash) | Windows |
---|---|
curl -fsSL https://get.docker.com -o get-docker.sh sh ./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 $USER Then 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_HOST
s), 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.
This tutorial explains how to run 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.