IAR Build Tools in a Jenkins CI

Warning

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.

Introduction

The IAR Build Tools comes with everything you need to build projects created with the IAR Embedded Workbench from the command line. Jenkins is an automation controller suitable for CI (Continuous Integration). Gitea is a lightweight Git server.

This tutorial provides a quick method for bootstrapping the IAR Build Tools, Gitea and Jenkins, each one on its own container, for building and analyzing your embedded projects on-premises. From this starting point, you can apply customizations suitable for your organization's needs.

In a picture:

Pre-requisites

For completing this tutorial you need to have the Docker image with the IAR Build Tools from the bx-docker tutorial.

You will also need a web browser to access webpages. It is assumed that the web browser is installed on a Windows PC in which you have privileges to execute administrative tasks and that can reach the Linux server containing the Docker daemon with the IAR Build Tools.

In the Linux server's shell, clone this repository to the user's home directory (~):

git clone https://github.com/iarsystems/bx-jenkins-ci.git ~/bx-jenkins-ci

Setting up a Docker Network

For simplifying this setup let's create a docker network named jenkins in the Linux server's shell:

docker network create jenkins

From here onwards, we spawn all the tutorial's containers with --network-alias <name> --network jenkins so that they become visible and reacheable from each other.

As administrator, edit the %WINDIR%/system32/drivers/etc/hosts file in the Windows PC. Add the following line, replacing 192.168.1.2 by the actual Linux server's IP address. With that, the Windows PC can reach the containers' exposed service ports by their respective network-alias names:

192.168.1.2 gitea jenkins

Setting up Gitea

Now it is time to setup the gitea container. On the Linux server's shell, execute:

docker run \
  --name gitea \
  --network jenkins \
  --network-alias gitea \
  --detach \
  --restart=unless-stopped \
  --volume gitea-data:/data \
  --volume /etc/timezone:/etc/timezone:ro \
  --volume /etc/localtime:/etc/localtime:ro \
  --publish 3000:3000 \
  --publish 2222:2222 \
  gitea/gitea:1.22.1

A webhook is a mechanism which can be used to trigger associated build jobs in Jenkins whenever, for example, code is pushed into a Git repository.

Update /data/gitea/conf/app.ini for accepting webhooks from the jenkins container:

docker exec gitea bash -c "echo -e '\n[webhook]\nALLOWED_HOST_LIST=jenkins\nDISABLE_WEBHOOKS=false' >> /data/gitea/conf/app.ini"
docker restart gitea

On the web browser, navigate to http://gitea:3000 to perform the initial Gitea setup:

• Make sure Server Domain is set to gitea.
• Make sure Gitea Base URL is set to http://gitea:3000.
• Unfold Administrator Account Settings.
  • Set the Administrator Username (suggested: jenkins)
  • Set the Email Address
  • Set the Password
  • Set the Confirm Password
• Click Install Gitea.

Note

These configuration options will be written into /data/gitea/conf/app.ini stored inside the gitea-data volume.

Generating an access token

Instead of using the Gitea administrator account credentials outside its container, it is recommended to use a personal access token so that jenkins can access the repository without the need of using Gitea's administrative credentials.

To generate a new token in the user profile settings:

