/bx-self-hosted-runners

A tutorial showing an example on how self-hosted runners can build projects using the IAR Build Tools within a DevOps CI/CD workflow. This tutorial focus on IAR Build Tools for Arm, still the same concepts apply to other target architectures. The IAR Build Tools for Linux is available for Arm, RISC-V, Renesas RH850 and Renesas RX.

Primary LanguageCMIT LicenseMIT

Tutorial: Self-hosted runners for the IAR Build Tools on Linux hosts

Objectives

This tutorial provides a simplified example containing general setup guidelines on how a GitHub Actions self-hosted runner can be used in a Continuous Integration (CI/CD) DevOps workflow when building projects with the IAR Build Tools on Linux hosts.

Notes

Requirements

For this tutorial, the following will be required:

Additional Resources

If you are new to CI/CD, Docker, Jenkins and Self-Hosted Runners or just want to learn more and see the IAR tools in action, you can find an useful selection of recorded webinars about automated building and testing in Linux-based environments here!

Table of Contents

Introduction

For this tutorial, we are going to use the GitHub's Self-hosted runners to build a project on a local building machine while GitHub Actions orchestrates the entire DevOps workflow for us.

On this DevOps workflow, we are going to create one private repository hosted at GitHub containing our project.

The private repository will have a production branch in which only the Project Manager should have the authority to approve code changes.

A Developer clones the repository with the production branch and then create a feature branch named dev-<feature-name||bug-fix> containing a new feature or a bug fix. Then he pushes the branch to the Origin. This will trigger a GitHub Action to build the project using the IAR Build Tools in a Self-hosted runner.

This way we can make sure that a newly developed feature will not break the build. This scheme will improve the project's quality, and it will help the Project Manager in the validation process while deciding which code changes are acceptable and if it does integrate well to the production-grade code base.

Prepare the repository

The first part of this tutorial assumes that the Project Manager is already logged into his https://github.com/<username> in order to setup a private repository on GitHub.

Accelerating things a little bit, we are going to re-use this public repository as base template for the new private one since it comes with an IAR Embedded Workbench workspace that the Developer will, later on, be able to experiment with simulating a new feature implementation under a CI/CD paradigm.

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

  • Click on that link to the new repository in the message.

  • Go to Settings

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

  • And then Actions

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

  • On the bottom of the page, click Add Runner

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

  • For Operating System

    • Select Linux

  • For Architecture

    • Select x64

Setup the Self-hosted runner

The Project Manager should access the Build-Server to perform the following setup:

Install the BXARM build tools

Install the IAR Build Tools for Arm 8.50.6 (BXARM) on the Build-Server as follows:

# Setup the BXARM with dpkg 
$ sudo dpkg --install <path-to>/bxarm-8.50.6.deb

# Initialize the IAR License Manager on the Build-Server
$ sudo /opt/iarsystems/bxarm-8.50.6/common/bin/lightlicensemanager init

# Setup the license on the Build-Server
$ /opt/iarsystems/bxarm-8.50.6/common/bin/lightlicensemanager setup -s <IAR.License.Server.IP.address>

Notes

  • Additionally, it is possible to add the BXARM directories containing the executables on the search PATH, so they can be executed from anywhere.

For example:

# Append it to the $HOME/.profile (or the $HOME/.bashrc) file

# If BXARM 8.50.6 is installed, set PATH so it includes its bin folders
if [ -d "/opt/iarsystems/bxarm-8.50.6" ]; then
  PATH="/opt/iarsystems/bxarm-8.50.6/arm/bin:/opt/iarsystems/bxarm-8.50.6/common/bin:$PATH"
fi

Configure the GitHub Actions runner

Then follow the GitHub's instructions for...

  • Download

and

  • Configure

...your self-hosted runner, using its default configurations.

Tip

  • You can move the mouse pointer to each desired line in the sequence and click on the clipboard icon to copy it to the clipboard and then paste it to the terminal of your Build-Server.

