kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/windows/icons.py

@@ -0,0 +1,64 @@
+"""Generate the Windows app icon (windows-spec).
+
+When the project supplies ``[tool.kivy.windows.icons].source`` (a 1024×1024 PNG,
+validated like the other platforms) kivyforge renders it into a multi-resolution
+Windows ``.ico`` (256/48/32/16 px) with [Pillow](https://python-pillow.org/) —
+the optional ``kivyforge[windows]`` extra. The ``.ico`` is then patched into the
+launcher's resources with ``rcedit`` at assembly time.
+
+Unlike Linux (whose ``appimagetool`` requires an icon and so always gets a
+generated default), Windows needs none: an app with no configured icon simply
+keeps the executable's default shell icon, and Pillow is only needed when an
+icon *is* configured.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kivyforge.config.icons import validate_icon_source
+from kivyforge.config.model import Config
+
+from . import WindowsBundleError
+
+# Sizes embedded in the .ico, largest first (Windows picks per display context).
+ICO_SIZES = (256, 48, 32, 16)
+
+
+def stage_icon(config: Config, project_root: Path, dest: Path) -> Path | None:
+    """Render the app ``.ico`` at *dest*; return it, or ``None`` if unconfigured.
+
+    ``None`` means no ``[tool.kivy.windows.icons].source`` was set, and the
+    launcher keeps its default icon (no ``rcedit --set-icon``).
+    """
+    source = config.windows_required.icons.source
+    if not source:
+        return None
+
+    src = (project_root / source).resolve()
+    validate_icon_source(src)
+    image = _open(src)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    # Pillow writes every requested size into one .ico from the largest render.
+    image.save(dest, format="ICO", sizes=[(s, s) for s in ICO_SIZES])
+    return dest
+
+
+def _open(src: Path):
+    image_module = _pillow()
+    try:
+        return image_module.open(src).convert("RGBA")
+    except OSError as exc:
+        raise WindowsBundleError(f"cannot read app icon {src}: {exc}") from exc
+
+
+def _pillow():
+    try:
+        from PIL import Image
+    except ModuleNotFoundError as exc:
+        raise WindowsBundleError(
+            "generating the Windows icon needs Pillow, which is not installed.\n"
+            "  Install the Windows extra: pip install 'kivyforge[windows]'\n"
+            "  (or unset [tool.kivy.windows.icons].source to build without an icon)."
+        ) from exc
+    return Image

kivyforge/platforms/windows/launcher/__init__.py

@@ -0,0 +1,193 @@
+r"""Launcher: vendored-binary build + per-app bootstrap generation/placement.
+
+This package is "everything launcher" for the Windows backend:
+
+* the in-repo C source (``launcher.c``) and its deterministic build/vendoring
+  (:mod:`~kivyforge.platforms.windows.launcher.build_launcher`) — the launcher is
+  compiled once in CI, never on user machines, and shipped as a vendored binary;
+* the per-app assembly-time pieces here in this module: generating the
+  ``_kivyforge_bootstrap.py`` module and placing + resource-patching a per-app
+  copy of the vendored launcher.
+
+Unlike macOS/Linux (where the launcher itself is per-app), the Windows launcher
+is a single prebuilt binary; everything app-specific lives in the generated
+``_kivyforge_bootstrap.py`` at the bundle root, which the launcher runs under the
+bundled ``python.exe``. The bootstrap:
+
+1. sets the explicit **AppUserModelID** (``SetCurrentProcessExplicitAppUserModelID``
+   via ctypes) **before** any window, so the taskbar groups the app under its own
+   identity/icon;
+2. discovers ``python\share\*\bin`` **generically** (not SDL-hard-coded) and
+   registers each with ``os.add_dll_directory`` before ``import kivy`` (defense in
+   depth — the real DLL-discovery fix is those dirs existing in the prefix at all);
+3. when ``<bundle>\bin`` exists (declared native binaries, Phase 6), registers it
+   for DLL discovery and prepends it to ``PATH``;
+4. **retains every ``add_dll_directory`` cookie for the process lifetime** (closing
+   / GC-ing a cookie removes its directory from the search path);
+5. puts ``<bundle>\app`` on ``sys.path``, sets the CWD there, and **runs** the
+   entry-point module as ``__main__`` (via :func:`runpy.run_module`) so a
+   standard ``if __name__ == "__main__": App().run()`` guard fires.
+
+Then the vendored launcher is copied to ``<safe-name>.exe`` and its icon/version
+resources are patched with ``rcedit``. Numeric version fields come from the
+Phase 9 PEP 440 mapping; here we set the human/string resources.
+"""
+
+from __future__ import annotations
+
+import keyword
+import shutil
+from pathlib import Path
+
+from .. import WindowsBundleError
+from ..assets import vendored_launcher
+from ..naming import windows_safe_name
+from ..rcedit import ResourcePatch, patch_resources
+
+BOOTSTRAP_NAME = "_kivyforge_bootstrap.py"
+
+# ``{app_id}`` and ``{entry}`` are validated (AppUserModelID / dotted module
+# name) before formatting, so inlining them as repr literals is safe.
+_BOOTSTRAP = '''\
+# Generated by kivyforge - do not edit.
+"""Onedir bootstrap: DLL discovery + AppUserModelID + entry-point import."""
+
+import os
+import sys
+from pathlib import Path
+
+_BUNDLE = Path(__file__).resolve().parent
+_APP_ID = {app_id!r}
+_ENTRY = {entry!r}
+
+# Retain every add_dll_directory cookie for the whole process lifetime: closing
+# or garbage-collecting a cookie removes its directory from the DLL search path.
+_DLL_DIR_COOKIES = []
+
+
+def _register_dll_dir(path):
+    if path.is_dir():
+        _DLL_DIR_COOKIES.append(os.add_dll_directory(str(path)))
+
+
+def _set_app_id(app_id):
+    if not app_id:
+        return
+    try:
+        import ctypes
+
+        ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(app_id)
+    except Exception:
+        # Taskbar identity is best-effort; never block startup on it.
+        pass
+
+
+def _bootstrap():
+    # (1) Taskbar identity before any window is created.
+    _set_app_id(_APP_ID)
+
+    # (2) Native DLL directories from the runtime prefix, discovered generically.
+    share = _BUNDLE / "python" / "share"
+    if share.is_dir():
+        for dep in sorted(share.iterdir()):
+            _register_dll_dir(dep / "bin")
+
+    # (3) Declared native binaries in <bundle>\\bin: DLL search + PATH prepend.
+    native_bin = _BUNDLE / "bin"
+    if native_bin.is_dir():
+        _register_dll_dir(native_bin)
+        os.environ["PATH"] = str(native_bin) + os.pathsep + os.environ.get("PATH", "")
+
+    # (5) App code on sys.path; CWD = app dir; run the entry module as __main__
+    # so a standard ``if __name__ == "__main__": App().run()`` guard fires. This
+    # mirrors the macOS/Linux launchers, which exec the interpreter on the entry
+    # script (importing it as an ordinary module would not run that block).
+    app_dir = _BUNDLE / "app"
+    sys.path.insert(0, str(app_dir))
+    os.chdir(app_dir)
+    import runpy
+
+    runpy.run_module(_ENTRY, run_name="__main__", alter_sys=True)
+
+
+_bootstrap()
+'''
+
+
+def _validate_entry_point(entry_point: str) -> None:
+    parts = entry_point.split(".")
+    if not entry_point or not all(
+        p.isidentifier() and not keyword.iskeyword(p) for p in parts
+    ):
+        raise WindowsBundleError(
+            f"entry_point {entry_point!r} is not a valid module name."
+        )
+
+
+def render_bootstrap(*, entry_point: str, app_id: str) -> str:
+    """The ``_kivyforge_bootstrap.py`` source for *entry_point* + *app_id* (pure)."""
+    _validate_entry_point(entry_point)
+    return _BOOTSTRAP.format(app_id=app_id, entry=entry_point)
+
+
+def write_bootstrap(bundle: Path, *, entry_point: str, app_id: str) -> Path:
+    """Write ``_kivyforge_bootstrap.py`` at the *bundle* root; return its path."""
+    dest = bundle / BOOTSTRAP_NAME
+    dest.write_text(
+        render_bootstrap(entry_point=entry_point, app_id=app_id), encoding="utf-8"
+    )
+    return dest
+
+
+def launcher_exe_name(display_name: str) -> str:
+    """The Windows-safe ``<name>.exe`` file name for *display_name*."""
+    return f"{windows_safe_name(display_name)}.exe"
+
+
+def copy_launcher(
+    bundle: Path,
+    *,
+    display_name: str,
+    launcher_src: Path | None = None,
+) -> Path:
+    """Copy the vendored launcher to ``<bundle>\\<safe-name>.exe`` (no patch).
+
+    *launcher_src* defaults to the vendored, SHA-256-verified binary; tests
+    inject a fake. Returns the copied ``.exe`` path. Resource patching is a
+    separate step (:func:`patch_launcher`) so callers can defer it until after
+    the bundle is in its final location — an rcedit-patched executable is a
+    strong antivirus trigger that holds the file open and can block a directory
+    rename of the still-being-assembled tree on Windows.
+    """
+    # arm64: pick the launcher matching the target arch, i.e. thread arch into
+    # vendored_launcher(arch) so an arm64 bundle gets launcher-arm64.exe. The
+    # bundler (bundle.py) already resolves target_arch. See arm64-windows.md §5.
+    src = launcher_src if launcher_src is not None else vendored_launcher()
+    dest = bundle / launcher_exe_name(display_name)
+    shutil.copy2(src, dest)
+    return dest
+
+
+def patch_launcher(
+    exe: Path, patch: ResourcePatch, *, rcedit: Path | None = None
+) -> None:
+    """Patch a placed launcher's icon/version resources in place with rcedit."""
+    patch_resources(exe, patch, rcedit=rcedit)
+
+
+def place_launcher(
+    bundle: Path,
+    *,
+    display_name: str,
+    patch: ResourcePatch,
+    launcher_src: Path | None = None,
+    rcedit: Path | None = None,
+) -> Path:
+    """Copy the vendored launcher to ``<bundle>\\<safe-name>.exe`` + patch it.
+
+    Convenience wrapper over :func:`copy_launcher` + :func:`patch_launcher` for
+    callers that place and patch in one location. Returns the placed ``.exe``.
+    """
+    dest = copy_launcher(bundle, display_name=display_name, launcher_src=launcher_src)
+    patch_resources(dest, patch, rcedit=rcedit)
+    return dest