Test compile for Arduino

arduino-test-compile action / script

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.
The action is a Docker action which uses Ubuntu 18.04 and the arduino-cli program for compiling. All the other work is done by the arduino-test-compile.sh bash script.
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 appropriate directory is created on the fly for test-compiling and the file is renamed to be .ino.

If you need more flexibility for e.g. installing additional board platforms, or want to save around 20 to 30 seconds for each job, then you may want to use the arduino-test-compile.sh directly. See example below.

Inputs

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.
Environment name for script usage is ENV_ARDUINO_BOARD_FQBN.

arduino-board-fqbn: esp8266:esp8266:huzzah:eesz=4M3M,xtal=80

For 3rd party boards, you must also specify the Boards Manager URL platform-url:.

`platform-url`

Required for 3rd party boards. 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 "".
Environment name for script usage is ENV_PLATFORM_URL.

platform-url: https://arduino.esp8266.com/stable/package_esp8266com_index.json

Sample URL's are:

http://drazzy.com/package_drazzy.com_index.json - for ATTiny boards
Old URL: http://digistump.com/package_digistump_index.json - for Digispark boards. https gives: x509: certificate signed by unknown authority
Improved URL: https://raw.githubusercontent.com/ArminJo/DigistumpArduino/master/package_digistump_index.json - up to 20% more code possible
https://arduino.esp8266.com/stable/package_esp8266com_index.json - for ESP8266 based boards
https://dl.espressif.com/dl/package_esp32_index.json - for ESP32 based boards
https://github.com/stm32duino/BoardManagerFiles/raw/dev/STM32/package_stm_index.json - for STM32 boards
https://raw.githubusercontent.com/sparkfun/Arduino_Boards/master/IDE_Board_Manager/package_sparkfun_index.json - for Sparkfun boards, esp. Apollo3 boards
https://files.pololu.com/arduino/package_pololu_index.json - for Pololu boards, esp. ATMega328PB boards

`required-libraries`

Comma separated list of library dependencies to install. You may add a version number like @1.3.4.
Default is "".
Environment name for script usage is ENV_REQUIRED_LIBRARIES.

required-libraries: Servo,Adafruit NeoPixel@1.3.4

Comma separated list without double quotes around the list or a library name. A list of correct library names can be found here.

`examples-exclude`

Examples to be excluded from build. Comma or space separated list of (unique substrings of) sketch / example names to exclude in build.
Environment name for script usage is ENV_EXAMPLES_EXCLUDE.

  examples-exclude: QuadrupedControl,RobotArmControl # QuadrupedControl and RobotArmControl because of missing EEprom

`examples-build-properties`

Build parameter like -DDEBUG for each example specified or for all examples, if example name is All.
Environment name for script usage is ENV_EXAMPLES_BUILD_PROPERTIES.

In the include: section you may specify:

include:
  examples-build-properties:
    WhistleSwitch:
      -DDEBUG
      -DFREQUENCY_RANGE_LOW
    SimpleFrequencyDetector:
      -DINFO

include:
  examples-build-properties:
    All:
      -DDEBUG

in the with: section it must be:

with:
  examples-build-properties: '{ "WhistleSwitch": "-DDEBUG -DFREQUENCY_RANGE_LOW", "SimpleFrequencyDetector": "-DINFO" }'

`cli-version`

The version of arduino-cli to use.
Default is latest.
Environment name for script usage is ENV_CLI_VERSION.

cli-version: 0.9.0 # The current one (3/2020)

`sketch-names`

Comma sepatated 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 is a * the list must be enclosed in double quotes!
Default is *.ino.
Environment name for script usage is ENV_SKETCH_NAMES.

sketch-names: "*.ino,SimpleTouchScreenDSO.cpp"

If the sketch is not contained in a directory with the same name as the sketch, this directory will be created internally and the content of the sketch directory will be recursively copied to it. This is required by arduino-cli to successful compile a sketch.
The sketches to compile are internally searched by the command find . -name "$SKETCH_NAME" with . as the root of the repository, so you do not need to specify the full path.

`arduino-platform`

Comma separated list of platform specifies with optional version. Useful if you require multiple platforms for your board or a fixed version like arduino:avr@1.8.2.
In general, use it 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
Environment name for script usage is ENV_ARDUINO_PLATFORM.

arduino-platform: arduino:avr@1.8.2,digistump:avr

Workflows examples

Simple - without any parameter

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@master
    - name: Compile all examples
      uses: ArminJo/arduino-test-compile@v2.2.0

One ESP8266 board with parameter

name: LibraryBuild
on: [push, pull_request]
jobs:
  build:
    name: Test compiling examples for esp8266
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout
      uses: actions/checkout@master
      
    - name: Compile all examples
        uses: ArminJo/arduino-test-compile@v2.2.0
      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
        examples-exclude: WhistleSwitch 50Hz
        examples-build-properties: '{ "WhistleSwitch": "-DDEBUG -DFREQUENCY_RANGE_LOW", "SimpleFrequencyDetector": "-DINFO" }'