Once you have it configurated, the Actions configuration page (https://github.com/<username>/shr-private/settings/actions) should show the Self-hosted runner as Idle:

Develop the project

As soon as the preliminary setup is done, the Project Manager can notify the Developer about the new private repository for the project's CI/CD workflow.

And then, on the Dev-Machine, the Developer will perform the following:

  • Launch Bash for Git and then:
# Clone the "shr-private" repository
$ git clone https://github.com/<username>/shr-private.git

# Change to the repository directory
$ cd shr-private

# Checkout a new branch named "dev-component2-improvement"
$ git checkout -b  dev-component2-improvement

Note

  • This repository comes prepared with a GitHub Action workflow configurated in the bxarm.yml file to build all the 3 projects.
  • Launch the IAR Embedded Workbench for Arm 8.50.6 and
    • Go to File → Open Workspace... and select the workspace.eww file inside the workspace folder. On the Workspace window, the library project should show up highlighted as the active project.
    • Right-click on the library project and choose Make (or F7). The library project should build with no errors.
    • Now right-click on the component2 project and Set as Active.
    • Unfold the component2 project tree and double click on its main.c file so it will open in the Code Editor.
    • Right-click on component2 and choose Make (or F7). The component2 project should build with no errors.

Changing the code for component2 project

Now the Developer will start to work on the dev-component2-improvement and, for some reason the DATATYPE used in component2 had to change from uint16_t to float to hold values greater than 0xFFFF.

#define DATATYPE float

  • Now rebuild the library project

    • Right-click on library and choose Make (or F7). It should build with no errors.

  • And then rebuild the component2 project

    • Right-click on component2 and choose Make (or F7). It should build with no errors.

Back to the Git Bash

  • Commit to the changes to the cloned shr-private repository
# Stage the modified file for commit
$ git add workspace/library/library.h

# Commit the changes to the local "shr-private" repository
$ git commit -m "Component 2 improvement proposal"
  • The expected output is similar to this, but with a different commit hash:
[dev-component2-improvement e167db8] Component 2 improvement proposal
1 file changed, 1 insertion(+), 1 deletion(-)
  • Finally push the code changes back to the origin repository:
$ git push -u origin dev-component2-improvement

The expected output is similar to:

Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 8 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 1.07 KiB | 363.00 KiB/s, done.
Total 5 (delta 4), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'dev-component2-improvement' on GitHub by visiting:
remote:      https://github.com/<username>/shr-private/pull/new/dev-component2-improvement
remote:
To github.com:<username>/shr-private.git
 * [new branch]      dev-component2-improvement -> dev-component2-improvement
Branch 'dev-component2-improvement' set up to track remote branch 'dev-component2-improvement' from 'origin'.

Creating a Pull Request

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

  • Go to https://github.com/<username>/shr-private and notice that there is a new yellow bar saying that

  • Click Compare & pull request

  • Here, GitHub will give the Developer the opportunity to write the rationale for the component2 improvement proposal so the Project Manager can have a better picture of what is going on

  • Once ready, click Create pull request

Tip

Reviewing the Pull Request

It is time for the Project Manager to start reviewing the pull request which was proposed by the Developer containing the new feature.

Our basic GitHub Actions workflow file bxarm.yml will trigger every time a new feature branch goes through a pull request.

Once it is triggered, it will use the IAR Build Tools installed in the Build Server alongside the runner deamon listening for new jobs.

If a Developer created something new that breaks the build, it will fail the automated verification, warn the Project Manager about the breakage and detail the root cause of the failure.

In this case, the author's proposed change to the shared library worked nicely for the component2 but it has broken the component1 build.

The Project Manager can now contact the author using the pull request itself to keep track of any changes, propose alternatives or even fix other components of the project which might had lurking bugs and which no one else noticed for a while.

Over time this practice helps 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.

Summary

And that is how it can be done. Building a dedicated self-hosted GitHub Action runner might be a good solution for CI/CD workflows depending on your requirements.

Keep in mind that this tutorial was created to inspire you and your team with one example taken from many other combinations that orchestrates DevOps CI/CD workflows to build firmware projects with our IAR Build Tools. For more tutorials, stay tuned on our GitHub page. As always, this tutorial is not a replacement for the all the aforementioned tools' documentation.