{"id":51115992,"url":"https://github.com/m5stack/CardputerZero-AppBuilder","last_synced_at":"2026-07-13T04:00:58.601Z","repository":{"id":356300430,"uuid":"1224171711","full_name":"m5stack/CardputerZero-AppBuilder","owner":"m5stack","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-30T11:38:42.000Z","size":4943,"stargazers_count":47,"open_issues_count":2,"forks_count":10,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-06-30T13:18:18.195Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m5stack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-29T03:00:06.000Z","updated_at":"2026-06-30T11:38:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/m5stack/CardputerZero-AppBuilder","commit_stats":null,"previous_names":["m5stack/cardputerzero-appbuilder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/m5stack/CardputerZero-AppBuilder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m5stack%2FCardputerZero-AppBuilder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m5stack%2FCardputerZero-AppBuilder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m5stack%2FCardputerZero-AppBuilder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m5stack%2FCardputerZero-AppBuilder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m5stack","download_url":"https://codeload.github.com/m5stack/CardputerZero-AppBuilder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m5stack%2FCardputerZero-AppBuilder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35409469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-24T22:00:24.003Z","updated_at":"2026-07-13T04:00:58.594Z","avatar_url":"https://github.com/m5stack.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# CardputerZero AppBuilder\n\nOnline build system \u0026 desktop development toolkit for [M5CardputerZero](https://docs.m5stack.com/) applications. Submit any public Git repository and get a ready-to-install `.deb` package — no local toolchain required. Or develop locally with the built-in emulator.\n\n## Desktop Emulator\n\nThe `czdev` CLI includes a desktop emulator that renders the CardputerZero 320x170 LCD inside a keyboard skin. Develop and test apps without a physical device.\n\n### NC2000 (文曲星 PDA Emulator)\n\n```bash\ncargo run -p czdev --release -- run apps/nc2000\n```\n\n![NC2000 Emulator](docs/nc2000_emu.png)\n\n### APPLauncher (Home Screen)\n\n```bash\ncargo run -p czdev --release -- run apps/applaunch/\n```\n\n![APPLauncher Emulator](docs/emu-applauncher.png)\n\n### Hello CardputerZero (Example App)\n\n```bash\ncargo run -p czdev --release -- run examples/key_echo\n```\n\n![Hello Example](docs/emu-hello.png)\n\n## Quickstart — Desktop Dev\n\n[中文](docs/QUICKSTART_ZH.md) | [日本語](docs/QUICKSTART_JA.md)\n\nGet a 320x170 LVGL app running on your Mac or Linux machine in ~3 minutes — no CardputerZero device required.\n\n### 1. Prerequisites\n\n**macOS:**\n```bash\nbrew install cmake pkg-config sdl2 sdl2_image sdl2_mixer freetype\n```\n\n**Linux (Debian/Ubuntu):**\n```bash\nsudo apt install -y build-essential cmake pkg-config \\\n    libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libfreetype-dev\n```\n\n**Windows:** MSYS2 MINGW64 shell. See [DESKTOP_DEV.md §4](docs/DESKTOP_DEV.md#4-windows-lvgl--emulator--known-issues-and-plan) for Windows-specific notes.\n\nYou also need a recent Rust toolchain (for the emulator commands in `czdev`):\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n```\n\n\u003e **Note:** Publishing commands (`./czdev login/publish/unpublish/bump`) only require Python 3 — no Rust needed.\n\n### 2. Clone with submodules\n\n```bash\ngit clone --recursive git@github.com:m5stack/CardputerZero-AppBuilder.git\ncd CardputerZero-AppBuilder\n```\n\nIf you already cloned without `--recursive`:\n```bash\ngit submodule update --init --recursive\n```\n\n### 3. Verify the environment\n\n```bash\ncargo run -p czdev --release -- doctor\n```\n\nAll required rows should be green. If anything is MISSING, the output shows the exact install command for your OS.\n\n### 4. Run the hello app\n\n```bash\ncargo run -p czdev --release -- run examples/hello_cz\n```\n\nOn first run this will:\n1. Build the emulator (once, cached in `emulator/build/`).\n2. Build the app into `.czdev/build/`.\n3. Stage the resulting shared library into the emulator's `apps/` directory.\n4. Launch the emulator with the app loaded via `dlopen`.\n\n### 5. Edit-run loop\n\n```bash\ncargo run -p czdev --release -- watch examples/hello_cz\n```\n\nThe watcher polls `src/`, `include/`, `assets/`, `CMakeLists.txt` and `app-builder.json`. Any change triggers a rebuild and relaunches the emulator.\n\n### 6. Writing your own app\n\nCopy `examples/hello_cz/` and edit `src/hello_cz.c`. The ABI:\n\n```c\n#include \u003ccz_app.h\u003e\n\nvoid app_main(lv_obj_t *parent) {\n    lv_obj_t *label = lv_label_create(parent);\n    lv_label_set_text(label, \"your UI here\");\n    lv_obj_center(label);\n}\n\nvoid app_event(int type, void *data) {\n    (void)type; (void)data;\n}\n```\n\nThe `CMakeLists.txt`:\n\n```cmake\ncmake_minimum_required(VERSION 3.16)\nlist(APPEND CMAKE_MODULE_PATH \"${CMAKE_CURRENT_LIST_DIR}/../../sdk/cmake\")\ninclude(CZApp)\ncz_add_lvgl_app(my_app SOURCES src/my_app.c)\n```\n\nAnd the manifest (`app-builder.json`, see [docs/APP_BUILDER_JSON.md](docs/APP_BUILDER_JSON.md)):\n\n```json\n{\n  \"package_name\": \"my_app\",\n  \"bin_name\": \"my_app\",\n  \"app_name\": \"My App\",\n  \"runtime\": \"lvgl-dlopen\",\n  \"lvgl_version\": \"9.5\"\n}\n```\n\n### 7. Shipping to a real device\n\nBuild the aarch64 `.deb` via CI (trigger the `build-deb.yml` workflow), then deploy:\n\n```bash\ncargo run -p czdev --release -- deploy \\\n    --host pi@192.168.50.150 \\\n    --deb path/to/my_app_arm64.deb\n```\n\n### 8. Publishing to the AppStore\n\nPublishing uses the Python-based `czdev` wrapper (no Rust toolchain needed):\n\n```bash\n# Login to GitHub (one-time)\n./czdev login\n\n# Check next version\n./czdev bump --deb build/my_app_1.0.0_arm64.deb\n\n# Publish (version in deb must be newer than existing)\n./czdev publish --deb build/my_app_1.0.1_arm64.deb\n\n# Remove your own package\n./czdev unpublish my_app --version 1.0.1\n```\n\nRequirements: Python 3, `git`, `git-lfs`, `dpkg-deb`.\n\n#### Publish Workflow\n\n```\n┌──────────────────────────────────────────────────────────────────────────────┐\n│                    czdev publish — End-to-End Flow                            │\n└──────────────────────────────────────────────────────────────────────────────┘\n\n ┌─────────┐         ┌─────────┐         ┌──────────┐         ┌─────────────┐\n │  LOGIN  │────────▶│  BUILD  │────────▶│  PUBLISH │────────▶│   REVIEW    │\n └─────────┘         └─────────┘         └──────────┘         └─────────────┘\n      │                    │                    │                      │\n      ▼                    ▼                    ▼                      ▼\n czdev login          czdev build         czdev publish           Admin merges\n (GitHub OAuth        or CI workflow       --deb xxx.deb           the PR\n  Device Flow)        ─▶ .deb artifact    ┌────────────┐          │\n      │                                   │ Preflight: │          ▼\n      ▼                                   │ • .desktop │    ┌───────────┐\n Token saved                              │ • email ✓  │    │  RELEASE  │\n ~/.config/                               │ • version ✓│    └───────────┘\n czdev/token                              │ • size ✓   │          │\n                                          └─────┬──────┘          ▼\n                                                │           APT repo updated\n                                                ▼           App live in Store\n                                          Fork + Push\n                                          ─▶ PR created\n                                             on packages\n\n─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─\n\n Timeline:\n\n You (Developer)                  czdev                     GitHub (Remote)\n ───────────────                  ─────                     ───────────────\n      │                             │                             │\n      │── czdev login ─────────────▶│── OAuth Device Flow ──────▶│\n      │                             │◀── access token ───────────│\n      │                             │                             │\n      │── czdev publish ───────────▶│                             │\n      │                             │── validate .deb ──────────▶│ (check ver)\n      │                             │── fork packages repo ─────▶│\n      │                             │── git push (LFS) ─────────▶│\n      │                             │── POST /pulls ────────────▶│\n      │◀── PR URL ─────────────────│                             │\n      │                             │                             │\n      │                             │              Admin reviews \u0026 merges\n      │                             │                             │\n      │                             │              CI rebuilds APT index\n      │                             │                             │\n      │◀───────────────────── App available in AppStore ─────────│\n      │                                                           │\n```\n\n## Install czdev\n\n`czdev` is split into two parts:\n\n**Publishing commands** (`login`, `logout`, `bump`, `publish`, `unpublish`) — pure Python, no compilation needed:\n\n```bash\ngit clone --recursive git@github.com:m5stack/CardputerZero-AppBuilder.git\ncd CardputerZero-AppBuilder\n./czdev --help    # works immediately with Python 3\n```\n\n**Emulator commands** (`doctor`, `list`, `build`, `run`, `watch`, `deploy`) — require Rust toolchain:\n\n```bash\ncargo build --release -p czdev\n# Binary at: target/release/czdev\ncargo run -p czdev --release -- run examples/hello_cz\n```\n\n## CI Online Build\n\n1. Go to **Actions** \u003e **Build DEB Package** \u003e **Run workflow**\n2. Fill in the form:\n\n   | Field | Required | Example | Description |\n   |-------|----------|---------|-------------|\n   | **Repository URL** | Yes | `https://github.com/eggfly/M5CardputerZero-UserDemo.git` | Any public HTTP Git URL (GitHub, GitCode, Gitee, etc.) |\n   | **Branch** | No | `master` | Leave empty to use the repository's default branch |\n\n3. The system automatically scans for `app-builder.json` files in the repo, builds each project, and packages them as `.deb`\n4. Download the `.deb` from the workflow run's **Artifacts** section\n\n### Install on Device\n\n```bash\nscp \u003cpackage\u003e_arm64.deb pi@\u003cdevice-ip\u003e:/tmp/\nssh pi@\u003cdevice-ip\u003e \"sudo dpkg -i /tmp/\u003cpackage\u003e_arm64.deb\"\n```\n\n## Architecture\n\nThe CI pipeline runs on x86_64 and **cross-compiles** to ARM64 (aarch64) using the `aarch64-linux-gnu-` toolchain — the same approach used by the [M5Stack_Linux_Libs](https://github.com/m5stack/M5Stack_Linux_Libs) SDK.\n\n```\nUser Input (repo URL)\n        │\n        ▼\n  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n  │  git clone   │────▶│   discover   │────▶│ scons build  │────▶│  dpkg-deb    │\n  │  --recursive │     │ app-builder  │     │ (x86→arm64)  │     │  packaging   │\n  └──────────────┘     │    .json     │     └──────────────┘     └──────────────┘\n                       └──────────────┘              │\n                              │                      ▼\n                        N projects          N × .deb artifacts\n                        (parallel)            (download)\n```\n\n## DEB Package Structure\n\nGenerated packages follow the [APPLaunch packaging conventions](https://github.com/dianjixz/M5CardputerZero-UserDemo/blob/main/doc/APPLaunch-App-%E6%89%93%E5%8C%85%E6%8C%87%E5%8D%97.md):\n\n```\n\u003cpackage\u003e.deb\n├── DEBIAN/\n│   ├── control\n│   ├── postinst      (enable \u0026 start systemd service)\n│   └── prerm         (stop \u0026 disable service)\n├── lib/systemd/system/\n│   └── \u003cpackage\u003e.service\n└── usr/share/APPLaunch/\n    ├── applications/\u003cpackage\u003e.desktop\n    ├── bin/\u003cexecutable\u003e\n    ├── lib/\n    └── share/\n        ├── font/*.ttf\n        └── images/*.png\n```\n\n## Troubleshooting\n\n- **`emulator submodule not checked out`** — you forgot `--recursive`. Fix: `git submodule update --init --recursive`.\n- **LVGL link errors about unresolved symbols** — expected in the app library; resolved at `dlopen` time by the emulator.\n- **`indev_read_cb is not registered` warnings** — benign; the emulator falls back to a default keypad indev.\n- **macOS: `Library not loaded: @rpath/SDL2.framework/...`** — re-run `czdev doctor` and install what it reports.\n\n## Related Projects\n\n- [M5CardputerZero-UserDemo](https://github.com/dianjixz/M5CardputerZero-UserDemo) — Reference user demo application\n- [M5Stack_Linux_Libs](https://github.com/m5stack/M5Stack_Linux_Libs) — SDK with SCons build system\n- [m5stack-linux-dtoverlays](https://github.com/m5stack/m5stack-linux-dtoverlays) — Device tree overlays \u0026 drivers\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm5stack%2FCardputerZero-AppBuilder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm5stack%2FCardputerZero-AppBuilder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm5stack%2FCardputerZero-AppBuilder/lists"}