Arduino CI Scripts

This repo contains various scripts and tools related to running continuous integration (CI) checks on Arduino Library Repos. The operations include:

checking formatting using clang-format,
generating documentation from source comments using Doxygen, and
building each example in the library for selected targets.

There is an associated guide available here: https://learn.adafruit.com/the-well-automated-arduino-library/

Adding GitHub Actions to Repo

To run these continuous integration checks on each push, pull-request or repository dispatch using GitHub actions:

Create a folder named .github/worflows in the root of the repo.
Copy example_actions.yml into the above directory and rename it githubci.yml.
Edit githubci.yml and change PRETTYNAME to the library repo name. Optionally, delete or comment out steps (using the # character), you don't want to include.
Here's an example: Adafruit_BME280_Library

Controlling Test Behavior

The build_platform.py script is used to test each .ino example in the repo for selected build platforms. The ALL_PLATFORMS dictionary contains a listing of all available platforms and selected platform groups. By default, main_platforms is used. To select a specific platform or group, replace main_platforms in githubci.yml with the group or platform name.

Additionally, UF2 files of the compiled sketches can be generated for supported platforms.

Fine tuning test selection

The script behavior can be controlled using special filenames:

.PLATFORM_ID.test.skip - Skip the specified platform. All others are tested.
.PLATFORM_ID.test.only - Test the specified platform. All others are skipped.
.PLATFORM_ID.generate - Generate UF2 of sketch for specified platform (if supported).

These are just empty files placed in an example folder. Replace PLATFORM_ID in the name with the key from ALL_PLATFORMS. metro_m0 from the following line in build_platform.py, for example:

"metro_m0" : ["adafruit:samd:adafruit_metro_m0", "0x68ed2b88", None],

You can use several .PLATFORM_ID.test.skip or .PLATFORM_ID.test.only to exclude or include multiple platforms. For example:

To skip testing on ESP8266, add a file named .esp8266.test.skip
To test only the Arduino UNO, add a file named .uno.test.only
To skip all and test nothing, add a file named .none.test.only
To generate UF2s for PyPortal, add a file named .pyportal.generate

Dependencies

Any library dependencies included in the library.properties are automatically installed before the tests are started. To install additional dependencies (e.g., those required for some examples but not the library itself) using arduino-cli, you could add additional steps to the githubci.yml file. For example:

- name: Set configuration
  run: arduino-cli config set library.enable_unsafe_install true 

- name: Install test dependencies
  run: arduino-cli lib install --git-url https://github.com/arduino-libraries/Servo --git-url https://github.com/arduino-libraries/Ethernet

Note: you'll only need to enable the enable_unsafe_install option if you want to identify libraries using urls. This isn't necessary when using the library name.

Formatting Check with Clang

The run-clang-format.py script is used to run clang-format and check file formatting. See the guide for details on installing clang-format to run formatting locally. Even a single extra white space can cause the CI to fail on formatting. You can typically just let clang do its thing and edit files in place using:

clang-format -i File_To_Format.cpp

Documentation with Doxygen

The doxy_gen_and_deploy.sh script uses Doxygen to generate and deploy documentation for the library. Any issues, like missing documentation, will cause the CI to fail. See the guide for details on installing and running Doxygen locally. The guide also has some tips on basic usage of Doxygen markup within your code.

Preserving Folders in Documentation Branch

By default, the documentation deployment script cleans the gh-pages branch before adding new documentation. If you need to preserve certain folders (like custom web interfaces), you can set the PRESERVE_FOLDERS environment variable in your workflow:

- name: doxygen
  env:
    GH_REPO_TOKEN: ${{ secrets.GH_REPO_TOKEN }}
    PRETTYNAME : "My Arduino Library"
    PRESERVE_FOLDERS: "webserial,assets"
  run: bash ci/doxy_gen_and_deploy.sh

This will preserve the listed folders (comma-separated) during the documentation generation process.