项目生成器(ameba-generate)
概述
ameba-generate 是 Ameba Rust SDK 的项目生成器,一条命令即可生成可直接编译、可直接烧录的裸机 Rust 应用——一个只包含 app 固件 crate 的 workspace,并已配置为使用 SDK 的 ameba-flash 工具作为 cargo runner,无需复制示例工程再手动修改。这是新建项目的推荐方式;手动方式见
快速入门
。
安装
该 crate 尚未发布到 crates.io,需从源码安装:
$ git clone https://github.com/Ameba-AIoT/ameba-generate.git
$ cd ameba-generate
$ cargo install --path . --locked
确认安装:
$ ameba-generate --version
ameba-generate 0.1.0
备注
ameba-generate 还需要 rustfmt 组件,用于格式化生成项目的源码:
$ rustup component add rustfmt
编译和烧录生成的项目还需要 Rust 工具链和 ameba-flash,参见
开发环境搭建
。
快速开始
交互式 TUI(推荐)
不带任何参数运行:
$ ameba-generate
系统会依次提示输入项目名和 SDK 路径。如果不想每次输入 SDK 路径,可以用 --sdk 预先指定,提示中会显示为默认值,直接回车即可接受:
$ ameba-generate --sdk <path/to/rust>
Project name: my-app
SDK path [<path/to/rust>]:
随后进入全屏菜单勾选选项:
┌─────────────────────────────────────────────────────┐
│ ameba-generate — Select options │
├─────────────────────────────────────────────────────┤
│ ▸ Chip │
│ ► [✓] RTL8721F │
│ [✓] Embassy (async runtime) │
│ [ ] Wi-Fi (ameba-wifi, STA bring-up) │
├─────────────────────────────────────────────────────┤
│ Adds embassy-executor and embassy-time for │
│ async/await support. │
├─────────────────────────────────────────────────────┤
│ ↑↓ navigate Space toggle g generate q quit │
└─────────────────────────────────────────────────────┘
按键 |
操作 |
|---|---|
|
移动光标 |
|
切换光标所在选项 |
|
校验并生成项目 |
|
取消退出 |
同一分组内的选项互斥(目前只有 Chip 一个分组):选中一个会自动取消另一个。取消某选项时,依赖它的选项也会一并取消(例如取消 Embassy 会连带取消 Wi-Fi)。未满足依赖时按 g 只会在底部显示红色错误提示,不会退出。
命令行(无头)模式
适用于 CI 环境和脚本调用。在非 TTY 环境下会自动进入该模式,也可用 --headless 显式指定;此外,只要传入了项目名或任一 -o 选项,也会进入该模式,此时必须指定 --sdk:
$ ameba-generate --sdk <path/to/rust> -o rtl8721f -o embassy my-app --headless
✓ Generated project 'my-app' (sdk: <path/to/rust>)
Selected options: rtl8721f, embassy
cd my-app/app && cargo build
cd my-app/app && cargo run --release -- --port <PORT> # package + flash
生成器会在新项目中执行 git init。已安装 git 但未配置 init.defaultBranch 时,上面几行输出之前会先出现 git 打印的 hint: Using 'master' as the name for the initial branch ...;未安装 git 时仍可正常生成,只会打印 warning: could not run git init: program not found。
查看所有可用选项:
$ ameba-generate list-options
Available options:
[chip] Chip
Select the target Ameba SoC.
-o rtl8721f (group: chip) — RTL8721F
-o embassy — Embassy (async runtime)
Adds embassy-executor and embassy-time for async/await support.
-o wifi — Wi-Fi (ameba-wifi, STA bring-up)
Adds the ameba-wifi dependency and brings Wi-Fi up in STA mode at startup (WHC handlers,
background task, wifi_on). Connecting to an AP is left to you — see the SDK's
examples/wifi-connect.
requires: embassy
Required groups: chip
可用选项
选项 |
说明 |
备注 |
|---|---|---|
|
RTL8721F ——必选,芯片分组必须选一个 |
会设置 |
|
Embassy 异步运行时(executor + time) |
—— |
|
添加 |
依赖 |
生成的项目结构
以选择 rtl8721f + embassy 为例:
my-app/
├── .git/ ← 自动执行 git init 生成
├── .gitignore ← 忽略 /target
├── Cargo.toml ← workspace 根(members = ["app"])
├── rust-toolchain.toml ← 工具链锁定(stable)
└── app/ ← 固件 crate,在此目录下运行 `cargo build` / `cargo run`
├── .cargo/
│ └── config.toml ← ARM target、linker、rustflags、ameba-flash runner
├── Cargo.toml ← 依赖声明(ameba-hal、ameba-rt 等)
└── src/
└── main.rs ← 应用入口
选中 wifi 选项时目录结构不变:app/Cargo.toml 会增加 ameba-wifi 依赖,Wi-Fi 启动代码直接生成在 main.rs 中。
为什么 target 配置放在 app/.cargo/config.toml
Cargo 会将某个目录下的 .cargo/config.toml 应用到该目录及其下所有的包。ARM target、链接参数和烧录 runner 都放在 app/.cargo/config.toml 中,只对 app crate 生效;在 workspace 根目录编译会使用主机 target(见
常见错误
)。
app/.cargo/config.toml 内容:
[build]
target = "thumbv8m.main-none-eabi"
[target.thumbv8m.main-none-eabi]
linker = "rust-lld"
runner = "ameba-flash flash --monitor"
rustflags = [
"-Clink-arg=-Tameba.x",
"-Clink-arg=--gc-sections",
"-Clink-arg=--nmagic",
]
编译生成的项目
cargo build 必须在 app/ 子目录下运行,才能读到 app/.cargo/config.toml 中的 ARM target 配置:
$ cd my-app/app
$ cargo build # 调试版
$ cargo build --release # 发布版(opt-level=z,panic=abort)
编译产物是 ELF 文件。app crate 属于 my-app workspace,因此产物位于 workspace 根目录的 target/ 下:
target/thumbv8m.main-none-eabi/debug/my-app
target/thumbv8m.main-none-eabi/release/my-app
烧录(ameba-flash runner)
生成的项目使用 Rust SDK 的 ameba-flash 工具作为 cargo runner。cargo run 编译出 ELF 后交给 ameba-flash,由它提取可加载段、打包 app.bin,与 Bootloader 一起通过串口烧录,并打开串口监视。
从生成时 --sdk 指定的 Rust SDK 目录安装一次 ameba-flash (另见
开发环境搭建
):
$ cargo install --path <rust-sdk>/ameba-flash --locked
Bootloader、Wi-Fi 核固件和 Flash Loader 均已内嵌在可执行文件中。请确认 ~/.cargo/bin 已加入 PATH。
备注
请在 Rust SDK 目录下执行 cargo install。如果提示默认工具链被 rust-toolchain.toml 覆盖,可改用
cargo +stable install --path <rust-sdk>/ameba-flash --locked。重复安装会替换之前已安装的 ameba-flash。
烧录并监视串口:
$ cd my-app/app
$ cargo run --release -- --port /dev/ttyUSB0 # Windows 上为 COM29 等
串口也可以通过环境变量 RTK_SERIAL_PORT 指定:
$ export RTK_SERIAL_PORT=/dev/ttyUSB0
$ cargo run --release
开发板正在运行正常固件时会自动重启进入下载模式;否则请手动让开发板进入下载模式。按 Ctrl-C 退出串口监视。
生成的模板只在启动时打印一次 my-app running,之后空转不再输出,串口监视窗口停在该行属正常现象。
备注
--port 前面的 -- 不能省略,它用于分隔 cargo run 自身的参数与转发给 runner 的参数。