How a CircuitPython build differs
--interpreter circuitpython is a flag rather than a second command because
everything around the interpreter is shared: the module names and
DEPENDENCIES.lock, the workspace links, the output layout and the build record.
What differs is one function, and these are its parts.
The checkout. CircuitPython is pinned in
DEPENDENCIES.locklike a toolchain and cloned intodeps/circuitpython, always our own clone, never a link to a sibling checkout. A build fetches only the submodules its target needs, with CircuitPython’s owntools/ci_fetch_deps.py(a board’s name, ortestsfor unix), and its build tools go indeps/circuitpython-venvfrom itsrequirements-dev.txt.The modules go in as
USER_C_MODULES, not a manifest. CircuitPython’spy/py.mkcarries MicroPython’sUSER_C_MODULESblock unchanged, so a module’smicropython.mkis the one our MicroPython builds read. CircuitPython freezes Python its own way (FROZEN_MPY_DIRS), so a module with nomicropython.mkand no Python to freeze is refused rather than left out quietly. Each module is handed to make through a link named for it, inusermods/in the build directory: make puts a module’s objects under a directory named like the module’s, and two worktrees checked out under the same branch name would otherwise share one.espressif brings its own ESP-IDF. CircuitPython’s espressif port builds with the ESP-IDF in
ports/espressif/esp-idf, not theesp-idfinDEPENDENCIES.lock. Before make, the build initialises that tree’s submodules shallowly (ESP-IDF’s CMake would otherwise clone them with their whole history), runs itsinstall.shfor the board’s chip (compilers go in~/.espressif, shared with any ESP-IDF of the same version) and puts ESP-IDF’s Python requirements indeps/circuitpython-venv.Our patches and boards go on first.
patches/circuitpython/*.patchare applied todeps/circuitpythonand eachboards/circuitpython/<port>/<board>is linked into the port’sboards/, once each; the build record lists the patches. The boards table lists the boards.A module can ask espressif for ESP-IDF components. CircuitPython’s espressif port builds and links a fixed list of ESP-IDF components, which leaves out the camera’s. With patch
0006-espressif-esp-idf-components-a-user-c-module-asks-for.patch, a module’smicropython.mkadds names toUSER_ESP_IDF_COMPONENTS(cameraif: the CSI controller, the ISP and the sensor drivers; jpegio and ppa: the P4’s JPEG engine and PPA; h264enc:esp_h264), and the make line’sUSER_ESP_IDF_COMPONENT_DIRSadds components ESP-IDF doesn’t ship. CircuitPython builds with the component manager off, so for cameraif the build fetchesesp_cam_sensor,esp_sccb_intfandcmake_utilitiesat theirDEPENDENCIES.lockversions intodeps/and passes them, andesp_h264the same way for h264enc. The DEV-KIT’s board sdkconfig enables the OV5647.mpy-cross is built first, on its own, for the same reason as on MicroPython (the
BUILD=trap).BUILD=is a short link. make is givenBUILD=build-<board>, a link in the port directory to our build directory: raspberrypi’s link step echoes every object path in one shell argument, and with a long absolute path in front of each it passes Linux’s 128 KB limit on one argument.
What a module sees
The banner is CircuitPython’s, unchanged: Adafruit CircuitPython <version> on <date>; <board name> with <chip>. A module that has to behave differently here
can test CIRCUITPY, which every CircuitPython port sets, unix included.
pygraphics also passes its own define from its micropython.mk, so it knows it
came in as a user C module and not through CircuitPython’s shared-bindings.
A module’s MP_QSTR_ names mean what they say, as on MicroPython.
CircuitPython’s own C reads an HTML entity name between underscores as a
character (MP_QSTR_UTF_hyphen_8 is "UTF-8"), and without patch
0011-qstrs-from-user-c-modules-keep-their-names.patch it read a user C
module’s names the same way, so LVGL’s set_style_image_recolor came out as
set_styleℑrecolor.
Two things a module’s C has to absorb on CircuitPython’s MCU ports. They append
-Werror warnings (sign-compare, float-equal, cast-align on atmel-samd;
float-equal, double-promotion, cast-align on espressif) after the module’s
flags, so a -Wno- meant for them goes on each object, where it lands last. And
atmel-samd has no C heap, so malloc() doesn’t link there; use m_malloc().