docs/examples.md

# 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):
    ```bash
    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.