From 82da39b74c84893a3d747f926de2fe2df2c6e400 Mon Sep 17 00:00:00 2001 From: Melissa LeBlanc-Williams Date: Thu, 19 Dec 2019 14:32:48 -0800 Subject: [PATCH] Initial Commit --- .gitignore | 12 +++ LICENSE | 21 ++++++ PULL_REQUEST_TEMPLATE.md | 26 +++++++ README.md | 156 ++++++++++++++++++++++++++++++++++++++- install.sh | 15 ++++ workflows/githubci.yml | 19 +++++ 6 files changed, 247 insertions(+), 2 deletions(-) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 PULL_REQUEST_TEMPLATE.md create mode 100755 install.sh create mode 100644 workflows/githubci.yml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cc1a9c8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +*.mpy +.idea +__pycache__ +_build +*.pyc +.env +build* +bundles +*.DS_Store +.eggs +dist +**/*.egg-info diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..7806e61 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2019 Adafruit for Adafruit Industries + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..7b641eb --- /dev/null +++ b/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,26 @@ +Thank you for creating a pull request to contribute to Adafruit's GitHub code! +Before you open the request please review the following guidelines and tips to +help it be more easily integrated: + +- **Describe the scope of your change--i.e. what the change does and what parts + of the code were modified.** This will help us understand any risks of integrating + the code. + +- **Describe any known limitations with your change.** For example if the change + doesn't apply to a supported platform of the library please mention it. + +- **Please run any tests or examples that can exercise your modified code.** We + strive to not break users of the code and running tests/examples helps with this + process. + +Thank you again for contributing! We will try to test and integrate the change +as soon as we can, but be aware we have many GitHub repositories to manage and +can't immediately respond to every request. There is no need to bump or check in +on a pull request (it will clutter the discussion of the request). + +Also don't be worried if the request is closed or not integrated--sometimes the +priorities of Adafruit's GitHub code (education, ease of use) might not match the +priorities of the pull request. Don't fret, the open source community thrives on +forks and GitHub makes it easy to keep your changes in a forked repo. + +After reviewing the guidelines above you can delete this text from the pull request. diff --git a/README.md b/README.md index a98c039..6207977 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,154 @@ -# actions-ci-circuitpython-libs -A script that will install all of the common dependencies for testing CircuitPython library builds using Github Actions or Travis CI +# Actions CI CircuitPython Init Script + +The purpose of this repo is to create a centrally managed dependency +install script for all Adafruit CircuitPython Library Github Actions and Travis CI configs. +This will allow us to easily update the install steps without +having to manually or programatically update 100+ `.travis.yml` files or github workflows. + +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/ + +## Adding to Github Actions Workflows + +This section should be added. + +## Adding to Travis CI Configs + +You will need to source the script in the `before_install` step of your +`.travis.yml` file. + +```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` envionrment variable to a comma-seperated list of platforms. + +**Example `.travis.yml`:** +```yaml +language: c +sudo: false +cache: + directories: + - ~/arduino_ide + - ~/.arduino15/packages/ +git: + depth: false + quiet: true +env: + global: + # You can uncomment this to explicitly choose an (old) version of the Arduino IDE + #- ARDUINO_IDE_VERSION="1.8.10" +before_install: + - source <(curl -SLs https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/install.sh) +install: + # Note that every library should be installed in a seperate command + - arduino --install-library "Adafruit SleepyDog Library" + - arduino --install-library "Adafruit FONA Library" +script: + - build_main_platforms +notifications: + email: + on_success: change + on_failure: change +``` + +**Choosing Arduino IDE version** + +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. + +## 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 +``` + +Build the examples only using the trinket: +```yaml +script: + - build_platform trinket +``` + +### 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 +``` + +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) + + 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/" ]; then git clone $HOME/arduino_ide/libraries/; 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 +``` diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..00d7bbf --- /dev/null +++ b/install.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash + +# we need bash 4 for associative arrays +if [ "${BASH_VERSION%%[^0-9]*}" -lt "4" ]; then + echo "BASH VERSION < 4: ${BASH_VERSION}" >&2 + exit 1 +fi + +#This condition is to avoid reruning install when build argument is passed +if [[ $# -eq 0 ]] ; then +# define colors +GRAY='\033[1;30m'; RED='\033[0;31m'; LRED='\033[1;31m'; GREEN='\033[0;32m'; LGREEN='\033[1;32m'; ORANGE='\033[0;33m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; LBLUE='\033[1;34m'; PURPLE='\033$ + +# Install libusb +sudo apt-get install libudev-dev libusb-1.0 diff --git a/workflows/githubci.yml b/workflows/githubci.yml new file mode 100644 index 0000000..35513a1 --- /dev/null +++ b/workflows/githubci.yml @@ -0,0 +1,19 @@ +name: Github Arduino Library CI + +on: [push] + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-python@v1 + with: + python-version: '3.x' # Version range or exact version of a Python version to use, using semvers version range syntax. + architecture: 'x64' # optional x64 or x86. Defaults to x64 if not specified + - name: pre-install + run: | + source install.sh +