Build CircuitPython

Fetch the Code to Build

Once your build tools are installed, fetch the CircuitPython source code from its GitHub repository ("repo") and also fetch the git "submodules" it needs. The submodules are extra code that you need that's stored in other repos.

In the commands below, you're cloning from Adafruit's CircuitPython repo. But if you want to make changes, you might want to "fork" that repo on GitHub to make a copy for yourself, and clone from there.

Download: file
git clone https://github.com/adafruit/circuitpython.git
cd circuitpython
git submodule sync
git submodule update --init --recursive

Build mpy-cross

Build the mpy-cross compiler first, which compiles Circuitpython .py files into .mpy files. It's needed to include library code in certain boards.

Download: file
make -C mpy-cross

Build CircuitPython

Now you're all set to build CircuitPython. If you're in the master branch of the repo, you'll be building the latest version (3.0 as of this writing). Choose which board you want to build for. The boards available are all the subdirectories in ports/atmel-samd/boards/.

Download: file
cd ports/atmel-samd
make BOARD=circuitplayground_express

If you want to build the 2.x version of CircuitPython, you need to check out that branch, and build in a slightly different location.

Download: file
git checkout 2.x
git submodule sync
git submodule update --init --recursive
cd atmel-samd
make BOARD=circuitplayground_express

In 4.x we've introduced translated versions of CircuitPython. By default the en_US version will be built. To build for a different language supply a TRANSLATION argument.

Download: file
cd ports/atmel-samd
make BOARD=circuitplayground_express TRANSLATION=es

Run your build!

When you've successfully built, you'll see output like:

Download: file
Create build-circuitplayground_express/firmware.bin
Create build-circuitplayground_express/firmware.uf2
python2 ../../tools/uf2/utils/uf2conv.py -b 0x2000 -c -o build-circuitplayground_express/firmware.uf2 build-circuitplayground_express/firmware.bin
Converting to uf2, output size: 485888, start address: 0x2000
Wrote 485888 bytes to build-circuitplayground_express/firmware.uf2.

Copy firmware.uf2 to your board the same way you'd update CircuitPython: Double-click to get the BOOT drive, and then just copy the .uf2 file:

Download: file
# Double-click the reset button, then:
cp build-circuitplayground_express/firmware.uf2 /media/yourname/CPLAYBOOT

The board will restart, and your build will start running.

If you're using a board without a UF2 bootloader, you'll need to use bossac and the firmware.bin file, not the .uf2 file. Detailed instructions are here.

When to make clean

After you make changes to code, normally just doing make BOARD=... will be sufficient. The changed files will be recompiled and CircuitPython will be rebuilt.

However, there are some circumstance where you must do:

Download: file
make clean BOARD=...

If you have changed the #include file structure in certain ways, or if you have defined QSTR's (a way of defining constants strings in the CircuitPython source), then you must make clean before rebuilding. If you're not sure, it's always safe to make clean and then make. It might take a little longer to build, but you'll be sure it was rebuilt properly.

Updating Your Repo

When there are changes in the GitHub repo, you might want to fetch those and then rebuild. Just "pull" the new code (assuming you haven't made changes yourself), update the submodules if necessary, and rebuild:

Download: file
git pull
git submodule sync
git submodule update --init --recursive
# Then make again.

Those are the basics. There's a lot more to know about how to keep your forked repo up to date, merge "upstream" (Adafruit's) changes into your code, etc. We'll be writing all that up later.

This guide was first published on Apr 26, 2018. It was last updated on Apr 26, 2018. This page (Build CircuitPython) was last updated on Dec 06, 2018.