tan-cli 0.7.0__py3-none-any.whl

tan/planner/project_emit/hw_info.py

@@ -0,0 +1,221 @@
+# SPDX-License-Identifier: Apache-2.0
+"""C header emission for `<alp/hw_info.h>` (`--emit hw-info-h`).
+
+RELOCATED (was alp-sdk `scripts/alp_project_emit/hw_info.py`) -- see this
+package's `__init__.py` for the move's contract.
+
+alp-sdk#1964 (tan-cli#1156 hand-port) made this emitter a second reader of
+`hw-revisions.yaml`, through `board_designator()`: `ALP_HW_BUILD_SOM_HW_REV`
+now carries the COMPOSED `<board_datecode>-<hw_rev>` form (`"2626-r2"`), not
+the bare revision key, matching what `scripts/program_eeprom.py` writes into
+the manifest and what the boot banner compares the live EEPROM read
+against. The bare key is untouched everywhere it is a LOOKUP key
+(board.yaml, `family_revision_known()`, `pad_route_overrides`) -- only this
+identity/compare surface composes. A family that declares no
+`board_datecode:` is unaffected (`board_designator` returns the bare key).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..sdk_compat import board_designator, load_family_table
+from ..som_metadata import _sku_family
+
+
+# ---------------------------------------------------------------------
+# C header emission (build-time identifiers for <alp/hw_info.h>)
+# ---------------------------------------------------------------------
+#
+# Produces the auto-generated `<alp_hw_info_build.h>` companion to
+# `<alp/hw_info.h>` -- a small header that bakes the customer's
+# board.yaml identifiers in as `ALP_HW_BUILD_*` string macros so the
+# runtime check has something to compare the EEPROM read against:
+#
+#     #include "alp/hw_info.h"
+#     #include "alp_hw_info_build.h"   // generated
+#
+#     alp_hw_info_t info;
+#     alp_hw_info_read(&info);
+#     alp_hw_info_assert_matches_build(&info,
+#                                      ALP_HW_BUILD_SOM_SKU,
+#                                      ALP_HW_BUILD_SOM_HW_REV);
+#
+# A CMakeLists.txt consuming it writes the header to
+# `${CMAKE_BINARY_DIR}/generated/` and adds that path to the include search.
+
+
+def _pick_primary_core_os(cores: dict[str, str]) -> tuple[str, str]:
+    """Pick the "primary" core for the `ALP_HW_BUILD_OS` macro.
+
+    `cores` maps core id -> os string ("zephyr" / "yocto" / "baremetal" /
+    "off").  The selection rule:
+
+      1. First M-class core (alphabetical by id), with os != off, if any.
+      2. Else first A-class core (alphabetical by id), with os != off, if any.
+      3. Else first non-off core (alphabetical by id), if any.
+      4. Else returns ("", "off").
+
+    Returns (core_id, os).
+    """
+    active = {cid: os_ for cid, os_ in cores.items() if os_ != "off"}
+    if not active:
+        return ("", "off")
+    m_class = sorted(cid for cid in active if cid.startswith("m"))
+    if m_class:
+        cid = m_class[0]
+        return (cid, active[cid])
+    a_class = sorted(cid for cid in active if cid.startswith("a"))
+    if a_class:
+        cid = a_class[0]
+        return (cid, active[cid])
+    cid = sorted(active.keys())[0]
+    return (cid, active[cid])
+
+
+def _emit_hw_info_h(
+    project: dict[str, Any],
+    sku_preset: dict[str, Any],
+    board_preset: dict[str, Any] | None,
+    *,
+    v2_cores: dict[str, str] | None = None,
+    v2_selected_core: str | None = None,
+    metadata_root: Path,
+) -> str:
+    """Emit <alp_hw_info_build.h> -- build-time identifier companion to
+    <alp/hw_info.h>.
+
+    v1 path (`v2_cores is None`): the `ALP_HW_BUILD_OS` macro comes from
+    `project.os` (the v1 schema's single top-level OS).
+
+    v2 path: derive `ALP_HW_BUILD_OS` from the cores: block.  If
+    `v2_selected_core` is set (i.e. the caller passed `--core <id>`),
+    use that core's OS.  Else pick a "primary" core via
+    `_pick_primary_core_os`: first M-class core alphabetically, falling
+    back to first A-class core, falling back to any non-off core.
+
+    The v2 path also emits `ALP_HW_BUILD_CORES` (comma-separated list of
+    every non-off core id) and one `ALP_HW_BUILD_HAS_<id>` macro per
+    non-off core so consumers can `#ifdef` on the topology.
+
+    `metadata_root` (alp-sdk#1964) resolves this SKU's family
+    `hw-revisions.yaml` (via `load_family_table`) so `ALP_HW_BUILD_SOM_HW_REV`
+    can be composed through `board_designator` -- see the module docstring.
+    """
+    sku = project["som"]["sku"]
+    som_hw_rev = (project["som"].get("hw_rev")
+                  or sku_preset.get("default_hw_rev")
+                  or "unknown")
+    family = _sku_family(sku)
+    som_hw_rev = board_designator(
+        load_family_table(metadata_root, family), som_hw_rev)
+
+    board_block = project.get("board") or {}
+    board_name = board_block.get("name") or ""
+    board_hw_rev = ""
+    if board_name and board_preset is not None:
+        board_hw_rev = (board_block.get("hw_rev")
+                          or board_preset.get("default_hw_rev")
+                          or "")
+
+    # Resolve the OS string.
+    primary_core_id = ""
+    primary_core_os = ""
+    if v2_cores is not None:
+        if v2_selected_core is not None and v2_selected_core in v2_cores:
+            primary_core_id = v2_selected_core
+            primary_core_os = v2_cores[v2_selected_core]
+        else:
+            primary_core_id, primary_core_os = _pick_primary_core_os(v2_cores)
+        os_choice = primary_core_os
+    else:
+        os_choice = project.get("os") or ""
+
+    lines: list[str] = [
+        "/*",
+        " * Auto-generated by scripts/alp_project.py -- do not edit by hand.",
+        " * Regenerate after changes to board.yaml.",
+        " *",
+        " * Build-time identifier companion to <alp/hw_info.h>.  Apps include",
+        " * this header alongside <alp/hw_info.h> and pass the ALP_HW_BUILD_*",
+        " * string macros to alp_hw_info_assert_matches_build() so the runtime",
+        " * EEPROM read can be checked against what the firmware was built for.",
+        " */",
+        "",
+        "#ifndef ALP_HW_INFO_BUILD_H",
+        "#define ALP_HW_INFO_BUILD_H",
+        "",
+        f'#define ALP_HW_BUILD_SOM_SKU         "{sku}"',
+        f'#define ALP_HW_BUILD_SOM_FAMILY      "{family}"',
+        f'#define ALP_HW_BUILD_SOM_HW_REV      "{som_hw_rev}"',
+    ]
+    if board_name:
+        lines.append(f'#define ALP_HW_BUILD_BOARD_NAME      "{board_name}"')
+        if board_hw_rev:
+            lines.append(f'#define ALP_HW_BUILD_BOARD_HW_REV    "{board_hw_rev}"')
+    if os_choice:
+        lines.append(f'#define ALP_HW_BUILD_OS              "{os_choice}"')
+    if v2_cores is not None:
+        # `active` and the loop below range over every non-off core in the
+        # PROJECT, not the compiling slice, so this block's output --
+        # `CORES` and the `HAS_<id>` macros -- is identical in every
+        # slice's copy of the header.  `PRIMARY_CORE` is the one
+        # exception: it tracks --core when the caller passes one.
+        # Primary-core selection rule (used when --core is not given):
+        #   1. First M-class core (alphabetical by id), if any non-off.
+        #   2. Else first A-class core (alphabetical by id), if any non-off.
+        #   3. Else first non-off core (alphabetical by id).
+        active = sorted(cid for cid, os_ in v2_cores.items() if os_ != "off")
+        if active:
+            lines.append("")
+            lines.append(
+                f'#define ALP_HW_BUILD_CORES           "{",".join(active)}"'
+            )
+            if primary_core_id:
+                lines.append(
+                    f'#define ALP_HW_BUILD_PRIMARY_CORE    "{primary_core_id}"'
+                )
+            lines.append("")
+            lines.append("/* Per-core presence flags: `ALP_HW_BUILD_HAS_<id>` means "
+                         "core <id> exists in")
+            lines.append(" * the project; its value is that core's OS string.  Defined "
+                         "for EVERY active")
+            lines.append(" * core in EVERY slice -- it cannot say which core is "
+                         "compiling.")
+            lines.append(" *")
+            lines.append(" * `ALP_HW_BUILD_PRIMARY_CORE` names the compiling slice ONLY "
+                         "when this header")
+            lines.append(" * was emitted --core-scoped (the per-slice build path).  "
+                         "Emitted without")
+            lines.append(" * --core -- as the project-wide recipe in "
+                         "docs/board-config-emit.md does -- it")
+            lines.append(" * names the project's primary core (first M-class core "
+                         "alphabetically),")
+            lines.append(" * which on a multi-core project is not necessarily the one "
+                         "you are")
+            lines.append(" * building.")
+            lines.append(" *")
+            lines.append(" * Zephyr's own CONFIG_BOARD and CONFIG_BOARD_TARGET differ "
+                         "per slice too --")
+            lines.append(" * the board name and the board/soc/cpucluster target "
+                         "passed to `west build")
+            lines.append(" * -b` -- and do so no matter how this header was emitted.  "
+                         "E.g. on E1M-AEN801,")
+            lines.append(" * the HE slice's CONFIG_BOARD is "
+                         "\"alp_e1m_aen801_m55_he\" and its")
+            lines.append(" * CONFIG_BOARD_TARGET ends \".../rtss_he\"; the HP "
+                         "slice's end \"_hp\" and")
+            lines.append(" * \".../rtss_hp\".  Prefer them over PRIMARY_CORE where "
+                         "that portability")
+            lines.append(" * matters. */")
+            for cid in active:
+                lines.append(
+                    f'#define ALP_HW_BUILD_HAS_{cid.upper():<12} "{v2_cores[cid]}"'
+                )
+    lines += [
+        "",
+        "#endif /* ALP_HW_INFO_BUILD_H */",
+        "",
+    ]
+    return "\n".join(lines)

tan/planner/project_emit/native_sim.py

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: Apache-2.0
+"""native_sim board overlay emission (`--emit native-sim-overlay`).
+
+RELOCATED (was alp-sdk `scripts/alp_project_emit/native_sim.py`) -- see this
+package's `__init__.py` for the move's contract.
+
+One change beyond the import repoint: the three form-factor STRINGS are derived
+from `_sku_form_factor`'s own return value instead of written out per branch.
+alp-sdk spelled `form_factor = "E1M-X"` literally, which inside `tan` is a
+hardware fact and fails `tests/gates/test_no_new_hardware_facts.py` -- correctly,
+since naming the connector family is metadata's job, not tan's. `e1m-x` ->
+`E1M-X` / `e1m_x_pinout.h` / `ALP_E1M_X_GPIO` is a pure re-spelling of the token
+the loader already resolved, so the emitted bytes do not move;
+`test_the_in_process_engine_matches_alp_project_for_every_mode` proves that over
+every `board.yaml` in the SDK's `examples/`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..project_loader import _sku_form_factor
+
+from . import _e1m_gpio_canonical, _e1m_x_gpio_canonical
+
+
+# ---------------------------------------------------------------------
+# native_sim overlay emission (canonical alp,pin-array on gpio-emul)
+# ---------------------------------------------------------------------
+#
+# Studio + `alp init` want a native_sim board overlay so a scaffolded GPIO
+# app links + runs on `native_sim/native/64` (host emulation, emulated CI)
+# with no silicon.  Unlike `--emit dts-overlay` -- which stubs every
+# pin-array triplet at <&gpio0 0> pending the upstream SoM board file --
+# gpio-emul IS the backing controller under native_sim, so this overlay is
+# complete and directly buildable.  Keeping it here (not hand-rolled in a
+# downstream scaffolder) means the E1M/E1M-X pad ABI lives in exactly one
+# place: the canonical helpers above.
+
+# zephyr,gpio-emul controllers cap at 32 pins.
+_GPIO_EMUL_MAX_PINS = 32
+
+
+def _emit_native_sim_overlay(project: dict[str, Any]) -> str:
+    """Emit a native_sim board overlay: the canonical alp,pin-array mapped
+    onto zephyr,gpio-emul controllers.
+
+    The pin-array is the full positional map in the form-factor pinout header's
+    canonical order, so alp_z_gpio_resolve(pin_id) is a direct index for
+    any pad (the GPIO backend derives ALP_PIN_COUNT from this node's gpios
+    length).  gpio-emul caps at 32 pins, so the pads span as many
+    controllers as the active form factor needs.  Every pad defaults to
+    GPIO_ACTIVE_HIGH; an app that needs a
+    different polarity (e.g. an active-low button) overrides its own pad.
+
+    GPIO only: non-GPIO peripherals (display, sensors) have no universal
+    native_sim emulation, so an app that needs them adds its own emulated
+    nodes (e.g. a zephyr,dummy-dc display), exactly as the curated examples
+    do.
+    """
+    sku = project["som"]["sku"]
+    # `e1m-x` / `e1m` -> the three spellings the overlay's prose uses. Derived,
+    # not written out: the connector-family name is a hardware fact (I-26).
+    ff = _sku_form_factor(sku)
+    form_factor = ff.upper()
+    pinout_header = f"{ff.replace('-', '_')}_pinout.h"
+    gpio_macro_prefix = f"ALP_{form_factor.replace('-', '_')}_GPIO"
+    if ff == "e1m-x":
+        canonical = _e1m_x_gpio_canonical()
+        index_summary = [
+            "         *   0..35  IO0..IO35       36..43 PWM0..PWM7",
+            "         *   44..51 ENC0_X..ENC3_Y  52..59 ADC0..ADC7   60..61 DAC0..DAC1",
+            "         *   62..72 I2C2/3 + SPI2 + CAN1",
+            "         *   73..98 LCD_B0..LCD_B23 + LCD_HSYNC/LCD_VSYNC */",
+        ]
+    else:
+        canonical = _e1m_gpio_canonical()
+        index_summary = [
+            "         *   0..25  IO0..IO25       26..33 PWM0..PWM7",
+            "         *   34..41 ENC0_X..ENC3_Y  42..49 ADC0..ADC7   50..51 DAC0..DAC1 */",
+        ]
+    n = len(canonical)
+    n_ctrl = (n + _GPIO_EMUL_MAX_PINS - 1) // _GPIO_EMUL_MAX_PINS
+
+    lines: list[str] = []
+    lines.append("/*")
+    lines.append(" * Auto-generated by scripts/alp_project.py "
+                 "--emit native-sim-overlay -- do not edit by hand.")
+    lines.append(f" * Regenerate after changes to the {pinout_header} GPIO order.")
+    lines.append(" *")
+    lines.append(f" * native_sim GPIO emulation for SoM SKU {sku}: the canonical")
+    lines.append(" * alp,pin-array mapped onto zephyr,gpio-emul so alp_gpio_open(pin_id)")
+    lines.append(f" * resolves under `west build -b native_sim/native/64`.  All {n} {form_factor} pads")
+    lines.append(" * are present so any pin_id resolves; pads default to GPIO_ACTIVE_HIGH")
+    lines.append(" * -- override per pad in your app for a different polarity.  GPIO only:")
+    lines.append(" * add your own emulated nodes for non-GPIO peripherals (display, etc.).")
+    lines.append(" */")
+    lines.append("")
+    lines.append("#include <zephyr/dt-bindings/gpio/gpio.h>")
+    lines.append("")
+    lines.append("/ {")
+
+    # gpio-emul controllers -- one per 32-pad span.
+    for c in range(n_ctrl):
+        base = c * _GPIO_EMUL_MAX_PINS
+        count = min(_GPIO_EMUL_MAX_PINS, n - base)
+        lines.append(f"    gpio_emul{c}: gpio_emul{c} {{")
+        lines.append('        compatible = "zephyr,gpio-emul";')
+        lines.append('        status = "okay";')
+        lines.append("        gpio-controller;")
+        lines.append("        rising-edge;")
+        lines.append("        falling-edge;")
+        lines.append("        #gpio-cells = <2>;")
+        lines.append(f"        ngpios = <{count}>;")
+        lines.append("    };")
+        lines.append("")
+
+    # alp,pin-array -- the full positional map spanning the controllers.
+    lines.append("    alp_pins: alp-pins {")
+    lines.append('        compatible = "alp,pin-array";')
+    lines.append(f"        /* {n} entries in {form_factor} canonical order ({pinout_header}).  Indices:")
+    for line in index_summary:
+        lines.append(line)
+    lines.append("        gpios =")
+    for i, suffix in enumerate(canonical):
+        ctrl = i // _GPIO_EMUL_MAX_PINS
+        local = i % _GPIO_EMUL_MAX_PINS
+        terminator = ";" if i == n - 1 else ","
+        lines.append(
+            f"            <&gpio_emul{ctrl} {local:2d} GPIO_ACTIVE_HIGH>{terminator}"
+            f"  /* [{i:2d}] {gpio_macro_prefix}_{suffix} */"
+        )
+    lines.append("    };")
+    lines.append("};")
+
+    return "\n".join(lines) + "\n"

tan/planner/project_emit/west_libs.py

@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: Apache-2.0
+"""west.yml fragment emission (`--emit west-libraries`).
+
+RELOCATED (was alp-sdk `scripts/alp_project_emit/west_libs.py`) -- see this
+package's `__init__.py` for the move's contract.
+
+Only the west.yml half came across. That file's other half --
+`_emit_library_hw_backends` + `_SOC_FAMILY_TOKEN`, the per-library
+HW-accelerator Kconfig matcher -- is NOT reached by `--emit west-libraries` at
+all (`_slice_alp_conf` calls it, and that is the `zephyr-conf` path), and it
+already relocated with the rest of the Kconfig emitter into
+`tan/planner/libraries.py`. A second copy here would be a second source of truth
+for which accelerator a SKU gets. `_library_alias_table` is imported for the
+same reason -- from `tan/planner/loader.py`, its one definition since
+tan-cli#868 (`libraries.py` carried a twin of it until then, and the two had
+already drifted by a docstring clause).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ..loader import _library_alias_table
+
+# ---------------------------------------------------------------------
+# west.yml fragment emission (libraries -> Zephyr-module name-allowlist)
+# ---------------------------------------------------------------------
+#
+# Closes the second v0.4 gap docs/board-config.md flagged: customers
+# whose board.yaml declares `libraries: [lvgl, mbedtls]` should not
+# also have to hand-add those modules to their app's west.yml
+# `name-allowlist:`.  The emitter produces a paste-ready fragment
+# they import via a self-referencing `import:` block.
+
+
+# Canonical library name -> Zephyr module name the workspace's west.yml must
+# import.  Keyed by the CANONICAL manifest name (metadata/libraries/<name>.yaml)
+# because the v2 `libraries:` resolution feeds canonical names here; the
+# conservative allowlist stays four upstream Zephyr modules (the vendored /
+# header-only libraries deliberately do NOT get a west entry -- `west update`
+# would reject a name it can't resolve).  Mirrors zephyr/modules.git; LittleFS
+# ships as `fs/littlefs` while the rest match their names 1:1.
+_LIBRARY_WEST_MODULES: dict[str, str] = {
+    "lvgl":          "lvgl",
+    "mbedtls":       "mbedtls",
+    "cmsis-dsp":     "cmsis-dsp",
+    "littlefs":      "fs/littlefs",
+    # The four header-only C++ libraries (etl / fmt / nlohmann_json /
+    # doctest) are not Zephyr modules today -- they land in v0.4 via
+    # the per-library profile + include-path hook in the loader, not
+    # via west.yml.  Listing them here would emit an entry that
+    # `west update` rejects.
+}
+
+
+# OTA provider -> Zephyr module name the workspace's west.yml must
+# import.  Hawkbit and MCUmgr ship in Zephyr upstream so no entry --
+# only out-of-tree clients need a west.yml line.  See ADR 0009.
+_OTA_PROVIDER_WEST_MODULES: dict[str, str] = {
+    "mender":  "mender-mcu-client",
+    # hawkbit -- in Zephyr upstream
+    # mcumgr  -- in Zephyr upstream
+}
+
+
+def _load_curated_library_manifest(
+        lib: str, metadata_root: Path) -> dict[str, Any] | None:
+    """Load a top-level ADR 0018 library manifest if one exists.
+
+    `metadata_root` is required, not defaulted -- see `_library_alias_table`
+    (alp-sdk#1485).
+    """
+    path = metadata_root / "libraries" / f"{lib}.yaml"
+    if not path.is_file():
+        return None
+    doc = yaml.safe_load(path.read_text(encoding="utf-8"))
+    return doc if isinstance(doc, dict) else None
+
+
+def _emit_west_libraries(
+    project: dict[str, Any],
+    sku_preset: dict[str, Any],
+    board_preset: dict[str, Any] | None,
+    *,
+    v2_libraries: list[str] | None = None,
+    v2_project_libraries: list[str] | None = None,
+    metadata_root: Path,
+) -> str:
+    """Emit a west.yml fragment that the customer's manifest can
+    import to pin the Zephyr modules board.yaml's `libraries:` array
+    requires.  Idempotent: emitting an empty `libraries:` array gives
+    an empty (but well-formed) name-allowlist.
+
+    v1 path (`v2_libraries is None`): reads project-level `libraries:`.
+    v2 path: callers compute the union across the Zephyr-runtime cores
+    (or pick one when `--core <id>` is supplied) and pass it in via
+    `v2_libraries`.  `v2_project_libraries` carries the top-level ADR 0018
+    curated library manifests; these may either import a Zephyr-owned module
+    by name or emit a standalone west project pin from the manifest's
+    `integration.zephyr.west` block.
+
+    `metadata_root` is required, not defaulted -- pass the project's
+    `effective_metadata_root()` so the alias table and every curated library
+    manifest read below resolve against the SAME tree
+    `load_board_yaml(..., metadata_root=...)` validated the project against,
+    instead of an omitted argument silently falling back to the bound SDK's
+    own in-tree `metadata/` (alp-sdk#1485).
+    """
+    del sku_preset, board_preset  # unused -- libraries are SoM-agnostic
+    if v2_libraries is not None:
+        libs = list(v2_libraries)
+    else:
+        libs = project.get("libraries") or []
+    project_libs = list(v2_project_libraries
+                        if v2_project_libraries is not None
+                        else [])
+    modules: list[tuple[str, str]] = []   # (library, Zephyr-owned west module)
+    west_projects: list[tuple[str, dict[str, Any]]] = []
+    unsupported: list[str] = []
+    seen_modules: set[str] = set()
+    seen_projects: set[str] = set()
+
+    def add_module(lib: str, mod: str) -> None:
+        if mod not in seen_modules:
+            modules.append((lib, mod))
+            seen_modules.add(mod)
+
+    def add_west_project(lib: str, west: dict[str, Any]) -> None:
+        name = str(west.get("name") or "")
+        if name and name not in seen_projects:
+            west_projects.append((lib, west))
+            seen_projects.add(name)
+
+    # Normalise legacy per-core tokens (schemaVersion 1) to their canonical
+    # manifest name so the west-module lookup resolves regardless of which
+    # spelling the caller passed (v2 resolution already yields canonical).
+    alias = _library_alias_table(metadata_root)
+    for lib in libs:
+        mod = _LIBRARY_WEST_MODULES.get(alias.get(lib, lib))
+        if mod is None:
+            unsupported.append(lib)
+        else:
+            add_module(lib, mod)
+
+    for lib in project_libs:
+        manifest = _load_curated_library_manifest(lib, metadata_root)
+        zephyr = ((manifest or {}).get("integration") or {}).get("zephyr") or {}
+        if not zephyr:
+            continue
+        west = zephyr.get("west")
+        if isinstance(west, dict):
+            add_west_project(lib, west)
+            continue
+        mod = zephyr.get("module")
+        if isinstance(mod, str) and mod:
+            add_module(lib, mod)
+        else:
+            unsupported.append(lib)
+
+    # OTA provider-driven dispatch (ADR 0009 follow-up): out-of-tree
+    # Zephyr OTA clients need their own west.yml entry.  Mender-MCU-client
+    # is the only one today; hawkbit and mcumgr ship in Zephyr upstream.
+    ota = project.get("ota") or {}
+    if isinstance(ota, dict):
+        ota_provider = (ota.get("provider") or "").lower()
+        ota_mod = _OTA_PROVIDER_WEST_MODULES.get(ota_provider)
+        if ota_mod is not None:
+            modules.append((f"ota:{ota_provider}", ota_mod))
+
+    lines: list[str] = []
+    lines.append("# SPDX-License-Identifier: Apache-2.0")
+    lines.append("#")
+    lines.append("# Auto-generated by scripts/alp_project.py -- "
+                 "do not edit by hand.")
+    lines.append("# Regenerate after changes to board.yaml's `libraries:` array.")
+    lines.append("#")
+    lines.append("# Import into your application's west.yml so `west update`")
+    lines.append("# pulls only the Zephyr modules the libraries you enabled")
+    lines.append("# actually need.  Drop alongside your west.yml and reference")
+    lines.append("# from the `import:` field of the alp-sdk project entry.")
+    lines.append("")
+    lines.append("manifest:")
+    lines.append("  projects:")
+    lines.append("    - name: zephyr")
+    lines.append("      import:")
+    lines.append("        name-allowlist:")
+    if modules:
+        for lib, mod in modules:
+            lines.append(f"          - {mod}        # board.yaml libraries: '{lib}'")
+    else:
+        lines.append("          # no selected Zephyr-owned modules -- nothing to allowlist.")
+        lines.append("          []")
+
+    if west_projects:
+        lines.append("")
+        lines.append("    # ADR 0018 libraries not imported by Zephyr's own west.yml.")
+        for lib, west in west_projects:
+            lines.append(f"    - name: {west['name']}")
+            lines.append(f"      url: {west['url']}")
+            lines.append(f"      revision: {west['revision']}")
+            lines.append(f"      path: {west['path']}        # board.yaml libraries: '{lib}'")
+
+    if unsupported:
+        lines.append("")
+        lines.append("# The following libraries have no Zephyr west project entry today")
+        lines.append("# (header-only/profile libraries ride the loader's include path;")
+        lines.append("# Yocto-only or in-tree Zephyr subsystems do not need a project pin):")
+        for lib in unsupported:
+            lines.append(f"#   - {lib}")
+    return "\n".join(lines) + "\n"