Tutorial
IAR Build Tools for Linux in a GitHub CI

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 want to be notified in your GitHub inbox about updates to this tutorial, you can start watching this repository. You can customize which types of notification you want to get. Read more about notifications and how to customize 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.

Introduction

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 GitHub.

GitHub

At GitHub, 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 .github/workflows. 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 GitHub's self-hosted runner.

⚠️ GitHub requires an account. An Azure account also can be used.

Build server

The build server will be where the IAR Build Tools for Linux are installed.

It will serve as a self-hosted runner from where the GitHub's Actions workflow 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.

Development workstation

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 GitHub account, push the branch to the origin using a git client.

⚠️ Popular choices for Windows that provide a git client are Git for Windows, GitHub for Desktop or even Ubuntu WSL. In this tutorial, we are going to use the git from the command-line.

The typical CI workflow

The objective is to have automated builds for keeping track of which changes break the build before they are introduced into the master branch. This practice can help raise the project's overall quality metrics.

When a developer pushes changes to the origin, GitHub Actions comes into play and triggers an action to notify the runner in the build server about the new push.

On the build server, the runner will then execute the "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 GitHub's facilities for code revision.

This CI repeats as many times as required.

Conventions

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.

Packages

Here you will find some examples for different packages and their versions:

Others

Preparing the repository

Under GitHub's account, 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.

Importing an example repository

Navigate to

https://github.com/new/import

Fill Your old repository's clone URL with

https://github.com/IARSystems/bx-workspaces-ci

On Your new repository details, fill with the new name. For this example, let's use shr-private:

shr-private

Make sure that Privacy is set to private.

⚠️ GitHub adverts against using self-hosted runners with public repositories due security reasons.

Finally, click Begin import.

Once the importing process is complete, a message will show up:

"Your new repository `<username>/shr-private` is ready."

Click on the link to the new repository provided in the message to go to the new repository.

Adding a workflow

On your shr-private repository, use the GitHub interface to add the following new file .github/workflows/bx.yaml. This workflow contains a single job that runs on a self-hosted runner called "iarbuild" with 3 steps to build the projects in the sequence library, componentA and componentB, after the repository is checked out:

name: IAR Build Tools CI
on:
  push:
    branches: [ dev* ]
env:
  BUILD_TYPE: Debug  
  IARBUILD_PATH: /opt/iarsystems/bx<package>-<version>/common/bin
  IARBUILD_OPTS: -log all -parallel 2
jobs:
  iarbuild:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v2
      - name: Build Library
        run: $IARBUILD_PATH/iarbuild ./<package>/library.ewp    -build $BUILD_TYPE $IARBUILD_OPTS
      - name: Build Component A
        run: $IARBUILD_PATH/iarbuild ./<package>/componentA.ewp -build $BUILD_TYPE $IARBUILD_OPTS
      - name: Build Component B
        run: $IARBUILD_PATH/iarbuild ./<package>/componentB.ewp -build $BUILD_TYPE $IARBUILD_OPTS    

⚠️ Update <package> and <version> to match with the IAR Build Tools for Linux you are using. Please refer to Conventions for details.

Adding a runner to the repository

The GitHub repository must be set to use a runner.

Go to Settings/Actions/Runners/New:

https://github.com/<username>/shr-private/settings/actions/runner/new

For Operating System: select Linux.

For Architecture: select x64.

Leave this page open.

Setup the Build Server

Go to the build server and perform the following setup.

Setup the runner

Use the GitHub's provided instructions for Download and Configure the self-hosted runner, using its default configurations.

⚠️ By downloading and configuring the GitHub Actions Runner, you agree to the GitHub Terms of Service or GitHub Corporate Terms of Service, as applicable.

Once the runner is in place, go to the repository's Settings/Actions page at:

https://github.com/<username>/shr-private/settings/actions

The status for the Self-hosted runner should be Idle at this point:

Install the IAR Build Tools for Linux

Install the IAR Build Tools for Linux.

⚠️ Follow the instructions and recommendations of the User Guide that comes with the product.

Additionally, it is possible to add the IAR Build Tools directories containing the executables to the search PATH, so they can be executed from anywhere without entering with their full path. This is not a requirement for this tutorial, but it might be convenient for some users.

