Welcome to CircuitPython!
This document is a quick-start guide only.
Detailed guides on how to build CircuitPython can be found in the Adafruit Learn system at https://learn.adafruit.com/building-circuitpython/
Please ensure you set up your build environment appropriately, as per the guide. You will need:
Windows Subsystem for Linux (WSL): https://learn.adafruit.com/building-circuitpython/windows-subsystem-for-linux
This project has a bunch of git submodules. You will need to update them regularly.
In the root folder of the CircuitPython repository, execute the following:
Required Python Packages¶
Failing to install these will prevent from properly building.
pip3 install -r requirements-dev.txt
If you run into an error installing minify_html, you may need to install
As part of the build process, mpy-cross is needed to compile .py files into .mpy files. To compile (or recompile) mpy-cross:
make -C mpy-cross
There a number of ports of CircuitPython! To build for your board, change to the appropriate ports directory and build.
cd ports/atmel-samd make BOARD=circuitplayground_express cd ports/nrf make BOARD=circuitplayground_bluefruit
If you aren’t sure what boards exist, have a peek in the boards subdirectory of your port.
If you have a fast computer with many cores, consider adding
-j to your build flags, such as
a 6-core 12-thread machine.
If you are working on changes to the core language, you might find it useful to run the test suite.
The test suite in the top level
tests directory. It needs the unix port to run.
cd ports/unix make axtls make micropython
Then you can run the test suite:
cd ../../tests ./run-tests.py
A successful run will say something like
676 tests performed (19129 individual testcases) 676 tests passed 30 tests skipped: buffered_writer builtin_help builtin_range_binop class_delattr_setattr cmd_parsetree extra_coverage framebuf1 framebuf16 framebuf2 framebuf4 framebuf8 framebuf_subclass mpy_invalid namedtuple_asdict non_compliant resource_stream schedule sys_getsizeof urandom_extra ure_groups ure_span ure_sub ure_sub_unmatched vfs_basic vfs_fat_fileio1 vfs_fat_fileio2 vfs_fat_more vfs_fat_oldproto vfs_fat_ramdisk vfs_userfs
The easiest way to debug CircuitPython on hardware is with a JLink device, JLinkGDBServer, and an appropriate GDB. Instructions can be found at https://learn.adafruit.com/debugging-the-samd21-with-gdb
If using JLink, you’ll need both the
JLinkGDBServer -if SWD -device ATSAMD51J19 arm-none-eabi-gdb build-metro_m4_express/firmware.elf -iex "target extended-remote :2331"
If your port/build includes
arm-none-eabi-gdb-py, consider using it instead, as it can be used for better register
debugging with https://github.com/bnahill/PyCortexMDebug
Code Quality Checks¶
We apply code quality checks using pre-commit. Install pre-commit once per system with
python3 -mpip install pre-commit
Activate it once per git clone with
Pre-commit also requires some additional programs to be installed through your package manager:
Standard Unix tools such as make, find, etc
The gettext package, any modern version
uncrustify version 0.71 (0.72 is also tested)
Each time you create a git commit, the pre-commit quality checks will be run. You can also run them e.g., with
pre-commit run foo.c or
pre-commit run --all to run on all files whether modified or not.
Some pre-commit quality checks require your active attention to resolve, others (such as the formatting checks of uncrustify) are made automatically and must simply be incorporated into your code changes by committing them.