kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/linux/bundle.py

@@ -0,0 +1,235 @@
+"""Assemble the Linux AppDir (linux-spec).
+
+Orchestrates the stages: pick the assembly arch from the lock (+ ``--arch``),
+stage the runtime + wheels, copy the app sources, render the icons + ``AppRun``
+launcher + ``.desktop`` entry. Produces the layout documented in linux-spec:
+
+    build/linux/<Name>.AppDir/
+    ├── AppRun
+    ├── <app_id>.desktop
+    ├── <app_id>.png
+    └── usr/{app, lib, python, share/icons/hicolor/...}
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import tempfile
+from pathlib import Path
+
+import click
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.bundle.pycompile import PycompileError, byte_compile, select_compiler
+from kivyforge.config.model import Config
+
+from . import AppDirError
+from .desktop import validate_desktop_file, write_desktop_entry
+from .icons import stage_icons
+from .launcher import build_apprun, entry_point_rel_path
+from .lock import LinuxLockfile
+from .native_stage import stage_native_binaries
+from .runtime_stage import stage_runtime
+from .wheels_stage import stage_wheels
+
+_IGNORE = shutil.ignore_patterns("__pycache__", "*.pyc")
+
+
+def resolve_assembly_arch(locked: tuple[str, ...], arch: str | None) -> str:
+    """The single arch to assemble for an ``--arch`` request.
+
+    Linux ships one arch per AppImage, so this always resolves to exactly one.
+    ``None`` -> the lock's arch (there is exactly one this phase). An explicit
+    arch not covered by the lock is an error.
+    """
+    if not locked:
+        raise AppDirError("the lock covers no architectures; re-run `kivyforge lock`.")
+    if arch is None:
+        return locked[0]
+    if arch not in locked:
+        raise AppDirError(
+            f"--arch {arch} is not in the lock (covers {', '.join(locked)}).\n"
+            f"  Add {arch!r} to [tool.kivy.linux].archs and re-lock, or pick a "
+            "locked arch."
+        )
+    return arch
+
+
+def _setting_applies(value: bool | str, *, release: bool) -> bool:
+    """A ``build_settings`` tri-state resolved for the build being produced."""
+    if isinstance(value, bool):
+        return value
+    return release  # DESKTOP_RELEASE_ONLY
+
+
+def _resolve_byte_compile(
+    config: Config,
+    *,
+    staged_interpreter: Path,
+    target_arch: str,
+    python_version: str,
+    release: bool,
+) -> tuple[tuple[str, ...] | None, bool]:
+    """Decide whether to byte-compile, and with which interpreter.
+
+    Returns ``(compiler_argv_or_None, strip_source)``; ``None`` means do not
+    byte-compile. ``byte_compile = true`` is read as "I insist", so a missing
+    interpreter is an error; the default ``"release"`` degrades to shipping
+    source with a warning rather than breaking a build the user never
+    configured.
+    """
+    settings = config.linux_required.build_settings
+    if not _setting_applies(settings.byte_compile, release=release):
+        return None, False
+    native = platform.machine().lower() == target_arch
+    compiler = select_compiler(
+        staged_interpreter=staged_interpreter,
+        native=native,
+        python_version=python_version,
+    )
+    if compiler is None:
+        message = (
+            f"this project ships CPython {python_version}, and no CPython of "
+            "that minor could be found to byte-compile with (a .pyc is only "
+            "loadable by the exact CPython minor that wrote it)"
+        )
+        if settings.byte_compile is True:
+            raise AppDirError(
+                "[tool.kivy.linux.build_settings].byte_compile = true but "
+                f"{message}.\n"
+                "  Install a matching CPython, or set byte_compile = false."
+            )
+        click.echo(f"[stage] not byte-compiling: {message}.")
+        return None, False
+    strip = _setting_applies(settings.strip_source, release=release)
+    return compiler, strip
+
+
+def build_appdir(
+    config: Config,
+    lock: LinuxLockfile,
+    project_root: Path,
+    *,
+    arch: str | None = None,
+    staging_dir: Path | None = None,
+    no_cache: bool = False,
+    cache: ArtifactCache | None = None,
+    release: bool = False,
+    echo=click.echo,
+) -> Path:
+    """Build the AppDir tree and return its path."""
+    target_arch = resolve_assembly_arch(lock.archs, arch)
+    cache = cache or ArtifactCache()
+    staging_dir = staging_dir or (project_root / "build" / "linux")
+    appdir = staging_dir / f"{config.display_name}.AppDir"
+
+    # Assemble into a temp tree and swap it in only on success, so a failure
+    # mid-assembly (e.g. a transient runtime/wheel fetch error) leaves the
+    # previous, working AppDir untouched instead of a half-written one.
+    staging_dir.mkdir(parents=True, exist_ok=True)
+    work = Path(tempfile.mkdtemp(dir=staging_dir, prefix=f".{appdir.name}.tmp-"))
+    try:
+        (work / "usr").mkdir(parents=True)
+
+        echo(
+            f"Staging CPython {lock.python_runtime.version} runtime ({target_arch}) ..."
+        )
+        stage_runtime(
+            lock.python_runtime,
+            target_arch,
+            work / "usr" / "python",
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+
+        echo(f"Installing {len(lock.packages)} locked packages ...")
+        stage_wheels(
+            lock.packages,
+            target_arch,
+            work / "usr" / "lib",
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+
+        if lock.native_binaries:
+            echo(f"Staging {len(lock.native_binaries)} native binaries ...")
+            stage_native_binaries(
+                lock,
+                work / "usr",
+                project_root=project_root,
+                cache=cache,
+                no_cache=no_cache,
+            )
+
+        _copy_app_sources(config, project_root, work / "usr" / "app")
+
+        compiler, strip_source = _resolve_byte_compile(
+            config,
+            staged_interpreter=work / "usr" / "python" / "bin" / "python3",
+            target_arch=target_arch,
+            python_version=lock.python_runtime.version,
+            release=release,
+        )
+        if compiler is not None:
+            with_what = " ".join(compiler) if compiler else "this interpreter"
+            echo(
+                f"[stage] byte-compiling the Python payload with {with_what}"
+                + (" (.pyc only)" if strip_source else "")
+            )
+            try:
+                byte_compile(
+                    [work / "usr" / "app", work / "usr" / "lib"],
+                    compiler=compiler,
+                    strip_source=strip_source,
+                    stripdir=work,
+                )
+            except PycompileError as exc:
+                raise AppDirError(
+                    f"{exc}\n  Fix it, or set "
+                    "[tool.kivy.linux.build_settings].byte_compile = false."
+                ) from exc
+
+        stage_icons(config, project_root, work)
+
+        build_apprun(
+            work / "AppRun",
+            entry_point=config.kivy.entry_point,
+            app_id=config.linux_required.app_id,
+            has_native_binaries=bool(lock.native_binaries),
+        )
+        desktop_path = work / f"{config.linux_required.app_id}.desktop"
+        write_desktop_entry(config, desktop_path)
+        validate_desktop_file(desktop_path)
+    except BaseException:
+        shutil.rmtree(work, ignore_errors=True)
+        raise
+
+    # Swap the freshly built tree in for the previous one. The rename is atomic
+    # within staging_dir; the brief unlink→rename window only exists after a
+    # fully successful build.
+    if appdir.exists():
+        shutil.rmtree(appdir)
+    work.replace(appdir)
+    return appdir
+
+
+def _copy_app_sources(config: Config, project_root: Path, dest: Path) -> None:
+    src = (project_root / config.kivy.app_dir).resolve()
+    if not src.is_dir():
+        raise AppDirError(
+            f"[tool.kivy].app_dir points to {config.kivy.app_dir!r}, which is not "
+            f"a directory under {project_root}."
+        )
+    # A dotted entry_point (e.g. "pkg.start") maps to a nested source file
+    # (src/pkg/start.py), matching the shared app_dir/entry_point layout.
+    entry_rel = f"{entry_point_rel_path(config.kivy.entry_point)}.py"
+    entry = src / entry_rel
+    if not entry.is_file():
+        raise AppDirError(
+            f"entry point {entry_rel} not found in "
+            f"{config.kivy.app_dir}/ (set [tool.kivy].entry_point)."
+        )
+    shutil.copytree(src, dest, ignore=_IGNORE)

kivyforge/platforms/linux/cli.py

@@ -0,0 +1,232 @@
+"""Linux dispatch for the shared ``build`` / ``run`` / ``package`` verbs.
+
+Keeps the Linux AppDir flow out of the (iOS/Xcode-centric) verb modules: each
+verb resolves the target platform and, when it is Linux, calls in here. Loads the
+Linux config + ``pylock.linux.toml``, runs the drift check, and drives the
+AppDir bundler.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from pathlib import Path
+
+import click
+
+from kivyforge.cli._common import ToolchainError, lockfile_path_for
+from kivyforge.config import ConfigError, load_config
+from kivyforge.lock.reader import LockError, is_in_sync
+
+from .. import HostCapabilityError, get_platform
+from . import AppDirError
+from .appimage import build_appimage
+from .bundle import build_appdir, resolve_assembly_arch
+from .lock import LinuxLockfile
+from .lock import load as load_linux_lock
+
+
+def linux_build(
+    project_root: Path,
+    *,
+    arch: str | None,
+    no_verify_lock: bool,
+    no_cache: bool,
+) -> Path:
+    """Assemble the Linux AppDir; return its path."""
+    _require_linux_host()
+    config, lock = _load_and_verify(project_root, no_verify_lock)
+    appdir = _assemble(
+        config, lock, project_root, arch=arch, no_cache=no_cache, release=False
+    )
+    click.echo(f"Built {appdir.relative_to(project_root)}")
+    return appdir
+
+
+def linux_package(
+    project_root: Path,
+    *,
+    fmt: str,
+    arch: str | None,
+    no_verify_lock: bool,
+    no_cache: bool,
+) -> Path:
+    """Produce the distributable artifact: an ``.AppImage`` (default) or the AppDir."""
+    _require_linux_host()
+    config, lock = _load_and_verify(project_root, no_verify_lock)
+    target_arch = _resolve_arch(lock, arch)
+    appdir = _assemble(
+        config, lock, project_root, arch=target_arch, no_cache=no_cache, release=True
+    )
+
+    if fmt == "folder":
+        click.echo(
+            f"Packaged {appdir.relative_to(project_root)} (AppDir folder).\n"
+            "  Run it with ./AppRun, or `kivyforge package -f appimage` for a "
+            "single-file distributable."
+        )
+        return appdir
+
+    output = (
+        project_root
+        / "dist"
+        / "linux"
+        / f"{config.app_slug}-{config.project.version}-{target_arch}.AppImage"
+    )
+    try:
+        result = build_appimage(
+            appdir,
+            output,
+            target_arch,
+            project_root=project_root,
+            no_cache=no_cache,
+            echo=click.echo,
+        )
+    except AppDirError as exc:
+        raise ToolchainError(str(exc)) from exc
+
+    click.echo(
+        f"Packaged {result.relative_to(project_root)}.\n"
+        "  Distribute the .AppImage directly (chmod +x, then run). The host needs "
+        "glibc ≥ the effective floor, libGL/libEGL, and an X11/Wayland session.\n"
+        "  No libfuse2 package is required (static-FUSE runtime embedded). If the "
+        "host lacks kernel FUSE (/dev/fuse) — e.g. some containers/CI — run it "
+        "with --appimage-extract-and-run (or APPIMAGE_EXTRACT_AND_RUN=1)."
+    )
+    return result
+
+
+def _assemble(config, lock, project_root, *, arch, no_cache, release) -> Path:
+    try:
+        return build_appdir(
+            config, lock, project_root, arch=arch, no_cache=no_cache, release=release
+        )
+    except AppDirError as exc:
+        raise ToolchainError(str(exc)) from exc
+
+
+def _resolve_arch(lock: LinuxLockfile, arch: str | None) -> str:
+    try:
+        return resolve_assembly_arch(lock.archs, arch)
+    except AppDirError as exc:
+        raise ToolchainError(str(exc)) from exc
+
+
+def _load_and_verify(
+    project_root: Path, no_verify_lock: bool
+) -> tuple[object, LinuxLockfile]:
+    config = _load_config(project_root)
+    lock = _load_lock(project_root)
+    pyproject = project_root / "pyproject.toml"
+    if not no_verify_lock and not is_in_sync(lock, pyproject.read_text("utf-8")):
+        raise ToolchainError(
+            f"{lockfile_path_for('linux').name} is out of date with "
+            "pyproject.toml.\n"
+            "  Run `kivyforge lock -p linux` to regenerate it (or pass "
+            "--no-verify-lock to build against the stale lock anyway)."
+        )
+    return config, lock
+
+
+def linux_run(
+    project_root: Path,
+    *,
+    arch: str | None,
+    no_build: bool,
+) -> None:
+    """Build (unless --no-build) and launch the app via ``AppRun`` in foreground."""
+    if no_build:
+        _require_linux_host()
+        config = _load_config(project_root)
+        appdir = project_root / "build" / "linux" / f"{config.display_name}.AppDir"
+        if not appdir.exists():
+            raise ToolchainError(
+                f"no built AppDir at {appdir.relative_to(project_root)}; run "
+                "without --no-build first."
+            )
+    else:
+        appdir = linux_build(
+            project_root, arch=arch, no_verify_lock=False, no_cache=False
+        )
+
+    apprun = appdir / "AppRun"
+    click.echo(f"Launching {appdir.name} ...")
+    # Foreground exec so the dev sees stdout/stderr + tracebacks.
+    proc = subprocess.run([str(apprun)])
+    if proc.returncode != 0:
+        raise ToolchainError(f"{appdir.name} exited with status {proc.returncode}.")
+
+
+def linux_status(project_root: Path) -> None:
+    """Show app identity, Python version, lock sync, and build state."""
+    config = _load_config(project_root)
+    linux = config.linux_required
+    click.echo(f"App:        {config.display_name}  ({linux.app_id})")
+    click.echo(f"Python:     {linux.python_version or '(unset)'}")
+    click.echo(f"Lock:       {_lock_state(project_root)}")
+
+    appdir = project_root / "build" / "linux" / f"{config.display_name}.AppDir"
+    click.echo(f"Build:      {_build_state(appdir)}")
+
+
+def _lock_state(project_root: Path) -> str:
+    path = lockfile_path_for("linux", project_root)
+    if not path.is_file():
+        return "missing (run `kivyforge lock -p linux`)"
+    try:
+        lock = load_linux_lock(path)
+    except LockError:
+        return "unreadable (run `kivyforge lock -p linux`)"
+    pyproject = project_root / "pyproject.toml"
+    if is_in_sync(lock, pyproject.read_text("utf-8")):
+        return "in sync"
+    return "out of date (run `kivyforge lock -p linux`)"
+
+
+def _build_state(appdir: Path) -> str:
+    if not appdir.exists():
+        return "not built"
+    age = time.time() - appdir.stat().st_mtime
+    return f"last built {_humanize(age)}"
+
+
+def _humanize(seconds: float) -> str:
+    seconds = int(seconds)
+    if seconds < 60:
+        return "just now"
+    if seconds < 3600:
+        m = seconds // 60
+        return f"{m} minute{'s' if m != 1 else ''} ago"
+    if seconds < 86400:
+        h = seconds // 3600
+        return f"{h} hour{'s' if h != 1 else ''} ago"
+    d = seconds // 86400
+    return f"{d} day{'s' if d != 1 else ''} ago"
+
+
+def _require_linux_host() -> None:
+    try:
+        get_platform("linux").check_host_capability()
+    except HostCapabilityError as exc:
+        raise ToolchainError(str(exc)) from exc
+
+
+def _load_config(project_root: Path):
+    try:
+        return load_config(
+            project_root / "pyproject.toml", require_ios=False, require_linux=True
+        )
+    except ConfigError as exc:
+        raise ToolchainError(exc.format()) from exc
+
+
+def _load_lock(project_root: Path) -> LinuxLockfile:
+    path = lockfile_path_for("linux", project_root)
+    if not path.is_file():
+        raise ToolchainError(
+            f"no {path.name} found. Run `kivyforge lock -p linux` first."
+        )
+    try:
+        return load_linux_lock(path)
+    except LockError as exc:
+        raise ToolchainError(str(exc)) from exc

