Development Environment Setup

Overview

Building and flashing with the Rust SDK needs only the Rust toolchain. Linking uses the rust-lld that ships with Rust, and image packaging and UART flashing are implemented by the SDK’s ameba-flash crate.

Tool

Source

Purpose

Rust toolchain

Rust official

Compile Rust code and link the ELF firmware

ameba-flash (optional)

Rust SDK

Command-line cargo runner that packages an ELF into app.bin, flashes it over UART and opens a serial monitor. Only needed for cargo run inside an example or a project generated by ameba-generate; cargo xtask uses the same code as a library and does not need it installed

Install the Rust Toolchain

Linux / WSL:
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none --profile minimal
$ source ~/.cargo/env

source ~/.cargo/env only affects the current shell. If cargo is reported as command not found in a shell opened later, run it again or add ~/.cargo/bin to PATH.

Note

Users in mainland China may set the following mirrors before installing:

$ export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
$ export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup

Install the Stable Toolchain

rust-toolchain.toml at the repository root pins the required stable channel and cross-compilation targets. rustup installs everything automatically the first time rustc is run inside the repository.

Run the following from the Rust SDK root:

Linux / WSL:
$ cd <workdir>/rust
$ rustc --version

The first run triggers an automatic download and installation (may take a few minutes).

Install ameba-flash (Optional)

ameba-flash is installed once from the Rust SDK checkout, and the Bootloader, Wi-Fi core firmware and flash loader it flashes are embedded in the binary:

$ cd <workdir>/rust
$ cargo install --path ameba-flash --locked

Make sure ~/.cargo/bin (%USERPROFILE%\.cargo\bin on Windows) is on PATH.

Note

cargo install run inside the Rust SDK checkout may print warning: default toolchain implicitly overridden with ... because of rust-toolchain.toml. The installation still succeeds; to silence the warning, use cargo +stable install --path ameba-flash --locked. Installing again replaces any previously installed ameba-flash.

Verify Installation

Linux / WSL:
$ rustup show active-toolchain
stable-x86_64-unknown-linux-gnu (overridden by '.../rust/rust-toolchain.toml')

$ rustup target list --installed | grep thumbv8m.main-none-eabi
thumbv8m.main-none-eabi
thumbv8m.main-none-eabihf