Multiple boards with parameter

name: LibraryBuild
on: [push, 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: "*.ino" # is default setting
            examples-exclude: 50Hz # Comma separated list of (unique substrings of) example names to exclude in build
            examples-build-properties:
              WhistleSwitch:
                -DDEBUG
                -DFREQUENCY_RANGE_LOW
              SimpleFrequencyDetector:
                -DINFO

          - arduino-boards-fqbn: arduino:avr:uno|All-DEBUG # UNO board with -DDEBUG for all examples
            examples-exclude: 50Hz # Comma separated list of (unique substrings of) example names to exclude in build
            examples-build-properties:
              All:
                -DDEBUG

          - arduino-boards-fqbn: arduino:avr:uno|trace # UNO board with different build properties
            examples-exclude: 50Hz # Comma separated list of (unique substrings of) example names to exclude in build
            examples-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
            examples-exclude: WhistleSwitch,50Hz,SimpleFrequencyDetector          

      fail-fast: false
                
      steps:
      - name: Checkout
        uses: actions/checkout@master
      
      - name: Compile all examples
        uses: ArminJo/arduino-test-compile@v2.2.0
        with:
          arduino-board-fqbn: ${{ matrix.arduino-boards-fqbn }}
          platform-url: ${{ matrix.platform-url }}
          required-libraries: ${{ env.REQUIRED_LIBRARIES }}
          examples-exclude: ${{ matrix.examples-exclude }}
          examples-build-properties: ${{ toJson(matrix.examples-build-properties) }}

Multiple boards with parameter using the script directly

This is faster and more flexible.

name: LibraryBuild
on: [push, pull_request]
jobs:
  build:
    name: ${{ matrix.arduino-boards-fqbn }} - test compiling examples
    runs-on: ubuntu-latest
    env:
      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
            examples-build-properties:
              WhistleSwitch:
                -DDEBUG
                -DFREQUENCY_RANGE_LOW
              SimpleFrequencyDetector:
                -DINFO

          - arduino-boards-fqbn: arduino:avr:uno|All-DEBUG # UNO board with -DDEBUG for all examples
            examples-exclude: 50Hz # Comma separated list of (unique substrings of) example names to exclude in build
            examples-build-properties:
              All:
                -DDEBUG

          - arduino-boards-fqbn: arduino:avr:uno|trace # UNO board with different build properties
            examples-exclude: 50Hz # Comma separated list of (unique substrings of) example names to exclude in build
            examples-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
            examples-exclude: WhistleSwitch,50Hz,SimpleFrequencyDetector          

      fail-fast: false
      steps:
      - name: Checkout
        uses: actions/checkout@master
      - 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_URL: ${{ matrix.platform-url }}
          ENV_REQUIRED_LIBRARIES: ${{ env.REQUIRED_LIBRARIES }}
          ENV_EXAMPLES_EXCLUDE: ${{ matrix.examples-exclude }}
          ENV_EXAMPLES_BUILD_PROPERTIES: ${{ toJson(matrix.examples-build-properties) }}
        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:

The simple example from above. LightweightServo
One sketch, one library. Simple-DSO
Arduino library, only arduino:avr boards. Talkie
Arduino library, 2 boards. Arduino-FrequencyDetector

Samples for using arduino-test-compile.sh script instead of ArminJo/arduino-test-compile@v2.2.0 action:

One sketch, one board, multiple options. RobotCar
Arduino library, multiple boards. ServoEasing
Arduino library, multiple boards. NeoPatterns

Revision History

Version v2.2.0

Using ubuntu:18.04 for Docker container, since ubuntu:latest can not fetch python for ESP32 anymore.
CPP_EXTRA_FLAGS are now resetted.

Version v2.1.0 -> as of 30.4.2020 internally upgraded to content of v2.2.0, because of ESP32 compile bug

Added missing newline after print of "Install libraries $REQUIRED_LIBRARIES".
Added semantic for example name All in examples-build-properties.

Version v2.0.0 -> as of 30.4.2020 internally upgraded to content of v2.2.0, because of ESP32 compile bug

Changed required-libraries from space to comma separated list.
Renamed parameter sketch-name to sketch-names to enable comma separated list.
Accept comma separated list for examples-exclude.
Updated documentation.

Version v1.1.0 -> as of 30.4.2020 internally upgraded to content of v2.2.0, because of ESP32 compile bug

Renamed parameter libraries to required-libraries.
Renamed script.
Script instead of action can be used in steps.
Added parameter arduino-platform to enable specifying the version of the required platform.

Version v1.0.0

Initial tested version.

Requests for modifications / extensions

Please write me a PM including your motivation/problem if you need a modification or an extension.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GitHub Action

Test compile for Arduino