Menú
Guidelines for building Matter examples and running tests using Podman with the vscode image in a non-interactive environment.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | podman-vscode-build |
| description | Guidelines for building Matter examples and running tests using Podman with the vscode image in a non-interactive environment. |
This skill provides guidelines and instructions for configuring, launching, and
executing build/test commands within a Podman container using the official
ghcr.io/project-chip/chip-build-vscode image.
Podman runs rootless, which avoids file ownership complications (where files generated in the container are owned by root on the host) commonly encountered with Docker.
Before launching Podman, you must configure storage to avoid namespace and user limit errors (e.g., insufficient UIDs or GIDs in the user namespace).
Edit or create $HOME/.config/containers/storage.conf to include:
[storage]
driver = "overlay"
[storage.options]
ignore_chown_errors = "true"
If you previously attempted to use Podman without this setting, you may need to reset the storage.
[!CAUTION] Running
podman system resetwill delete all existing Podman containers, images, and volumes.
podman system reset
graphDriverName is overlay (instead of vfs):
podman info | grep graphDriverName
The correct tag for ghcr.io/project-chip/chip-build-vscode changes as
dependencies are updated. To find the tag currently used in CI:
.github/workflows/ (such as tests.yaml
or build.yaml) or the cloudbuild configurations under
integrations/cloudbuild/ (such as chef.yaml).ghcr.io/project-chip/chip-build-vscode:<TAG> to identify the correct
version tag (e.g., 200).To start a persistent vscode container in the background:
podman run -dt --cap-add=SYS_PTRACE --name bld_vscode \
--volume /path/to/connectedhomeip:/workspace \
ghcr.io/project-chip/chip-build-vscode:<TAG> \
/bin/sh
Replace /path/to/connectedhomeip with the absolute path to your local
repository checkout, and <TAG> with the version tag found in step 2.
Since agents run in a non-interactive environment, do NOT use interactive
flags like -it (e.g. podman exec -it ...). Instead, execute commands
directly or script them.
Because podman exec does not load login shell initialization scripts, the
Pigweed build environment is not activated by default. Sourcing the
environment activation script is required prior to compiling.
scripts/bootstrap.sh if this is the first time setup
inside the container, or if packages or submodules have changed.scripts/activate.sh for subsequent runs.Run the commands in a single subshell using bash -c:
podman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target <target> build"
By default, running bootstrap.sh inside the container installs python
requirements for host and Zephyr builds. To enable building for other specific
embedded platforms (which downloads/configures additional pip dependencies),
pass the platform names to the -p parameter:
podman exec -w /workspace bld_vscode bash -c "source scripts/bootstrap.sh -p esp32,nrfconnect,silabs,telink"
Supported platform identifiers include: esp32, nrfconnect, silabs,
telink, bouffalolab, mbed, ti, zephyr.
If building for the ESP32 platform, the ESP-IDF toolchain Python requirements inside the container must also be explicitly set up. Run the following command inside the container after bootstrapping:
podman exec -w /workspace bld_vscode bash -c "/opt/espressif/esp-idf/install.sh"
If compiling for Nordic nRF Connect targets, the pre-installed SDK files must be synchronized and updated before building. Discard local template modifications first, then run the update script inside the container:
podman exec -w /workspace bld_vscode git -C /opt/NordicSemiconductor/nrfconnect/zephyr checkout -- zephyr-env.sh
podman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && python3 scripts/setup/nrfconnect/update_ncs.py --update --shallow"
Using Podman with the official vscode image is particularly valuable when compiling for embedded or cross-compiled targets, as the image pre-packages all required toolchains and compilers.
Here are examples of compiling Matter applications (e.g., all-devices-app or
all-clusters-app) for various platforms and where the executables/artifacts
are generated:
linux-arm64-all-devices-boringssl-no-ble-clangpodman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target linux-arm64-all-devices-boringssl-no-ble-clang build"
<checkout_root>/out/linux-arm64-all-devices-boringssl-no-ble-clang/all-devices-appesp32-devkitc-all-devicespodman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target esp32-devkitc-all-devices build"
<checkout_root>/out/esp32-devkitc-all-devices/all-devices-app.elf and
all-devices-app.binefr32-brd4187c-all-devicespodman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target efr32-brd4187c-all-devices build"
<checkout_root>/out/efr32-brd4187c-all-devices/matter-silabs-all-devices-example.out
(and .hex / .s37)Note: Building with the Zephyr SDK toolchain requires setting
ZEPHYR_TOOLCHAIN_VARIANT=zephyr explicitly.
nrf-nrf52840dk-all-clusterspodman exec -w /workspace bld_vscode bash -c "export ZEPHYR_TOOLCHAIN_VARIANT=zephyr && source scripts/activate.sh && ./scripts/build/build_examples.py --target nrf-nrf52840dk-all-clusters build"
<checkout_root>/out/nrf-nrf52840dk-all-clusters/merged.hex (contains both
bootloader and app) and zephyr/zephyr.elftelink-tlsr9518adk80d-all-devicespodman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target telink-tlsr9518adk80d-all-devices build"
<checkout_root>/out/telink-tlsr9518adk80d-all-devices/zephyr/zephyr.binBecause the repository root is mounted as a volume
(--volume /path/to/connectedhomeip:/workspace), any build outputs written to
/workspace/out/ inside the container are immediately accessible on the
host filesystem at <checkout_root>/out/.
There is no need to copy binaries using podman cp. You can access or run
the built binary directly from your host repository checkout:
cp out/<target>/<binary_name> /path/to/destination
Guidelines for comparing binary (ELF) sizes using Rust-based tooling (elf-bloat and asm-annotate) across various platforms to analyze the impact of code changes on footprint.
Guidelines for building Matter examples and chip-tool, and testing examples using chip-tool.
Essential guidelines instructing AI agents on how to incrementally discover, read, and consult top-level monorepo documentation and example-specific reference guides before altering code or executing test harnesses.
Guidelines for generating clear, concise, and objective GitHub Pull Request descriptions.
Guidelines and instructions for building prerequisite example applications and running python-based integration and certification tests located in `src/python_testing/`. Use this skill to run important regression tests during developement or, when building new example apps, or when there is a need to execute python test scripts or "certification test scripts" or mentions of run_python_test.py and local.py.
Guidelines and common jq/grep/awk queries for investigating ZAP (.zap) and Matter (.matter) files to understand endpoints, clusters, attributes, and commands.