Repository navigation
Add Knulli/RG35XX SP packaging with pygame-ce squashfs runtime - #27
Merged
Merged
Conversation
Package the existing cardbrick-py app (unchanged) with a self-contained ARM64 Python squashfs runtime, following the approach proven by viniciusfs/pygame-ce-runtime on Knulli / Allwinner H700 hardware. - deploy/knulli/runtime-build/: Docker ARM64 builder that compiles pygame-ce 2.5.6 from source (links the firmware's SDL2, so the mali video driver works) plus the app's runtime deps into one squashfs - deploy/knulli/CardBrick.sh: on-device launcher — mounts the runtime (loop/squashfuse/extracted fallbacks), keeps all writes in /userdata/saves/cardbrick, first-boot smoke test, arg passthrough for --smoke-test / --input-diagnostic over SSH - deploy/knulli/scripts/: build_runtime.sh, build_package.sh (stage + versioned zip + sha256 manifest), validate_package.sh (pre-deploy PASS/WARN/FAIL checks), deploy_sdcard.sh (auto-detects the mounted SHARE partition), deploy_ssh.sh (tar-over-ssh, checksum-skips the runtime upload, on-device manifest verify, optional remote smoke) - deploy/knulli/Makefile: runtime / package / validate / deploy-sd / deploy-ssh / smoke-ssh targets - deploy/knulli/PACKAGING.md: end-to-end walkthrough + troubleshooting; README.md points at it; build outputs gitignored Validated locally: full package build + validation, corruption detection, SD deploy against a fake card layout, and the launcher run end-to-end against an extracted runtime — the app's own smoke test passes on the bundled interpreter. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TWGDLyDfezo58FxbCFzKih
tar --exclude patterns for unslashed names like '__pycache__' aren't guaranteed to prune nested directories the same way across GNU tar and macOS's bsdtar, so a dev tree with leftover pytest caches could ship into the package undetected until validate_package.sh caught it. Copy first, then strip with find+rm, which behaves identically on both. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TWGDLyDfezo58FxbCFzKih
The previous fix (find+rm after a full tar copy) still missed a real case: a local dev virtualenv living inside cardbrick-py/ (.venv, venv, env) gets copied wholesale by 'tar cf - cardbrick-py', and installed packages routinely ship their own nested tests/ and __pycache__ dirs that aren't covered by removing the top-level cardbrick-py/tests. Any denylist misses cruft with a name/location we didn't anticipate. build_package.sh now copies only the known-shipped paths (main.py, requirements.txt, README.md, cardbrick/, assets/, scripts/ — matching package_layout.md), so a stray venv next to the source is never touched regardless of what it contains. Also make validate_package.sh's stray-file check print the offending paths (up to 5) instead of just failing silently, so a future leak is diagnosable from the script output alone. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TWGDLyDfezo58FxbCFzKih
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a complete, production-ready packaging pipeline for deploying CardBrick to Knulli handheld devices (RG35XX SP and compatible hardware). The solution uses a self-contained ARM64 Python 3.12 + pygame-ce 2.5.6 runtime packaged as a SquashFS image, eliminating device-side dependencies while ensuring pygame-ce links against the firmware's SDL2 (enabling proper
mali/kmsdrmvideo driver support).Key Changes
PACKAGING.md: Comprehensive guide covering the entire workflow—from building the runtime once via Docker to deploying via SD card or SSH, with troubleshooting and on-device architecture details.
CardBrick.sh: On-device launch script that:
PYTHONHOME,PYTHONPATH,LD_LIBRARY_PATH)--smoke-test,--input-diagnostic)Build pipeline (
scripts/):build_runtime.sh: Host wrapper for Docker-based ARM64 runtime compilationbuild_package.sh: Stages the app + runtime intodist/, generates checksums and BUILD_INFOvalidate_package.sh: Pre-deployment checks (bash syntax, required files, no caches, py_compile, squashfs integrity, manifest verification)deploy_sdcard.sh: Auto-detects mounted Knulli SD card and copies the packagedeploy_ssh.sh: Uploads via tar-over-ssh with smart runtime skipping (checksums match), optional on-device smoke testRuntime builder (
runtime-build/):docker-compose.yml: ARM64 Debian container for compilationbuild-runtime.sh: Compiles pygame-ce from source against SDL2 headers (not manylinux wheel), installs extra deps, packs venv into squashfsbuild-config: Version pins (Python 3.12.8, pygame-ce 2.5.6—validated upstream on RG35XX-H)requirements.txt: Extra Python packages baked into the runtimeMakefile: Convenient targets for the full workflow (
make runtime,make package,make deploy-ssh, etc.)Updated README.md: Points to PACKAGING.md as the primary reference; notes the older vendored-wheels approach as a fallback.
Notable Implementation Details
libSDL2-2.0.so.0, which resolves to Knulli's firmware SDL2 with proper video drivers—unlike the manylinux wheel which bundles its own SDL2..pycfiles are redirected to the data directory viaPYTHONPYCACHEPREFIXso the app and runtime remain immutable.--no-runtimeflag enables fast code-only iteration.https://claude.ai/code/session_01TWGDLyDfezo58FxbCFzKih