Merge branch 'master' of github.com:adafruit/ci-arduino

Author: ladyada

Diff for: .github/workflows/githubci.yml

@@ -16,5 +16,5 @@ jobs:
       run: bash ./actions_install.sh
     - name: test platforms
       run: |
-        python3 build_platform.py uno leonardo mega2560 zero esp8266 esp32 pico_rp2040
+        python3 build_platform.py uno leonardo mega2560 zero esp8266 esp32 pico_rp2040 feather_m4_express
 

Diff for: README.md

@@ -1,256 +1,55 @@
-# Travis CI Arduino Init Script [![Build Status](https://travis-ci.com/adafruit/travis-ci-arduino.svg?branch=master)](https://travis-ci.com/adafruit/travis-ci-arduino)
+# Arduino CI Scripts
 
-The purpose of this repo is to create a centrally managed dependency
-install script for all Adafruit Arduino Library Travis CI and Github Actions configs.
-This will allow us to easily update the install steps without
-having to manually or programmatically update 100+ `.travis.yml` files.
+This repos contains various scripts and tools related to running
+continuous integration (CI) checks on Arduino Library Repos.
 
-We have a guide that you can use to follow along to install both TravisCI and Doxygen generation here https://learn.adafruit.com/the-well-automated-arduino-library/
+There is an associated guide available here:
+https://learn.adafruit.com/the-well-automated-arduino-library/
 
-## Adding to Travis CI Configs
+## Adding GitHub Actions to Repo
 
-You will need to source the script in the `before_install` step of your
-`.travis.yml` file.
+* 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.
+* Here's an example: [Adafruit_BME280_Library](https://github.com/adafruit/Adafruit_BME280_Library/blob/master/.github/workflows/githubci.yml)
+* These actions will now run automatically on any pull, push, or dispatch.
 
-```sh
-source <(curl -SLs https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/install.sh)
-```
-
-If you only want to install and build on certain platforms, you can set the
-`INSTALL_PLATFORMS` environment variable to a comma-separated list of platforms.
-
-**Example `.travis.yml`:**
-```yaml
-language: c
-sudo: false
-cache:
-  directories:
-    - ~/arduino_ide
-    - ~/.arduino15/packages/
-git:
-  depth: false
-  quiet: true
-addons:
-  apt:
-    sources:
-      - llvm-toolchain-trusty-5.0
-      - key_url: 'http://apt.llvm.org/llvm-snapshot.gpg.key'
-    packages:
-      - clang-format-5.0
-env:
-  global:
-#    - ARDUINO_IDE_VERSION="1.8.10"
-     - PRETTYNAME="Adafruit FT6206 Arduino Library"
-# Optional, will default to "$TRAVIS_BUILD_DIR/Doxyfile"
-#    - DOXYFILE: $TRAVIS_BUILD_DIR/Doxyfile
+## Controlling Test Behavior
 
-before_install:
-   - source <(curl -SLs https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/install.sh)
-   - curl -SLs https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/run-clang-format.py > run-clang-format.py
+The `build_platform.py` script is used to test each `.ino` example in the repo for the
+selected build platforms. The `ALL_PLATFORMS` dictionary contains a listing of all
+available platforms. By default, `main_platforms` is used. Additionally, UF2 files
+of the compiled sketches can be generated for supported platforms. The behavior
+can be controlled using special hidden filenames. These are just empty files
+placed in the root folder:
 
-install:
-   - arduino --install-library "Adafruit ILI9341","Adafruit GFX Library"
+* `.YOUR_PLATFORM_HERE.test.skip` - Skip the specified platform. All others are tested.
+* `.YOUR_PLATFORM_HERE.test.only` - Test only the specfied platform. All others are skipped.
+* `.YOUR_PLATFORM_HERE.generate` - Generate UF2 of sketch for specified platform (if supported).
 
-script:
-   - python run-clang-format.py -r .
-   - build_main_platforms
-
-# Generate and deploy documentation
-after_success:
-  - source <(curl -SLs  https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/library_check.sh)
-  - source <(curl -SLs  https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/doxy_gen_and_deploy.sh)
-```
+Replace `YOUR_PLATFORM_HERE` in the name with exact text from `ALL_PLATFORMS`.
 
-**Choosing Arduino IDE version**
+### Examples
 
-You could use any version of IDE by setting `ARDUINO_IDE_VERSION` variable but we recommend keeping this variable unused because script gets updated and you then will not have to modify `.travis.yml` manually.
+* 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 generate UF2s for PyPortal, add a file named `.pyportal.generate`
 
