kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/linux/launcher.py

@@ -0,0 +1,107 @@
+"""The AppDir ``AppRun`` launcher — a POSIX shell script (linux-spec).
+
+AppImage does not require an ELF ``AppRun``, and Linux has no analog of the
+Finder/LaunchServices problem that forced the compiled Mach-O stub on macOS, so
+the launcher is a small shell script. It resolves its own directory (so the
+AppDir stays relocatable), points the bundled CPython at its own home + the
+app's ``lib``/``app`` directories, sets the SDL WM_CLASS so the window groups
+under the ``.desktop``'s ``StartupWMClass``, and ``exec``s the interpreter on
+the entry-point module.
+
+By default there is deliberately **no ``LD_LIBRARY_PATH``**: PBS rpaths are
+``$ORIGIN``-relative and manylinux wheels vendor their own native libs
+(auditwheel), so the host's libGL/libEGL are found on the normal loader path.
+The one exception is when the app declares ``[tool.kivy.linux.native.binaries]``:
+then ``usr/bin`` is *prepended* to ``PATH`` (helpers win by name) and *appended*
+to ``LD_LIBRARY_PATH`` (declared libs load by soname but never shadow the host's
+or the wheels' own ``.so``s — decided Option B in linux-spec). The
+PATH-prepend / LD_LIBRARY_PATH-append asymmetry is deliberate: declared tools
+win; declared libs never shadow the host.
+"""
+
+from __future__ import annotations
+
+import keyword
+from pathlib import Path
+
+from . import AppDirError
+
+# ``{entry}`` is a ``/``-joined module path (a dotted ``entry_point`` such as
+# ``pkg.start`` maps to ``pkg/start``); ``{app_id}`` is a validated ``.desktop``
+# basename (letters/digits/hyphen/period) — both safe to inline.
+_APPRUN = """\
+#!/bin/sh
+# Generated by kivyforge — do not edit.
+HERE="$(dirname "$(readlink -f "$0")")"
+
+export PYTHONHOME="$HERE/usr/python"
+export PYTHONPATH="$HERE/usr/app:$HERE/usr/lib"
+export PYTHONNOUSERSITE=1
+{native_block}
+# Match the window's WM_CLASS to the .desktop StartupWMClass so the app groups
+# under its own icon on both X11 and Wayland.
+export SDL_VIDEO_X11_WMCLASS="{app_id}"
+export SDL_VIDEO_WAYLAND_WMCLASS="{app_id}"
+
+exec "$HERE/usr/python/bin/python3" "$HERE/usr/app/{entry}.py" "$@"
+"""
+
+# Only emitted when the app declares native binaries (no dead env vars
+# otherwise — symmetry with the "no empty bin/" rule). PATH is prepended so a
+# bundled helper wins by name; LD_LIBRARY_PATH is appended so the host's and the
+# wheels' auditwheel-vendored .so's still win the search and a declared lib is
+# only a last resort (decided Option B, linux-spec).
+_NATIVE_BINARIES_BLOCK = """
+# Declared native binaries (see linux-spec): helpers by name, libs by soname.
+export PATH="$HERE/usr/bin:$PATH"
+export LD_LIBRARY_PATH="${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$HERE/usr/bin"
+"""
+
+
+def entry_point_rel_path(entry_point: str) -> str:
+    """Map a (possibly dotted) ``entry_point`` to its ``/``-joined module path.
+
+    ``"main"`` -> ``"main"``; ``"pkg.start"`` -> ``"pkg/start"`` (i.e.
+    ``usr/app/pkg/start.py``), matching the ``app_dir``/``entry_point`` layout
+    contract in the shared pyproject spec.
+    """
+    return "/".join(entry_point.split("."))
+
+
+def render_apprun(
+    *, entry_point: str, app_id: str, has_native_binaries: bool = False
+) -> str:
+    """The ``AppRun`` shell source for *entry_point* + *app_id* (pure/testable).
+
+    *entry_point* may be a dotted module name (e.g. ``pkg.start``); each segment
+    must be a valid, non-keyword Python identifier. When *has_native_binaries*
+    is set, ``usr/bin`` is prepended to ``PATH`` and appended to
+    ``LD_LIBRARY_PATH``; otherwise the block is omitted entirely.
+    """
+    parts = entry_point.split(".")
+    if not entry_point or not all(
+        p.isidentifier() and not keyword.iskeyword(p) for p in parts
+    ):
+        raise AppDirError(f"entry_point {entry_point!r} is not a valid module name.")
+    native_block = _NATIVE_BINARIES_BLOCK if has_native_binaries else ""
+    return _APPRUN.format(
+        entry=entry_point_rel_path(entry_point),
+        app_id=app_id,
+        native_block=native_block,
+    )
+
+
+def build_apprun(
+    dest: Path, *, entry_point: str, app_id: str, has_native_binaries: bool = False
+) -> None:
+    """Write an executable ``AppRun`` at *dest*."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(
+        render_apprun(
+            entry_point=entry_point,
+            app_id=app_id,
+            has_native_binaries=has_native_binaries,
+        ),
+        "utf-8",
+    )
+    dest.chmod(0o755)

kivyforge/platforms/linux/lock/__init__.py

@@ -0,0 +1,126 @@
+"""Linux lock stack (``pylock.linux.toml``).
+
+A thin Linux *profile* (:class:`LinuxProfile`) over the generic wheel+runtime
+lock engine (``kivyforge.lock.wheelruntime``). This module is the stable Linux
+public surface: it binds the profile into the core and re-exports the engine's
+types under Linux-friendly names so callers (the CLI, tests) never reach into
+the generic package directly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+
+from kivyforge.config.model import Config
+from kivyforge.lock.wheelruntime import (
+    PythonRuntime as LinuxPythonRuntime,
+)
+from kivyforge.lock.wheelruntime import (
+    ResolvedPackage,
+    ResolvedWheel,
+    RuntimeArtifact,
+    RuntimeProvider,
+    RuntimeProviderError,
+    Variant,
+    WheelResolver,
+    WheelResolverError,
+    WheelRuntimeBuildError,
+    WheelRuntimeLock,
+    build_wheel_runtime_lock,
+    diff_summary,
+    get_wheel_resolver,
+    semantic_equal,
+)
+from kivyforge.lock.wheelruntime import serialize as _ser
+
+from .profile import (
+    LinuxProfile,
+    effective_glibc_floor,
+    is_plain_linux_tag,
+    linux_wheel_arch,
+    linux_wheel_coverage,
+    manylinux_platform_tags,
+    plain_linux_wheel_warning,
+    wheel_glibc_level,
+)
+from .runtime import PythonBuildStandaloneProvider
+
+# Linux-friendly aliases for the generic engine types.
+LinuxLockfile = WheelRuntimeLock
+LinuxBuildError = WheelRuntimeBuildError
+LinuxResolverError = WheelResolverError
+
+_PROFILE = LinuxProfile()
+
+__all__ = [
+    "LinuxBuildError",
+    "LinuxLockfile",
+    "LinuxProfile",
+    "LinuxPythonRuntime",
+    "LinuxResolverError",
+    "PythonBuildStandaloneProvider",
+    "ResolvedPackage",
+    "ResolvedWheel",
+    "RuntimeArtifact",
+    "RuntimeProvider",
+    "RuntimeProviderError",
+    "Variant",
+    "WheelResolver",
+    "build_linux_lockfile",
+    "diff_summary",
+    "dumps",
+    "effective_glibc_floor",
+    "get_linux_resolver",
+    "is_plain_linux_tag",
+    "linux_wheel_arch",
+    "linux_wheel_coverage",
+    "load",
+    "loads",
+    "manylinux_platform_tags",
+    "plain_linux_wheel_warning",
+    "semantic_equal",
+    "wheel_glibc_level",
+]
+
+
+def build_linux_lockfile(
+    config: Config,
+    pyproject_text: str,
+    *,
+    project_root: Path | None = None,
+    resolver: WheelResolver | None = None,
+    runtime_provider: RuntimeProvider | None = None,
+    offline: bool = False,
+    now: datetime | None = None,
+    on_warning: Callable[[str], None] | None = None,
+) -> LinuxLockfile:
+    return build_wheel_runtime_lock(
+        _PROFILE,
+        config,
+        pyproject_text,
+        project_root=project_root,
+        resolver=resolver,
+        runtime_provider=runtime_provider,
+        native_binaries=config.linux.binaries if config.linux else (),
+        offline=offline,
+        now=now,
+        on_warning=on_warning,
+    )
+
+
+def dumps(lock: LinuxLockfile) -> str:
+    return _ser.dumps(lock)
+
+
+def loads(text: str) -> LinuxLockfile:
+    return _ser.loads(text, platform="linux")
+
+
+def load(path: str | Path) -> LinuxLockfile:
+    return _ser.load(path, platform="linux")
+
+
+def get_linux_resolver(backend: str = "pip", **kwargs) -> WheelResolver:
+    return get_wheel_resolver(backend, **kwargs)

