ipeddle 0.1.0__py3-none-any.whl

ipeddle/__init__.py

@@ -0,0 +1,3 @@
+"""ipeddle: build iOS apps (.ipa) on Linux, no Mac or Xcode required."""
+
+__version__ = "0.1.0"

ipeddle/__main__.py

@@ -0,0 +1,3 @@
+from ipeddle.cli import main
+
+raise SystemExit(main())

ipeddle/build.py

@@ -0,0 +1,309 @@
+"""``ipeddle build``: SwiftPM package -> unsigned .ipa."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import signal
+import subprocess
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import config as appconfig
+from . import package, patcher, proc, ui
+from .errors import IpeddleError
+from .fsutil import locked, private_tmp, rmtree
+from .paths import SWIFT_SDK_ID, TRIPLE, Home
+from .setup import Installation, load_installation
+
+UNDEFINED_RE = re.compile(r"ld64\.lld: error: undefined symbol: (\S+)")
+NOISE = (
+    "does not support linking for platform iOS",
+    "'--build-system native' has been deprecated",
+    "Unable to locate libSwiftScan",
+)
+MAX_LEARN_ROUNDS = 3
+
+
+@dataclass
+class BuildResult:
+    ipa: Path
+    app: Path
+    seconds: float
+    compile_seconds: float
+    learned: dict
+    warnings: list[str]
+
+
+def _describe(app_dir: Path, inst: Installation, cache_dir: Path) -> dict:
+    """``swift package describe`` (cached on the manifest's contents)."""
+    h = hashlib.sha256()
+    for name in ("Package.swift", "Package.resolved"):
+        p = app_dir / name
+        if p.exists():
+            h.update(p.read_bytes())
+    for p in sorted(app_dir.glob("Package@swift-*.swift")):
+        h.update(p.read_bytes())
+    key = h.hexdigest()[:16]
+    cache = cache_dir / f"describe-{key}.json"
+    if cache.exists():
+        try:
+            return json.loads(cache.read_text())
+        except ValueError:
+            pass
+    out = proc.run([inst.swift.tool("swift"), "package", "--package-path", app_dir,
+                    "describe", "--type", "json"], timeout=600, check=False)
+    text = out.stdout
+    start = text.find("{")
+    if out.returncode != 0 or start < 0:
+        raise IpeddleError(
+            f"`swift package describe` failed for {app_dir}:\n" + "\n".join(text.splitlines()[-20:]),
+            hint="is this a SwiftPM package with a valid Package.swift?",
+        )
+    data = json.loads(text[start:])
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    for old in cache_dir.glob("describe-*.json"):
+        old.unlink()
+    cache.write_text(json.dumps(data))
+    return data
+
+
+def pick_product(desc: dict, wanted: str | None) -> str:
+    exes = [p["name"] for p in desc.get("products", []) if "executable" in p.get("type", {})]
+    if wanted:
+        if wanted not in exes:
+            raise IpeddleError(
+                f"no executable product named {wanted!r}",
+                hint="executable products: " + (", ".join(exes) or "none"),
+            )
+        return wanted
+    if len(exes) == 1:
+        return exes[0]
+    if not exes:
+        raise IpeddleError(
+            "the package has no executable product",
+            hint="add `.executable(name: \"MyApp\", targets: [\"MyApp\"])` with an "
+            "`.executableTarget` that contains your `@main` App (see examples/hello)",
+        )
+    raise IpeddleError(
+        f"several executable products ({', '.join(exes)})",
+        hint="choose one with --product or `product` in ipeddle.toml",
+    )
+
+
+def deployment_target(desc: dict) -> str:
+    for p in desc.get("platforms", []):
+        if p.get("name") == "ios":
+            return p.get("version", "16.0")
+    raise IpeddleError(
+        "Package.swift does not declare an iOS deployment target",
+        hint="add `platforms: [.iOS(.v16)]` (15 or newer) to the Package(...) declaration",
+    )
+
+
+def _version_tuple(v: str) -> tuple[int, ...]:
+    return tuple(int(x) for x in re.findall(r"\d+", v)[:3])
+
+
+def _stream(cmd, cwd: Path, log: Path, timeout: int) -> tuple[int, str]:
+    """Run ``cmd`` streaming interesting lines; full output goes to ``log``."""
+    log.parent.mkdir(parents=True, exist_ok=True)
+    ui.debug("$ " + " ".join(str(c) for c in cmd))
+    lines = []
+    timed_out = threading.Event()
+    with open(log, "w") as fh:
+        p = subprocess.Popen([str(c) for c in cmd], cwd=cwd, stdout=subprocess.PIPE,
+                             stderr=subprocess.STDOUT, text=True, bufsize=1, start_new_session=True)
+
+        def _kill():
+            timed_out.set()
+            try:
+                os.killpg(p.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+
+        watchdog = threading.Timer(timeout, _kill)
+        watchdog.daemon = True
+        watchdog.start()
+        try:
+            assert p.stdout is not None
+            for line in p.stdout:
+                fh.write(line)
+                lines.append(line)
+                s = line.rstrip()
+                if any(n in s for n in NOISE):
+                    continue
+                if re.match(r"^\[\d+/\d+\] (Compiling|Linking|Emitting module)", s) or s.startswith("Build complete"):
+                    ui.info(s)
+                elif ("error:" in s or "warning:" in s) and not s.startswith("ld64.lld: error: undefined symbol"):
+                    ui.info(s)
+            p.wait()
+        except KeyboardInterrupt:
+            os.killpg(p.pid, signal.SIGINT)
+            p.wait()
+            raise
+        finally:
+            watchdog.cancel()
+    if timed_out.is_set():
+        raise IpeddleError(f"build timed out after {timeout}s (log: {log})",
+                           hint="raise it with --timeout")
+    return p.returncode, "".join(lines)
+
+
+def sdk_stamp(inst: Installation) -> str:
+    rep = (inst.sdk / patcher.REPORT_NAME)
+    data = rep.read_bytes() if rep.exists() else b""
+    return hashlib.sha256(data + str(inst.sdk).encode() + inst.swift.version.encode()).hexdigest()[:16]
+
+
+def build(app_dir: Path, *, home: Home | None = None, **kwargs) -> BuildResult:
+    app_dir = Path(app_dir).resolve()
+    with private_tmp(app_dir / ".build" / "ipeddle" / "tmp"):
+        return _build(app_dir, home=home, **kwargs)
+
+
+def _build(app_dir: Path, *, home: Home | None = None, configuration: str = "release",
+           product: str | None = None, output: Path | None = None, clean: bool = False,
+           timeout: int = 3600, jobs: int | None = None) -> BuildResult:
+    t0 = time.monotonic()
+    home = home or Home.default()
+    app_dir = Path(app_dir).resolve()
+    if not (app_dir / "Package.swift").exists():
+        raise IpeddleError(
+            f"{app_dir} has no Package.swift",
+            hint="ipeddle builds SwiftPM packages; see examples/hello for the layout",
+        )
+    inst = load_installation(home)
+    cfg = appconfig.load(app_dir)
+    build_root = app_dir / ".build"
+    meta = build_root / "ipeddle"
+    if clean:
+        ui.step("cleaning previous build")
+        rmtree(build_root / TRIPLE)
+        for child in meta.glob("*") if meta.is_dir() else []:
+            if child.name != "tmp":
+                rmtree(child) if child.is_dir() else child.unlink()
+    meta.mkdir(parents=True, exist_ok=True)
+
+    desc = _describe(app_dir, inst, meta)
+    exe = pick_product(desc, product or cfg.product)
+    min_os = deployment_target(desc)
+    if _version_tuple(min_os) < (15, 0):
+        raise IpeddleError(
+            f"deployment target iOS {min_os} is below what ipeddle supports",
+            hint="use .iOS(.v15) or newer in Package.swift (back-deployment libraries "
+            "for older iOS only ship with Xcode)",
+        )
+    bundle_id = cfg.bundle_id or appconfig.default_bundle_id(exe)
+    ui.step(f"building {exe} ({configuration}, iOS {min_os}+, {bundle_id})")
+
+    products_dir = build_root / TRIPLE / configuration
+    stamp_file = meta / "sdk-stamp"
+    stamp = sdk_stamp(inst)
+    if stamp_file.exists() and stamp_file.read_text() != stamp:
+        # The SDK stubs changed (new setup, learned symbols): relink.
+        ui.info("SDK changed since the last build; relinking")
+        (products_dir / exe).unlink(missing_ok=True)
+
+    learned_all: dict[str, list[str]] = {}
+    libs_file = meta / "link-libs.json"
+    try:
+        project_libs = set(json.loads(libs_file.read_text()))
+    except (OSError, ValueError):
+        project_libs = set()
+    compile_t0 = time.monotonic()
+    for round_no in range(MAX_LEARN_ROUNDS + 1):
+        cmd = [inst.swift.tool("swift"), "build",
+               "--package-path", app_dir,
+               "--swift-sdks-path", home.swift_sdks,
+               "--swift-sdk", SWIFT_SDK_ID,
+               "-c", configuration,
+               "--product", exe,
+               "--build-system", "native",
+               "-debug-info-format", "none",
+               "-Xlinker", "--error-limit=0",
+               "-Xlinker", "-rpath", "-Xlinker", "@executable_path/Frameworks"]
+        for lib in sorted(project_libs):
+            cmd += ["-Xlinker", f"-l{lib}"]
+        for flag in cfg.extra_swiftc:
+            cmd += ["-Xswiftc", flag]
+        if jobs:
+            cmd += ["-j", str(jobs)]
+        rc, out = _stream(cmd, app_dir, meta / "build.log", timeout)
+        if rc == 0:
+            break
+        undefined = sorted({"_" + s if not s.startswith("_") else s for s in UNDEFINED_RE.findall(out)})
+        if not undefined:
+            raise IpeddleError(
+                f"swift build failed (full log: {meta / 'build.log'})",
+                hint=_hint_for(out),
+            )
+        added, new_libs = {}, set()
+        if round_no < MAX_LEARN_ROUNDS:
+            with locked(home.root / ".lock"):
+                added = patcher.learn_missing(inst.sdk, undefined)
+            new_libs = patcher.overlays_exporting(inst.sdk, undefined) - project_libs
+        if not added and not new_libs:
+            raise IpeddleError(
+                "link failed: undefined symbols\n" + _describe_symbols(inst, undefined),
+                hint="these symbols are not in the SDK's stubs nor in an overlay ipeddle can "
+                "route them to; see 'Known issues' in the README",
+            )
+        for lib, syms in added.items():
+            learned_all.setdefault(lib, []).extend(syms)
+            ui.info(f"declared {len(syms)} Swift symbol(s) in {lib} (missing from the public SDK stubs)")
+        if new_libs:
+            project_libs |= new_libs
+            libs_file.write_text(json.dumps(sorted(project_libs)))
+            ui.info("linking " + ", ".join(f"lib{n}" for n in sorted(new_libs)))
+    compile_seconds = time.monotonic() - compile_t0
+    stamp_file.write_text(sdk_stamp(inst))
+
+    ui.step("packaging")
+    report = package.assemble_app(
+        work=meta / "package", products_dir=products_dir, executable=exe, cfg=cfg,
+        bundle_id=bundle_id, min_os=min_os, sdk_version=inst.sdk_version, app_name=exe,
+    )
+    suffix = "" if configuration == "release" else f"-{configuration}"
+    ipa = Path(output).resolve() if output else (build_root / f"{exe}{suffix}.ipa")
+    package.write_ipa(meta / "package", ipa)
+    rmtree(meta / "package")
+    for w in report.warnings:
+        ui.warn(w)
+    if report.flattened_images:
+        ui.info(f"asset catalog fallback: {report.flattened_images} image file(s) bundled loose")
+    return BuildResult(ipa=ipa, app=report.app, seconds=time.monotonic() - t0,
+                       compile_seconds=compile_seconds, learned=learned_all, warnings=report.warnings)
+
+
+def _describe_symbols(inst: Installation, syms: list[str], limit: int = 30) -> str:
+    shown = syms[:limit]
+    demangled = shown
+    tool = inst.swift.tool("swift-demangle")
+    if tool.exists():
+        try:
+            out = subprocess.run([str(tool), "--compact"], input="\n".join(shown), text=True,
+                                 capture_output=True, timeout=30).stdout.splitlines()
+            if len(out) == len(shown):
+                demangled = out
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+    lines = [f"  {d}" + (f"   [{s}]" if d != s else "") for s, d in zip(shown, demangled, strict=False)]
+    if len(syms) > limit:
+        lines.append(f"  ... and {len(syms) - limit} more")
+    return "\n".join(lines)
+
+
+def _hint_for(out: str) -> str | None:
+    if "no such module 'UIKit'" in out or "no such module 'SwiftUI'" in out:
+        return "the SDK is not set up correctly; run `ipeddle doctor`"
+    if "this SDK is not supported by the compiler" in out:
+        return ("the Swift toolchain could not read the SDK's module interfaces; try the Swift "
+                "version that matches the SDK (see `ipeddle doctor`)")
+    if "unable to resolve" in out.lower() or "could not resolve" in out.lower():
+        return "a package dependency could not be fetched; check your network"
+    return "scroll up for the first error; rerun with IPEDDLE_VERBOSE=1 for commands"

ipeddle/cli.py

@@ -0,0 +1,219 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__, ui
+from .errors import IpeddleError
+from .paths import Home
+
+
+def _home(args) -> Home:
+    return Home(Path(args.home).expanduser().resolve()) if args.home else Home.default()
+
+
+def cmd_doctor(args) -> int:
+    from . import doctor
+
+    home = _home(args)
+    ui.step(f"ipeddle {__version__} doctor (home: {home.root})")
+    ok = doctor.report(doctor.run_checks(home, deep=args.deep))
+    if ok:
+        ui.ok("everything needed is in place" + ("" if args.deep else " (add --deep for a test compile)"))
+    else:
+        ui.fail("some required pieces are missing (see the hints above)")
+    return 0 if ok else 1
+
+
+def cmd_setup(args) -> int:
+    from . import setup
+
+    home = _home(args)
+    ui.step(f"ipeddle {__version__} setup (home: {home.root})")
+    t = ui.Timer()
+    setup.setup(home, swift_dir=args.swift, swift_version=args.swift_version, linker=args.linker,
+                sdk_dir=args.sdk, xip=args.xip, sdk_version=args.sdk_version, mirror=args.mirror,
+                force=args.force, download=not args.no_download, warm=not args.no_test)
+    ui.ok(f"setup finished in {t.seconds:.1f}s — next: ipeddle build <your SwiftPM app>")
+    return 0
+
+
+def cmd_build(args) -> int:
+    from . import build
+
+    res = build.build(Path(args.path), home=_home(args), configuration=args.configuration,
+                      product=args.product, output=Path(args.output) if args.output else None,
+                      clean=args.clean, timeout=args.timeout, jobs=args.jobs)
+    size = res.ipa.stat().st_size
+    ui.ok(f"{res.ipa}  ({ui.human_bytes(size)}, unsigned) in {res.seconds:.1f}s "
+          f"(compile+link {res.compile_seconds:.1f}s)")
+    ui.info("sign and install it with Sideloadly or AltStore (free Apple ID)")
+    if args.inspect:
+        return _inspect(res.ipa, _home(args), None, False, False)
+    return 0
+
+
+def _sdk_for_inspect(home: Home, sdk_arg: str | None) -> Path | None:
+    if sdk_arg:
+        return Path(sdk_arg).expanduser().resolve()
+    st = home.load_state()
+    d = st.get("sdk", {}).get("derived")
+    return Path(d) if d and Path(d).is_dir() else None
+
+
+def _inspect(path: Path, home: Home, sdk_arg, as_json: bool, verbose: bool) -> int:
+    from . import inspect as insp
+
+    rep = insp.inspect(path, _sdk_for_inspect(home, sdk_arg))
+    if as_json:
+        print(json.dumps(rep.to_json(), indent=2))
+    else:
+        print(insp.format_report(rep, verbose=verbose))
+    return 0 if rep.ok else 2
+
+
+def cmd_inspect(args) -> int:
+    return _inspect(Path(args.ipa), _home(args), args.sdk, args.json, args.verbose)
+
+
+def cmd_init(args) -> int:
+    from . import scaffold
+    from .config import validate_bundle_id
+
+    if args.bundle_id:
+        validate_bundle_id(args.bundle_id)
+    d = scaffold.init(Path(args.path), args.name, args.bundle_id)
+    ui.ok(f"created a SwiftUI app in {d}")
+    ui.info(f"next: ipeddle build {args.path}")
+    return 0
+
+
+def cmd_clean(args) -> int:
+    from .fsutil import rmtree, tree_size
+
+    home = _home(args)
+    if args.path:
+        b = Path(args.path).resolve() / ".build"
+        size = tree_size(b) if b.exists() else 0
+        rmtree(b)
+        ui.ok(f"removed {b} ({ui.human_bytes(size)})")
+        return 0
+    targets = [home.downloads, home.root / "tmp"]
+    if args.cache:
+        targets.append(home.module_cache)
+    if args.all:
+        targets = [home.root]
+    freed = 0
+    for t in targets:
+        if t.exists():
+            freed += tree_size(t)
+            rmtree(t)
+    for partial in home.root.rglob("*.partial") if home.root.exists() else []:
+        freed += tree_size(partial)
+        rmtree(partial)
+    ui.ok(f"freed {ui.human_bytes(freed)}" + (" (ipeddle home removed)" if args.all else ""))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    from . import sdk as sdkmod
+    from . import toolchain
+
+    p = argparse.ArgumentParser(
+        prog="ipeddle",
+        description="Build iOS apps (.ipa) on Linux, no Mac or Xcode required.",
+    )
+    p.add_argument("--version", action="version", version=f"ipeddle {__version__}")
+    p.add_argument("--home", help="where ipeddle keeps the toolchain and SDK "
+                   "(default: $IPEDDLE_HOME or ~/.local/share/ipeddle)")
+    sub = p.add_subparsers(dest="command", metavar="<command>")
+
+    d = sub.add_parser("doctor", help="check this machine and explain what is missing")
+    d.add_argument("--deep", action="store_true", help="also compile and link a test program")
+    d.set_defaults(func=cmd_doctor)
+
+    s = sub.add_parser("setup", help="install Swift, the linker and the iOS SDK (once)")
+    s.add_argument("--swift", metavar="DIR", help="use this Swift toolchain (contains usr/bin/swift)")
+    s.add_argument("--swift-version", default=None,
+                   help=f"Swift version to download (default: {toolchain.DEFAULT_SWIFT_VERSION})")
+    s.add_argument("--linker", metavar="FILE", help="use this ld64.lld instead of downloading one")
+    g = s.add_mutually_exclusive_group()
+    g.add_argument("--sdk", metavar="DIR", help="use an iPhoneOS*.sdk directory you already have")
+    g.add_argument("--xip", metavar="FILE", help="extract the SDK from an Xcode .xip you downloaded")
+    s.add_argument("--sdk-version", default=None,
+                   help=f"SDK to fetch from the mirror (default: {sdkmod.DEFAULT_SDK_VERSION})")
+    s.add_argument("--mirror", default=None, help="git URL of the SDK mirror")
+    s.add_argument("--force", action="store_true", help="rebuild the patched SDK and runtime")
+    s.add_argument("--no-download", action="store_true", help="fail instead of downloading anything")
+    s.add_argument("--no-test", action="store_true",
+                   help="skip the final test compile (which also pre-builds the shared module cache)")
+    s.set_defaults(func=cmd_setup)
+
+    n = sub.add_parser("init", help="create a minimal SwiftUI app to start from")
+    n.add_argument("path", help="directory to create the app in")
+    n.add_argument("--name", help="app/module name (default: the directory name)")
+    n.add_argument("--bundle-id", help="bundle identifier (default: dev.ipeddle.<name>)")
+    n.set_defaults(func=cmd_init)
+
+    b = sub.add_parser("build", help="build a SwiftPM app into an unsigned .ipa")
+    b.add_argument("path", nargs="?", default=".", help="app directory (with Package.swift)")
+    b.add_argument("-c", "--configuration", choices=("release", "debug"), default="release")
+    b.add_argument("--product", help="executable product to package")
+    b.add_argument("-o", "--output", help="where to write the .ipa (default: .build/<App>.ipa)")
+    b.add_argument("--clean", action="store_true", help="discard previous build products first")
+    b.add_argument("--inspect", action="store_true", help="run `ipeddle inspect` on the result")
+    b.add_argument("-j", "--jobs", type=int, help="parallel compile jobs")
+    b.add_argument("--timeout", type=int, default=3600, help="give up after this many seconds")
+    b.set_defaults(func=cmd_build)
+
+    i = sub.add_parser("inspect", help="check an .ipa: arch, minimum iOS, Info.plist, symbols")
+    i.add_argument("ipa", help=".ipa file or .app directory")
+    i.add_argument("--sdk", help="SDK to check symbols against (default: the one from setup)")
+    i.add_argument("--json", action="store_true", help="machine-readable output")
+    i.add_argument("-v", "--verbose", action="store_true")
+    i.set_defaults(func=cmd_inspect)
+
+    c = sub.add_parser("clean", help="remove temporary files (or an app's build directory)")
+    c.add_argument("path", nargs="?", help="app directory whose .build to delete")
+    c.add_argument("--cache", action="store_true", help="also empty the shared module cache")
+    c.add_argument("--all", action="store_true", help="remove everything ipeddle installed")
+    c.set_defaults(func=cmd_clean)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    from . import sdk as sdkmod
+    from . import toolchain
+
+    argp = build_parser()
+    args = argp.parse_args(argv)
+    if not getattr(args, "func", None):
+        argp.print_help()
+        return 0
+    if args.command == "setup":
+        args.swift_version = args.swift_version or toolchain.DEFAULT_SWIFT_VERSION
+        args.mirror = args.mirror or sdkmod.DEFAULT_MIRROR
+    try:
+        if args.command in ("setup", "doctor"):
+            # The Swift driver leaves empty TemporaryDirectory.* folders in $TMPDIR.
+            from .fsutil import private_tmp
+
+            with private_tmp(_home(args).root / "tmp"):
+                return args.func(args)
+        return args.func(args)
+    except IpeddleError as e:
+        ui.fail(e.message)
+        if e.hint:
+            ui.info("hint: " + e.hint)
+        return e.code
+    except KeyboardInterrupt:
+        ui.fail("interrupted")
+        return 130
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

ipeddle/config.py

@@ -0,0 +1,95 @@
+"""Per-app settings: ``ipeddle.toml`` next to ``Package.swift`` (optional)."""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import IpeddleError
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+CONFIG_NAME = "ipeddle.toml"
+_BUNDLE_ID_RE = re.compile(r"^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$")
+
+
+@dataclass
+class AppConfig:
+    product: str | None = None
+    bundle_id: str | None = None
+    display_name: str | None = None
+    version: str = "1.0"
+    build: str = "1"
+    icon: Path | None = None
+    info_plist: Path | None = None
+    resources: list[Path] = field(default_factory=list)
+    device_family: list[int] = field(default_factory=lambda: [1, 2])
+    extra_swiftc: list[str] = field(default_factory=list)
+
+
+def _path(base: Path, value, key: str) -> Path:
+    if not isinstance(value, str):
+        raise IpeddleError(f"{CONFIG_NAME}: `{key}` must be a path string")
+    p = (base / value).resolve()
+    if not p.exists():
+        raise IpeddleError(f"{CONFIG_NAME}: `{key}` points to {value}, which does not exist")
+    return p
+
+
+def load(app_dir: Path) -> AppConfig:
+    cfg = AppConfig()
+    f = app_dir / CONFIG_NAME
+    if not f.exists():
+        return cfg
+    try:
+        data = tomllib.loads(f.read_text())
+    except tomllib.TOMLDecodeError as e:
+        raise IpeddleError(f"{f}: {e}") from e
+    app = data.get("app", {})
+    known = {"product", "bundle-id", "display-name", "version", "build", "icon", "info-plist",
+             "resources", "device-family", "swiftc-flags"}
+    unknown = set(app) - known
+    if unknown:
+        raise IpeddleError(
+            f"{f}: unknown key(s) in [app]: {', '.join(sorted(unknown))}",
+            hint="known keys: " + ", ".join(sorted(known)),
+        )
+    cfg.product = app.get("product")
+    cfg.bundle_id = app.get("bundle-id")
+    cfg.display_name = app.get("display-name")
+    cfg.version = str(app.get("version", cfg.version))
+    cfg.build = str(app.get("build", cfg.build))
+    if "icon" in app:
+        cfg.icon = _path(app_dir, app["icon"], "icon")
+    if "info-plist" in app:
+        cfg.info_plist = _path(app_dir, app["info-plist"], "info-plist")
+    cfg.resources = [_path(app_dir, r, "resources") for r in app.get("resources", [])]
+    fam = app.get("device-family")
+    if fam is not None:
+        names = {"iphone": 1, "ipad": 2}
+        try:
+            cfg.device_family = [names[x] if isinstance(x, str) else int(x) for x in fam]
+        except (KeyError, ValueError) as e:
+            raise IpeddleError(f"{f}: device-family must list \"iphone\" and/or \"ipad\"") from e
+    cfg.extra_swiftc = [str(x) for x in app.get("swiftc-flags", [])]
+    if cfg.bundle_id:
+        validate_bundle_id(cfg.bundle_id)
+    return cfg
+
+
+def validate_bundle_id(bid: str) -> None:
+    if not _BUNDLE_ID_RE.match(bid):
+        raise IpeddleError(
+            f"invalid bundle identifier {bid!r}",
+            hint="use reverse-DNS letters, digits, '-' and '.', e.g. com.example.myapp",
+        )
+
+
+def default_bundle_id(product: str) -> str:
+    slug = re.sub(r"[^A-Za-z0-9-]", "-", product).strip("-").lower() or "app"
+    return f"dev.ipeddle.{slug}"