• Go to Applications → Generate New Token (http://gitea:3000/user/settings/applications).
• Choose a Token Name (suggestion: Jenkins Token).
• Select the following permissions:
  • issue: Read and Write
  • notification: Read and Write
  • organization: Read and Write
  • packages: Read
  • repository: Read and Write
  • user: Read and Write
• click on Generate Token.

Tip

You can generate as many access tokens as you need however, when generating a new token, make sure to copy it when shown in the next page. It will never be shown again.

Example by migrating an existing repository

On the top-right corner of the page:

• Go to + → New Migration → GitHub (http://gitea:3000/repo/migrate?service_type=2).
• Migrate / Clone from URL: https://github.com/iarsystems/bx-workspaces-ci.
• Edit the Jenkinsfile
  • update the agent settings to match the image you created earlier when performing the bx-docker guide.

Setting up Jenkins

It is finally time to set up the jenkins container.

The standard Jenkins setup has a number of steps that can be automated with the configuration-as-code plugin. For this, let's use a custom Dockerfile that will:

• use the jenkins/jenkins:lts-slim as base image, a stable version offering LTS (Long-Term Support).
• use the configuration-as-code plugin, so that we script the initial Jenkins configuration.
• use the jenkins-plugin-cli command line utility to install a collection of plugins versions that are known to be working.
• and more... (check Dockerfile for details).

Note

Given its fast-paced and complex ecosystem, Jenkins' plugins sometimes might break compatibility regarding its interdependencies. For such reasons, if you try this tutorial at a point in time where a certain plugin prevents the Docker image from being created, it is possible to pin the broken plugin's version by replacing <broken-plugin>:latest for a plugin's earlier version in the plugin.txt file.

Build the image, tagging it as jenkins:jcasc:

docker build -t jenkins:jcasc ~/bx-jenkins-ci

Now run the jenkins container:

Note

Edit JENKINS_ADMIN_ID and JENKINS_ADMIN_PASSWORD for running with credentials other than admin/password for the Jenkins' administrative user.

docker run --name jenkins \
  --network jenkins \
  --network-alias jenkins \
  --detach \
  --restart unless-stopped \
  --env JENKINS_ADMIN_ID=admin \
  --env JENKINS_ADMIN_PASSWORD=password \
  --privileged \
  --publish 8080:8080 \
  --publish 50000:50000 \
  --volume jenkins-data:/var/jenkins_home \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  jenkins:jcasc

Setting up the Docker Cloud plugin

It is time to configure the docker-cloud plugin. In your web browser:

• Navigate to http://jenkins:8080.
• Log in as "administrator" (e.g., admin).
• Go to Configure a cloud →.
• Select New cloud → Docker. http://jenkins:8080/cloud/new
• Name it Jenkins cloud and hit Create .

In the New cloud page:

• Unfold Docker Cloud details.
• Fill Docker Host URI with unix:///var/run/docker.sock
• Click Test Connection. You should get an output similar to: Version = 27.1.0, API Version = 1.46.
• Tick the Enabled checkbox and, down below, click the Save button.

Setting up the Gitea plugin

To configure the gitea plugin proceed as follows, starting from the Jenkins Dashboard (http://jenkins:8080):

• Go to Manage Jenkins.
• Go to System under the "System Configuration" section (http://jenkins:8080/manage/configure).
• Scroll down to Gitea Servers and click Add → Gitea Server.
• Name it (e.g.) "Gitea Server".
• Set Server URL to http://gitea:3000. You should see Gitea Version: 1.22.1 as response.
• Enable the Manage hooks checkbox. This will allow Jenkins to manage the webhooks for the Gitea server.
  • Add a new Jenkins (global) credential.
  • Change its "Kind" to Gitea Personal Access Token.
  • Paste the Gitea access token created during the Gitea server setup.
  • Give it a Description (e.g. "Jenkins Token"), click Add.

Note

You should see Hook management will be performed as jenkins or the corresponding Gitea user.

• Click Save.

Creating an Organization Folder

Go back to the Jenkins Dashboard (http://jenkins:8080):

• Click New Item.
• Enter an item name (e.g. Organization).
• Select Organization Folder and click OK.

In the Configuration page:

• Select Projects → "Repository Sources" → Add → Gitea Organization.
• Select the "Jenkins Token" from the Credentials drop-down list.
• Fill the Owner field with the username you created for your Gitea server (e.g., jenkins) and Save.

What happens next?

After that, Jenkins will use its multi-branch scan plugin to retrieve all the project repositories available on the Gitea Server.

When a project repository contains a Jenkinsfile that uses a declarative pipeline, Jenkins will then automatically execute the pipeline.

When the pipeline requests a Docker agent for the docker-cloud plugin, it will automatically forward the request to the jenkins container so a new container based on the selected image is dynamically spawned during the workflow execution.

pipeline {
  agent {
    docker {
      image 'iarsystems/bx<package>:<version>' 
      args '...'
  }
/* ... */
  stage('Build project') {
     steps {
       sh '/opt/iarsystems/bx<package>/common/bin/iarbuild project.ewp -build Release -log all'
      }
/* ... */

Jenkins will get a push notification from Gitea (via webhooks) whenever a monitored event is generated on the owner's repositories.

Now you can start developing using the IAR Embedded Workbench and committing the project's code to the Gitea Server so you get automated builds and reports.

Highlights

• The warnings-ng plugin gives instantaneous feedback for every build on compiler-generated warnings as well violation warnings on coding standards provided by IAR C-STAT, our static code analysis tool for C/C++:

• The gitea-checks plugin has integrations with the warnings-ng plugin. On the Gitea server, it can help you to spot failing checks on pull requests, preventing potentially defective code from being inadvertently merged into a project's production branch:

Note

Jenkins provides plugins for many other Git server providers such as GitHub, GitLab or Bitbucket. Although these services also offer their own CI infrastructure and runners. Gitea was picked for this tutorial for its simplicity to deploy in a container. Refer to Managing Jenkins/Managing Plugins for further details.

Summary

This tutorial provides a quickly deployable and reproducible setup where everything runs on containers. This is just one of many ways to set up automated workflows using the IAR Build Tools. By using Jenkins Configuration as Code fto set up a new Jenkins controller, you can simplify the initial configuration with YAML syntax. This configuration can be validated and reproduced across other Jenkins controllers.

You can learn from the provided scripts, Dockerfile and official Jenkins Documentation. Together, these resources form a cornerstone for your organization, allowing you to use them as-is or customize them to ensure the containers run in ways that meet your specific needs.

Follow us on GitHub to get updates about tutorials like this and more.

Issues

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.