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 |
|
Rust SDK |
Command-line cargo runner that packages an ELF into |
Install the Rust Toolchain
$ 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 MSYS2:
winget install MSYS2.MSYS2
Open MSYS2 MSYS from the Start menu and run:
$ pacman -Syu
$ pacman -S --needed mingw-w64-x86_64-gcc
Open System Properties → Advanced → Environment Variables and add
C:\msys64\mingw64\bin to the user Path if it is not already present.
Install rustup in PowerShell:
Invoke-WebRequest https://win.rustup.rs/x86_64 -OutFile "$env:TEMP\rustup-init.exe"
& "$env:TEMP\rustup-init.exe" -y --default-host x86_64-pc-windows-gnu --default-toolchain none --profile minimal
Open a new PowerShell window after installation completes.
Note
Users in mainland China may set the following mirrors before installing:
$env:RUSTUP_DIST_SERVER = "https://mirrors.tuna.tsinghua.edu.cn/rustup"
$env:RUSTUP_UPDATE_ROOT = "https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup"
These can also be added as permanent system environment variables.
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none --profile minimal
$ source ~/.cargo/env
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:
$ cd <workdir>/rust
$ rustc --version
cd <workdir>/rust
rustc --version
$ 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
$ 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
> rustup show active-toolchain
stable-x86_64-pc-windows-gnu (overridden by '.../rust/rust-toolchain.toml')
> rustup target list --installed | findstr thumbv8m
thumbv8m.main-none-eabi
thumbv8m.main-none-eabihf
> where.exe x86_64-w64-mingw32-gcc
C:\msys64\mingw64\bin\x86_64-w64-mingw32-gcc.exe
$ rustup show active-toolchain
stable-aarch64-apple-darwin (overridden by '.../rust/rust-toolchain.toml')
$ rustup target list --installed | grep thumbv8m.main-none-eabi
thumbv8m.main-none-eabi
thumbv8m.main-none-eabihf