8000 Add Knulli/RG35XX SP packaging with pygame-ce squashfs runtime by jmahmood · Pull Request #27 · jmahmood/CardBrick · GitHub
[go: up one dir, main page]

Skip to content

Add Knulli/RG35XX SP packaging with pygame-ce squashfs runtime - #27

Merged
jmahmood merged 3 commits into
masterfrom
claude/knulli-rg35xx-pygame-packaging-1fxiw3
Jul 8, 2026
Merged

jmahmood merged 3 commits into
masterfrom
claude/knulli-rg35xx-pygame-packaging-1fxiw3

Conversation

@jmahmood
@jmahmood jmahmood commented Jul 8, 2026
Copy link
Copy Markdown
Owner

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/kmsdrm video 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:

    • Loop-mounts the squashfs runtime at startup
    • Configures Python environment (PYTHONHOME, PYTHONPATH, LD_LIBRARY_PATH)
    • Runs a one-time smoke test on first boot
    • Supports passthrough arguments (--smoke-test, --input-diagnostic)
    • Falls back to system Python or extracted runtime if needed
    • Cleans up mounts on exit
  • Build pipeline (scripts/):

    • build_runtime.sh: Host wrapper for Docker-based ARM64 runtime compilation
    • build_package.sh: Stages the app + runtime into dist/, generates checksums and BUILD_INFO
    • validate_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 package
    • deploy_ssh.sh: Uploads via tar-over-ssh with smart runtime skipping (checksums match), optional on-device smoke test
  • Runtime builder (runtime-build/):

    • docker-compose.yml: ARM64 Debian container for compilation
    • build-runtime.sh: Compiles pygame-ce from source against SDL2 headers (not manylinux wheel), installs extra deps, packs venv into squashfs
    • build-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 runtime
  • Makefile: 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

  • Source-built pygame-ce: Compiled against Debian SDL2 headers so it dynamically links 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.
  • Read-only app tree: .pyc files are redirected to the data directory via PYTHONPYCACHEPREFIX so the app and runtime remain immutable.
  • Smart deployment: SSH deploy skips the ~100 MB runtime when checksums match; --no-runtime flag enables fast code-only iteration.
  • Comprehensive validation: Pre-deploy checks catch syntax errors, missing files, stray caches, and squashfs corruption before touching a device.
  • Fallback chain: Prefers squashfs mount → unsquashed extracted runtime → system Python, with clear logging at each step.

https://claude.ai/code/session_01TWGDLyDfezo58FxbCFzKih

claude added 3 commits July 8, 2026 03:07
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
@jmahmood
jmahmood merged commit 874c8ac into master Jul 8, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

0