kivyforge/platforms/linux/lock/profile.py

@@ -0,0 +1,254 @@
+"""Linux lock profile — the platform-specific inputs to the wheel+runtime core.
+
+Linux variants are CPU architectures (``x86_64`` only this phase). Wheels use
+manylinux platform tags; because pip does not expand the manylinux hierarchy
+from a single explicit ``--platform`` (linux-spec spike), each variant requests
+the full ladder of compatible tags at or below the glibc floor in one pip
+invocation. The bundled runtime comes from python-build-standalone (linux-gnu).
+Everything else — resolve/serialize/build orchestration — is the shared core.
+"""
+
+from __future__ import annotations
+
+import re
+
+from kivyforge.config.errors import ConfigError
+from kivyforge.config.model import Config
+from kivyforge.lock.wheelruntime.model import WheelRuntimeLock
+from kivyforge.lock.wheelruntime.profile import PlatformLockProfile
+from kivyforge.lock.wheelruntime.resolver import Variant
+from kivyforge.lock.wheelruntime.runtime import RuntimeProvider
+
+from .runtime import DEFAULT_GLIBC_FLOOR, PythonBuildStandaloneProvider
+
+VALID_WHEEL_ARCHS = frozenset({"x86_64"})
+
+# Legacy manylinux aliases and the perennial (PEP 600) glibc minor they map to.
+_LEGACY_ALIASES = {5: "manylinux1", 12: "manylinux2010", 17: "manylinux2014"}
+# manylinux1 (glibc 2.5) is the oldest tag; nothing predates it.
+_MIN_MANYLINUX_MINOR = 5
+
+_PERENNIAL_RE = re.compile(r"^manylinux_(\d+)_(\d+)_(?P<arch>.+)$")
+_LINUX_TAG_RE = re.compile(
+    r"^(?:linux|manylinux1|manylinux2010|manylinux2014|manylinux_\d+_\d+)"
+    r"_(?P<arch>.+)$"
+)
+
+
+def _floor_parts(floor: str) -> tuple[int, int]:
+    """``"2.17"`` -> ``(2, 17)``; tolerant of extra/absent components."""
+    nums = [int(p) for p in re.findall(r"\d+", floor)]
+    major = nums[0] if nums else 2
+    minor = nums[1] if len(nums) > 1 else 0
+    return major, minor
+
+
+def manylinux_platform_tags(floor: str, arch: str) -> tuple[str, ...]:
+    """The pip ``--platform`` tags to request for a glibc *floor* + *arch*.
+
+    Returns the perennial ladder from the floor down to manylinux1 (glibc 2.5),
+    plus the legacy aliases (``manylinux1``/``manylinux2010``/``manylinux2014``)
+    at or below the floor. The floor tag is first (the variant's identity tag).
+    A wheel matching *any* of these runs on a host meeting the floor, so pip —
+    given all tags in one invocation — locks the newest compatible version.
+    """
+    major, minor = _floor_parts(floor)
+    tags: list[str] = []
+    if major == 2:
+        for m in range(minor, _MIN_MANYLINUX_MINOR - 1, -1):
+            tags.append(f"manylinux_{major}_{m}_{arch}")
+        for m, alias in sorted(_LEGACY_ALIASES.items()):
+            if m <= minor:
+                tags.append(f"{alias}_{arch}")
+    else:  # pragma: no cover - no manylinux_3_x exists yet
+        tags.append(f"manylinux_{major}_{minor}_{arch}")
+    return tuple(tags)
+
+
+def linux_wheel_arch(tag: str) -> str | None:
+    """The architecture a single Linux wheel platform (sub)tag targets.
+
+    ``manylinux2014_x86_64`` / ``manylinux_2_17_x86_64`` / ``linux_x86_64`` ->
+    ``x86_64``. ``musllinux_*`` never covers (returns ``None``). A tag that is
+    not a linux tag at all also returns ``None``.
+    """
+    if tag.startswith("musllinux"):
+        return None
+    match = _LINUX_TAG_RE.match(tag)
+    return match.group("arch") if match else None
+
+
+def is_plain_linux_tag(sub_tag: str) -> bool:
+    """A bare ``linux_<arch>`` platform tag (no manylinux/musllinux prefix).
+
+    Plain ``linux_*`` wheels carry **no glibc promise** — the tag says nothing
+    about which glibc the wheel was built against — so a distro-built one tied
+    to a newer glibc would abort the AppImage on older hosts.
+    """
+    return sub_tag.startswith("linux_")
+
+
+def plain_linux_wheel_warning(wheel_name: str, sub_tag: str) -> str:
+    """The mandated warning for accepting a vendored plain ``linux_*`` wheel."""
+    return (
+        f"warning: accepting vendored wheel {wheel_name} on its {sub_tag} tag; "
+        f"plain linux_* wheels make no glibc promise, so the AppImage may fail "
+        f"on hosts with an older glibc than this wheel's build host. Portability "
+        f"is your call (prefer a manylinux-tagged wheel where available)."
+    )
+
+
+def linux_wheel_coverage(wheel, archs: tuple[str, ...]) -> tuple[set[str], str | None]:
+    """Archs a locked *wheel* covers on Linux, plus an optional warning.
+
+    A manylinux/legacy tag covers its arch unconditionally. A plain
+    ``linux_<arch>`` tag covers **only when the wheel is vendored via
+    find_links** (``wheel.path`` is set) — a plain wheel pulled from
+    PyPI/an extra index makes no glibc promise and does *not* count toward
+    coverage — and yields the mandated warning when it does.
+    """
+    from_find_links = wheel.path is not None
+    covered: set[str] = set()
+    warning: str | None = None
+    for sub in wheel.platform_tag.split("."):
+        arch = linux_wheel_arch(sub)
+        if arch not in archs:
+            continue
+        if is_plain_linux_tag(sub):
+            if from_find_links:
+                covered.add(arch)
+                warning = plain_linux_wheel_warning(wheel.name, sub)
+        else:
+            covered.add(arch)
+    return covered, warning
+
+
+def _subtag_glibc_level(tag: str) -> tuple[int, int] | None:
+    """The (major, minor) glibc a single manylinux sub-tag requires, or None."""
+    if tag.startswith("musllinux"):
+        return None
+    match = _PERENNIAL_RE.match(tag)
+    if match:
+        return int(match.group(1)), int(match.group(2))
+    if tag.startswith("manylinux1_"):
+        return 2, 5
+    if tag.startswith("manylinux2010_"):
+        return 2, 12
+    if tag.startswith("manylinux2014_"):
+        return 2, 17
+    return None  # plain linux_* makes no glibc promise
+
+
+def wheel_glibc_level(platform_tag: str) -> tuple[int, int] | None:
+    """The glibc a wheel requires = the *lowest* level among its sub-tags.
+
+    A compound (dot-joined) tag declares the wheel valid under any of its
+    platforms, so its real requirement is the least demanding one.
+    """
+    levels = [
+        lvl
+        for sub in platform_tag.split(".")
+        if (lvl := _subtag_glibc_level(sub)) is not None
+    ]
+    return min(levels) if levels else None
+
+
+def effective_glibc_floor(lock: WheelRuntimeLock) -> str:
+    """The artifact's true host glibc requirement (derived, linux-spec).
+
+    ``max(runtime floor, highest locked wheel manylinux level)``. Computed on
+    demand from the locked wheels for ``doctor``/docs rather than stored as a
+    distinct lock field, keeping the shared lock model platform-agnostic.
+    """
+    floor = _floor_parts(lock.python_runtime.floor or DEFAULT_GLIBC_FLOOR)
+    for pkg in lock.packages:
+        for wheel in pkg.wheels:
+            level = wheel_glibc_level(wheel.platform_tag)
+            if level is not None and level > floor:
+                floor = level
+    return f"{floor[0]}.{floor[1]}"
+
+
+class LinuxProfile(PlatformLockProfile):
+    platform = "linux"
+
+    def overlay(self, config: Config):
+        return config.linux
+
+    def missing_overlay_error(self) -> str:
+        return "pyproject.toml has no [tool.kivy.linux] table; nothing to lock."
+
+    def python_version(self, config: Config) -> str:
+        # [tool.kivy.linux.python].version is required (the loader raises a
+        # ConfigError when it is missing), so it is always set here. Never
+        # silently substitute a hidden default — that would pin an unexpected
+        # (and possibly unreleased) Python instead of surfacing the misconfig.
+        version = config.linux_required.python_version
+        if not version:
+            raise ConfigError(
+                "missing required [tool.kivy.linux.python].version",
+                key_path="tool.kivy.linux.python.version",
+            )
+        return version
+
+    def _floor(self, config: Config) -> str:
+        return config.linux_required.glibc_floor or DEFAULT_GLIBC_FLOOR
+
+    def variants(self, config: Config) -> tuple[Variant, ...]:
+        floor = self._floor(config)
+        variants: list[Variant] = []
+        for arch in config.linux_required.archs:
+            tags = manylinux_platform_tags(floor, arch)
+            variants.append(
+                Variant(
+                    arch=arch,
+                    platform_tag=tags[0],
+                    extra_platform_tags=tags[1:],
+                )
+            )
+        return tuple(variants)
+
+    def wheel_covers(self, platform_tag: str, archs: tuple[str, ...]) -> set[str]:
+        covered: set[str] = set()
+        for sub in platform_tag.split("."):
+            arch = linux_wheel_arch(sub)
+            if arch in archs:
+                covered.add(arch)
+        return covered
+
+    def wheel_coverage(
+        self, wheel, archs: tuple[str, ...]
+    ) -> tuple[set[str], str | None]:
+        # Source-gate plain linux_* wheels (accepted only from find_links) and
+        # emit the mandated no-glibc-promise warning (linux-spec coverage rule).
+        return linux_wheel_coverage(wheel, archs)
+
+    def runtime_provider(self, config: Config) -> RuntimeProvider:
+        return PythonBuildStandaloneProvider()
+
+    def declared_floor(self, config: Config) -> str | None:
+        return config.linux_required.glibc_floor
+
+    def coverage_error(self, name: str, missing: list[str]) -> str:
+        return (
+            f"{name} has no manylinux wheel for arch(es): {', '.join(missing)} at "
+            f"the configured glibc floor.\n"
+            f"  A compiled package must publish a manylinux wheel that runs on the "
+            f"floor to be locked reproducibly.\n"
+            f"  Raise [tool.kivy.linux].glibc_floor to admit a newer-manylinux "
+            f"wheel, or supply the wheel via extra_index_urls/find_links."
+        )
+
+    def floor_error(self, declared: str, runtime_floor: str, version: str) -> str:
+        return (
+            f"glibc_floor {declared} is below the glibc {runtime_floor} floor "
+            f"required by the python-build-standalone {version} runtime.\n"
+            f"  Raise [tool.kivy.linux].glibc_floor to at least {runtime_floor}."
+        )
+
+    def wheel_scope_hint(self) -> str:
+        return (
+            "Vendored wheels must live under the project directory, a sibling "
+            "directory, or the enclosing repository (e.g. a wheels/ directory "
+            "beside pyproject.toml)."
+        )