-## Automated Example Verification Bash Functions
-
-`build_platform` will build all `.ino` examples in the repo using the passed platform. The platforms
-are defined in the `MAIN_PLATFORMS` and `AUX_PLATFORMS` associative arrays at the top of the script.
-
-All of the examples will be built with the platforms in `MAIN_PLATFORMS` if you call `build_main_platforms`,
-and `AUX_PLATFORMS` can be used to define other platforms that don't need to be verified for every repo.
-
-Build the examples using the platforms in the MAIN_PLATFORMS array:
-```yaml
-script:
-  - build_main_platforms
-```
+## Formatting Check with Clang
 
-Build the examples only using the trinket:
-```yaml
-script:
-  - build_platform trinket
+The `run-clang-format.py` script is used to run ClangFormat and check file formatting.
+See [the guide](https://learn.adafruit.com/the-well-automated-arduino-library/formatting-with-clang-format) 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:
 ```
-
-### Skipping Platforms
-
-If you would like to skip one of the main platforms when running `build_main_platforms`,
-you can commit a `.YOUR_PLATFORM_HERE.test.skip` file to the example sketch directory you
-wish to skip. You will need to use the array key defined in `MAIN_PLATFORMS` for the platform
-you wish to skip.
-
-For example, if you would like to skip the `esp8266` platform for an example
-in your lib called `blink.ino`, you would need to do something like this in your library repo:
-
-```sh
-$ touch examples/blink/.esp8266.test.skip
-$ git add -A
-$ git commit -a
-$ git push
+clang-format -i File_To_Format.cpp
 ```
 