For example, paste the snippet below to the user's $HOME/.profile (or else the $HOME/.bashrc) file:

if [ -d "/opt/iarsystems/bx<package>-<version>" ]; then
  PATH="/opt/iarsystems/bx<package>-<version>/<arch>/bin:/opt/iarsystems/bx<package>-<version>/common/bin:$PATH"
fi

⚠️ Change <arch>, <package> and <version> to match with the IAR Build Tools for Linux you are using. Please refer to Conventions for details.

After the file is saved, it is possible to source the file you modified so the changes take effect immediately. For example,

source ~/.profile

Developing a Project

Now that the server-side of the setup is done, let's start to try it from a developer's perspective, from within the Development workstation.

Cloning the repository

Launch the terminal which provides your git client and clone the shr-private repository you imported into your <username> account:

git clone https://github.com/<username>/shr-private.git /mnt/c/shr-private && cd /mnt/c/shr-private

⚠️ For this tutorial we are assuming that the clone location will be the C:\shr-private folder.

Switching to a feature branch

Now let's consider starting to work on a new feature for the ComponentB. Checkout a new branch named "dev-componentB", derived from the master branch:

git checkout -b dev-componentB master

In the IAR Embedded Workbench IDE choose File → Open Workspace... and navigate to C:\shr-project\<arch>. You will find a workspace.eww file. Go ahead and open it.

This example workspace comes with 3 projects:

• library
• componentA
• componentB

Right-click on the library project and choose Make (or F7). The library project should be built with no errors.

Now right-click on the componentB project and Set as Active.

Unfold the componentB project tree and double click on its main.c file so it will open in the Code Editor.

Right-click on componentB and choose Make (or F7). The componentB project should be built with no errors.

Changing the code for the componentB project

The developer starts to work on the dev-componentB branch and, for illustrative purposes, the DATATYPE used in componentB had to change from uint16_t to float, for example, to hold values greater than 0xFFFF.

On the main.c file, right-click on the line with the #include "library.h" and choose Open "library.h".

In the library.h file, find the line #define DATATYPE uint16_t and replace it with

#define DATATYPE float

In the main.c file, 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);

Rebuild the library project using right-click on library and choose Make (or F7). It should build with no errors.

Rebuild the componentB project using right-click on componentB and choose Make (or F7). It should build with no errors.

⚠️ If you want, you can debug the project using Project → Download & Debug (or CTRL+D). The details of debugging a project are not going to be covered in this tutorial. For further details on debugging a project, refer to the Help → C-SPY Debugging Guide document that is shipped with the product.

Commit the changes

Go back to the terminal where you used your git client.

Commit to the changes to the tracked files in the cloned shr-project repository:

git commit --all --message "Improvement proposal for componentB"

The expected output is similar to this, but with a different commit hash:

[dev-componentB 5b03ed8] Improvement proposal for componentB
 2 files changed, 5 insertions(+), 5 deletions(-)

Finally publish these changes with git push, so the code changes go back to the origin repository:

git push --set-upstream origin dev-componentB

Creating a Pull Request

Then it is time for the developer to go back his GitHub.com:

Go to https://github.com/<username>/shr-private and notice that there is a new yellow banner on the top

Click Compare & pull request.

Here, GitHub will give you the opportunity to write an explanation of the new feature you are pushing for the componentB project. That way, the code reviewer can have a better picture of what is going on.

Once ready, click Create pull request.

⚠️ Follow the link to learn more about pull requests.

Reviewing the Pull Request

The bx-workspaces-ci repository comes pre-loaded with a workflow configured in the .github/workflows/bx.yml file that will trigger the notification the runner in the build server needs to build all the 3 projects automatically when a new feature branch goes through a pull request.

Now a project's code reviewer can start reviewing the pull request containing the proposed changes in the new feature.

With the right workflow for a project, if some developer created something new that breaks the existing build, it will fail the automated verification. So a code reviewer can know immediately about the breakage and its details.

In this case, the author's proposed change to the shared library worked nicely for componentB but it didn't for componentA.

The code reviewer can contact the author using pull request page, so it is easy to keep track of any amends to the proposed code, until it is approved or rejected.

Summary

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 guaranteeing convergence to improved quality of the production grade code base. It also helps 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 GitHub 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 on our GitHub page.