kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/ios/xcode/runner.py

@@ -0,0 +1,316 @@
+"""Process execution + simctl/devicectl command builders (spec 05 run/open).
+
+``run_command`` is the single execution funnel (injectable for tests). The
+simctl/devicectl builders are pure argv factories so the run sequence is
+unit-testable without a simulator or device.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class CommandError(Exception):
+    """A spawned tool exited non-zero."""
+
+    def __init__(self, argv: list[str], returncode: int, output: str = "") -> None:
+        self.argv = argv
+        self.returncode = returncode
+        self.output = output
+        super().__init__(
+            f"command failed ({returncode}): {' '.join(argv)}"
+            + (f"\n{output}" if output else "")
+        )
+
+
+def run_command(argv: list[str], *, runner=subprocess.run, check: bool = True):
+    proc = runner(argv, capture_output=True, text=True)
+    if check and proc.returncode != 0:
+        # xcodebuild routes destination-matching notes/warnings to stderr but
+        # the actual `error:` diagnostics (signing, compile failures, ...) to
+        # stdout — picking only one stream (whichever is non-empty) can hide
+        # the real failure reason behind a harmless warning. Keep both.
+        output = "\n".join(part for part in (proc.stdout, proc.stderr) if part)
+        raise CommandError(argv, proc.returncode, output)
+    return proc
+
+
+def open_command(xcodeproj: str | Path) -> list[str]:
+    return ["open", str(xcodeproj)]
+
+
+# ---- simulator (simctl) -------------------------------------------------
+
+
+def simctl_boot(destination: str) -> list[str]:
+    return ["xcrun", "simctl", "boot", destination]
+
+
+def simctl_install(destination: str, app_path: str | Path) -> list[str]:
+    return ["xcrun", "simctl", "install", destination, str(app_path)]
+
+
+def simctl_launch(
+    destination: str, bundle_id: str, *, console: bool = True
+) -> list[str]:
+    cmd = ["xcrun", "simctl", "launch"]
+    if console:
+        cmd.append("--console-pty")
+    cmd += [destination, bundle_id]
+    return cmd
+
+
+def simctl_list() -> list[str]:
+    return ["xcrun", "simctl", "list", "devices", "available"]
+
+
+def simctl_list_json(*, state: str = "available") -> list[str]:
+    return ["xcrun", "simctl", "list", "devices", state, "-j"]
+
+
+def open_simulator_app() -> list[str]:
+    return ["open", "-a", "Simulator"]
+
+
+@dataclass(frozen=True)
+class SimulatorDevice:
+    udid: str
+    name: str
+    state: str
+    runtime: str
+
+
+def parse_simctl_devices(payload: dict) -> list[SimulatorDevice]:
+    """Flatten ``simctl list devices … -j`` output into a single device list."""
+    devices: list[SimulatorDevice] = []
+    for runtime_key, entries in payload.get("devices", {}).items():
+        runtime = _runtime_label(runtime_key)
+        for entry in entries:
+            if not entry.get("isAvailable", True):
+                continue
+            devices.append(
+                SimulatorDevice(
+                    udid=entry["udid"],
+                    name=entry["name"],
+                    state=entry.get("state", "Shutdown"),
+                    runtime=runtime,
+                )
+            )
+    return devices
+
+
+def pick_simulator(
+    devices: list[SimulatorDevice], destination: str | None = None
+) -> SimulatorDevice:
+    """Choose a simulator by explicit destination, booted state, or best default."""
+    if not devices:
+        raise CommandError(
+            ["simctl"],
+            1,
+            "no iOS simulators available (install one in Xcode > Settings > Components)",
+        )
+    if destination:
+        return _match_simulator(devices, destination)
+    booted = [d for d in devices if d.state == "Booted"]
+    if booted:
+        return booted[0]
+    iphones = [d for d in devices if "iphone" in d.name.lower()]
+    return max(iphones or devices, key=_default_simulator_sort_key)
+
+
+def resolve_simulator_destination(
+    destination: str | None,
+    *,
+    runner=subprocess.run,
+) -> SimulatorDevice:
+    """Return the simulator to target, booting a default when none is running."""
+    proc = run_command(simctl_list_json(), runner=runner)
+    devices = parse_simctl_devices(json.loads(proc.stdout))
+    device = pick_simulator(devices, destination)
+    if device.state != "Booted":
+        run_command(simctl_boot(device.udid), runner=runner, check=False)
+        run_command(open_simulator_app(), runner=runner, check=False)
+    return device
+
+
+def _match_simulator(
+    devices: list[SimulatorDevice], destination: str
+) -> SimulatorDevice:
+    dest = destination.lower()
+    for device in devices:
+        if device.udid.lower() == dest:
+            return device
+    for device in devices:
+        if device.name.lower() == dest:
+            return device
+    for device in devices:
+        if dest in device.name.lower():
+            return device
+    raise CommandError(
+        ["simctl"],
+        1,
+        f"no simulator matches {destination!r} (run `kivyforge run --list-devices`)",
+    )
+
+
+def _runtime_label(runtime_key: str) -> str:
+    # com.apple.CoreSimulator.SimRuntime.iOS-26-5 -> 26.5
+    tail = runtime_key.rsplit(".", 1)[-1]
+    if tail.startswith("iOS-"):
+        return tail[4:].replace("-", ".")
+    return tail
+
+
+def _default_simulator_sort_key(device: SimulatorDevice) -> tuple:
+    parts: list[int] = []
+    for piece in device.runtime.split("."):
+        try:
+            parts.append(int(piece))
+        except ValueError:
+            parts.append(0)
+    return (tuple(parts), device.name)
+
+
+# ---- device (devicectl) -------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Device:
+    identifier: str
+    name: str
+    platform: str
+    tunnel_state: str
+    pairing_state: str
+
+
+def parse_devicectl_devices(payload: dict) -> list[Device]:
+    """Flatten ``devicectl list devices -j`` output into a device list."""
+    devices: list[Device] = []
+    for entry in payload.get("result", {}).get("devices", []):
+        props = entry.get("deviceProperties", {})
+        hardware = entry.get("hardwareProperties", {})
+        connection = entry.get("connectionProperties", {})
+        devices.append(
+            Device(
+                identifier=entry["identifier"],
+                name=props.get("name", entry["identifier"]),
+                platform=hardware.get("platform", "unknown"),
+                tunnel_state=connection.get("tunnelState", "disconnected"),
+                pairing_state=connection.get("pairingState", "unpaired"),
+            )
+        )
+    return devices
+
+
+def pick_device(devices: list[Device], destination: str | None = None) -> Device:
+    """Choose a device by explicit destination, or the sole paired iPhone/iPad.
+
+    ``tunnelState`` only reports ``"connected"`` while some CoreDevice client
+    (normally Xcode) already has a tunnel open to the device — it stays
+    ``"disconnected"`` for a device that is plugged in and paired but idle,
+    e.g. when Xcode isn't running. ``devicectl install``/``launch`` establish
+    the tunnel themselves on demand, so a paired device is a valid target
+    regardless of ``tunnelState``.
+    """
+    if destination:
+        if not devices:
+            raise CommandError(
+                ["devicectl"],
+                1,
+                "no iOS devices found (connect one via USB/Wi-Fi and trust "
+                "this Mac, then run `kivyforge run --list-devices`)",
+            )
+        return _match_device(devices, destination)
+    # No explicit destination: only consider paired iOS devices — unpaired
+    # accessories or devices that are merely discoverable don't qualify.
+    paired = [d for d in devices if d.platform == "iOS" and d.pairing_state == "paired"]
+    if len(paired) == 1:
+        return paired[0]
+    if not paired:
+        raise CommandError(
+            ["devicectl"],
+            1,
+            "no paired iOS device found (connect it via USB/Wi-Fi and trust "
+            "this Mac, then run `kivyforge run --list-devices`)",
+        )
+    names = ", ".join(f"{d.name!r}" for d in paired)
+    raise CommandError(
+        ["devicectl"],
+        1,
+        f"multiple paired iOS devices found ({names}) — pass one "
+        "explicitly, e.g. `kivyforge run --device --destination 'NAME'`",
+    )
+
+
+def _match_device(devices: list[Device], destination: str) -> Device:
+    dest = destination.lower()
+    for device in devices:
+        if device.identifier.lower() == dest:
+            return device
+    for device in devices:
+        if device.name.lower() == dest:
+            return device
+    for device in devices:
+        if dest in device.name.lower():
+            return device
+    raise CommandError(
+        ["devicectl"],
+        1,
+        f"no device matches {destination!r} (run `kivyforge run --list-devices`)",
+    )
+
+
+def devicectl_list_json(output_path: str | Path) -> list[str]:
+    return ["xcrun", "devicectl", "list", "devices", "-j", str(output_path)]
+
+
+def resolve_device_destination(
+    destination: str | None,
+    *,
+    runner=subprocess.run,
+) -> Device:
+    """Return the physical device to target for ``--device`` install/launch."""
+    with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as fh:
+        output_path = Path(fh.name)
+    try:
+        run_command(devicectl_list_json(output_path), runner=runner)
+        # devicectl writes JSON as UTF-8 (device names may be non-ASCII).
+        payload = json.loads(output_path.read_text(encoding="utf-8"))
+    finally:
+        output_path.unlink(missing_ok=True)
+    devices = parse_devicectl_devices(payload)
+    return pick_device(devices, destination)
+
+
+def devicectl_install(destination: str, app_path: str | Path) -> list[str]:
+    return [
+        "xcrun",
+        "devicectl",
+        "device",
+        "install",
+        "app",
+        "--device",
+        destination,
+        str(app_path),
+    ]
+
+
+def devicectl_launch(destination: str, bundle_id: str) -> list[str]:
+    return [
+        "xcrun",
+        "devicectl",
+        "device",
+        "process",
+        "launch",
+        "--device",
+        destination,
+        bundle_id,
+    ]
+
+
+def devicectl_list() -> list[str]:
+    return ["xcrun", "devicectl", "list", "devices"]

kivyforge/platforms/linux/__init__.py

@@ -0,0 +1,120 @@
+"""Linux platform backend.
+
+Produces a self-contained AppDir and, by default, an AppImage (linux-spec).
+Linux is the host default on Linux, so a Linux box with ``[tool.kivy.linux]``
+configured resolves to this backend without ``-p``. It requires a Linux host:
+the bundled python-build-standalone runtime is a gnu/glibc ELF build.
+"""
+
+from __future__ import annotations
+
+import platform as _platform
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ..base import HostCapabilityError, Platform
+
+if TYPE_CHECKING:
+    from kivyforge.doctor.result import CheckResult
+
+
+class AppDirError(Exception):
+    """A Linux AppDir bundling failure surfaced with an actionable message."""
+
+
+class LinuxPlatform(Platform):
+    name = "linux"
+    # Linux is a desktop target built on its own OS, so Linux maps to it as the
+    # host default (resolution-chain step 3).
+    host_system = "Linux"
+    # AppImage is the primary distributable; the AppDir folder is the substrate.
+    package_formats = ("appimage", "folder")
+
+    def check_host_capability(self, *, host_system: str | None = None) -> None:
+        host = host_system if host_system is not None else _platform.system()
+        if host != "Linux":
+            raise HostCapabilityError(
+                "building for Linux requires a Linux host; "
+                f"this host is {host!r}.\n"
+                "  The AppDir bundles a python-build-standalone gnu/glibc runtime "
+                "and runs the app against the host's libGL/X11/Wayland.\n"
+                "  Run `kivyforge doctor -p linux` on a Linux box to check the "
+                "setup."
+            )
+
+    def build(
+        self,
+        project_root: Path,
+        *,
+        target: str | None,
+        arch: str | None,
+        no_verify_lock: bool,
+        no_cache: bool,
+        team_id: str | None,
+        signing_identity: str | None,
+        export_method: str,
+        debug: bool = False,
+        fmt: str | None = None,
+        abi: str | None = None,
+    ) -> None:
+        self.reject_ios_only_target(target)
+        from .cli import linux_build
+
+        linux_build(
+            project_root,
+            arch=arch,
+            no_verify_lock=no_verify_lock,
+            no_cache=no_cache,
+        )
+
+    def run(
+        self,
+        project_root: Path,
+        *,
+        target: str,
+        arch: str | None,
+        destination: str | None,
+        no_build: bool,
+    ) -> None:
+        from .cli import linux_run
+
+        linux_run(project_root, arch=arch, no_build=no_build)
+
+    def package(
+        self,
+        project_root: Path,
+        *,
+        fmt: str,
+        arch: str | None,
+        team_id: str | None,
+        signing_identity: str | None,
+        export_method: str,
+        notarize: bool | None,
+        notary_profile: str | None,
+        no_verify_lock: bool,
+        no_cache: bool,
+        abi: str | None = None,
+        keystore: str | None = None,
+        key_alias: str | None = None,
+    ) -> None:
+        from .cli import linux_package
+
+        linux_package(
+            project_root,
+            fmt=fmt,
+            arch=arch,
+            no_verify_lock=no_verify_lock,
+            no_cache=no_cache,
+        )
+
+    def status(self, project_root: Path) -> None:
+        from .cli import linux_status
+
+        linux_status(project_root)
+
+    def doctor(
+        self, cwd: Path, *, kivyforge_version: str, offline: bool
+    ) -> list[CheckResult]:
+        from .doctor import linux_doctor
+
+        return linux_doctor(cwd, kivyforge_version=kivyforge_version, offline=offline)

kivyforge/platforms/linux/appimage.py

@@ -0,0 +1,169 @@
+"""Wrap an AppDir into a single ``.AppImage`` (linux-spec, Step 5).
+
+Acquires two **pinned build tools** through the shared ``kivyforge/artifacts``
+download / cache / SHA-256-verify machinery — a static ``appimagetool`` and a
+type2 **static-FUSE** runtime file — then runs ``appimagetool --runtime-file``
+to produce the output. Embedding a static-FUSE runtime means the *shipped*
+AppImage needs no host ``libfuse2`` *package* (it does still use the kernel's
+``/dev/fuse`` to self-mount unless run with ``--appimage-extract-and-run``);
+invoking appimagetool with ``APPIMAGE_EXTRACT_AND_RUN=1`` means the *build host*
+needs no FUSE at all (WSL2 / containers / CI just work).
+
+The pins are constants here (versioned with kivyforge releases): they are build
+tools, not app dependencies, so they never enter the app's lockfile.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.download import DownloadError, fetch_artifact
+
+from . import AppDirError
+
+# Pinned appimagetool (AppImage/appimagetool) and type2 static-FUSE runtime
+# (AppImage/type2-runtime). Per-arch so aarch64 is purely additive later.
+APPIMAGETOOL_VERSION = "1.9.1"
+TYPE2_RUNTIME_VERSION = "20251108"
+
+_APPIMAGETOOL = {
+    "x86_64": (
+        "https://github.com/AppImage/appimagetool/releases/download/"
+        f"{APPIMAGETOOL_VERSION}/appimagetool-x86_64.AppImage",
+        "ed4ce84f0d9caff66f50bcca6ff6f35aae54ce8135408b3fa33abfc3cb384eb0",
+    ),
+}
+
+_TYPE2_RUNTIME = {
+    "x86_64": (
+        "https://github.com/AppImage/type2-runtime/releases/download/"
+        f"{TYPE2_RUNTIME_VERSION}/runtime-x86_64",
+        "2fca8b443c92510f1483a883f60061ad09b46b978b2631c807cd873a47ec260d",
+    ),
+}
+
+
+def appimagetool_asset(arch: str) -> tuple[str, str]:
+    """The (url, sha256) for the pinned appimagetool for *arch*."""
+    try:
+        return _APPIMAGETOOL[arch]
+    except KeyError:
+        raise AppDirError(
+            f"no pinned appimagetool for arch {arch!r} "
+            f"(have: {', '.join(sorted(_APPIMAGETOOL))})."
+        ) from None
+
+
+def type2_runtime_asset(arch: str) -> tuple[str, str]:
+    """The (url, sha256) for the pinned type2 static-FUSE runtime for *arch*."""
+    try:
+        return _TYPE2_RUNTIME[arch]
+    except KeyError:
+        raise AppDirError(
+            f"no pinned type2 runtime for arch {arch!r} "
+            f"(have: {', '.join(sorted(_TYPE2_RUNTIME))})."
+        ) from None
+
+
+def build_appimage(
+    appdir: Path,
+    output: Path,
+    arch: str,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+    echo=lambda *a: None,
+) -> Path:
+    """Package *appdir* into an ``.AppImage`` at *output*; return *output*."""
+    cache = cache or ArtifactCache()
+    tool = _acquire(
+        appimagetool_asset(arch),
+        f"appimagetool-{APPIMAGETOOL_VERSION}-{arch}.AppImage",
+        "appimagetool",
+        project_root,
+        cache,
+        no_cache,
+    )
+    runtime = _acquire(
+        type2_runtime_asset(arch),
+        f"appimage-runtime-{TYPE2_RUNTIME_VERSION}-{arch}",
+        "type2 runtime",
+        project_root,
+        cache,
+        no_cache,
+    )
+    # appimagetool must be executable; run it from a copy so the
+    # content-addressed cache entry is never mutated.
+    tool = _executable_copy(tool, cache)
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    # Emit to a temp file and swap it in only on success, so a tool failure (or
+    # crash) leaves any previous .AppImage intact rather than deleting it up
+    # front — the write-in-place guarantee the other platforms also uphold.
+    tmp_out = output.parent / f".{output.name}.tmp-{os.getpid()}"
+    tmp_out.unlink(missing_ok=True)
+
+    echo(f"Packaging {output.name} with appimagetool {APPIMAGETOOL_VERSION} ...")
+    env = {
+        **os.environ,
+        "ARCH": arch,
+        # No FUSE on the build host: appimagetool extracts + runs itself.
+        "APPIMAGE_EXTRACT_AND_RUN": "1",
+    }
+    cmd = [
+        str(tool),
+        "--runtime-file",
+        str(runtime),
+        str(appdir),
+        str(tmp_out),
+    ]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, env=env)
+    except OSError as exc:
+        tmp_out.unlink(missing_ok=True)
+        raise AppDirError(f"failed to run appimagetool: {exc}") from exc
+    if proc.returncode != 0:
+        tmp_out.unlink(missing_ok=True)
+        raise AppDirError(
+            "appimagetool failed to build the AppImage.\n"
+            f"  {(proc.stderr or proc.stdout).strip()}"
+        )
+    tmp_out.chmod(0o755)
+    os.replace(tmp_out, output)
+    return output
+
+
+def _acquire(
+    asset: tuple[str, str],
+    filename: str,
+    label: str,
+    project_root: Path,
+    cache: ArtifactCache,
+    no_cache: bool,
+) -> Path:
+    url, sha256 = asset
+    try:
+        return fetch_artifact(
+            name=label,
+            sha256=sha256,
+            filename=filename,
+            url=url,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+    except DownloadError as exc:
+        raise AppDirError(str(exc)) from exc
+
+
+def _executable_copy(tool: Path, cache: ArtifactCache) -> Path:
+    exec_copy = cache.root.parent / "bin" / tool.name
+    exec_copy.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(tool, exec_copy)
+    exec_copy.chmod(0o755)
+    return exec_copy