Online build system & desktop development toolkit for M5CardputerZero 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.
The czdev CLI includes a desktop emulator that renders the CardputerZero 320x170 LCD inside a keyboard skin. Develop and test apps without a physical device.
cargo run -p czdev --release -- run apps/nc2000
cargo run -p czdev --release -- run apps/applaunch/
cargo run -p czdev --release -- run examples/key_echo
Get a 320x170 LVGL app running on your Mac or Linux machine in ~3 minutes — no CardputerZero device required.
macOS:
brew install cmake pkg-config sdl2 sdl2_image sdl2_mixer freetypeLinux (Debian/Ubuntu):
sudo apt install -y build-essential cmake pkg-config \
libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libfreetype-devWindows: MSYS2 MINGW64 shell. See DESKTOP_DEV.md §4 for Windows-specific notes.
You also need a recent Rust toolchain (for czdev):
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shgit clone --recursive git@github.com:m5stack/CardputerZero-AppBuilder.git
cd CardputerZero-AppBuilderIf you already cloned without --recursive:
git submodule update --init --recursivecargo run -p czdev --release -- doctorAll required rows should be green. If anything is MISSING, the output shows the exact install command for your OS.
cargo run -p czdev --release -- run examples/hello_czOn first run this will:
- Build the emulator (once, cached in
emulator/build/). - Build the app into
.czdev/build/. - Stage the resulting shared library into the emulator's
apps/directory. - Launch the emulator with the app loaded via
dlopen.
cargo run -p czdev --release -- watch examples/hello_czThe watcher polls src/, include/, assets/, CMakeLists.txt and app-builder.json. Any change triggers a rebuild and relaunches the emulator.
Copy examples/hello_cz/ and edit src/hello_cz.c. The ABI:
#include <cz_app.h>
void app_main(lv_obj_t *parent) {
lv_obj_t *label = lv_label_create(parent);
lv_label_set_text(label, "your UI here");
lv_obj_center(label);
}
void app_event(int type, void *data) {
(void)type; (void)data;
}The CMakeLists.txt:
cmake_minimum_required(VERSION 3.16)
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/../../sdk/cmake")
include(CZApp)
cz_add_lvgl_app(my_app SOURCES src/my_app.c)And the manifest (app-builder.json, see docs/APP_BUILDER_JSON.md):
{
"package_name": "my_app",
"bin_name": "my_app",
"app_name": "My App",
"runtime": "lvgl-dlopen",
"lvgl_version": "9.5"
}Build the aarch64 .deb via CI (trigger the build-deb.yml workflow), then deploy:
cargo run -p czdev --release -- deploy \
--host pi@192.168.50.150 \
--deb path/to/my_app_arm64.deb# Login to GitHub (one-time)
./target/release/czdev login
# Check next version
./target/release/czdev bump --deb build/my_app_1.0.0_arm64.deb
# Publish (version in deb must be newer than existing)
./target/release/czdev publish --deb build/my_app_1.0.1_arm64.deb
# Remove your own package
./target/release/czdev unpublish my_app --version 1.0.1Option A — Build from source (recommended):
git clone --recursive git@github.com:m5stack/CardputerZero-AppBuilder.git
cd CardputerZero-AppBuilder
cargo build --release -p czdev
# Binary at: target/release/czdevThen use directly: ./target/release/czdev <command>
Option B — Download prebuilt binary:
Download from Releases for your platform (macOS/Linux/Windows).
-
Go to Actions > Build DEB Package > Run workflow
-
Fill in the form:
Field Required Example Description Repository URL Yes https://github.com/eggfly/M5CardputerZero-UserDemo.gitAny public HTTP Git URL (GitHub, GitCode, Gitee, etc.) Branch No masterLeave empty to use the repository's default branch -
The system automatically scans for
app-builder.jsonfiles in the repo, builds each project, and packages them as.deb -
Download the
.debfrom the workflow run's Artifacts section
scp <package>_arm64.deb pi@<device-ip>:/tmp/
ssh pi@<device-ip> "sudo dpkg -i /tmp/<package>_arm64.deb"The 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 SDK.
User Input (repo URL)
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ git clone │────▶│ discover │────▶│ scons build │────▶│ dpkg-deb │
│ --recursive │ │ app-builder │ │ (x86→arm64) │ │ packaging │
└──────────────┘ │ .json │ └──────────────┘ └──────────────┘
└──────────────┘ │
│ ▼
N projects N × .deb artifacts
(parallel) (download)
Generated packages follow the APPLaunch packaging conventions:
<package>.deb
├── DEBIAN/
│ ├── control
│ ├── postinst (enable & start systemd service)
│ └── prerm (stop & disable service)
├── lib/systemd/system/
│ └── <package>.service
└── usr/share/APPLaunch/
├── applications/<package>.desktop
├── bin/<executable>
├── lib/
└── share/
├── font/*.ttf
└── images/*.png
emulator submodule not checked out— you forgot--recursive. Fix:git submodule update --init --recursive.- LVGL link errors about unresolved symbols — expected in the app library; resolved at
dlopentime by the emulator. indev_read_cb is not registeredwarnings — benign; the emulator falls back to a default keypad indev.- macOS:
Library not loaded: @rpath/SDL2.framework/...— re-runczdev doctorand install what it reports.
- M5CardputerZero-UserDemo — Reference user demo application
- M5Stack_Linux_Libs — SDK with SCons build system
- m5stack-linux-dtoverlays — Device tree overlays & drivers
MIT