bspctl 0.0.2__py3-none-any.whl

bspctl/__init__.py

@@ -0,0 +1,3 @@
+"""bspctl: NXP i.MX and TI Sitara BSP build orchestrator."""
+
+__version__ = "0.0.2"

bspctl/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m bspctl`."""
+
+from bspctl.cli import app
+
+if __name__ == "__main__":
+    app()

bspctl/bsp_detect.py

@@ -0,0 +1,154 @@
+"""Inspect a kas YAML and classify the BSP family.
+
+Used by the BYO (Form A) path of ``bspctl build``: when the user hands
+bspctl a kas YAML directly, we cannot rely on the manifest filename
+regex in :func:`bspctl.bsp_model.detect_bsp_family`. Instead the
+classifier reads ``machine:`` and ``repos:`` from the YAML and applies
+a small first-match-wins rule set:
+
+* machine starts with ``imx``                                  -> ``nxp``
+* machine starts with ``am`` / ``k3-`` / ``j7-``               -> ``ti``
+* repos contains ``meta-imx`` / ``meta-freescale*`` / ``meta-nxp*`` -> ``nxp``
+* repos contains ``meta-ti-bsp`` / ``meta-ti`` / ``meta-arago`` -> ``ti``
+* parseable YAML with at least ``machine:`` or ``repos:``      -> ``generic``
+* unparseable / empty                                          -> ``unknown``
+
+The ``generic`` classification is the BSP-agnostic fallback for kas
+YAMLs that look like real builds but do not target an NXP/TI SoM
+(e.g. qemuarm64 + poky + meta-arm). Callers layer the
+``bspctl-tuning-generic.yml`` overlay - which carries only the
+BSP-agnostic optimizations (ccache, MIRRORS, PREMIRRORS, FETCHCMD_wget,
+PYTHONMALLOC) - onto these YAMLs.
+
+The function never raises - I/O on the YAML is wrapped defensively so
+``bspctl build my.yml`` can fail with a single typer.Exit(2) instead of
+a Python traceback.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+import yaml
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# Repo-name substrings that identify each BSP. Order matters within a
+# family: the first matching substring wins. The lists are kept short
+# and explicit so a future BSP addition does not collide silently.
+_NXP_REPO_NAMES: tuple[str, ...] = (
+    "meta-imx",
+    "meta-freescale",
+    "meta-nxp",
+    "meta-variscite-bsp-imx",
+    "meta-variscite-sdk-imx",
+)
+
+_TI_REPO_NAMES: tuple[str, ...] = (
+    "meta-ti-bsp",
+    "meta-ti-extras",
+    "meta-ti",
+    "meta-tisdk",
+    "meta-arago",
+    "meta-variscite-bsp-ti",
+    "meta-variscite-sdk-ti",
+)
+
+
+def _machine_family(machine: str) -> Literal["nxp", "ti", "unknown"]:
+    if not machine:
+        return "unknown"
+    name = machine.lower()
+    if name.startswith("imx"):
+        return "nxp"
+    if name.startswith(("am", "k3-", "j7-", "j72", "j78", "j784")):
+        return "ti"
+    return "unknown"
+
+
+def _repos_family(repos: dict[str, Any] | None) -> Literal["nxp", "ti", "unknown"]:
+    if not isinstance(repos, dict):
+        return "unknown"
+    names = set(repos.keys())
+    for hit in _NXP_REPO_NAMES:
+        if hit in names:
+            return "nxp"
+    for hit in _TI_REPO_NAMES:
+        if hit in names:
+            return "ti"
+    return "unknown"
+
+
+def detect_bsp_from_yaml(yaml_path: Path) -> Literal["nxp", "ti", "generic", "unknown"]:
+    """Inspect a kas YAML and classify the BSP family.
+
+    Pure function over a parsed YAML dict. Returns ``"generic"`` for a
+    kas YAML that parses cleanly but lacks NXP/TI markers; callers
+    use that to layer the BSP-agnostic tuning overlay. Returns
+    ``"unknown"`` only for unparseable, empty, or shape-incomplete
+    YAMLs - those exit with a typer.Exit(2) and a hint.
+    """
+    if yaml_path is None or not yaml_path.is_file():
+        return "unknown"
+    try:
+        with yaml_path.open("r", encoding="utf-8") as fh:
+            data = yaml.safe_load(fh)
+    except (OSError, yaml.YAMLError):
+        return "unknown"
+    if not isinstance(data, dict):
+        return "unknown"
+
+    machine = data.get("machine", "")
+    machine_hit = _machine_family(machine if isinstance(machine, str) else "")
+    if machine_hit != "unknown":
+        return machine_hit
+
+    repos_hit = _repos_family(data.get("repos"))
+    if repos_hit != "unknown":
+        return repos_hit
+
+    # No NXP/TI markers but the YAML has at least a machine string or a
+    # repos block - treat as a generic kas build. Reject only YAMLs
+    # that lack both anchors (typo or empty file).
+    has_machine = isinstance(machine, str) and bool(machine.strip())
+    has_repos = isinstance(data.get("repos"), dict) and bool(data["repos"])
+    if has_machine or has_repos:
+        return "generic"
+    return "unknown"
+
+
+def is_meta_avocado_yaml(yaml_path: Path) -> bool:
+    """Return True if the YAML lives inside a meta-avocado repository.
+
+    Walks the resolved path and checks whether any ancestor directory is
+    named ``meta-avocado``. This is how bspctl detects that a generic kas
+    YAML belongs to the Avocado OS build system and needs the
+    ``init-build``-style build-directory setup before kas can run.
+    """
+    try:
+        return "meta-avocado" in yaml_path.resolve().parts
+    except Exception:
+        return False
+
+
+def detect_kas_workspace(yaml_path: Path) -> Path:
+    """Return the effective workspace root for a generic kas YAML.
+
+    For meta-avocado YAMLs the YAML sits several levels deep inside the
+    ``meta-avocado`` repository (e.g. ``sources/meta-avocado/kas/machine/
+    qemux86-64.yml``). kas must run from a build directory that is a
+    *sibling* of ``meta-avocado/`` (e.g. ``sources/build-qemux86-64/``),
+    not from inside the repo. This function walks up from the YAML to
+    find the ``meta-avocado`` boundary and returns its parent
+    (e.g. ``sources/``) so :func:`bspctl.config.BuildConfig.bsp_root`
+    can derive the correct build-directory path.
+
+    For every other generic kas YAML the workspace is simply the YAML's
+    parent directory (preserving the existing behavior).
+    """
+    resolved = yaml_path.resolve()
+    for parent in resolved.parents:
+        if parent.name == "meta-avocado":
+            return parent.parent
+    return resolved.parent

bspctl/bsp_model.py

@@ -0,0 +1,258 @@
+"""Per-BSP model for the bspctl CLI.
+
+NXP i.MX and TI Sitara BSP families are supported.
+Each family has its own toolchain (Google ``repo`` + ``var-setup-release.sh``
+for NXP; ``varigit/oe-layersetup`` shell wrapper for TI), its own
+manifest format (``imx-A.B.C-X.Y.Z.xml`` vs ``processor-sdk-...-config_var<N>.txt``),
+its own static tuning overlay (``overlays/bspctl-tuning-<bsp>.yml``),
+and its own pre-flight checks.
+
+This module exports:
+
+* :func:`detect_bsp_family` - classify a manifest filename. Pure regex,
+  no I/O. The return value drives both the dispatcher in
+  :mod:`bspctl.cli` and the ``check_host_tools`` decision.
+* :func:`infer_bsp_branch` - synthesize the
+  ``meta-variscite-bsp-ti`` branch suffix from a TI config filename.
+* :class:`BspModel` - dataclass + registry that hold every per-BSP
+  knob: defaults, kas template, sync/setup steps, doctor extras.
+* :func:`get_model` - factory returning the dispatched model. Imports
+  are lazy so :mod:`bspctl.config` (which imports
+  :func:`infer_bsp_branch` for TI branch fallback) can keep its
+  circular dep-free top-level import.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, Any, Literal
+
+from bspctl.vendor_config import load_vendors
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from bspctl.kas import KasTemplate
+
+
+# ---------------------------------------------------------------------------
+# Manifest-shape detection (no I/O on the regex path)
+# ---------------------------------------------------------------------------
+
+
+# NXP manifest filename: imx-<kernel>-<bsp>.xml
+# Examples: imx-6.6.52-2.2.2.xml, imx-6.12.49-2.2.0.xml
+_NXP_MANIFEST_RE = re.compile(r"^imx-\d+\.\d+\.\d+-\d+\.\d+\.\d+\.xml$")
+
+# TI Processor SDK config filename:
+#   processor-sdk-<poky>-<flavour>-<sdk>-config_<var>.txt
+# where <poky> is the LTS code name (scarthgap, walnascar, ...),
+# <flavour> is "chromium" / "non-chromium" / etc,
+# <sdk> is a 4-part TI SDK version (11.00.09.04),
+# <var>  is "var01" / "var02" / ...
+_TI_PROCESSOR_SDK_RE = re.compile(
+    r"^processor-sdk-"
+    r"(?P<poky>[A-Za-z]\w*)-"
+    r".*?-"
+    r"(?P<sdk>\d+\.\d+\.\d+\.\d+)-"
+    r"config_(?P<var>var\d+)\.txt$"
+)
+
+# TI legacy/Arago manifest filename: arago-<anything>.txt
+# Kept as alternation for forward compatibility with older
+# config naming conventions.
+_TI_ARAGO_RE = re.compile(r"^arago-.*\.txt$")
+
+# Layer name string used as a fallback heuristic when a config file is
+# present but does not match either regex.
+_TI_LAYER_PREFIX = "meta-variscite-bsp-ti"
+
+
+def detect_bsp_family(
+    manifest_path: Path | None,
+    config_file: Path | None = None,
+) -> Literal["nxp", "ti", "unknown"]:
+    """Detect the BSP family from a manifest filename and optional config.
+
+    Only the filename (``path.name``) is inspected; the file need not
+    exist on disk. Pass ``None`` for either argument to skip that
+    check. The function never raises - I/O on ``config_file`` is
+    wrapped defensively.
+    """
+    if manifest_path is not None:
+        name = manifest_path.name
+        for vendor in load_vendors():
+            if re.match(vendor.manifest_regex, name):
+                return vendor.family  # type: ignore[return-value]
+        if _NXP_MANIFEST_RE.match(name):
+            return "nxp"
+        if _TI_PROCESSOR_SDK_RE.match(name) or _TI_ARAGO_RE.match(name):
+            return "ti"
+
+    if config_file is not None:
+        try:
+            text = config_file.read_text(encoding="utf-8", errors="replace")
+            if _TI_LAYER_PREFIX in text:
+                return "ti"
+        except OSError:
+            pass
+
+    return "unknown"
+
+
+def infer_bsp_branch(config_filename: str) -> str:
+    """Derive the ``meta-variscite-bsp-ti`` branch from a TI config name.
+
+    The canonical filename
+    ``processor-sdk-scarthgap-chromium-11.00.09.04-config_var01.txt``
+    parses to ``(poky=scarthgap, sdk=11.00.09.04, var=var01)`` and
+    yields ``scarthgap_11.00.09.04_var01`` - the actual branch name on
+    the layer repo.
+
+    Returns ``"<unknown>"`` for inputs that do not match the regex
+    (legacy ``arago-*.txt`` configs go through the legacy versioning
+    scheme, which is out of scope for this helper).
+    """
+    m = _TI_PROCESSOR_SDK_RE.match(config_filename)
+    if not m:
+        return "<unknown>"
+    return f"{m.group('poky')}_{m.group('sdk')}_{m.group('var')}"
+
+
+# ---------------------------------------------------------------------------
+# BspModel registry
+# ---------------------------------------------------------------------------
+
+
+# Type aliases. ``Callable[..., None]`` is intentionally permissive so
+# both the NXP sync step (``init_and_sync(cfg, log, *, force_init=...)``)
+# and the TI sync step (``populate(cfg, log, *, force_init=...)``) fit.
+SyncStep = Callable[..., None]
+SetupEnvStep = Callable[..., None]
+DoctorCheck = Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class BspModel:
+    """Per-BSP knobs consumed by the dispatch layer.
+
+    Every field that varies between NXP and TI lives here. The CLI's
+    ``_dispatch_bsp`` returns one of two singleton instances; downstream
+    code reads the fields instead of switching on ``cfg.bsp_family``.
+    """
+
+    family: Literal["nxp", "ti"]
+    workspace_subdir: str  # "nxp" or "ti"
+    kas_yaml_filename: str  # "kas-nxp.yml" or "kas-ti.yml"
+    tuning_overlay_filename: str  # "bspctl-tuning-nxp.yml" or "bspctl-tuning-ti.yml"
+    manifest_kind: Literal["repo-xml", "oe-layertool-config"]
+    default_machine: str
+    default_distro: str
+    default_image: str
+    default_manifest: str
+    default_branch: str
+    required_host_tools: tuple[str, ...]
+    sync_step: SyncStep
+    setup_env_step: SetupEnvStep
+    kas_template: KasTemplate
+    doctor_extras: tuple[DoctorCheck, ...]
+
+
+def get_model(family: Literal["nxp", "ti"]) -> BspModel:
+    """Return the BspModel singleton for ``family``.
+
+    Imports are intentionally lazy. ``bsp_model`` is imported from
+    ``config.py`` (``infer_bsp_branch``) and from ``cli.py``; deferring
+    the heavy imports until ``get_model`` is actually called keeps the
+    import graph clean and lets unit tests construct dummy models
+    without dragging in diagnostics or steps.
+    """
+    # Lazy: avoid pulling diagnostics/steps/kas into every consumer of
+    # detect_bsp_family or infer_bsp_branch.
+    from bspctl import config as cfg_mod
+    from bspctl.diagnostics import (
+        check_forks_linux_imx,
+        check_forks_ti_linux_kernel,
+        check_forks_ti_u_boot,
+        check_git_object_cache,
+        check_manifest_consistency,
+        check_ti_layertool_config_consistency,
+        check_ti_layertool_present,
+    )
+    from bspctl.kas import NXP_KAS_TEMPLATE, TI_KAS_TEMPLATE
+    from bspctl.steps import repo as step_repo
+    from bspctl.steps import setup_env as step_setup
+    from bspctl.steps import ti_layertool as step_ti_layertool
+    from bspctl.steps import ti_setup_env as step_ti_setup
+
+    if family == "nxp":
+        model = BspModel(
+            family="nxp",
+            workspace_subdir="nxp",
+            kas_yaml_filename="kas-nxp.yml",
+            tuning_overlay_filename="bspctl-tuning-nxp.yml",
+            manifest_kind="repo-xml",
+            default_machine=cfg_mod.DEFAULT_NXP_MACHINE,
+            default_distro=cfg_mod.DEFAULT_NXP_DISTRO,
+            default_image=cfg_mod.DEFAULT_NXP_IMAGE,
+            default_manifest=cfg_mod.DEFAULT_NXP_MANIFEST,
+            default_branch=cfg_mod.DEFAULT_NXP_REPO_BRANCH,
+            required_host_tools=("repo", "kas-container", "docker", "python3"),
+            sync_step=step_repo.init_and_sync,
+            setup_env_step=step_setup.run,
+            kas_template=NXP_KAS_TEMPLATE,
+            doctor_extras=(
+                check_forks_linux_imx,
+                check_manifest_consistency,
+                check_git_object_cache,
+            ),
+        )
+    elif family == "ti":
+        model = BspModel(
+            family="ti",
+            workspace_subdir="ti",
+            kas_yaml_filename="kas-ti.yml",
+            tuning_overlay_filename="bspctl-tuning-ti.yml",
+            manifest_kind="oe-layertool-config",
+            default_machine=cfg_mod.DEFAULT_TI_MACHINE,
+            default_distro=cfg_mod.DEFAULT_TI_DISTRO,
+            default_image=cfg_mod.DEFAULT_TI_IMAGE,
+            default_manifest=cfg_mod.DEFAULT_TI_MANIFEST,
+            default_branch=cfg_mod.DEFAULT_TI_REPO_BRANCH,
+            required_host_tools=("git", "kas-container", "docker", "python3"),
+            sync_step=step_ti_layertool.populate,
+            setup_env_step=step_ti_setup.run,
+            kas_template=TI_KAS_TEMPLATE,
+            doctor_extras=(
+                check_ti_layertool_present,
+                check_ti_layertool_config_consistency,
+                check_forks_ti_linux_kernel,
+                check_forks_ti_u_boot,
+            ),
+        )
+    else:
+        raise ValueError(f"Unknown BSP family: {family!r}")
+
+    # Apply optional VendorEntry overrides for the first matching vendor.
+    for entry in load_vendors():
+        if entry.family == family:
+            overrides: dict[str, Any] = {}
+            if entry.default_machine is not None:
+                overrides["default_machine"] = entry.default_machine
+            if entry.default_distro is not None:
+                overrides["default_distro"] = entry.default_distro
+            if entry.default_image is not None:
+                overrides["default_image"] = entry.default_image
+            if entry.default_manifest is not None:
+                overrides["default_manifest"] = entry.default_manifest
+            if entry.default_branch is not None:
+                overrides["default_branch"] = entry.default_branch
+            if entry.tuning_overlay is not None:
+                overrides["tuning_overlay_filename"] = entry.tuning_overlay
+            if overrides:
+                model = replace(model, **overrides)
+            break
+
+    return model