-If you need an easy way to skip a platform, you can also add something like this to your `~/.bash_profile`:
-
-```sh
-function travis_skip()
-{
-
-  local platform_key=$1
-
-  # grab all pde and ino example sketches
-  local examples=$(find $PWD -name "*.pde" -o -name "*.ino")
-
-  # loop through example sketches
-  for example in $examples; do
-
-    # store the full path to the example's sketch directory
-    local example_dir=$(dirname $example)
+## Documentation with Doxygen
 
-    touch ${example_dir}/.${platform_key}.test.skip
-
-  done
-
-}
-```
-
-You will then be able to skip a platform for all examples by running the `travis_skip` function from your library repo.
-It will automatically add the `.YOUR_PLATFORM_HERE.test.skip` files to the examples.
-
-```sh
-$ travis_skip esp8266
-```
-
-## Using external libraries
-External libraries (which are not hosted by the Arduino library manager) can be installed using the following command:
-```sh
-- if [ ! -d "$HOME/arduino_ide/libraries/<Name>" ]; then git clone <URL> $HOME/arduino_ide/libraries/<Name>; fi
-```
-
-## Deploying compiled artifacts
-If you need to get hold of the compiled sketches of your project, in order to release them or forward them to an
-deployment pipeline, you can find them in the `$ARDUINO_HEX_DIR` directory. Specifically, if `Foo` is the name
-of your project, you are compiling for an `Arduino Mega` and the primary sketch is called `Foo.ino`, the flashable
-`.hex` files will be found inside `$ARDUINO_HEX_DIR/mega2560/Foo` as `Foo.ino.hex` and `Foo.ino.with_bootloader.hex`.
-Similarly for the rest of the platforms.
-
-For example, assuming you have a `Foo` project as outlined above, to create a release which includes the `.hex`
-files on GitHub, you could add this to your `.travis.yml` configuration:
-
-```yaml
-deploy:
-  provider: releases
-  api_key:
-    secure: YOUR_API_KEY_ENCRYPTED
-  file:
-    - $ARDUINO_HEX_DIR/mega2560/Foo/Foo.ino.hex
-    - $ARDUINO_HEX_DIR/mega2560/Foo/Foo.ino.with_bootloader.hex
-  skip_cleanup: true
-  on:
-    tags: true
-```
-
-## Running build_platforms.py locally
-1. Install arduino-cli from here: https://arduino.github.io/arduino-cli/installation/
-2. Download ci-arduino
-   * `git clone https://github.com/adafruit/ci-arduino`
-3. Put these lines at the end of your `.bashrc` or `.bash_profile` if you're on OSX. Make sure to fill in the path to where you installed ci-arduino and replacing USER with your username.
-   ```bash
-   alias test-platforms='python3 ~/path/to/ci-arduino/build_platform.py'
-   export HOME=/home/USER/
-   ```
-4. Run this at the top level of the library you want to test
-   ```bash
-   adafruit@adafruit:~/Adafruit_BMP183_Library$ export GITHUB_WORKSPACE=$(pwd)
-   ```
-5. Remove everything in test library, and re-create it
-   ```bash
-   adafruit@adafruit:~/Adafruit_BMP183_Library$ rm -rf ~/Arduino/libraries/Adafruit_Test_Library/; mkdir ~/Arduino/libraries/Adafruit_Test_Library
-   ```
-6. Still in the top-level directory of the library you'll be testing, copy the current library to Adafruit_Test_Library
-   ```bash
-   adafruit@adafruit:~/Adafruit_BMP183_Library$ cp * ~/Arduino/libraries/Adafruit_Test_Library/
-   ```
-7. Grep for build_platform.py in githubci.yml to find out what boards to test.
-   ```bash
-   adafruit@adafruit:~/Adafruit_BMP183_Library$ grep 'build_platform.py' .github/workflows/githubci.yml
-           run: python3 ci/build_platform.py main_platforms
-   ```
-8. Run test-platforms. This may take a while, and tests for some boards sometimes run orders of magnitude slower than tests for other boards.
-   ```bash
-   test-platforms main_platforms
-   ```
-   OR, if githubci.yml specified other boards, let's say the metro m0 and pyportal, you'd run this:
-   ```bash
-   test-platforms metro_m0 pyportal
-   ```
-
-Here's what that returns
-```bash
-adafruit@adafruit:~/Adafruit_BMP183_Library$ test-platforms main_platforms
-build dir: /home/dherrada/Adafruit_BMP183_Library
-
-########################################
-INSTALLING ARDUINO BOARDS
-########################################
-arduino-cli core update-index --additional-urls https://adafruit.github.io/arduino-board-index/package_adafruit_index.json,http://arduino.esp8266.com/stable/package_esp8266com_index.json,https://dl.espressif.com/dl/package_esp32_index.json,https://sandeepmistry.github.io/arduino-nRF5/package_nRF5_boards_index.json > /dev/null
-
-Installing Adafruit Unified Sensor
-arduino-cli lib install "Adafruit Unified Sensor" > /dev/null
-arduino-cli lib uninstall "Adafruit BMP183 Library"
-Library Adafruit BMP183 Library is not installed
-Libraries installed:  ['/home/adafruit/Arduino/libraries/Adafruit_VL53L0X', '/home/adafruit/Arduino/libraries/RTClib', '/home/adafruit/Arduino/libraries/Adafruit-RGB-LCD-Shield-Library', '/home/adafruit/Arduino/libraries/readme.txt', '/home/adafruit/Arduino/libraries/Adafruit_Test_Library', '/home/adafruit/Arduino/libraries/Adafruit_Unified_Sensor']
-  elif isinstance(platform, collections.Iterable):
-################################################################################
-SWITCHING TO arduino:avr:uno
-Installing arduino:avr ✓
-################################################################################
-	BMP183test.ino ✓
-################################################################################
-SWITCHING TO arduino:avr:leonardo
-Installing arduino:avr ✓
-################################################################################
-	BMP183test.ino ✓
-################################################################################
-SWITCHING TO arduino:avr:mega:cpu=atmega2560
-Installing arduino:avr ✓
-################################################################################
-	BMP183test.ino ✓
-################################################################################
-SWITCHING TO arduino:samd:arduino_zero_native
-Installing arduino:samd ✓
-################################################################################
-	BMP183test.ino ✓
-################################################################################
-SWITCHING TO esp8266:esp8266:huzzah:eesz=4M3M,xtal=80
-Installing esp8266:esp8266 ✓
-################################################################################
-	BMP183test.ino ✓
-################################################################################
-SWITCHING TO esp32:esp32:featheresp32:FlashFreq=80
-Installing esp32:esp32 ✓
-################################################################################
-  BMP183test.ino ✓
-################################################################################
-SWITCHING TO adafruit:samd:adafruit_metro_m4:speed=120
-Installing adafruit:samd ✓
-################################################################################
-	BMP183test.ino ✓
-################################################################################
-SWITCHING TO adafruit:nrf52:feather52840:softdevice=s140v6,debug=l0
-Installing adafruit:nrf52 ✓
-################################################################################
-	BMP183test.ino ✓
-```
+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 [the guide](https://learn.adafruit.com/the-well-automated-arduino-library/doxygen)
+for details on installing and running doxygen locally. The guide also has some
+[tips](https://learn.adafruit.com/the-well-automated-arduino-library/doxygen-tips)
+on basic usage of doxygen markup within your code.