kivyforge/platforms/linux/lock/runtime.py

@@ -0,0 +1,75 @@
+"""Linux runtime provider — python-build-standalone with linux-gnu triples.
+
+A one-line specialization of the generic :class:`PbsProvider`: it fixes the
+arch→target-triple map to Linux's baseline ``*-unknown-linux-gnu`` builds (not
+the ``_v2``/``_v3`` microarchitecture variants), and otherwise inherits the
+shared PBS resolution + injectable metadata fetcher. The linux-gnu
+``install_only`` archives share the same relocatable unix-prefix layout as the
+darwin ones, so no patchelf pass is needed (linux-spec).
+"""
+
+from __future__ import annotations
+
+from kivyforge.lock.wheelruntime.runtime import (
+    MetadataFetcher,
+    PbsProvider,
+    ReleaseAsset,
+    RuntimeProvider,
+    RuntimeProviderError,
+    pbs_asset_glob,
+)
+
+__all__ = [
+    "LINUX_TRIPLES",
+    "PythonBuildStandaloneProvider",
+    "ReleaseAsset",
+    "RuntimeProvider",
+    "RuntimeProviderError",
+    "get_runtime_provider",
+    "pbs_asset_name",
+]
+
+# The manylinux2014-class glibc floor PBS's linux-gnu builds inherit from their
+# build host. Recorded on the runtime so the lock/doctor can state (and the
+# builder can validate against) the artifact's host requirement.
+#
+# IMPORTANT — this is a *pinned assumption* about PBS's build baseline, not a
+# value derived from inspecting the resolved artifact. PBS's ``install_only``
+# archives carry no structured glibc metadata, and `kivyforge lock` records only
+# the artifact URL + SHA-256 (it does not download the runtime), so there is
+# nothing to derive from at lock time. This constant is versioned with kivyforge:
+# if PBS ever raises its linux-gnu baseline above 2.17, THIS VALUE MUST BE
+# BUMPED IN LOCKSTEP, otherwise the lock/doctor would advertise a floor the
+# binary no longer meets. (A deeper, deferred safeguard would ELF-inspect the
+# staged ``bin/python3`` version-needs at build time to prove the floor.)
+DEFAULT_GLIBC_FLOOR = "2.17"
+
+# kivyforge arch name -> PBS/LLVM linux target triple (baseline microarch).
+LINUX_TRIPLES = {
+    "x86_64": "x86_64-unknown-linux-gnu",
+}
+
+# Linux-facing alias for the generic PBS asset glob helper.
+pbs_asset_name = pbs_asset_glob
+
+
+class PythonBuildStandaloneProvider(PbsProvider):
+    """PBS provider fixed to Linux gnu triples (glibc 2.17 floor by default)."""
+
+    def __init__(
+        self,
+        metadata_fetcher: MetadataFetcher | None = None,
+        *,
+        floor: str | None = DEFAULT_GLIBC_FLOOR,
+    ) -> None:
+        super().__init__(LINUX_TRIPLES, metadata_fetcher, floor=floor)
+
+
+def get_runtime_provider(
+    name: str = "python-build-standalone", **kwargs
+) -> RuntimeProvider:
+    if name in ("python-build-standalone", "pbs", "python_build_standalone"):
+        return PythonBuildStandaloneProvider(**kwargs)
+    raise RuntimeProviderError(
+        f"unknown runtime provider {name!r} (expected python-build-standalone)"
+    )

