Adafruit CircuitPython Build Tools

This repo contains build scripts used to build the Adafruit CircuitPython bundle, CircuitPython Community bundle and individual library release zips. Its focused on Travis CI support but will also work locally when a gcc compiler is present.

The pip package includes mpy-crosses that run on Travis. When building locally, the scripts will automatically clone the CircuitPython repo and attempt to build mpy-crosses. You'll need some version of gcc for this to work.

Setting up libraries

These build tools are intended for use with Travis CI to automatically build .mpy files and zip them up for CircuitPython when a new tagged release is created. To add support to a repo you need to:

1. Use the CircuitPython cookiecutter to generate .travis.yml.

2. For adafruit repositories, simply give the CircuitPythonLibrarians team write access to the repo and Adabot will do the rest.

   Otherwise, go to travis-ci.org and find the repository (it needs to be setup to access your github account, and your github account needs access to write to the repo). Flip the 'ON' switch on for Travis and the repo, see the Travis docs for more details: https://docs.travis-ci.com/user/getting-started/

3. Get a GitHub 'personal access token' which has at least 'public_repo' or 'repo' scope: https://help.github.com/articles/creating-an-access-token-for-command-line-use/ Keep this token safe and secure! Anyone with the token will be able to access and write to your GitHub repositories. Travis will use the token to attach the .mpy files to the release.

4. In the Travis CI settings for the repository that was enabled find the environment variable editing page: https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings Add an environment variable named GITHUB_TOKEN and set it to the value of the GitHub personal access token above. Keep 'Display value in build log' flipped off.

5. That's it! Tag a release and Travis should go to work to add zipped .mpy files to the release. It takes about a 2-3 minutes for a worker to spin up, build mpy-cross, and add the binaries to the release.

The bundle build will produce one zip file for every major CircuitPython release supported containing compatible mpy files and a zip with human readable py files. It'll also "release" a z-build_tools_version-x.x.x.ignore file that will be used to determine when a library needs new release files because the build tools themselves changed, such as when a new major CircuitPython release happens.

Building libraries locally

To build libraries built with the build tools you'll need to install the circuitpython-build-tools package.

python3 -m venv .env
source .env/bin/activate
pip install circuitpython-build-tools
circuitpython-build-bundles --filename_prefix <output file prefix> --library_location .

When making changes to circuitpython-build-tools itself, you can test your changes locally like so:

cd circuitpython-build-tools # this will be specific to your storage location
python3 -m venv .env
source .env/bin/activate
pip install -e .  # '-e' is pip's "development" install feature
circuitpython-build-bundles --filename_prefix <output file prefix> --library_location <library location>

Contributing

Contributions are welcome! Please read our [Code of Conduct] (https://github.com/adafruit/Adafruit_CircuitPython_adabot/blob/master/CODE_OF_CONDUCT.md) before contributing to help this project stay welcoming.