Sharing in a Bundle

We've created a couple library bundles for CircuitPython. The idea is that one can have all available libraries stored on the CircuitPython drive at once and then import them as needed. (They won't all fit into memory though.) This makes experimentation super easy because you only need to load everything once.

Another advantage of the bundle is that it makes it easy to find a list of all libraries. Even if you can't store all of the libraries on the drive, for example the Gemma M0 is only 64kb, the bundle makes it easy to copy over what you need when you need it.

It also helps CircuitPython devs keep track of libraries and update them as things change.

So, lets get our example library into the community bundle. To do so, we'll make a pull request on GitHub. First, lets fork the community bundle.

After the fork is done, the repo will look the same except the repo name will be different at the top left.

Next we'll clone the repo to our computer. See this guide for detailed instructions on cloning and submitting a pull request. Consider this a quickstart.

When cloning, make sure that you add --recursive to get all of the submodules too.

Adding the submodule to the Library Bundle

Now to add our library to the bundle we'll do:

git submodule add URL_TO_LIBRARY_INCLUDING.git libraries/SUBFOLDER/lowercase_library_name

You'll change the following:

  • URL_TO_LIBRARY_INCLUDING.git  - This will be the full URL to the library including the .git on the end. To get this URL, click on "Clone" in the GitHub repo, choose HTTPS, and copy that URL. Or you can copy the URL from the repo and add the .git.
    • Example: https://github.com/adafruit/Adafruit_CircuitPython_PyPortal.git
  • SUBFOLDER - The subfolder will be helpers or drivers. Choose which based on your library. Is it a driver? Choose drivers. Is it a helper? Choose helpers.
    • Example:  libraries/helpers/ or libraries/drivers/
  • lowercase_library_name - This is the name of your library, minus the Adafruit_CircuitPython_, in lowercase letters.
    • Example: pyportal

FULL EXAMPLE:

  • git submodule add https://github.com/adafruit/Adafruit_CircuitPython_PyPortal.git libraries/drivers/pyportal

And then we'll verify it worked by looking at the build log and versions file.

Updating the drivers.rst Library List

Before we submit a pull request with our new library, lets update the bundle documentation to include a link to the documentation for our library. Use whichever method you wish to open /docs/drivers.rst.

In drivers.rst, choose one of the categories to place your documentation link. The current categories are: Board-specific Helpers, Helper, Blinky, Displays, Real-time Clocks, Motion Sensors, Environmental Sensors, Light Sensors, Distance Sensors, Radio, IO Expansion, and Miscellaneous. Or, you can create a new category if that best describes your library.

With your category chosen, simply add a new line to that section using the reStructuredText hyperlink format. Easiest way, is to copy an existing line and edit it to change both the link text and the URL.

The reST markup language is indent-sensitive. Make sure you are properly aligned under the '.. toctree::' directive.

Next, lets do our normal commit and push process for a new branch.

Going to GitHub will show an easy prompt to create the pull request.

Follow that to see a differences. Make sure that at the top you are comparing against adafruit/CircuitPython_Community_Bundle as the base fork and your branch as the head fork. Make sure at the bottom left that maintainers can edit it (for simple fixes before they submit). Then click Create pull request at the bottom right.

This is the last step you need to do. One of the maintainers will come and respond on the pull request. Once they are happy with the request, it will be merged into the bundle and go out with the next release. It'll show up as purple once accepted.

This guide was first published on Jul 31, 2017. It was last updated on Jul 31, 2017. This page (Sharing in a Bundle) was last updated on Apr 16, 2019.