Examples and Integration Tests

The zephyr-bazel repository contains an examples/ directory that serves a dual purpose: it provides pristine, board-agnostic templates for end users to learn how to structure their applications, and it houses the regression test suite for the zephyr-bazel build system.

Examples Directory Structure

The examples/ directory is structured as an independent Bazel workspace with its own MODULE.bazel file. This workspace consumes the local zephyr-bazel module using a local_path_override.

Each subdirectory under examples/ (e.g., hello_bazel, sysbuild_app, nrf52) is a standalone, pristine example of a Zephyr application.

Board-Agnostic Application Rules

A key design principle in zephyr is that application BUILD.bazel files should remain completely board-agnostic. They define what the application is (sources, libraries, Kconfig options), but they do not contain custom, board-specific flashing, running, or verification targets.

Target-specific details (like which debugger tool to use or which memory layout checks to apply) are delegated to the board platform definition in the repository overlay.

Distinction between Examples and Tests

To maintain pristine templates for end users while ensuring robust CI coverage for maintainers, the repository makes a clear distinction between Examples and Build-System Integration Tests.

Examples (End-User Focus)

  • Location: examples/<app_name>/
  • Purpose: Demonstrate how to use zephyr_app, zephyr_cc_library, and zephyr_sysbuild rules in a standard Zephyr project layout (main.cc, prj.conf, app.overlay).
  • Workflow: End users interact with these using standard Bazel commands and the unified hardware runner mechanism (if applicable):
    examples/hello_bazel $ bazelisk build :hello_bazel \
    --platforms=@zephyr//boards/raspberrypi/rpi_pico:rp2040
examples/hello_bazel $ bazelisk run :hello_bazel \
    --platforms=@zephyr//boards/raspberrypi/rpi_pico:rp2040 -- --monitor

Integration Tests (Build-System Maintainer Focus)

  • Location: examples/tests/
  • Purpose: Regression testing for the build system infrastructure, including SoC-specific ELF memory layout validation (RP2xxx bootloader requirements), multi-image configuration generation (sysbuild), and repository lockfile portability checks.
  • Workflow: Run by CI or maintainers to verify the toolchain, linker scripts, and Bzlmod integration across multiple platforms. Targets in this package often use platform_data to test multiple SoC configurations in a single invocation without changing the global Bazel context.

Summary for Users

  • If you are learning how to set up a new Zephyr-Bazel project, look at the minimal, clean BUILD.bazel files inside examples/hello_bazel or examples/nrf52.
  • If you are interested in how the build system statically validates generated binaries, or if you are developing new features for zephyr-bazel, look at the implementation and test targets inside the examples/tests package.