`phpflash build`

build compiles the firmware for the project in the current directory. It reads php-esp32.config.toml, works out which extensions to compile and which fetch scripts they need, resolves the toolchain and PHP version, and drives ESP-IDF into an isolated build tree under the project's own build/. On success the flashable images sit in build/, ready for phpflash flash.

phpflash build

What it does

1. 01

   Load the config.

   Reads php-esp32.config.toml (overlaying php-esp32.config.local.toml if present). Errors out with a pointer to phpflash init when there is no config here.

2. 02

   Resolve toolchain and version.

   Finds ESP-IDF and php-esp32 by the usual precedence (flag → config → env → default). The PHP language version is the project's [php] version if it pins one, otherwise the php-esp32 repo default; a version that is not installed is rejected with the list of what is available.

3. 03

   Compute the flags.

   Turns the enabled extensions into a deterministic -D<flag>=ON/OFF list from the manifest, and collects the fetch scripts those extensions need.

4. 04

   Fetch, then build.

   Runs each fetch script (oniguruma, SQLite, OpenSSL, as needed), then invokes idf.py into build/compiled.

5. 05

   Collect the images.

   Copies the flashable .bin files up from the build tree into build/.

The idf.py invocation it drives, with the deterministic flag list:

idf.py -B ./build/compiled -DSDKCONFIG=./build/sdkconfig \
       -DBOARD=<board> -DPHP_VERSION=<version> -DIDF_TARGET=<target> \
       -D<PHP_EXT_*>=ON/OFF ... build

The build tree

The build tree and its generated sdkconfig live under the project's own build/ (build/compiled for the full ESP-IDF tree, build/sdkconfig for the config). Because both are per project, several projects can share one php-esp32 install with isolated, side-by-side builds, and a build never depends on what a shared directory held before.

my-project/
├── php-esp32.config.toml
├── project-src/
└── build/
    ├── compiled/               the full ESP-IDF build tree
    ├── sdkconfig               the generated config (per project)
    ├── php-esp32.bin           the app image
    ├── bootloader.bin
    └── partition-table.bin

On success the app image (the .bin at the build root), bootloader.bin (from compiled/bootloader/) and partition-table.bin (from compiled/partition_table/) are copied up into build/. Those three are what phpflash flash writes.

Target pinning

build pins the ESP-IDF target from the board's family — -DIDF_TARGET=esp32p4 for a P4 board, esp32s3 for an S3 board — rather than letting idf.py infer it. Without the pin, idf.py guesses the target from any stray in-source sdkconfig, which silently builds the wrong architecture when that file is left over from a different family (an esp32p4 sdkconfig while building an S3 board, say). Pinning makes the target follow the configured board, not whatever config happens to be lying around.

microSD versus embedded source

The project's storage_type decides where the PHP source lives, and build encodes that in two flags:

build also translates other config into flags automatically: a non-default [php] entry becomes -DPHP_ENTRY (for a framework's nested front controller), a web-server project's [web-server] init becomes -DPHP_WEB_INIT, a firmware/exts/ directory with a custom extension becomes -DPHP_PROJECT_EXTS_DIR, a project .env is baked in, a full-openssl TLS project ships the host's CA bundle, and [network] dns / [board] cpu_freq_mhz / [store] size_kb each get their own define.

Flags

build takes only the two path overrides; everything else comes from the config.

Guardrails

After a successful build, write it to the board with phpflash flash.