Repository files navigation

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

• checking formatting usingclang-format,
• generating documentation from source comments usingDoxygen, 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/

To run these continuous integration checks on each push, pull-request orrepository dispatch usingGitHub actions:

• Create a folder named.github/worflows in the root of the repo.
• Copyexample_actions.yml into the above directory and rename itgithubci.yml.
• Editgithubci.yml and changePRETTYNAME 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

Thebuild_platform.py script is used to test each.ino example in the repo for selected build platforms. TheALL_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, replacemain_platforms ingithubci.yml with the group or platform name.

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

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. ReplacePLATFORM_ID in the name with the key fromALL_PLATFORMS.metro_m0 from the following line inbuild_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:

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

Any library dependencies included in thelibrary.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) usingarduino-cli, you could add additional steps to thegithubci.yml file. For example:

-name:Set configurationrun:arduino-cli config set library.enable_unsafe_install true-name:Install test dependenciesrun: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 theenable_unsafe_install option if you want to identify libraries using urls. This isn't necessary when using the library name.

Therun-clang-format.py script is used to runclang-format and check file formatting.Seethe guide for details on installingclang-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

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

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 thePRESERVE_FOLDERS environment variable in your workflow:

-name:doxygenenv: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.