Prerequisites

build-essential
cmake
git
libusb-1.0-0
ninja-build
python-is-python3
python3-pip
python3-venv

sudo apt update
sudo apt upgrade
sudo apt --assume-yes install \
  build-essential \
  cmake \
  git \
  libusb-1.0-0 \
  ninja-build \
  python-is-python3 \
  python3-pip \
  python3-venv

Clone CircuitPython repository

git clone https://github.com/adafruit/circuitpython.git cp-repo-espressif
cd cp-repo-espressif

Create a branch for your work and check it out

git checkout -b issue-myissue

Install the ESP-IDF submodule and the toolchains it requires

git submodule update --init --remote ports/espressif/esp-idf
cd ports/espressif
esp-idf/install.sh

If you are running the fish shell, use esp-idf/install.fish instead.

Install Python packages required for building CircuitPython

NB: There are version conflicts between the ESP-IDF and CircuitPython package requirements. We source the esp-idf/export.sh script (or export.fish for fish shell) to setup access to tools installed by esp-idf/install.sh and enter ESP-IDF's virtual environment. We run CircuitPython Python's package install to install CircuitPython required packages into ESP-IDF's virtual environment. Finally, we re-run esp-idf/install.sh to resolve the Python package version conflicts in favor of ESP-IDF.

source esp-idf/export.sh
cd ../..
pip install --upgrade -r requirements-dev.txt
pip install --upgrade -r requirements-doc.txt
cd ports/espressif
esp-idf/install.sh

Install submodules required to build CircuitPython for an Espressif board

make fetch-port-submodules

Install `pre-commit` and build `mpy-cross`

cd ../..
pre-commit install
make -C mpy-cross

Build CircuitPython for your Espressif board

cd ports/espressif
make BOARD=adafruit_feather_esp32s3_4mbflash_2mbpsram

NB: The first time you build an Espressif board, it will pull in an additional boatload of submodules. Some of these submodules are quite large and may take several minutes to load.

NB: You will see this warning when you build:

/home/rabeles/Development/cp-development/cp-repo-espressif/ports/espressif/esp-idf/components/esp_psram/esp_psram.c: In function 'esp_psram_get_address':
/home/rabeles/Development/cp-development/cp-repo-espressif/ports/espressif/esp-idf/components/esp_psram/esp_psram.c:457:62: warning: returning 'intptr_t' {aka 'int'} from a function with return type 'uint8_t *' {aka 'unsigned char *'} makes pointer from integer without a cast [-Wint-conversion]
  457 |     return s_psram_ctx.mapped_regions[PSRAM_MEM_8BIT_ALIGNED].vaddr_start;
      |            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~

It is harmless and can be safely ignored.

Re-using Your Espressif CircuitPython Repository

Whenever you wish to use your Espressif CircuitPython repository in a new shell, be sure to do the following before attempting to build:

cd ports/espressif
source esp-idf/export.sh

This will re-establish the proper environment variables and the ESP-IDF virtual environment required for building CircuitPython.

eightycc/build-espressif-circuitpython.md