Desktop dev loop: czdev CLI + emulator + SDK + NC2000/APPLaunch/LVGL demos

[eggfly]

Lays down a working desktop development environment for CardputerZero LVGL apps on macOS and Linux — clone, run one command, see a 320×170 LCD skin with your app loaded. Same source tree builds into an aarch64 .deb via the existing CI. Windows is pre-wired with a known-issue plan (T08 in docs/DESKTOP_DEV.md §4).

What you can run today

git checkout ci/desktop-dev
git submodule update --init --recursive
cargo run -p czdev --release -- doctor
cargo run -p czdev --release -- run examples/hello_cz       # minimal cz_app.h
cargo run -p czdev --release -- run examples/lvgl_widgets   # lv_demo_widgets
cargo run -p czdev --release -- run examples/lvgl_music     # lv_demo_music
cargo run -p czdev --release -- run examples/key_echo       # lv_demo_keypad_encoder
cargo run -p czdev --release -- run apps/applaunch          # real APPLaunch (from UserDemo)
cargo run -p czdev --release -- run apps/nc2000             # Wenquxing NC2000 emulator

All verified running locally (macOS/arm64). CI run: https://github.com/m5stack/CardputerZero-AppBuilder/actions/runs/25414878081 (mac + Linux smoke green).

Architecture

Piece	What it is
emulator/ (submodule)	SDL2 + LVGL 9.5 host, force-loads lvgl + lvgl_demos so dlopen'd apps can use built-in widgets/music/keypad demos as host symbols
sdk/include/cz_app.h	Public C ABI: app_main(lv_obj_t *parent) + app_event(int, void*) + CZ_EV_* enum — same contract on desktop and on the device
sdk/include/lv_conf.h	Pinned LVGL v9.5 config, byte-matches the emulator's
sdk/cmake/CZApp.cmake	cz_add_lvgl_app(name SOURCES ...) one-liner — handles per-OS link flags, generates ui_init thunk, default weak keyboard stubs with a real indev read_cb
crates/czdev/	Rust CLI in a Cargo workspace alongside src-tauri/ — doctor / list / build / run / watch / deploy
apps/applaunch/	Zero edits to UserDemo — reuses the libAPPLaunch.dylib the emulator's own CMake builds; new runtime: "prebuilt-emulator-app"
apps/nc2000/	Submodule to CardputerZero-NC2000:ci-cd which adds port_lvgl/ alongside existing port_fb/ — produces libnc2000.dylib implementing the cz_app.h ABI, NC2000_ROM_DIR auto-set via manifest env

Manifest schema (app-builder.json)

Backward-compatible extension: existing packaging fields (package_name, version, bin_name, …) keep working. New optional fields for desktop dev:

• runtime: "lvgl-dlopen" (default), "legacy-deb-only", "prebuilt-emulator-app"
• entry / event_entry: C symbol names (default app_main / app_event)
• lvgl_version: host must match on major.minor (currently "9.5")
• cmake_args: extra -DX=Y args with ${CZ_SDK_DIR} / ${CZ_LVGL_DIR} substitution
• cmake_target: override the CMake target name
• env: runtime env vars with ${APP_DIR} substitution
• caps: declared capabilities (keyboard, audio, network, …) — metadata now, wiring later

Full schema: docs/APP_BUILDER_JSON.md.

What's explicitly out of scope this round

Listed in docs/DESKTOP_DEV.md §5:

• Python / Qt / Tkinter / raw-framebuffer examples (stays on CardputerZero-Examples/scripts/dev-on-mac/ Docker path)
• Subprocess + SHM runtime channel (dlopen covers 100% of LVGL apps)
• Hot dlclose / live reload (czdev watch restarts the emulator instead)
• Full Windows support: LVGL DLL rework is planned as T08 with an 8-issue table in docs/DESKTOP_DEV.md §4. The CI has a windows-todo placeholder job that surfaces this rather than failing silently.

CI

.github/workflows/desktop-smoke.yml — mac + Linux matrix, builds the emulator + hello_cz via czdev, headless-launches with SDL_VIDEODRIVER=dummy and asserts the process survives 5 s.

Submodule notes

• emulator/ pinned to eggfly/M5CardputerZero-Emulator:ci-cd (repo unarchived for this PR; two-commit diff: force-load lvgl_demos + enable music/keypad demo flags).
• apps/nc2000/ tracks eggfly/CardputerZero-NC2000:ci-cd (adds port_lvgl/ and its manifest; leaves port_fb/ untouched).
• M5CardputerZero-UserDemo is not modified — APPLaunch is consumed via the emulator submodule's existing vendor path.

🤖 Generated with Claude Code