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.
Each of the IAR Build Tools for Linux packages requires its specific license. Please feel free to contact us if you would like to learn how to get access to them.
If you end up with a question specifically related to this tutorial, you might be interested in verifying if it was already answered from earlier questions. Or, ask a new question if you could not find any answer for your question.
This tutorial provides a simple example with general guidelines on how to set up a CI (Continuous Integration) workflow with IAR Build Tools for Linux alongside Bitbucket.
At Bitbucket, a private project repository, called origin in the Git jargon, starts with a master branch containing the production code.
The repository also contains a "recipe" for the workflow under bitbucket-pipelines.yml. The recipe is written in the YAML format and can be customized. We provided one simple example as base, although the official documentation can help with further customizations.
The repository will be configured to use one Bitbucket's self-hosted runner.
⚠️ Bitbucket requires an account.
The build server is a x64 Linux machine and it will be where the IAR Build Tools for Linux are installed.
It will serve as a self-hosted runner from where the pipeline will take place. This runner will be configured to automatically connect to the origin. When triggered, the runner will execute a job that, after cloning the repository and will use the IAR Build Tools for Linux to build these projects.
On his workstation, a developer clones the repository to start working on a new feature for some project. For that, he creates a feature branch.
The developer then launches the IAR Embedded Workbench, from where he can code, build and debug the project.
When the developer is done with that, he can, through his own Bitbucket account, push the branch to the origin using a git client.
💡 Bitbucket provides instructions on how Install and set up Git.
In a nutshell, the primary objective is to have automated builds within reproducible build environments. This workflow is useful for keeping track of any changes that potentially break the build before they are introduced into the production branch. This practice can help raise the project's overall quality metrics.
When a developer pushes changes to the origin, the Bitbucket Pipeline for the repository comes into play, triggering its associated runner in the build server.
On the build server, the runner will then execute the user-defined "recipe" to build the project with the IAR Build Tools.
If the new feature passes, the code reviewer can decide if these changes are ready to be merged to the master branch.
If the new feature fails, the follow-up can be performed within Bitbuckets's own facilities for code revision.
This process repeats as many times as required.
As this tutorial is intended to be flexible with respect to the tools and packages that can be used, it becomes important to establish some conventions for when referring to certain entities.
| Placeholder | Meaning |
|---|---|
<arch> |
Architecture Valid: arm, riscv, rh850, rl78, rx |
<package> |
Product package Valid: arm, armfs, riscv, rh850, rh850fs, rl78, rx |
<version> |
Package version Valid: major.minor.patch [.build] |
Here you will find some examples for different packages and their versions:
| Package/Version | Replace with |
|---|---|
| BXARM 9.20.1 | IAR Build Tools for Arm version 9.20.1<arch>=arm<package>=arm<version>=9.20.1 |
| BXARMFS 9.20.3.45671 | IAR Build Tools for Arm, Functional Safety Edition, version 9.20.3<arch>=arm<package>=armfs<version>=9.20.3.45671 |
| BXRISCV 3.10.1 | IAR Build Tools for RISC-V version 3.10.1<arch>=riscv<package>=riscv<version>=3.10.1 |
| Placeholder | Meaning |
|---|---|
<username> |
Refer to the user's Bitbucket's account or the user's account in the local machine, according to the context. |
In order to illustrate the concept, we are going to import the bx-workspaces-ci repository. This is a public repository containing a collection of workspaces which were created using the IAR Embedded Workbench. They can be imported to become a private repository and then used for experimentation with the IAR Build Tools for Linux.
Navigate to
https://bitbucket.org/repo/import
Fill Old repository with
https://github.com/IARSystems/bx-workspaces-ci
Fill Project name and Repository name. For this example, let's use shr-private:
shr-private
Make sure that Access level is set to Private repository.
⚠️ Bitbucket adverts against using self-hosted runners with public repositories due [performance and security reasons][bb-private-url].
Finally, click Import repository.
Once the importing process is complete, a temporary message banner will show up:
"Import completed successfully."
Then you will automatically be taken to the repository's page.
On your shr-private repository, use the Bitbucket interface to add the following new file bitbucket-pipelines.yml. This workflow contains 3 jobs to be run on the runner tagged as "self.hosted". This workflow first builds library and then, in the sequence, it builds componentA and componentB:
definitions:
buildProject: &buildProject
name: Build the project
runs-on:
- self.hosted
services:
- docker
script:
- echo $DOCKER_HUB_PASSWORD | docker login -u $DOCKER_HUB_USERNAME --password-stdin
- docker pull $DOCKER_HUB_USERNAME/bx<arch>:<version>
- docker tag $DOCKER_HUB_USERNAME/bx<arch>:<version> bx<arch>:latest
- docker run --detach --tty --name bx --hostname bxd-bb --volume $BITBUCKET_CLONE_DIR:/build bx<arch>
- docker exec bx lightlicensemanager setup -s <lms2-server-ipv4>
- docker exec bx iarbuild <arch>/library.ewp -build Debug -log all
- docker exec bx iarbuild <arch>/componentA.ewp -build Debug -log all
- docker exec bx iarbuild <arch>/componentB.ewp -build Debug -log all
artifacts:
- <arch>/Debug/Exe/*.a
- <arch>/Debug/Exe/*.out
- <arch>/Debug/List/*.map
pipelines:
default:
- step: *buildProject
⚠️ Change<arch>,<version>and<lms2-server-ipv4>to match with the IAR Build Tools for Linux you are using. Please refer to Conventions for details.
💡 Find more information on how to configure your pipeline.
The Bitbucket repository must be set to use Pipelines.
⚠️ Bitbucket requires Two-step verification before allowing to enable Pipelines.
Go to Repository settings → Pipelines → Settings.
https://bitbucket.org/<username>/shr-private/admin/addon/admin/pipelines/settings
And Enable Pipelines.
Go to Repository settings → Pipelines → Runners → Add runner.
Make sure that System and architecture is set to Linux/x86_64.
Fill Runner name (i.e. bx-runner) and click Next.
The interface will provide you with the entire docker container run ... command to be used in the build server.
⚠️ The token for the runner is only displayed once during this step. You can copy it to the clipboard using the "copy" icon on the lower-right corner.
Click Next.
The last wizard's screen provides some hints on how to configure the bitbucket-pipelines.yml to take advantage of the self-hosted runner. Click Finish.
Go to the build server and paste the complete docker run ... command to enable the runner.
After the Updating runner state to "ONLINE" message appears on the build server's terminal, you can go back to the Repository settings and visit the Pipelines → Runners page. The page will now show that the runner became ONLINE.
Now it is time to create the Docker Image with the IAR Build Tools for Linux. In this example we're going to illustrate the proper procedure of how to push a Docker Image with the IAR Build Tools to a private Docker Hub repository.
On the build server, follow the instructions in the bx-docker tutorial to build a Docker image for the IAR Build Tools of your choice.
Once you get your image built, login into your hub.docker.com account. Sign up if you do not have one.
Once you logged into your Docker Hub account, create a private repository named bx<arch>.
⚠️ At the time of this writing, Docker Hub offered 1 private repository (that is only visible to you) on their Free Tier option, which is enough for evaluation purposes. It is imperative to use a Docker Registry service which provides the possibility of storing private Docker Images. Never publish a Docker Image with the IAR Build Tools in a public repository.⚠️
💡 For more information on how to authenticate on alternative private registries, refer to the Using private build images section in the "Use Docker images as build environments" from the Bitbucket's documentation.
Now, in the build server tag your docker image using your Docker Hub's <Docker-ID>:
docker tag iarsystems/bx<arch>:<version> <Docker-ID>/bx<arch>:<version>
Use docker login to login into your Docker Hub account.
And then push the local image containing the IAR Build Tools to the new private repository:
docker push <username>/bx<arch>:<version>
The push refers to repository [docker.io/<Docker-ID>/bx<arch>] 0a8286155869: Pushed 479335d4fe94: Pushed b4c32fc56cba: Pushing [> ] 37.02MB/2.191GB 3b739915e189: Pushing [=================> ] 62.92MB/176.7MB 867d0767a47c: Mounted from library/ubuntu
Earlier when we created the file bitbucket-pipelines.yml on our repository, you might have noticed references to variables such as $DOCKER_HUB_USERNAME and $DOCKER_HUB_PASSWORD. Those are secret repository variables that can be defined in the Repository Settings, under Pipelines and then Repository Variables:
Use the repository settings page to set up your username and password to the Docker Hub so your Bitbucket pipeline can make use of it.
Go to your repository's page on Bitbucket, select Pipelines and then choose Run pipeline.
Use the Bitbucket's interface to edit componentB.
For illustrative purposes, the DATATYPE used in componentB had to change from uint16_t to float, for example, to hold values greater than 0xFFFF.
Open the library.h file from your private repository and find the line #define DATATYPE uint16_t.
Replace it with
#define DATATYPE floatIn the main.c file from your repository, update the constant z to 100000.
const DATATYPE z = 100000;On the same file, update the debug_log() function string format to handle the float type. Change the formatted string from %d to %f as below:
debug_log("Sum = %f\r\n", sum);and
debug_log("Mul = %f\r\n", mul);Re-run the Pipeline and watch the results.
In short, in this tutorial we went through one of the many ways that the IAR Build Tools for Linux can be used in CI scenarios.
Over time, a practice like this can help guarantee convergence to improved quality of the production grade code base. It also helps in avoiding that new features break other parts of a project. Ultimately it builds a development log of the project which, when properly used, can become a solid asset for consistent deliveries as the project evolves.
The IAR Build Tools for Linux along with the Bitbucket CI provides a great and scalable way to manage automation tasks for building, and analyzing embedded software projects. Hence it might be suitable for many use cases.
For more tutorials like this, stay tuned in our GitHub page.