php-baremetal/php-esp32-sdk

SDK First-party

The esp32 SDK: boards, the PHP build recipe, runtimes, storages and the ESP-IDF toolchain for ESP32-P4 and ESP32-S3. phpbm downloads and drives it.

SDK · Reference

Toolchain

The esp32 SDK builds with ESP-IDF v6.1 for the ESP32-S3 and the ESP32-P4. What phpbm toolchain:install does for it, where things go, and the variables and path rules that matter.

The toolchain of the esp32 SDK is ESP-IDF v6.1 (v6.1 and any v6.1.x), with its compiler, CMake, Ninja and Python environment, for the targets esp32s3 and esp32p4. The general behaviour of phpbm toolchain:install is in the phpbm toolchains guide; this page adds what is specific to this SDK.

What toolchain:install does

Run inside a project, phpbm toolchain:install does three things, each only when it is missing:

  1. Clones ESP-IDF v6.1 from https://github.com/espressif/esp-idf.git, shallow and with its submodules, into ~/.phpbm/toolchains/esp32/esp-idf-v6.1. An incomplete or wrong-version checkout in that folder is deleted first.
  2. Installs the ESP-IDF tools with idf_tools.py (required, cmake and ninja) for esp32s3,esp32p4, into ~/.phpbm/toolchains/esp32/tools.
  3. Creates the ESP-IDF Python environment, install-python-env, in ~/.phpbm/toolchains/esp32/tools/python_env/idf6.1_py<version>_env.

It needs git and a Python 3.10 or newer on the machine. A failed step stops with its last output line; run the command again to resume.

phpbm build, flash, sync and monitor run through that environment: the build calls idf.py, the flash calls esptool at 460800 baud, the monitor runs esp_idf_monitor at 115200 baud. Each activates the toolchain first and stops with the reason when it is missing.

Python

phpbm looks for a Python 3.10 or newer in this order and takes the first that answers:

System Candidates
any the command in PHPBM_PYTHON
Linux and macOS python3, python3.13, python3.12, python3.11, python3.10, python
Windows py -3, python

Without one the build stops with ESP-IDF needs Python 3.10 or newer. On Windows install Python from python.org and tick "Add python.exe to PATH".

Where things are

What Default Moved by
phpbm home ~/.phpbm (%USERPROFILE%\.phpbm on Windows) PHPBM_HOME
ESP-IDF <home>/toolchains/esp32/esp-idf-v6.1 PHPBM_ESP32_IDF_PATH
ESP-IDF tools and Python environment <home>/toolchains/esp32/tools PHPBM_ESP32_IDF_TOOLS_PATH or IDF_TOOLS_PATH, with PHPBM_ESP32_IDF_PATH
Build of a project .phpbm/build

Environment variables

Variable Meaning
PHPBM_PYTHON The Python to use, tried before the others.
PHPBM_ESP32_IDF_PATH An ESP-IDF v6.1 that you manage yourself. phpbm uses it in place and never installs into it: install its tools there with its own tools/idf_tools.py install and install-python-env. phpbm toolchain:install refuses with this variable set.
PHPBM_ESP32_IDF_TOOLS_PATH With PHPBM_ESP32_IDF_PATH: where that ESP-IDF's tools live.
IDF_TOOLS_PATH Read when the previous one is not set. With neither, the tools are in ~/.espressif (%USERPROFILE%\.espressif on Windows).
PHPBM_HOME Where phpbm keeps SDKs, toolchains and cache; set it to a short path without spaces on Windows.

Whichever ESP-IDF is used, phpbm sets IDF_PATH, IDF_TOOLS_PATH and IDF_PYTHON_ENV_PATH for the commands it runs, so your shell does not need export.sh.

Version check

phpbm reads the version from components/esp_common/include/esp_idf_version.h of the ESP-IDF in use. Only v6.1 and v6.1.x are accepted. Otherwise the toolchain counts as not installed:

  • ESP-IDF not found in <path>: there is no ESP-IDF there;
  • ESP-IDF <version> in <path>, the esp32 sdk needs v6.1: another version is there.

With the managed toolchain, phpbm toolchain:install replaces a wrong version; with PHPBM_ESP32_IDF_PATH you replace it yourself. A change of ESP-IDF path or version also starts the next build from scratch.

Path rules

Warning Windows: no spaces, no non-ASCII

ESP-IDF cannot work from a path with spaces or non-ASCII characters. On Windows phpbm checks the ESP-IDF path, the tools path, the project folder, its .phpbm/build folder and the SDK folder, and stops with ESP-IDF cannot work from a path with spaces or non-ASCII characters (<path>). Move the project, or set PHPBM_HOME to a path without them.

On every system the project, the SDK, the PHP sources, the build folder and the packages must not contain ; or =: the build passes them through CMake lists and -ffile-prefix-map. The error is <what> (<path>) contains ';' or '=', which the build cannot handle: move it to a path without them.

Last updated 2026-11-15 · v2.0.x Edit on GitHub Report issue