kivyforge/platforms/linux/native_stage.py

@@ -0,0 +1,47 @@
+"""Stage locked native binaries into the AppDir's ``usr/bin`` (linux-spec).
+
+The ``[tool.kivy.linux.native.binaries]`` channel: each entry is fetched +
+SHA-256-verified from ``pylock.linux.toml`` (URL or vendored path), then staged
+into ``usr/bin`` — a single native file copied in with its exec bit set, or a
+``.zip`` / ``.tar.gz`` / ``.tgz`` of several extracted with a path-traversal
+guard. The directory is created only when the lock actually pins binaries (no
+empty ``bin/``). AppRun exposes ``usr/bin`` on ``PATH`` (helpers by name) and
+appends it to ``LD_LIBRARY_PATH`` (libraries by soname).
+
+The staging mechanics live in the shared
+:mod:`kivyforge.artifacts.native_stage_util`; this module is the Linux-facing
+wrapper that translates the neutral :class:`NativeStageError` into
+``AppDirError``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.native_stage_util import NativeStageError, stage_binaries
+
+from . import AppDirError
+from .lock import LinuxLockfile
+
+
+def stage_native_binaries(
+    lock: LinuxLockfile,
+    usr_dir: Path,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+) -> None:
+    """Stage every pinned native binary for the lock into ``usr_dir/bin``."""
+    try:
+        stage_binaries(
+            lock.native_binaries,
+            usr_dir,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+            bin_label="usr/bin",
+        )
+    except NativeStageError as exc:
+        raise AppDirError(str(exc)) from exc