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).
ske087