kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/ios/xcframeworks.py

@@ -0,0 +1,194 @@
+"""Wire ``Frameworks/*.xcframework`` into the generated ``.xcodeproj`` (spec 06).
+
+``kivyforge build`` runs ``sync_native_frameworks`` as part of the every-build,
+idempotent project sync. For each ``.xcframework`` staged under ``Frameworks/``
+it ensures a file reference (under the ``Frameworks`` group) and then wires the
+**link** and **embed** phases independently:
+
+* ``link``  -> a build file in the Frameworks (Link Binary) phase,
+* ``embed`` -> a build file in the Embed Frameworks (Copy Files) phase, with
+  ``CodeSignOnCopy``.
+
+The link/embed intent comes from the locked ``[[tool.kivyforge.xcframeworks]]``
+entries (keyed by framework name). Wheel-embedded frameworks (SDL3/ANGLE, etc.)
+have no lock entry and default to Embed & Sign (link + embed), preserving prior
+behavior. Reconciliation is full each run, so flipping ``link``/``embed`` in the
+lock removes the now-unwanted build file. Finally, references for frameworks no
+longer present on disk are pruned so a removed dependency does not linger in the
+project as a dangling reference.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pbxproj.pbxextensions.ProjectFiles import FileOptions, TreeType
+from pbxproj.pbxsections.PBXBuildFile import PBXBuildFile
+
+# pbxproj ships no type stubs and builds objects dynamically (PBXGenericObject),
+# so the project graph is treated as ``Any`` throughout this interop module.
+
+# PBXCopyFilesBuildPhase destination for frameworks (Embed Frameworks).
+FRAMEWORKS_DST_SUBFOLDER_SPEC = "10"
+
+
+def sync_native_frameworks(
+    project: Any,
+    target_name: str,
+    *,
+    frameworks_dir: Path,
+    frameworks_group: Any,
+    link_embed: dict[str, tuple[bool, bool]],
+) -> None:
+    """Reconcile ``Frameworks/*.xcframework`` refs + link/embed phases with disk.
+
+    ``link_embed`` maps a framework's on-disk stem (e.g. ``"Sentry"`` for
+    ``Sentry.xcframework``) to ``(link, embed)``. Frameworks not present in the
+    map default to ``(True, True)``.
+    """
+    if frameworks_dir.is_dir():
+        for xc in sorted(frameworks_dir.glob("*.xcframework")):
+            rel = f"Frameworks/{xc.name}"
+            ref = _ensure_file_ref(project, rel, target_name, frameworks_group)
+            if ref is None:
+                continue
+            link, embed = link_embed.get(xc.stem, (True, True))
+            if link:
+                _ensure_link(project, target_name, ref)
+            else:
+                _remove_build_files(project, ref.get_id(), "PBXFrameworksBuildPhase")
+            if embed:
+                _ensure_embed(project, target_name, ref)
+            else:
+                _remove_build_files(project, ref.get_id(), "PBXCopyFilesBuildPhase")
+    _prune(project, frameworks_dir)
+
+
+# -- file reference ------------------------------------------------------------ #
+
+
+def _ensure_file_ref(
+    project: Any, rel: str, target_name: str, group: Any
+) -> Any | None:
+    existing = project.get_files_by_path(rel, tree=TreeType.SOURCE_ROOT)
+    if existing:
+        ref = existing[0]
+        _ensure_under_group(project, ref, group)
+        return ref
+    # First add: let pbxproj create the file reference, place it under the group,
+    # and register the framework search path. It also creates default link+embed
+    # build files; the caller's reconciliation trims them to the lock's intent.
+    project.add_file(
+        rel,
+        parent=group,
+        target_name=target_name,
+        tree=TreeType.SOURCE_ROOT,
+        file_options=FileOptions(embed_framework=True, code_sign_on_copy=True),
+    )
+    refs = project.get_files_by_path(rel, tree=TreeType.SOURCE_ROOT)
+    if not refs:
+        return None
+    ref = refs[0]
+    _ensure_under_group(project, ref, group)
+    return ref
+
+
+def _ensure_under_group(project: Any, file_ref: Any, group: Any) -> None:
+    """Move an existing file reference under ``group`` (idempotent)."""
+    if group.has_child(file_ref):
+        return
+    for grp in project.objects.get_objects_in_section("PBXGroup"):
+        if grp.has_child(file_ref):
+            grp.remove_child(file_ref)
+    group.add_child(file_ref)
+
+
+# -- link / embed build files -------------------------------------------------- #
+
+
+def _ensure_link(project: Any, target_name: str, file_ref: Any) -> None:
+    phase = _link_phase(project, target_name)
+    if phase is None or _has_build_file(project, phase, file_ref.get_id()):
+        return
+    build_file: Any = PBXBuildFile.create(file_ref)
+    project.objects[build_file.get_id()] = build_file
+    phase.add_build_file(build_file)
+
+
+def _ensure_embed(project: Any, target_name: str, file_ref: Any) -> None:
+    phase = _embed_phase(project, target_name)
+    if _has_build_file(project, phase, file_ref.get_id()):
+        return
+    build_file: Any = PBXBuildFile.create(file_ref, attributes=["CodeSignOnCopy"])
+    project.objects[build_file.get_id()] = build_file
+    phase.add_build_file(build_file)
+
+
+def _link_phase(project: Any, target_name: str) -> Any:
+    target = project.get_target_by_name(target_name)
+    if target is None:
+        return None
+    phases = target.get_or_create_build_phase("PBXFrameworksBuildPhase")
+    return phases[0] if phases else None
+
+
+def _embed_phase(project: Any, target_name: str) -> Any:
+    target = project.get_target_by_name(target_name)
+    if target is None:
+        raise RuntimeError(f"target {target_name!r} not found in Xcode project")
+    phases = target.get_or_create_build_phase(
+        "PBXCopyFilesBuildPhase",
+        search_parameters={"dstSubfolderSpec": FRAMEWORKS_DST_SUBFOLDER_SPEC},
+        create_parameters=(
+            "Embed Frameworks",
+            [],
+            "",
+            FRAMEWORKS_DST_SUBFOLDER_SPEC,
+        ),
+    )
+    return phases[0]
+
+
+def _has_build_file(project: Any, phase: Any, ref_id: str) -> bool:
+    for build_file_id in phase["files"]:
+        build_file = project.objects[build_file_id]
+        if _file_ref(build_file) == ref_id:
+            return True
+    return False
+
+
+def _remove_build_files(project: Any, ref_id: str, section: str) -> None:
+    for phase in project.objects.get_objects_in_section(section):
+        for build_file_id in list(phase["files"]):
+            build_file = project.objects[build_file_id]
+            if _file_ref(build_file) == ref_id:
+                phase.remove_build_file(build_file)
+
+
+def _file_ref(build_file: Any) -> str | None:
+    return build_file["fileRef"] if "fileRef" in build_file else None
+
+
+# -- pruning ------------------------------------------------------------------- #
+
+
+def _prune(project: Any, frameworks_dir: Path) -> None:
+    """Remove references for ``Frameworks/*.xcframework`` no longer on disk."""
+    for ref in list(project.objects.get_objects_in_section("PBXFileReference")):
+        path = ref["path"] if "path" in ref else None
+        if (
+            not path
+            or not path.startswith("Frameworks/")
+            or not path.endswith(".xcframework")
+        ):
+            continue
+        name = path.split("/", 1)[1]
+        if not (frameworks_dir / name).is_dir():
+            ref_id = ref.get_id()
+            # Drop the link/embed build files first so remove_file_by_id sees no
+            # remaining references and actually deletes the file reference (it
+            # otherwise short-circuits while any build file still points at it).
+            _remove_build_files(project, ref_id, "PBXFrameworksBuildPhase")
+            _remove_build_files(project, ref_id, "PBXCopyFilesBuildPhase")
+            project.remove_file_by_id(ref_id)

kivyforge/platforms/ios/xcode/__init__.py

@@ -0,0 +1,76 @@
+"""xcodebuild / simctl / devicectl command construction and execution (spec 05).
+
+The command builders are pure functions returning ``argv`` lists (and the
+``ExportOptions.plist`` dict), so they unit-test hermetically. Actual process
+execution funnels through a single injectable ``run`` helper.
+"""
+
+from __future__ import annotations
+
+from .commands import (
+    SigningError,
+    XcodeBuild,
+    archive_command,
+    build_command,
+    default_simulator_arch,
+    export_command,
+    export_options_plist,
+    preflight_signing,
+    product_app_path,
+    resolve_team_id,
+    sdk_for,
+)
+from .runner import (
+    CommandError,
+    Device,
+    SimulatorDevice,
+    devicectl_install,
+    devicectl_launch,
+    devicectl_list,
+    devicectl_list_json,
+    open_command,
+    parse_devicectl_devices,
+    parse_simctl_devices,
+    pick_device,
+    pick_simulator,
+    resolve_device_destination,
+    resolve_simulator_destination,
+    run_command,
+    simctl_boot,
+    simctl_install,
+    simctl_launch,
+    simctl_list,
+)
+
+__all__ = [
+    "XcodeBuild",
+    "SigningError",
+    "build_command",
+    "default_simulator_arch",
+    "archive_command",
+    "export_command",
+    "export_options_plist",
+    "preflight_signing",
+    "product_app_path",
+    "resolve_team_id",
+    "sdk_for",
+    "run_command",
+    "open_command",
+    "CommandError",
+    "SimulatorDevice",
+    "parse_simctl_devices",
+    "pick_simulator",
+    "resolve_simulator_destination",
+    "simctl_boot",
+    "simctl_install",
+    "simctl_launch",
+    "simctl_list",
+    "Device",
+    "devicectl_install",
+    "devicectl_launch",
+    "devicectl_list",
+    "devicectl_list_json",
+    "parse_devicectl_devices",
+    "pick_device",
+    "resolve_device_destination",
+]

kivyforge/platforms/ios/xcode/commands.py

@@ -0,0 +1,296 @@
+"""xcodebuild command + ExportOptions.plist construction (spec 05 step 7).
+
+Pure builders: no subprocess, no filesystem side effects beyond returning the
+argv/plist the caller will execute or write. This keeps the signing pre-flight,
+SDK selection, archive/export pipeline, and export-options mapping fully
+unit-testable on any host.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from kivyforge.config.model import Config
+
+
+def default_simulator_arch() -> str:
+    """The iOS-simulator CPU arch matching the host Mac.
+
+    Apple-Silicon Macs run the simulator as ``arm64``; Intel Macs as ``x86_64``.
+    This is the default when ``--arch`` is not given, so a bare or targeted
+    simulator build collects (and ``xcodebuild`` builds) the slice the developer's
+    own machine can actually run — collecting only ``arm64`` would break the very
+    first simulator build on an Intel host even though the lock pinned ``x86_64``.
+    ``platform.machine()`` reports ``x86_64`` under Rosetta too, which is correct:
+    an x86_64 Python process drives an x86_64 simulator.
+    """
+    return "x86_64" if platform.machine() == "x86_64" else "arm64"
+
+
+# build-target -> xcodebuild SDK.
+SDK = {
+    "simulator": "iphonesimulator",
+    "device": "iphoneos",
+    "release": "iphoneos",
+}
+
+TEAM_ID_ENV = "KIVYFORGE_TEAM_ID"
+SIGNING_IDENTITY_ENV = "KIVYFORGE_SIGNING_IDENTITY"
+
+# --export-method -> ExportOptions.plist `method` value.
+EXPORT_METHOD = {
+    "app-store": "app-store",
+    "ad-hoc": "ad-hoc",
+    "development": "development",
+}
+
+
+class SigningError(Exception):
+    """Code signing is required but no team_id could be resolved."""
+
+
+def sdk_for(target: str) -> str:
+    try:
+        return SDK[target]
+    except KeyError:
+        raise ValueError(f"unknown build target {target!r}") from None
+
+
+def configuration_for(target: str) -> str:
+    return "Release" if target == "release" else "Debug"
+
+
+@dataclass(frozen=True)
+class XcodeBuild:
+    """Locates the generated project for a config under a project root."""
+
+    project_root: Path
+    scheme: str
+
+    @classmethod
+    def from_config(cls, config: Config, project_root: str | Path) -> XcodeBuild:
+        return cls(project_root=Path(project_root), scheme=config.app_slug)
+
+    @property
+    def staging(self) -> Path:
+        return self.project_root / f"{self.scheme}-ios"
+
+    @property
+    def project_path(self) -> Path:
+        return self.staging / f"{self.scheme}.xcodeproj"
+
+    @property
+    def build_dir(self) -> Path:
+        return self.staging / "build"
+
+    @property
+    def archive_path(self) -> Path:
+        return self.build_dir / f"{self.scheme}.xcarchive"
+
+    @property
+    def ipa_path(self) -> Path:
+        return self.build_dir / f"{self.scheme}.ipa"
+
+
+def resolve_team_id(
+    config: Config,
+    *,
+    team_id_flag: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> str | None:
+    """Resolve the effective team_id (flag → env → pyproject), or None."""
+    effective_env: Mapping[str, str] = os.environ if env is None else env
+    candidates = (
+        team_id_flag,
+        effective_env.get(TEAM_ID_ENV),
+        config.ios_required.signing.team_id or None,
+    )
+    for value in candidates:
+        if value:
+            return value
+    return None
+
+
+def resolve_signing_identity(
+    config: Config,
+    *,
+    identity_flag: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> str | None:
+    effective_env: Mapping[str, str] = os.environ if env is None else env
+    for value in (
+        identity_flag,
+        effective_env.get(SIGNING_IDENTITY_ENV),
+        config.ios_required.signing.identity,
+    ):
+        if value:
+            return value
+    return None
+
+
+def preflight_signing(
+    config: Config,
+    target: str,
+    *,
+    team_id_flag: str | None = None,
+    env: dict | None = None,
+) -> str | None:
+    """Fail fast when --device/--release lack a team_id (spec 05 step 7).
+
+    Returns the resolved team_id (None for --simulator, which does not sign).
+    """
+    if target == "simulator":
+        return None
+    team_id = resolve_team_id(config, team_id_flag=team_id_flag, env=env)
+    if not team_id:
+        raise SigningError(
+            "code signing required for --device/--release, but no team_id is set.\n"
+            "  Set it one of these ways:\n"
+            '    - [tool.kivy.ios.signing].team_id = "ABCDE12345" in pyproject.toml, '
+            "then re-lock\n"
+            "    - kivyforge build --release --team-id ABCDE12345\n"
+            "    - export KIVYFORGE_TEAM_ID=ABCDE12345"
+        )
+    return team_id
+
+
+def build_command(
+    xb: XcodeBuild,
+    target: str,
+    *,
+    arch: str | None = None,
+    derived_data_path: str | Path | None = None,
+    signing_identity: str | None = None,
+    allow_provisioning_updates: bool = False,
+) -> list[str]:
+    """`xcodebuild build` argv for --simulator/--device (Debug).
+
+    ``derived_data_path`` pins where the ``.app`` is written so ``kivyforge run``
+    can locate the product deterministically. ``signing_identity`` overrides the
+    project's baked ``CODE_SIGN_IDENTITY`` for device builds (simulator builds are
+    unsigned, so it is ignored there). ``allow_provisioning_updates`` passes
+    ``-allowProvisioningUpdates`` — required for automatic signing to actually
+    register the App ID / fetch or create a matching profile when driven from
+    the command line (Xcode's IDE does this silently; bare ``xcodebuild`` does
+    not unless asked — see "Resolving common notarization issues"-adjacent
+    Apple guidance on ``xcodebuild`` + automatic signing).
+    """
+    cmd = [
+        "xcodebuild",
+        "-project",
+        str(xb.project_path),
+        "-scheme",
+        xb.scheme,
+        "-configuration",
+        configuration_for(target),
+        "-sdk",
+        sdk_for(target),
+    ]
+    if derived_data_path is not None:
+        cmd += ["-derivedDataPath", str(derived_data_path)]
+    # python.org's install_stdlib uses lib-$ARCHS; a universal simulator build
+    # (arm64 x86_64) produces an invalid path. Pin a single arch for CLI builds.
+    if target == "simulator":
+        cmd += [f"ARCHS={arch or default_simulator_arch()}", "ONLY_ACTIVE_ARCH=NO"]
+    else:
+        if signing_identity:
+            cmd.append(f"CODE_SIGN_IDENTITY={signing_identity}")
+        if allow_provisioning_updates:
+            cmd.append("-allowProvisioningUpdates")
+    cmd.append("build")
+    return cmd
+
+
+def product_app_path(derived_data_path: str | Path, scheme: str, target: str) -> Path:
+    """Path to the built ``<scheme>.app`` under a pinned DerivedData dir."""
+    sdk = sdk_for(target)
+    config = configuration_for(target)
+    return (
+        Path(derived_data_path)
+        / "Build"
+        / "Products"
+        / f"{config}-{sdk}"
+        / f"{scheme}.app"
+    )
+
+
+def archive_command(
+    xb: XcodeBuild,
+    *,
+    signing_identity: str | None = None,
+    allow_provisioning_updates: bool = False,
+) -> list[str]:
+    """`xcodebuild archive` argv for --release (step 7.1).
+
+    ``signing_identity`` overrides the project's baked ``CODE_SIGN_IDENTITY`` for
+    the archive's signing step — only pass this for an *explicit* user override;
+    forcing the pyproject default (typically "Apple Development", meant for
+    ``--device`` debug builds) onto a distribution archive requests the wrong
+    profile type and fails. ``allow_provisioning_updates``: see ``build_command``.
+    """
+    cmd = [
+        "xcodebuild",
+        "archive",
+        "-project",
+        str(xb.project_path),
+        "-scheme",
+        xb.scheme,
+        "-configuration",
+        "Release",
+        "-sdk",
+        "iphoneos",
+        "-archivePath",
+        str(xb.archive_path),
+    ]
+    if signing_identity:
+        cmd.append(f"CODE_SIGN_IDENTITY={signing_identity}")
+    if allow_provisioning_updates:
+        cmd.append("-allowProvisioningUpdates")
+    return cmd
+
+
+def export_command(
+    xb: XcodeBuild, options_plist: Path, *, allow_provisioning_updates: bool = False
+) -> list[str]:
+    """`xcodebuild -exportArchive` argv for --release (step 7.2)."""
+    cmd = [
+        "xcodebuild",
+        "-exportArchive",
+        "-archivePath",
+        str(xb.archive_path),
+        "-exportPath",
+        str(xb.build_dir),
+        "-exportOptionsPlist",
+        str(options_plist),
+    ]
+    if allow_provisioning_updates:
+        cmd.append("-allowProvisioningUpdates")
+    return cmd
+
+
+def export_options_plist(
+    *,
+    method: str,
+    team_id: str,
+    upload_symbols: bool = True,
+    signing_identity: str | None = None,
+) -> dict:
+    """Map --export-method + signing to ExportOptions.plist keys (spec 05).
+
+    ``signing_identity`` pins the certificate used to re-sign during export
+    (``-exportArchive``); omitted, Xcode selects one for the export method.
+    """
+    if method not in EXPORT_METHOD:
+        raise ValueError(f"unknown export method {method!r}")
+    options: dict = {
+        "method": EXPORT_METHOD[method],
+        "teamID": team_id,
+        "uploadSymbols": upload_symbols,
+    }
+    if signing_identity:
+        options["signingCertificate"] = signing_identity
+    return options