kivyforge/platforms/linux/desktop.py

@@ -0,0 +1,71 @@
+"""Generate the freedesktop ``.desktop`` entry for the AppDir (linux-spec).
+
+The Linux analog of the macOS ``Info.plist``: kivyforge owns the entry, built
+from ``[project]`` + ``[tool.kivy]`` + ``[tool.kivy.linux]``. ``Exec=AppRun %f``
+and ``StartupWMClass=<app_id>`` (matched by the ``AppRun`` launcher's SDL
+WM_CLASS env) so the running window groups under the app's own icon. The
+generated file must pass ``desktop-file-validate`` (also a ``doctor`` check).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from kivyforge.config.model import Config
+
+from . import AppDirError
+
+
+def render_desktop_entry(config: Config) -> str:
+    """The ``.desktop`` file contents for *config* (pure/testable)."""
+    linux = config.linux_required
+    categories = "".join(f"{c};" for c in linux.desktop.categories)
+    lines = [
+        "[Desktop Entry]",
+        "Type=Application",
+        f"Name={config.display_name}",
+    ]
+    if config.project.description:
+        lines.append(f"Comment={config.project.description}")
+    lines += [
+        "Exec=AppRun %f",
+        f"Icon={linux.app_id}",
+        f"Categories={categories}",
+        f"StartupWMClass={linux.app_id}",
+        "Terminal=false",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def write_desktop_entry(config: Config, dest: Path) -> None:
+    """Write ``<app_id>.desktop`` for *config* at *dest*."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(render_desktop_entry(config), encoding="utf-8")
+
+
+def validate_desktop_file(dest: Path) -> None:
+    """Run ``desktop-file-validate`` on *dest*; hard-fail on validation errors.
+
+    The generated ``.desktop`` must pass ``desktop-file-validate`` (linux-spec):
+    an invalid entry produces an AppImage that launches but fails desktop
+    integration (menu/search/icon association). ``desktop-file-validate`` (from
+    ``desktop-file-utils``) is optional on the build host — when it isn't
+    installed we can't run it, so we skip (config-time category validation still
+    guards the common typo). When it *is* installed, any reported error is a hard
+    failure.
+    """
+    tool = shutil.which("desktop-file-validate")
+    if tool is None:
+        return
+    try:
+        proc = subprocess.run([tool, str(dest)], capture_output=True, text=True)
+    except (OSError, ValueError):
+        return
+    if proc.returncode != 0:
+        detail = (proc.stdout + proc.stderr).strip() or "validation failed"
+        raise AppDirError(
+            f"generated {dest.name} failed desktop-file-validate:\n{detail}\n"
+            "  Fix [tool.kivy.linux.desktop] / [project] metadata and rebuild."
+        )