Add build and development instructions for the workspace
Document how to build, package and release the player so the knowledge is not rediscovered on each machine or session. New file: .github/instructions/kiwy-build-and-development.instructions.md Contents: - Entry points: src/main.py on Linux/Pi, windows/run_win.py on Windows (which patches platform differences before running main.py). - Verified toolchain: Python 3.12.9 x64 in windows\venv, Kivy 2.3.1, PyInstaller 6.21.0. Python 3.13+/3.14 is unsupported for the Windows build because Kivy 2.3.1 has no wheels for them. - Build commands (pyinstaller build.spec, build_win.bat) and the real output path, including the note that cefpython3 is not installed in this venv, so the embedded-CEF engine is inactive and web links use the subprocess adapter. - build.spec expectations: runtime hook for DPI awareness, console=True, excludes, and the rule that lazily/dynamically imported modules must be listed in hiddenimports or the packaged exe fails with ModuleNotFoundError. - Code signing constraint: production hosts enforce Smart App Control, where an unsigned (or self-signed) exe is blocked at kernel level, so a public CA cert is required. - Verification: py_compile gate, the need to close the running player before a rebuild (output lock / "Access is denied"), the .exe reserved-device-name pitfall that makes Test-Path report a false positive without -LiteralPath, and the stale duplicate one-file exe at windows\dist\KiwySignagePlayer.exe that must not be deployed. - Release checklist and commit hygiene (do not track dist/build output or the player_auth.json credential files).
This commit is contained in:
ske087
@@ -0,0 +1,140 @@
|
||||
---
|
||||
description: "Use when building, compiling, packaging or releasing the Kiwy Signage Player: PyInstaller build, .exe generation, build.spec, hiddenimports, code signing, Smart App Control, Windows development, Raspberry Pi deployment, or adding new modules under src/. Covers the exact build commands, environment constraints, bundling rules and verification steps."
|
||||
name: "Kiwy Build & Development"
|
||||
---
|
||||
|
||||
# Kiwy Signage Player — Build & Development
|
||||
|
||||
Cross-platform Kivy digital signage player.
|
||||
|
||||
- **Raspberry Pi / Linux** — `src/main.py` is the entry point (root `install.sh`, `start.sh`).
|
||||
- **Windows** — `windows/run_win.py` is the entry point; it sets Windows env vars, imports
|
||||
`main.py`, then monkey-patches platform differences. Packaged to `.exe` with PyInstaller.
|
||||
|
||||
## Ground Rules
|
||||
|
||||
- **Keep `src/main.py` cross-platform.** Windows-specific behaviour belongs in
|
||||
`windows/run_win.py` (see `_patch_main()`), Pi-specific behaviour in `main.py` guarded
|
||||
by capability checks. Do not add Windows-only imports to `main.py`.
|
||||
- **Rebuild is mandatory.** The `.exe` bundles `src/`, so Python edits are invisible until
|
||||
you rebuild. There is no hot reload in the packaged app.
|
||||
- **`dist/` is a runtime folder, not just build output.** It holds `config/`, `media/`,
|
||||
`playlists/`, `logs/`, `.kiosk-profile/` and `.player_heartbeat`. Never wipe `dist/`
|
||||
blindly; a `--clean` rebuild preserves it, but a manual delete destroys player state.
|
||||
|
||||
## Environment
|
||||
|
||||
| Item | Value |
|
||||
|------|-------|
|
||||
| Interpreter | **Python 3.12.9** (64-bit) — project venv at `windows\venv` |
|
||||
| Kivy | 2.3.1 |
|
||||
| PyInstaller | 6.21.0 |
|
||||
| Linux target | Python 3.13 (`repo/python-wheels/`, `repo/system-packages/`) |
|
||||
|
||||
- **Python 3.13+/3.14 is NOT supported for the Windows build** — Kivy 2.3.1 has no wheels
|
||||
for them.
|
||||
- `cefpython3` is **not installed** in the project venv. The embedded-CEF web-link engine is
|
||||
therefore unavailable and web links fall back to the Chrome/Edge subprocess adapter.
|
||||
Installing `cefpython3` (uncomment it in `windows/requirements_win.txt`) restores the
|
||||
CEF engine.
|
||||
|
||||
## Build
|
||||
|
||||
From `windows\`:
|
||||
|
||||
```
|
||||
venv\Scripts\python.exe -m PyInstaller build.spec --clean --noconfirm
|
||||
```
|
||||
|
||||
Or the full one-click path (creates venv, installs deps, builds, then signs):
|
||||
|
||||
```
|
||||
build_win.bat
|
||||
```
|
||||
|
||||
Output (folder mode, via `COLLECT`):
|
||||
|
||||
```
|
||||
windows\dist\KiwySignagePlayer\KiwySignagePlayer.exe <- the real build output
|
||||
```
|
||||
|
||||
**Deployment hazard:** `windows\dist\KiwySignagePlayer.exe` (one level up) is a stale
|
||||
leftover from an older single-file build of the same name. It is not refreshed by the
|
||||
current spec, so deploying it ships old code. Always take the executable from the
|
||||
`KiwySignagePlayer\` subfolder, and delete the stray copy if it reappears.
|
||||
|
||||
### `build.spec` facts
|
||||
|
||||
- Entry point `run_win.py`; `pathex=[BUILD_DIR, SRC_DIR]` so `src/` modules resolve.
|
||||
- `runtime_hooks=[pyi_runtime_hook.py]` — sets per-monitor DPI awareness **before** SDL/Kivy
|
||||
initialise. Keep DPI work here; it must run before any window is created.
|
||||
- `datas += Tree(src)` bundles all of `src/`. `console=True` so startup errors and the Kivy
|
||||
log remain visible — do not flip this to `False` without a reason.
|
||||
- `hiddenimports` must list modules that PyInstaller's static analysis **cannot** see:
|
||||
lazily imported ones (`cef_browser` is imported inside a function) or dynamic imports
|
||||
(`getattr`, `importlib`). Top-level imports such as `weblink_session` are found
|
||||
automatically via `pathex`, but listing them is harmless insurance.
|
||||
**When you add a module under `src/` that is imported lazily or by string, add it to
|
||||
`hiddenimports` or the packaged exe will fail at runtime with `ModuleNotFoundError`.**
|
||||
- `excluded_imports` drops Linux-only packages (`evdev`, `gi`, GStreamer) and the
|
||||
non-matching `cefpython3` `.pyd` variants.
|
||||
|
||||
## Code Signing (production constraint)
|
||||
|
||||
Production PCs run with **Smart App Control enforced** (`VerifiedAndReputablePolicyState=1`,
|
||||
UMCI enforced) with **no "Run anyway" bypass** — an unsigned exe is blocked at kernel level.
|
||||
|
||||
- A **self-signed certificate does NOT satisfy Smart App Control.** A cert from a reputable
|
||||
public CA is required. `create_self_signed_cert.ps1` is dev-only.
|
||||
- Provide a cert as `KIWY_SIGN_PFX` (+ optional `KIWY_SIGN_PFX_PASSWORD`) or drop
|
||||
`kiwy_signing.pfx` in `windows\`; `build_win.bat` then signs via `sign_exe.ps1`
|
||||
(signtool with RFC3161 timestamp when available).
|
||||
- See `documentation/CODE_SIGNING_SMART_APP_CONTROL.md`.
|
||||
|
||||
## Verify Before Committing
|
||||
|
||||
Fast syntax gate (no build, seconds):
|
||||
|
||||
```
|
||||
python -m py_compile src/main.py src/weblink_session.py windows/run_win.py
|
||||
```
|
||||
|
||||
**Close the running player before rebuilding.** A running
|
||||
`dist\KiwySignagePlayer\KiwySignagePlayer.exe` locks the output and the build fails with
|
||||
"Access is denied". Chrome/Edge kiosk processes left over from web-link playback can also
|
||||
hold locks; if the build fails, check for stray `msedge.exe` / `chrome.exe` before retrying.
|
||||
|
||||
Because `.exe` is a **reserved Windows device name** as well as a real file, use
|
||||
`Test-Path -LiteralPath` when probing for the executable, otherwise the path silently
|
||||
resolves to the console device.
|
||||
|
||||
Development run — **use this on a SAC-locked host**, since the unsigned exe cannot launch:
|
||||
|
||||
```
|
||||
cd windows
|
||||
venv\Scripts\activate
|
||||
python run_win.py
|
||||
```
|
||||
|
||||
Diagnose playback transitions via the trace log (`logs\playback_trace.log`), written by
|
||||
`src/playback_trace.py`.
|
||||
|
||||
## Release Checklist
|
||||
|
||||
1. Bump `PLAYER_VERSION` in `src/main.py` **and** `filevers`/`prodvers`/`FileVersion`/
|
||||
`ProductVersion` in `windows\version_info.txt`; keep them in sync.
|
||||
2. Rebuild (`build_win.bat`).
|
||||
3. Confirm the exe is signed (`Get-AuthenticodeSignature`); unsigned builds are blocked on
|
||||
production hosts.
|
||||
4. Smoke-test a mixed playlist: image → video → weblink → image, verifying durations, audio
|
||||
(`audio: off` / `muted`), and a clean exit/restart.
|
||||
|
||||
## Commit Hygiene
|
||||
|
||||
- Never commit `windows\build\` or `windows\dist\` (git-ignored). Tracked build output such
|
||||
as `windows\archive_list.txt` and `windows\build_last.txt` is the exception, not the rule.
|
||||
- **Do not commit `player_auth.json` or `src/player_auth.json`** — they contain live
|
||||
credentials (`auth_code`, `player_id`, `server_url`). These are currently tracked; treat any
|
||||
future change to them as a deliberate, reviewed decision.
|
||||
- Do not commit `config\app_config.json` values that are host-specific without checking
|
||||
whether they belong in the repo default.
|
||||
Reference in New Issue
Block a user