Github Action to compile all examples of an Arduino library for one board and check for errors
This action does a test-compile of one or more Arduino programs in a repository for different boards
each with different compile parameters.
It can be used e.g. to test-compile all examples contained in an Arduino library repository.
Node.js 12 actions are deprecated
update your checkout action from actions/checkout@v2
to actions/checkout@v3
or actions/checkout@master
.The action is a "composite run steps" action which uses the arduino-cli program for compiling. All the work like loading libraries, installing board definitions and setting parameters is orchestrated by the arduino-test-compile.sh bash script.
In case of a compile error the complete compile output is logged in the Compile all examples... step, otherwise only a green check is printed. Examples can be found here.
If you want to test compile a sketch, it is not required that the sketch resides in a directory with the same name (as Arduino IDE requires it) or has the extension .ino. Internally the file is renamed to be .ino and the appropriate directory is created on the fly at /home/runner/<sketch-name>
for test-compiling. See parameter sketch-names
.
Since version 0.11.0 of arduino-cli, the generated files (.bin, .hex, .elf, .eep etc.) can be found in the build/<FQBN> subfolder of the example directory $GITHUB_WORKSPACE/src/<example_name>
or in $HOME/<sketch-name>
for files not residing in a directory with the same name.
If you require a custom library for your build, add an extra step for loading a custom library.
Be aware to use the path:
parameter for checkout, otherwise checkout will overwrite the last checkout content.
Take care that the path parameter matches the pattern *Custom*
like here. You do not need to put the "Custom" library in the required-libraries list.
If you have problems with you workflow file, you find additional information in the output if you set the flags debug-compile
and / or debug-install
to true
.
If actions / workflow for your repository is not enabled, select Allow all actions
it in your repositorys Settings -> Actions -> General menu.
See action.yml for comprehensive list of parameters.
arduino-board-fqbn
The fully qualified board name to use for compiling with arduino-cli. You may add a suffix behind the fqbn with |
to specify one board for e.g. different compile options like arduino:avr:uno|trace
.
Default is arduino:avr:uno
.
arduino-board-fqbn: esp8266:esp8266:huzzah:eesz=4M3M,xtal=80
For 3rd party boards, you must also specify the Boards Manager URL platform-default-url:
or platform-url:
.
platform-default-url
Default value to take, if platform-url
is not specified for a 3rd party board. Useful, if you want to test compile for different boards types of one architecture.
Default is ""
.
platform-default-url: https://arduino.esp8266.com/stable/package_esp8266com_index.json
platform-url
Required for 3rd party boards, if platform-default-url
is not specified or applicable. If you need, you may specify more than one URL as a comma separated list (without enclosing it in double quotes) like http://drazzy.com/package_drazzy.com_index.json,https://raw.githubusercontent.com/ArminJo/DigistumpArduino/master/package_digistump_index.json
.
Default is ""
.
platform-url: https://arduino.esp8266.com/stable/package_esp8266com_index.json
Unofficial list of 3. party URL's
Some sample URL's are:
arduino-platform
Comma separated list of platform specifiers with optional version to specify multiple platforms for your board or a fixed version like arduino:[email protected]
.
The suffix @latest
is always removed from specified platform to enable usage of platform versions in a matrix.
In general, use it only if you require another specifier than the one derived from the 2 first elements of the arduino-board-fqbn e.g. esp8266:esp8266:huzzah:eesz=4M3M,xtal=80, esp32:esp32:featheresp32:FlashFreq=80 -> esp8266:esp8266. Do not forget to specify the related URL's, if it is not the arduino URL, which is built in.
Useful in the case you require a dedicated version of a core or two cores as for MegaCore, which requires the compiler from the Arduino core.
It is also useful if you install the core manually, but require e.g. tools from another core.
Default is ""
.
arduino-platform: arduino:avr,SparkFun:[email protected]
platform-url: https://raw.githubusercontent.com/sparkfun/Arduino_Boards/master/IDE_Board_Manager/package_sparkfun_index.json # Arduino URL is not required here
- arduino-boards-fqbn: MegaCore:avr:128:bootloader=no_bootloader,eeprom=keep,BOD=2v7,LTO=Os,clock=8MHz_internal
platform-url: https://mcudude.github.io/MegaCore/package_MCUdude_MegaCore_index.json
arduino-platform: MegaCore:avr,arduino:avr # gcc is taken from arduino:avr
required-libraries
Comma separated list of arduino library dependencies to install. You may add a version number like @1.3.4
.
Only libraries available in the Arduino library manager can be installed this way.
If you want to use other or custom libraries, you must put all the library files into the sketch directory or add an extra step as in this example.
Be careful, some library names can contain spaces, e.g. LiquidCrystal I2C
even if they are defined in library.properties with underscores like: name=LiquidCrystal_I2C
.
Default is ""
.
required-libraries: Servo,Adafruit [email protected],${{ env.REQUIRED_LIBRARIES }},${{ matrix.required-libraries }}
A list of correct Arduino library names can be found here.
sketches-exclude
Sketches to be excluded from build. Comma or space separated list of complete sketch / example names to exclude in build. Comment is only allowed at the end of the list
# 1.TinyWireM not usable; 2. incompatible I2C Hardware for Wire.h; 3. SoftPwm is not required and not working
sketches-exclude:
WiiClassicJoystick
BasicUsage,DigisparkOLED,DigiUSB2LCD
SoftPwm13Pins,TinySoftPwmDemo
DigisparkUSBDemo ArduinoNunchukDemo DigisparkJoystickDemo # Nunchuck library: incompatible I2C Hardware, the original library uses TinyWireM library
build-properties
Build parameter like -DDEBUG
for each example specified or for all examples which have no dedicated specification, if example name is All
. I.e. if an example specific parameter is specified, the value for All is ignored for this example.
The content is passed to the arduino-cli commandline in 3 parameters:
--build-property compiler.[cpp,c,S].extra_flags="${GCC_EXTRA_FLAGS}"
In the include:
section you may specify:
include:
...
build-properties:
SymmetricEasing:
-DDISABLE_COMPLEX_FUNCTIONS
-DDEBUG
AsymmetricEasing:
-DTRACE
Simple: -DPRINT_FOR_SERIAL_PLOTTER
PCA9685_ExpanderFor32Servos: -DTRACE -DENABLE_MICROS_AS_DEGREE_PARAMETER
...
build-properties:
Simple:
-DPRINT_FOR_SERIAL_PLOTTER -DDEBUG
All:
-DDEBUG
...
and reference it in the with:
section by:
with:
build-properties: ${{ toJson(matrix.build-properties) }}
If you want to specify it directly in the with:
section it must be:
with:
build-properties: '{ "WhistleSwitch": "-DDEBUG -DFREQUENCY_RANGE_LOW", "SimpleFrequencyDetector": "-DINFO", "All": "-DDEBUG" }'
extra-arduino-cli-args
This string is passed verbatim without additional quoting to the arduino-cli compile commandline as last argument before the filename.
See https://arduino.github.io/arduino-cli/commands/arduino-cli_compile/ for compile parameters.
E.g. if you specify extra-arduino-cli-args: "--warnings default"
, this overwrites the default setting of --warnings all
for compile, which may be especially useful for ESP32 source compilation.
Be aware, that you cannot add to --build-property compiler.[cpp,c,S].extra_flags
, if you already specified build-properties
, they will be overwritten by your content. See https://github.com/arduino/arduino-cli/pull/1044.
This example tells arduino-cli to do the lolin32 build for what the Arduino IDE calls Tools > Partition Scheme > No OTA (Large APP), what can also be specified with arduino-boards-fqbn: esp32:esp32:lolin32:PartitionScheme=no_ota
.
strategy:
matrix:
arduino-board-fqbn:
- esp32:esp32:lolin32
include:
- arduino-boards-fqbn: esp32:esp32:lolin32
extra-arduino-cli-args: "--warnings default --build-property build.partitions=no_ota --build-property upload.maximum_size=2097152"
...
steps:
- name: Arduino build
uses: ArminJo/arduino-test-compile@master
with:
...
arduino-board-fqbn: ${{ matrix.arduino-board-fqbn }}
extra-arduino-cli-args: ${{ matrix.extra-arduino-cli-args }}
extra-arduino-lib-install-args
This string is passed verbatim without double quotes to the arduino-cli lib install commandline as last argument before the library names. It can be used e.g. to suppress dependency resolving for libraries by using --no-deps
as argument string.
steps:
- name: Arduino build
uses: ArminJo/arduino-test-compile@v3
with:
...
arduino-board-fqbn: ${{ matrix.arduino-board-fqbn }}
extra-arduino-lib-install-args: "--no-deps"
cli-version
The version of arduino-cli
to use.
Default is latest
.
cli-version: 0.9.0 # The current one (3/2020)
sketch-names
Comma separated list of patterns or filenames (without path) of the sketch(es) to test compile. Useful if the sketch is a *.cpp or .c file or only one sketch in the repository should be compiled. If first character is a *
like in ".ino" the list must be enclosed in double quotes!
The sketch names to compile are searched in the whole repository by the command find . -name "$SKETCH_NAME"
with .
as the root of the repository, so you do not need to specify the full path.
If you specify sketch-names-find-start
then the find command is changed to find ${PWD}/${SKETCH_NAMES_FIND_START} -name "$SKETCH_NAME"
.
Sketches do not need to be in an example directory. This enables plain programs to be test compiled.
Since Arduino requires a sketch to end with .ino and to reside in a directory with the same name as the sketch, if required, the renaming and directory creation is done internally to fulfill the requirements of the Arduino IDE.
Default is *.ino
.
sketch-names: "*.ino,SimpleTouchScreenDSO.cpp"
sketch-names-find-start
The start directory to look for the sketch-names to test compile. Can be a path like digistump-avr/libraries/*/examples/
. Must be a path relative to the root of the repository. Used here to compile all library examples of the board package.
Default is .
(root of repository).
sketch-names-find-start: digistump-avr/libraries/*/examples/C*/
set-build-path
If set to true, the build directory (arduino-cli paramer --build-path) is set to $GITHUB_WORKSPACE/src/<example_name>/build/
or to $HOME/<sketch-name>/build/
for files not residing in a directory with the same name.
This is useful, if you need to access the result files of the Arduino build in later workflow steps.
Default is false
.
set-build-path: true
debug-compile
and debug-install
If you have problems with you workflow file, try to set this flags to true
.
Default is false
.
Compile all sketches / examples for the UNO board.
name: SimpleBuild
on: push
jobs:
build:
name: Test compiling examples for UNO
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Compile all examples
uses: ArminJo/arduino-test-compile@v3
name: LibraryBuild
on: [push, pull_request]
jobs:
build:
name: Test compiling examples for esp8266
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Compile all examples
uses: ArminJo/arduino-test-compile@v3
with:
arduino-board-fqbn: esp8266:esp8266:huzzah:eesz=4M3M,xtal=80
platform-url: https://arduino.esp8266.com/stable/package_esp8266com_index.json
required-libraries: Servo,Adafruit NeoPixel
sketches-exclude: WhistleSwitch 50Hz
build-properties: '{ "WhistleSwitch": "-DDEBUG -DFREQUENCY_RANGE_LOW", "SimpleFrequencyDetector": "-DINFO" }'
name: LibraryBuild with parameter matrix
on:
push: # see: https://help.github.com/en/actions/reference/events-that-trigger-workflows#pull-request-event-pull_request
paths:
- '**.ino'
- '**.cpp'
- '**.h'
- '**LibraryBuild.yml'
pull_request:
jobs:
build:
name: ${{ matrix.arduino-boards-fqbn }} ${{ matrix.log-options }} ${{ matrix.other-options }}
runs-on: ubuntu-latest
env:
REQUIRED_LIBRARIES: Servo,Adafruit NeoPixel
strategy:
matrix:
arduino-boards-fqbn:
- arduino:avr:uno
log-options: [-DDEBUG, -DINFO]
other-options: [-DTEST, -DDUMMY]
fail-fast: false
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Compile all examples
uses: ArminJo/arduino-test-compile@v3
with:
arduino-board-fqbn: ${{ matrix.arduino-boards-fqbn }}
platform-url: ${{ matrix.platform-url }}
required-libraries: ${{ env.REQUIRED_LIBRARIES }}
build-properties: '{ "All": "${{ matrix.log-options }} ${{ matrix.other-options }}" }'
name: LibraryBuild
on:
push: # see: https://help.github.com/en/actions/reference/events-that-trigger-workflows#pull-request-event-pull_request
paths:
- '**.ino'
- '**.cpp'
- '**.h'
- '**LibraryBuild.yml'
pull_request:
jobs:
build:
name: ${{ matrix.arduino-boards-fqbn }} - test compiling examples
runs-on: ubuntu-latest
env:
REQUIRED_LIBRARIES: Servo,Adafruit NeoPixel
strategy:
matrix:
arduino-boards-fqbn:
- arduino:avr:uno
- arduino:avr:uno|All-DEBUG
- arduino:avr:uno|trace
- esp8266:esp8266:huzzah:eesz=4M3M,xtal=80
include:
- arduino-boards-fqbn: arduino:avr:uno
sketch-names: WhistleSwitch.ino,SimpleFrequencyDetector.ino # Comma separated list of sketch names (no path required) or patterns to use in build
build-properties:
WhistleSwitch:
-DDEBUG
-DFREQUENCY_RANGE_LOW
SimpleFrequencyDetector:
-DINFO
- arduino-boards-fqbn: arduino:avr:uno|All-DEBUG # UNO board with -DDEBUG for all examples
sketches-exclude: 50Hz # Comma separated list of (unique substrings of) example names to exclude in build
build-properties:
All:
-DDEBUG
- arduino-boards-fqbn: arduino:avr:uno|trace # UNO board with different build properties
sketches-exclude: 50Hz # Comma separated list of (unique substrings of) example names to exclude in build
build-properties:
WhistleSwitch:
-DDEBUG
-DTRACE
- arduino-boards-fqbn: esp8266:esp8266:huzzah:eesz=4M3M,xtal=80
platform-url: https://arduino.esp8266.com/stable/package_esp8266com_index.json
sketches-exclude: WhistleSwitch,50Hz,SimpleFrequencyDetector
- arduino-boards-fqbn: esp32:esp32:featheresp32:FlashFreq=80
platform-url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
required-libraries: ESP32 ESP32S2 AnalogWrite
fail-fast: false
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Compile all examples
uses: ArminJo/arduino-test-compile@v3
with:
arduino-board-fqbn: ${{ matrix.arduino-boards-fqbn }}
platform-default-url: ${{ env.PLATFORM_DEFAULT_URL }}
platform-url: ${{ matrix.platform-url }}
required-libraries: ${{ env.REQUIRED_LIBRARIES }},${{ matrix.required-libraries }}
sketch-names: ${{ matrix.sketch-names }}
sketches-exclude: ${{ matrix.sketches-exclude }}
build-properties: ${{ toJson(matrix.build-properties) }}
Add an extra step Checkout custom library
for loading custom library. You must use the path:
parameter, otherwise checkout overwrites the last checkout content.
Take care that the path parameter matches the pattern *Custom*
like here.
You do not need to put the custom libraries, you loaded manually, in the required-libraries
list, since they are already loaded now!
But if you use this library as substitute for an Arduino library take care to remove the substituted Arduino linrary in your required-libraries
list.
...
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Checkout custom library
uses: actions/checkout@v3
with:
repository: ArminJo/ATtinySerialOut
ref: master
path: CustomLibrary # must contain string "Custom"
# No need to put "Custom" library in the required-libraries list
- name: Checkout second custom library # This name must be different from the one above
uses: actions/checkout@v3
with:
repository: ArminJo/Arduino-BlueDisplay
ref: master
path: CustomLibrary_BlueDisplay # This path must be different from the one above but must also contain string "Custom"
...
sketch-names
parametername: TestCompile
on: push
jobs:
build:
name: Test compiling examples for UNO
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Compile all examples
uses: ArminJo/arduino-test-compile@master
with:
sketch-names: SimpleTouchScreenDSO.cpp
required-libraries: BlueDisplay
arduino-platform
parameter like herename: TestCompile
on: push
jobs:
build:
name: Test compiling examples for Digispark
runs-on: ubuntu-latest
strategy:
matrix:
arduino-boards-fqbn:
- digistump:avr:digispark-tiny # ATtiny85 board @16.5 MHz
- digistump:avr:MHETtiny88 # Chinese MH-Tiny ATTiny88
include:
- arduino-boards-fqbn: digistump:avr:MHETtiny88 # ATtiny88 China clone board @16 MHz
# 1.TinyWireM not usable; 2. incompatible I2C Hardware for Wire.h; 3. SoftPwm is not required and not working
sketches-exclude:
WiiClassicJoystick
BasicUsage,DigisparkOLED,DigiUSB2LCD
SoftPwm13Pins,TinySoftPwmDemo
DigisparkUSBDemo ArduinoNunchukDemo DigisparkJoystickDemo # Nunchuck library: incompatible I2C Hardware, the original library uses TinyWireM library
# Do not cancel all jobs / architectures if one job fails
fail-fast: false
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Use this repo as Arduino core
run: |
mkdir --parents $HOME/.arduino15/packages/digistump/hardware/avr/0.0.7 # dummy release number
cp --recursive $GITHUB_WORKSPACE/digistump-avr/* $HOME/.arduino15/packages/digistump/hardware/avr/0.0.7/
- name: Compile all examples
uses: ArminJo/arduino-test-compile@master
with:
arduino-board-fqbn: digistump:avr:digispark-tiny
arduino-platform: digistump:avr,arduino:avr # we require the C compiler from it. See dependencies of package_digistump_index.json
sketches-exclude: ${{ matrix.sketches-exclude }}
sketch-names: "*.ino"
sketch-names-find-start: digistump-avr/libraries/*/examples/
This is not longer required since version v3.0.0.
name: LibraryBuild
on:
push: # see: https://help.github.com/en/actions/reference/events-that-trigger-workflows#pull-request-event-pull_request
paths:
- '**.ino'
- '**.cpp'
- '**.h'
- '**LibraryBuild.yml'
pull_request:
jobs:
build:
name: ${{ matrix.arduino-boards-fqbn }} - test compiling examples
runs-on: ubuntu-latest
env:
PLATFORM_DEFAULT_URL: https://arduino.esp8266.com/stable/package_esp8266com_index.json
REQUIRED_LIBRARIES: Adafruit NeoPixel,Servo
strategy:
matrix:
arduino-boards-fqbn:
- arduino:avr:uno
- arduino:avr:uno|All-DEBUG
- arduino:avr:uno|trace
- esp8266:esp8266:huzzah:eesz=4M3M,xtal=80
include:
- arduino-boards-fqbn: arduino:avr:uno
sketch-names: WhistleSwitch.ino,SimpleFrequencyDetector.ino # Comma separated list of sketch names (no path required) or patterns to use in build
build-properties:
WhistleSwitch:
-DDEBUG
-DFREQUENCY_RANGE_LOW
SimpleFrequencyDetector:
-DINFO
- arduino-boards-fqbn: arduino:avr:uno|All-DEBUG # UNO board with -DDEBUG for all examples
sketches-exclude: 50Hz # Comma separated list of (unique substrings of) example names to exclude in build
build-properties:
All:
-DDEBUG
- arduino-boards-fqbn: arduino:avr:uno|trace # UNO board with different build properties
sketches-exclude: 50Hz # Comma separated list of (unique substrings of) example names to exclude in build
build-properties:
WhistleSwitch:
-DDEBUG
-DTRACE
- arduino-boards-fqbn: esp8266:esp8266:huzzah:eesz=4M3M,xtal=80
sketches-exclude: WhistleSwitch,50Hz,SimpleFrequencyDetector
fail-fast: false
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Compile all examples using the bash script arduino-test-compile.sh
env:
# Passing parameters to the script by setting the appropriate ENV_* variables.
ENV_ARDUINO_BOARD_FQBN: ${{ matrix.arduino-boards-fqbn }}
ENV_PLATFORM_DEFAULT_URL: ${{ env.PLATFORM_DEFAULT_URL }}
ENV_PLATFORM_URL: ${{ matrix.platform-url }}
ENV_REQUIRED_LIBRARIES: ${{ env.REQUIRED_LIBRARIES }}
ENV_SKETCHES_EXCLUDE: ${{ matrix.sketches-exclude }}
ENV_BUILD_PROPERTIES: ${{ toJson(matrix.build-properties) }}
ENV_SKETCH_NAMES: ${{ matrix.sketch-names }}
ENV_SKETCH_NAMES_FIND_START: examples/ # Not really required here, but serves as an usage example.
run: |
wget --quiet https://raw.githubusercontent.com/ArminJo/arduino-test-compile/master/arduino-test-compile.sh
chmod +x arduino-test-compile.sh
./arduino-test-compile.sh
Samples for using action in workflow:
@latest
is always removed from specified arduino-platform
.extra-arduino-lib-install-args
.extra-arduino-cli-args
.examples-exclude
and examples-build-properties
from action definition.examples-exclude
to sketches-exclude
. Old name is still valid.examples-build-properties
to build-properties
. Old name is still valid.examples-build-properties
now used also for *c and S extra_flags.set-build-path
.sketch-names
.sketch-names-find-start
to compile multiple libraries.platform-default-url
to ease compiling for multiple boards of the same architecture.CPP_EXTRA_FLAGS
are now reseted.All
in examples-build-properties
.required-libraries
from space to comma separated list.sketch-name
to sketch-names
to enable comma separated list.examples-exclude
.libraries
to required-libraries
.arduino-platform
to enable specifying the version of the required platform.Please write me a PM including your motivation/problem if you need a modification or an extension.