Skip to content

Commit 0a0f624

Browse files
author
Felipe Torrezan
committed
Initial commit
0 parents  commit 0a0f624

24 files changed

Lines changed: 8545 additions & 0 deletions

‎.github/workflows/bxarm.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
#
2+
# Copyright (c) 2020 IAR Systems AB
3+
#
4+
# BXARM CI Workflow Example
5+
#
6+
# See LICENSE for detailed license information
7+
#
8+
9+
name: IAR Build Tools CI
10+
11+
# Controls when the action will run. Triggers the workflow on push
12+
on:
13+
push:
14+
branches: [ dev* ]
15+
16+
env:
17+
BUILD_TYPE: Debug
18+
IARBUILD_PATH: /opt/iarsystems/bxarm/common/bin
19+
IARBUILD_OPTS: -log all -parallel 2
20+
21+
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
22+
jobs:
23+
24+
# This workflow contains a single job called "iarbuild"
25+
iarbuild:
26+
# The type of runner that the job will run on
27+
runs-on: self-hosted
28+
29+
# Steps represent a sequence of tasks that will be executed as part of the job
30+
steps:
31+
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
32+
- uses: actions/checkout@v2
33+
34+
- name: Build Library
35+
run: $IARBUILD_PATH/iarbuild ./workspace/library/library.ewp -build $BUILD_TYPE $IARBUILD_OPTS
36+
37+
- name: Build Component 1
38+
run: $IARBUILD_PATH/iarbuild ./workspace/component1/component1.ewp -build $BUILD_TYPE $IARBUILD_OPTS
39+
40+
- name: Build Component 2
41+
run: $IARBUILD_PATH/iarbuild ./workspace/component2/component2.ewp -build $BUILD_TYPE $IARBUILD_OPTS

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
**/Debug
2+
**/settings
3+
**/logs
4+
**/*.dep

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2020 Felipe Torrezan
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Tutorial: Self-hosted runners for the IAR Build Tools on Linux hosts
2+
3+
### Objectives
4+
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][iar-bx-url].
5+
6+
> __Notes__
7+
> * For more tutorials, stay tuned on our [__IAR Systems__ page on GitHub][gh-iar-url].
8+
> * If you have questions, you can always refer to the [__bx-self-hosted-runners wiki__][repo-wiki-url], or [here][repo-old-issue-url] for earlier questions. In case you have a new question, post it [here][repo-new-issue-url].
9+
10+
### Requirements
11+
For this tutorial, the following will be required:
12+
13+
* __Dev-Machine__: a __Windows 10__ build 1903+ with the following software installed:
14+
- [__IAR Embedded Workbench for Arm 8.50.6__](https://www.iar.com/arm)
15+
- [Git for Windows](https://git-scm.com/download/win) (includes _bash_)
16+
17+
* __Build-Server__: a __Ubuntu__ v18.04+ with the following software installed:
18+
- [__IAR build tools for Arm 8.50.6__](https://www.iar.com/about-us/contact) (referred as `BXARM`)
19+
20+
* [__IAR License Server__][iar-lms2-url] already __up__, loaded with __activated__ `BXARM` licenses and __reachable__ from the __Build-Server__
21+
22+
* __GitHub.com__:
23+
- A [GitHub account][gh-join-url] (or a [Microsoft Azure account][gh-azure-url])
24+
- A private GitHub git repository to store the project files
25+
- A __Developer__
26+
- A __Project Manager__ (who, for the current purposes, can temporarily assume the role of the __Developer__)
27+
28+
## Table of Contents
29+
* [Introduction](#introduction)
30+
* [Prepare the repository](#prepare-the-repository)
31+
* [Setup the Self-hosted runner](#setup-the-self-hosted-runner)
32+
* [Develop the project](#develop-the-project)
33+
* [Creating a pull request](#creating-a-pull-request)
34+
* [Manage the code changes](#manage-the-code-changes)
35+
* [Summary](#summary)
36+
37+
38+
## Introduction
39+
For this tutorial, we are going to use the [GitHub's Self-hosted-runners][gh-shr-url] to build a project on a local building machine while __GitHub Actions__ orchestrates the entire DevOps workflow for us.
40+
41+
On this DevOps workflow, we are going to create one [__private__][gh-shr-priv-url] repository hosted at __GitHub__ containing our project.
42+
43+
The private repository will have a __`production`__ branch in which __only__ the __Project Manager__ should have the authority to approve code changes.
44+
45+
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__.
46+
47+
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 not integrate well to the __`production`-grade__ code base.
48+
49+
![](images/bx-shr-devops-flow.png)
50+
51+
52+
## Prepare the repository
53+
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.
54+
55+
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.
56+
57+
* On __GitHub.com__, import [this repository](https://github.com/IARSystems/bx-self-hosted-runners)
58+
- into a [new private repository](https://github.com/new/import)
59+
- __Name__ `shr-private`
60+
- __Privacy__ `Private`
61+
- Click __Begin import__
62+
63+
* Once the _importing is complete_, a message will show up:
64+
```
65+
"Your new repository '<username>/shr-private' is ready."
66+
```
67+
* Click on that link to the new repository in the message.
68+
69+
* Go to __Settings__
70+
> Equivalent URL: `https://github.com/<username>/shr-private/settings`
71+
72+
* And then __Actions__
73+
> Equivalent URL: `https://github.com/<username>/shr-private/settings/actions`
74+
75+
* On then bottom of the page, click __`Add Runner`__
76+
> Equivalent URL: `https://github.com/<username>/shr-private/settings/actions/add-new-runner`
77+
78+
* For __Operating System__
79+
- Select `Linux`
80+
81+
* For __Architecture__
82+
- Select `x64`
83+
84+
## Setup the Self-hosted runner
85+
The __Project Manager__ should access the __Build-Server__ to perform the following setup:
86+
87+
### Install the `BXARM` build tools
88+
Install the IAR Build Tools for Arm 8.50.6 (`BXARM`) on the __Build-Server__ as follows:
89+
```sh
90+
# Setup the BXARM with dpkg
91+
$ sudo dpkg --install <path-to>/bxarm-8.50.6.deb
92+
93+
# Initialize the IAR License Manager on the Build-Server
94+
$ sudo /opt/iarsystems/bxarm-8.50.6/common/bin/lightlicensemanager init
95+
96+
# Setup the license on the Build-Server
97+
$ /opt/iarsystems/bxarm-8.50.6/common/bin/lightlicensemanager setup -s <IAR.License.Server.IP.address>
98+
```
99+
> __Notes__
100+
> * Additionally, it is possible to add the `BXARM` directories containing the executables on the search `PATH`, so they can be executed from anywhere.
101+
>
102+
> For example:
103+
> ```sh
104+
> # Append it to the $HOME/.profile (or the $HOME/.bashrc) file
105+
>
106+
> # If BXARM 8.50.6 is installed, set PATH so it includes its bin folders
107+
> if [ -d "/opt/iarsystems/bxarm-8.50.6" ]; then
108+
> PATH="/opt/iarsystems/bxarm-8.50.6/arm/bin:/opt/iarsystems/bxarm-8.50.6/common/bin:$PATH"
109+
> fi
110+
> ```
111+
> * Alternatively, it is possible to use the __IAR Build Tools__ directly from a __Docker Container__ in a transparent manner. Jump to our [Docker images for IAR Build tools on Linux hosts][gh-bxarm-docker-url] tutorial for further details.
112+
113+
### Configure the GitHub Actions runner
114+
Then follow the GitHub's instructions for...
115+
116+
* __Download__
117+
118+
and
119+
120+
* __Configure__
121+
122+
...your self-hosted runner, using its default configurations.
123+
124+
> __Tip__
125+
> * 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__.
126+
127+
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`:
128+
![](images/shr-idle.png)
129+
130+
## Develop the project
131+
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.
132+
133+
And then, on the __Dev-Machine__, the __Developer__ will perform the following:
134+
135+
* Launch __Bash for Git__ and then:
136+
```sh
137+
# Clone the "shr-private" repository
138+
$ git clone https://github.com/<username>/shr-private.git
139+
140+
# Change to the repository directory
141+
$ cd shr-private
142+
143+
# Checkout a new branch named "dev-component2-improvement"
144+
$ git checkout -b dev-component2-improvement
145+
```
146+
> __Note__
147+
> * This repository comes prepared with a __GitHub Action [workflow](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions)__ configurated in the [bxarm.yml](.github/workflows/bxarm.yml) file to build all the 3 projects.
148+
149+
* Launch the __IAR Embedded Workbench for Arm 8.50.6__ and
150+
- Go to `File` → `Open Workspace...` and select the `workspace.eww` file inside the [workspace](workspace) folder. On the __Workspace__ window, the __`library`__ project should show up __highlighted__ as the active project.
151+
- Right-click on the __`library`__ project and choose `Make` (or <kbd>F7</kbd>). The `library` project should build with no errors.
152+
- Now right-click on the `component2` project and __Set as Active__.
153+
- Unfold the __`component2`__ project tree and double click on its [main.c](workspace/component2/main.c) file so it will open in the __Code Editor__.
154+
- Right-click on __`component2`__ and choose `Make` (or <kbd>F7</kbd>). The `component2` project should build with no errors.
155+
156+
### Changing the code for `component2` project
157+
158+
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`.
159+
160+
* On the [main.c](workspace/component2/main.c) file, right-click on the line with the __[`#include "library.h"`](workspace/component2/main.c#L12)__ and choose __Open "library.h"__.
161+
162+
* In the [library.h](workspace/library/library.h) file, find the line __[`#define DATATYPE uint16_t`](workspace/library/library.h#L19)__ and replace it with
163+
```c
164+
#define DATATYPE float
165+
```
166+
167+
* Now rebuild the `library` project
168+
- Right-click on `library` and choose `Make` (or <kbd>F7</kbd>). It should build with no errors.
169+
170+
* And then rebuild the `component2` project
171+
- Right-click on `component2` and choose `Make` (or <kbd>F7</kbd>). It should build with no errors.
172+
173+
Back to the __Git Bash__
174+
175+
* Commit to the changes to the cloned `shr-private` repository
176+
```sh
177+
# Stage the modified file for commit
178+
$ git add workspace/library/library.h
179+
180+
# Commit the changes to the local "shr-private" repository
181+
$ git commit -m "Component 2 improvement proposal"
182+
```
183+
184+
* The expected output is similar to this, but with a different commit hash:
185+
> ```
186+
> [dev-component2-improvement e167db8] Component 2 improvement proposal
187+
> 1 file changed, 1 insertion(+), 1 deletion(-)
188+
> ```
189+
190+
* Finally `push` the code changes back to the `origin` repository:
191+
```sh
192+
$ git push -u origin dev-component2-improvement
193+
```
194+
195+
The expected output is similar to:
196+
> ```
197+
> Enumerating objects: 9, done.
198+
> Counting objects: 100% (9/9), done.
199+
> Delta compression using up to 8 threads
200+
> Compressing objects: 100% (5/5), done.
201+
> Writing objects: 100% (5/5), 1.07 KiB | 363.00 KiB/s, done.
202+
> Total 5 (delta 4), reused 0 (delta 0), pack-reused 0
203+
> remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
204+
> remote:
205+
> remote: Create a pull request for 'dev-component2-improvement' on GitHub by visiting:
206+
> remote: https://github.com/<username>/shr-private/pull/new/dev-component2-improvement
207+
> remote:
208+
> To github.com:<username>/shr-private.git
209+
> * [new branch] dev-component2-improvement -> dev-component2-improvement
210+
> Branch 'dev-component2-improvement' set up to track remote branch 'dev-component2-improvement' from 'origin'.
211+
> ```
212+
213+
## Creating a Pull Request
214+
Then it is time for the __Developer__ to go back to __GitHub.com__:
215+
216+
* Go to `https://github.com/<username>/shr-private` and notice that there is a new yellow bar saying that
217+
![](images/pr-compare.png)
218+
219+
* Click `Compare & pull request`
220+
221+
* 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
222+
![](images/pr-rationale.png)
223+
224+
* Once ready, click `Create pull request`
225+
226+
> __Tip__
227+
> * Follow the link to learn more [About pull requests](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
228+
229+
230+
## Reviewing the Pull Request
231+
It is time for the __Project Manager__ to start [reviewing the pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/approving-a-pull-request-with-required-reviews) which was proposed by the __Developer__ containing the new feature.
232+
233+
Our basic GitHub Actions workflow file bxarm.yml will trigger every time a new feature branch goes through a pull request.
234+
235+
Once it is triggered, it will use the __IAR Build Tools__ installed in the __Build Server__ alongside the runner deamon listening for new jobs.
236+
237+
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.
238+
![](images/pr-build-fail.png)
239+
240+
In this case, the author's proposed change to the shared `library` worked nicely for the `component2` but it has broken the `component1` build.
241+
242+
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.
243+
244+
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.
245+
246+
247+
## Summary
248+
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.
249+
250+
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][iar-bx-url]. For more tutorials, stay tuned on our [GitHub page][gh-iar-url]. As always, this tutorial is __not__ a replacement for the all the aforementioned tools' documentation.
251+
252+
253+
<!-- links -->
254+
[iar-bx-url]: https://www.iar.com/bx
255+
[iar-lms2-url]: https://www.iar.com/support/tech-notes/licensing/iar-license-server-tools-lms2/
256+
257+
[gh-join-url]: https://github.com/join
258+
[gh-azure-url]: https://azure.microsoft.com/en-us/products/github/
259+
[gh-shr-url]: https://docs.github.com/en/free-pro-team@latest/actions/hosting-your-own-runners/about-self-hosted-runners
260+
[gh-shr-priv-url]: https://docs.github.com/en/free-pro-team@latest/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories
261+
[gh-iar-url]: https://github.com/IARSystems
262+
[gh-bxarm-docker-url]: https://github.com/IARSystems/bxarm-docker
263+
264+
[repo-wiki-url]: https://github.com/IARSystems/bx-self-hosted-runners
265+
[repo-new-issue-url]: https://github.com/IARSystems/bx-self-hosted-runners/issues/new
266+
[repo-old-issue-url]: https://github.com/IARSystems/bx-self-hosted-runners/issues?q=is%3Aissue+is%3Aopen%7Cclosed

‎images/bx-shr-devops-flow.png‎

106 KB
Loading

‎images/pr-build-fail.png‎

22.6 KB
Loading

‎images/pr-compare.png‎

6.05 KB
Loading

‎images/pr-rationale.png‎

12.7 KB
Loading

‎images/shr-idle.png‎

11.7 KB
Loading

0 commit comments

Comments
 (0)