This article was written by Per Tillisch from the Arduino Tooling Team.
The Arduino team created some tools that make it easy to automate a check for whether your Arduino sketches compile. Used with GitHub Actions, the tools allow anyone to set up a simple “smoke test” on every commit and pull request made to a GitHub repository, with reports on the impacts of those changes.
These free, open source actions are now listed on the GitHub Marketplace.
Why do a compile test?
Although passing a “Does it compile?” check is not definitive proof of a working project, failure to compile is a sure sign of a non-working project! For this reason, it can provide a useful “smoke test”.
Even if you have more formal tests in place, a compilation check remains a valuable supplement, since it is able to catch incompatibilities with the Arduino build system that other tests will miss.
The biggest advantage of this approach is that, unlike other testing methods, it takes very little effort to set up and maintain. All that’s needed is to define a few basic parameters of the compilations, such as which Arduino boards to compile for and which library dependencies of the sketch need to be installed. After that, everything is automatic!
GitHub Actions
GitHub Actions is the preferred automation service for continuous integration in the Arduino firmware repositories. Let’s take a look at its fundamental concepts.
Workflows define the procedure that should run when a specific event occurs in the repository. For example, you might have a workflow that runs every time someone submits a pull request to your repository. Using GitHub Actions is only a matter of adding a workflow configuration file to your repository.
Actions are programs that do specific tasks. These programs are packaged in a manner that makes them easy to reuse in any GitHub Actions workflow. By using combinations of the many actions provided by the open source community, you can easily do complex things with simple, easy to maintain workflows.
Actions for Arduino projects
Several GitHub Actions actions are available for use with Arduino projects. One of these is arduino/compile-sketches. As you might have guessed from the name, this is a tool for compiling Arduino sketches.
A complete workflow to compile the sketches in a repository can be as minimal as this:
On every commit and pull request, this workflow searches the subfolders of the repository recursively for sketches and compiles them for the Arduino Uno. If compilation of any of the sketches has an error, the commit status will be set to failure.
You can see a live demonstration of the workflow here: https://github.com/arduino/arduino-cli-example/tree/compile-sketches-demo
Next, let’s take a look at a workflow that shows some of the other features of the arduino/compile-sketches action:
This is a workflow used to test the sketches that accompany a machine learning tutorial. There are a few differences from the previous workflow:
The tutorial’s sketches were written for the Arduino Nano 33 BLE board, so instead of compiling for the action’s default Arduino Uno board as in the previous workflow, the workflow was configured to compile for the Nano 33 BLE by specifying that board’s fully qualified board name (FQBN) identifier (arduino:mbed:nano33ble) via the action’s fqbn input.
These sketches require some libraries to be installed. The names of the libraries are specified via the action’s libraries input. This causes them to be installed from the Arduino Library Manager.
You can see this workflow in use in the repository: https://github.com/arduino/ArduinoTensorFlowLiteTutorials/blob/master/.github/workflows/compile-sketch.yml
Not just for sketches
Just because we are compiling sketches, that doesn’t mean this action can only be used to test sketches. Compiling a sketch is also testing whether the libraries and boards platform used by that sketch will compile. Continuous integration in library and platform repositories is especially important to avoid breaking components other people rely upon. These projects often have multiple sketches that need to be compiled for multiple boards, making automation of the task even more beneficial. If you’re a library or platform developer, we strongly recommend spending a little time to set up a workflow.
This is the workflow used to test the ArduinoBLE library:
This library supports multiple architectures, so the compilations must be done for several boards. This is done by creating a job matrix. A copy of the compile-examples job runs for each of the boards listed under the jobs.compile-examples.strategy.matrix.fqbn[] key, avoiding the need to define a separate job for each board in the workflow.
You can see this workflow in use in the library’s repository: https://github.com/arduino-libraries/ArduinoBLE/blob/master/.github/workflows/compile-examples.yml
Don’t let its ease of use for basic applications fool you into thinking it’s not suitable for advanced use cases. arduino/compile-sketches is a powerful general purpose tool for compiling Arduino sketches. The configuration options provide a lot of flexibility that will make it useful no matter what your requirements are. See the documentation for details: https://github.com/arduino/compile-sketches#readme
Here’s a workflow using the action to test the ArduinoIoTCloud library: https://github.com/arduino-libraries/ArduinoIoTCloud/blob/master/.github/workflows/compile-examples.yml
This workflow uses the action to test the “Arduino mbed-enabled Boards” platform: https://github.com/arduino/ArduinoCore-mbed/blob/master/.github/workflows/compile-examples.yml
Compilation data reports
The arduino/compile-sketches action can be configured to report the change in memory usage and compiler warnings resulting from commits and pull requests. These will be displayed in the build log:
A companion action, arduino/report-size-deltas, comments on pull requests with a report of the resulting change in memory usage of the sketches that were compiled by the arduino/compile-sketches action:
The workflow for arduino/report-size-deltas is very simple, and doesn’t require any modifications to be used in your repository:
Give it a try!
Continuous integration can reduce the tedious task of manual testing. You probably wouldn’t enjoy compiling multiple sketches for multiple boards for every commit and every pull request, but these new actions are happy to do it for you.
These actions are especially useful for pull request triage. They provide an initial “smoke test” of the pull request without any effort from the repository maintainer. If the workflow job for the pull request fails or reports an undue increase in memory usage, the contributor of the pull request will often work to resolve the issues revealed by the CI system on their own initiative, reducing some of the effort required to review contributions.
We use these actions in the Arduino firmware repositories and are sure you’ll also find them useful for your projects.
Support and feedback
You can discuss or get assistance with setting up continuous integration for your Arduino projects on the Arduino Forum.
Feedback is welcome! Please submit feature requests or bug reports to the issue trackers:
- https://github.com/arduino/compile-sketches/issues
- https://github.com/arduino/report-size-deltas/issues
The post Test your Arduino projects with GitHub Actions appeared first on Arduino Blog.
