From 17805e3c04f434aba1dd49bc6fda07f5f2c36bcb Mon Sep 17 00:00:00 2001 From: LiHaohua Date: Thu, 7 May 2026 20:00:16 +0800 Subject: [PATCH] docs: add Chinese and Japanese quickstart guides for czdev CLI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds QUICKSTART_ZH.md and QUICKSTART_JA.md covering the full desktop dev workflow (doctor → run → watch → deploy). Links added to the English quickstart and README. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 2 + crates/czdev/src/manifest.rs | 1 + docs/QUICKSTART.md | 2 + docs/QUICKSTART_JA.md | 164 +++++++++++++++++++++++++++++++++++ docs/QUICKSTART_ZH.md | 162 ++++++++++++++++++++++++++++++++++ 5 files changed, 331 insertions(+) create mode 100644 docs/QUICKSTART_JA.md create mode 100644 docs/QUICKSTART_ZH.md diff --git a/README.md b/README.md index aab607b..d9893f1 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Online build system for [M5CardputerZero](https://docs.m5stack.com/) applications. Submit any public Git repository and get a ready-to-install `.deb` package — no local toolchain required. +**Desktop Dev (czdev CLI):** [Quickstart](docs/QUICKSTART.md) | [快速上手](docs/QUICKSTART_ZH.md) | [クイックスタート](docs/QUICKSTART_JA.md) + ## How It Works 1. Go to **Actions** > **Build DEB Package** > **Run workflow** diff --git a/crates/czdev/src/manifest.rs b/crates/czdev/src/manifest.rs index 72cbe34..9ce9edc 100644 --- a/crates/czdev/src/manifest.rs +++ b/crates/czdev/src/manifest.rs @@ -5,6 +5,7 @@ use serde::Deserialize; use std::path::{Path, PathBuf}; #[derive(Debug, Deserialize, Clone)] +#[allow(dead_code)] pub struct Manifest { pub package_name: String, #[serde(default = "default_version")] diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 22ba56c..0c8ec89 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -1,5 +1,7 @@ # Quickstart — desktop dev for CardputerZero apps +[中文](QUICKSTART_ZH.md) | [日本語](QUICKSTART_JA.md) + Get a 320×170 LVGL app running on your Mac or Linux machine in ~3 minutes — no CardputerZero device required. diff --git a/docs/QUICKSTART_JA.md b/docs/QUICKSTART_JA.md new file mode 100644 index 0000000..331cf9e --- /dev/null +++ b/docs/QUICKSTART_JA.md @@ -0,0 +1,164 @@ +# クイックスタート — CardputerZero デスクトップ開発 (czdev CLI) + +[English](QUICKSTART.md) | [中文](QUICKSTART_ZH.md) + +CardputerZero 実機がなくても、Mac / Linux 上で約3分で 320×170 LVGL アプリを動かせます。 + +## 1. 依存関係のインストール + +**macOS:** +```bash +brew install cmake pkg-config sdl2 sdl2_image sdl2_mixer freetype +``` + +**Linux (Debian/Ubuntu):** +```bash +sudo apt install -y build-essential cmake pkg-config \ + libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libfreetype-dev +``` + +**Windows:** MSYS2 MINGW64 環境が必要です。詳細は +[DESKTOP_DEV.md §4](DESKTOP_DEV.md#4-windows-lvgl--emulator--known-issues-and-plan) +を参照。現状 macOS / Linux のワークフローが完全にサポートされています。 + +Rust ツールチェーン（`czdev` のビルドに必要）： +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +## 2. リポジトリのクローン（サブモジュール含む） + +```bash +git clone --recursive git@github.com:m5stack/CardputerZero-AppBuilder.git +cd CardputerZero-AppBuilder +``` + +`--recursive` を付け忘れた場合： +```bash +git submodule update --init --recursive +``` + +## 3. 開発環境の確認 + +```bash +cargo run -p czdev --release -- doctor +``` + +required の行がすべて OK なら準備完了。MISSING と表示されたら、 +出力に書かれたインストールコマンドを実行してください。 + +## 4. hello サンプルを実行 + +```bash +cargo run -p czdev --release -- run examples/hello_cz +``` + +初回実行時は： + +1. エミュレータをビルド（初回のみ、`emulator/build/` にキャッシュ） +2. `examples/hello_cz` を `.czdev/build/` にビルド +3. 生成された `libhello_cz.dylib`（または `.so`）をエミュレータの `apps/` にコピー +4. エミュレータを起動し、`dlopen` でアプリをロード + +320×170 の LCD ウィンドウ（キーボードスキン付き）に `Hello, CardputerZero!` と表示されます。 +ウィンドウを閉じれば終了。 + +## 5. ホットリロード開発ループ + +```bash +cargo run -p czdev --release -- watch examples/hello_cz +``` + +`watch` は `src/`、`include/`、`assets/`、`CMakeLists.txt`、 +`app-builder.json` を監視し、変更を検出すると自動で再ビルド＋エミュレータ再起動します。 + +## 6. 自分のアプリを作る + +`examples/hello_cz/` をコピーして `src/hello_cz.c` を編集。ABI 定義は +`sdk/include/cz_app.h` にあります： + +```c +#include + +void app_main(lv_obj_t *parent) { + lv_obj_t *label = lv_label_create(parent); + lv_label_set_text(label, "あなたのUIコード"); + lv_obj_center(label); +} + +void app_event(int type, void *data) { + (void)type; (void)data; +} +``` + +`CMakeLists.txt` はたった3行： + +```cmake +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) +``` + +`app-builder.json` マニフェスト（詳細は `docs/APP_BUILDER_JSON.md`）： + +```json +{ + "package_name": "my_app", + "bin_name": "my_app", + "app_name": "My App", + "runtime": "lvgl-dlopen", + "lvgl_version": "9.5" +} +``` + +## 7. 実機へのデプロイ + +arm64 `.deb` は CI でビルドします — リポジトリの `build-deb.yml` ワークフローを +トリガーしてください。その後デバイスへ転送： + +```bash +cargo run -p czdev --release -- deploy \ + --host pi@192.168.50.150 \ + --deb path/to/my_app_arm64.deb +``` + +## czdev コマンド一覧 + +| コマンド | 機能 | +|----------|------| +| `czdev doctor` | 依存関係のチェック（cmake, SDL2, freetype 等） | +| `czdev list [パス]` | ディレクトリ内の `app-builder.json` プロジェクトを一覧表示 | +| `czdev build [パス]` | アプリの共有ライブラリ（.dylib / .so）をビルド | +| `czdev run [パス]` | ビルド＋エミュレータ起動でアプリをロード | +| `czdev watch [パス]` | ソース変更を監視し、自動再ビルド＋再起動 | +| `czdev deploy --host --deb` | .deb を SSH でデバイスに転送＋インストール | + +すべてのコマンドは `cargo run -p czdev --release --` のプレフィックス付きで実行します。 +または `cargo install --path crates/czdev` でグローバルにインストールすることも可能です。 + +## トラブルシューティング + +- **`emulator submodule not checked out`** — `git submodule update --init --recursive` +- **LVGL 未定義シンボルのリンクエラー** — 正常です（ランタイムにエミュレータが提供）。 + linker が error（warning ではなく）を出す場合は `DESKTOP_DEV.md` を参照 +- **macOS `Library not loaded: @rpath/SDL2.framework`** — `brew install sdl2` + してから `czdev doctor` を再実行 + +## アーキテクチャ概要 + +``` +┌──────────────────────────────────────────────────────────────┐ +│ cardputer-zero-emu（エミュレータ） │ +│ ┌────────────────┐ ┌────────────────────────────┐ │ +│ │ LVGL 9.5 エンジン│ ◄──── │ SDL2 ウィンドウ (320×170) │ │ +│ │ + フォント/アイコン│ │ + キーボードイベントマッピング│ │ +│ └───────┬────────┘ └────────────────────────────┘ │ +│ │ dlopen(RTLD_GLOBAL) │ +│ ▼ │ +│ ┌────────────────┐ │ +│ │ あなたの App │ ← app_main(parent) / app_event(...) │ +│ │ .dylib / .so │ │ +│ └────────────────┘ │ +└──────────────────────────────────────────────────────────────┘ +``` diff --git a/docs/QUICKSTART_ZH.md b/docs/QUICKSTART_ZH.md new file mode 100644 index 0000000..7cb3429 --- /dev/null +++ b/docs/QUICKSTART_ZH.md @@ -0,0 +1,162 @@ +# 快速上手 — CardputerZero 桌面开发 (czdev CLI) + +[English](QUICKSTART.md) | [日本語](QUICKSTART_JA.md) + +无需 CardputerZero 实体设备，在你的 Mac / Linux 上 3 分钟跑起来一个 320×170 LVGL 应用。 + +## 1. 安装依赖 + +**macOS:** +```bash +brew install cmake pkg-config sdl2 sdl2_image sdl2_mixer freetype +``` + +**Linux (Debian/Ubuntu):** +```bash +sudo apt install -y build-essential cmake pkg-config \ + libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libfreetype-dev +``` + +**Windows:** 需要 MSYS2 MINGW64 环境，参考 +[DESKTOP_DEV.md §4](DESKTOP_DEV.md#4-windows-lvgl--emulator--known-issues-and-plan)。 +目前 macOS / Linux 流程是完整可用的。 + +还需要 Rust 工具链（用于编译 `czdev`）： +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +## 2. 克隆仓库（含子模块） + +```bash +git clone --recursive git@github.com:m5stack/CardputerZero-AppBuilder.git +cd CardputerZero-AppBuilder +``` + +如果你已经克隆但忘了 `--recursive`： +```bash +git submodule update --init --recursive +``` + +## 3. 检查开发环境 + +```bash +cargo run -p czdev --release -- doctor +``` + +所有 required 行应该显示 OK。缺什么就按输出的提示装。 + +## 4. 跑 hello 示例 + +```bash +cargo run -p czdev --release -- run examples/hello_cz +``` + +第一次运行会： + +1. 编译模拟器（仅一次，产物缓存在 `emulator/build/`） +2. 编译 `examples/hello_cz` 到 `.czdev/build/` +3. 把生成的 `libhello_cz.dylib`（或 `.so`）复制到模拟器 `apps/` 目录 +4. 启动模拟器，通过 `dlopen` 加载你的 App + +你会看到一个 320×170 的 LCD 窗口（带键盘皮肤），显示 `Hello, CardputerZero!`。 +关闭窗口即退出。 + +## 5. 热重载开发循环 + +```bash +cargo run -p czdev --release -- watch examples/hello_cz +``` + +`watch` 会监视 `src/`、`include/`、`assets/`、`CMakeLists.txt` 和 +`app-builder.json`。任何文件修改后自动重新编译并重启模拟器。 + +## 6. 写你自己的 App + +复制 `examples/hello_cz/` 然后改 `src/hello_cz.c`。ABI 定义见 +`sdk/include/cz_app.h`： + +```c +#include + +void app_main(lv_obj_t *parent) { + lv_obj_t *label = lv_label_create(parent); + lv_label_set_text(label, "你的界面代码"); + lv_obj_center(label); +} + +void app_event(int type, void *data) { + (void)type; (void)data; +} +``` + +`CMakeLists.txt` 只需三行： + +```cmake +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) +``` + +`app-builder.json` 清单文件（详见 `docs/APP_BUILDER_JSON.md`）： + +```json +{ + "package_name": "my_app", + "bin_name": "my_app", + "app_name": "My App", + "runtime": "lvgl-dlopen", + "lvgl_version": "9.5" +} +``` + +## 7. 部署到真机 + +arm64 `.deb` 通过 CI 构建——触发仓库里的 `build-deb.yml` workflow。 +然后推送到设备： + +```bash +cargo run -p czdev --release -- deploy \ + --host pi@192.168.50.150 \ + --deb path/to/my_app_arm64.deb +``` + +## czdev 命令速查 + +| 命令 | 作用 | +|------|------| +| `czdev doctor` | 检查依赖是否就绪（cmake, SDL2, freetype 等） | +| `czdev list [路径]` | 扫描目录下所有 `app-builder.json` 项目 | +| `czdev build [路径]` | 编译 App 的共享库（.dylib / .so） | +| `czdev run [路径]` | 编译 + 启动模拟器加载 App | +| `czdev watch [路径]` | 监视源码变化，自动重编译 + 重启 | +| `czdev deploy --host --deb` | 将 .deb 通过 SSH 推送到设备 | + +所有命令通过 `cargo run -p czdev --release --` 前缀调用，或者你也可以先 +`cargo install --path crates/czdev` 装到全局 PATH。 + +## 常见问题 + +- **`emulator submodule not checked out`** — `git submodule update --init --recursive` +- **LVGL 未定义符号链接错误** — 正常现象（运行时由模拟器提供），如果 linker 直接 + 报 error 而不是 warning，参考 `DESKTOP_DEV.md` +- **macOS `Library not loaded: @rpath/SDL2.framework`** — `brew install sdl2` + 然后重新跑 `czdev doctor` + +## 架构简图 + +``` +┌──────────────────────────────────────────────────────────────┐ +│ cardputer-zero-emu (模拟器) │ +│ ┌────────────────┐ ┌────────────────────────────┐ │ +│ │ LVGL 9.5 引擎 │ ◄──── │ SDL2 窗口 (320×170) │ │ +│ │ + 字体/图标 │ │ + 键盘事件映射 │ │ +│ └───────┬────────┘ └────────────────────────────┘ │ +│ │ dlopen(RTLD_GLOBAL) │ +│ ▼ │ +│ ┌────────────────┐ │ +│ │ 你的 App .dylib │ ← app_main(parent) / app_event(...) │ +│ └────────────────┘ │ +└──────────────────────────────────────────────────────────────┘ +```