You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+1-314Lines changed: 1 addition & 314 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,319 +4,6 @@ This repository contains:
4
4
5
5
- Workflows for building a Rust fork [esp-rs/rust](https://github.com/esp-rs/rust) with Xtensa support
6
6
- Binary artifacts in [Releases](https://github.com/esp-rs/rust-build/releases)
7
-
- An [installation script](install-rust-toolchain.sh) to locally install a pre-compiled nightly ESP32 toolchain
8
7
9
-
If you want to know more about the Rust ecosystem on ESP targets, see [The Rust on ESP Book chapter](https://esp-rs.github.io/book/installation/index.html)
> For Windows MSVC/GNU, Rust environment can also be installed with Universal Online idf-installer: https://dl.espressif.com/dl/esp-idf/
86
-
87
-
### Windows x86_64 MSVC
88
-
89
-
The following instructions are specific for the ESP32 and ESP32-S series based on Xtensa architecture. If you do not have Visual Studio and Windows 10 SDK installed, consider the alternative option [Windows x86_64 GNU](#windows-x86_64-gnu).
90
-
91
-
Instructions for ESP-C series based on RISC-V architecture are described in [RISC-V section](#risc-v-installation).
92
-
93
-
#### Prerequisites x86_64 MSVC
94
-
95
-
Installation of prerequisites using [Winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/):
96
-
97
-
```powershell
98
-
winget install --id Git.Git
99
-
winget install Python # requirements for ESP-IDF based development, skip in case of Bare metal
Installation of prerequisites using Visual Studio installer GUI - installed with option Desktop development with C++ - components: MSVCv142 - VS2019 C++ x86/64 build tools, Windows 11 SDK
105
-
106
-
107
-
108
-
Installation of MSVC and Windows 11 SDK using [vs_buildtools.exe](https://learn.microsoft.com/en-us/visualstudio/install/use-command-line-parameters-to-install-visual-studio?view=vs-2022):
The following instructions describe deployment with the GNU toolchain. If you're using Visual Studio with Windows 10 SDK, consider option [Windows x86_64 MSVC](#windows-x86_64-msvc).
133
-
134
-
#### Prerequisites x86_64 GNU
135
-
136
-
Install MinGW x86_64 e.g., from releases https://github.com/niXman/mingw-builds-binaries/releases and add bin to environment variable PATH
The following instructions are specific for ESP32-C based on RISC-V architecture.
155
-
156
-
Install the RISC-V target for Rust:
157
-
158
-
```sh
159
-
rustup target add riscv32imc-unknown-none-elf
160
-
```
161
-
162
-
## Building projects
163
-
164
-
### Cargo first approach
165
-
166
-
1. Install `cargo-generate`
167
-
168
-
```sh
169
-
cargo install cargo-generate
170
-
```
171
-
2. Generate project from template with one of the following templates
172
-
173
-
```sh
174
-
# STD Project
175
-
cargo generate esp-rs/esp-idf-template cargo
176
-
# NO-STD (Bare-metal) Project
177
-
cargo generate esp-rs/esp-template
178
-
```
179
-
180
-
To understand the differences between the two ecosystems, see [Ecosystem Overview chapter of the book](https://esp-rs.github.io/book/overview/index.html). There is also a Chapter that explains boths template projects:
Where `SERIAL` is the serial port connected to the target device.
191
-
192
-
> [cargo-espflash](https://github.com/esp-rs/espflash/tree/master/cargo-espflash) also allows opening a serial monitor after flashing with `--monitor` option.
193
-
>
194
-
> If no `SERIAL` argument is used, `cargo-espflash` will print a list of the connected devices, so the user can choose
195
-
> which one to flash.
196
-
>
197
-
> See [Usage](https://github.com/esp-rs/espflash/tree/master/cargo-espflash#usage) section for more information about arguments.
198
-
199
-
> If `espflash` is installed (`cargo install espflash`), `cargo run` will build, flash the device, and open a serial monitor.
200
-
201
-
If you are looking for inspiration or more complext projects see:
- [Rust on ESP32 STD demo app](https://github.com/ivmarkov/rust-esp32-std-demo)
204
-
### Idf first approach
205
-
206
-
When building for Xtensa targets, we need to [override the `esp` toolchain](https://rust-lang.github.io/rustup/overrides.html), there are several solutions:
207
-
- Set `esp` toolchain as default: `rustup default esp`
208
-
- Use `cargo +esp`
209
-
- Override the project directory: `rustup override set esp`
210
-
- Create a file called `rust-toolchain.toml` or `rust-toolchain` with:
- `esp32`for the ESP32(Xtensa architecture). \[Default]
232
-
- `esp32s2`for the ESP32-S2(Xtensa architecture).
233
-
- `esp32s3`for the ESP32-S3(Xtensa architecture).
234
-
235
-
3. Build and flash
236
-
237
-
```sh
238
-
idf.py build flash
239
-
```
240
-
241
-
## Using Containers
242
-
243
-
Alternatively, some container images with pre-installed Rust and ESP-IDF, are published to Dockerhub and can be used to build Rust projects for ESP boards:
and [web-flash](https://github.com/bjoernQ/esp-web-flash-server) installed to use them
249
-
in Dev Containers.
250
-
- Tags are generated for`linux/arm64` and `linux/amd64`,
251
-
- [idf-rust-examples](https://hub.docker.com/r/espressif/idf-rust-examples) - includes two examples: [rust-esp32-example](https://github.com/espressif/rust-esp32-example) and [rust-esp32-std-demo](https://github.com/ivmarkov/rust-esp32-std-demo).
252
-
253
-
Podman example with mapping multiple /dev/ttyUSB from host computer to the container:
254
-
255
-
```sh
256
-
podman run --device /dev/ttyUSB0 --device /dev/ttyUSB1 -it docker.io/espressif/idf-rust-examples
257
-
```
258
-
259
-
Docker (does not support flashing from a container):
260
-
261
-
```sh
262
-
docker run -it espressif/idf-rust-examples
263
-
```
264
-
265
-
If you are using the `idf-rust-examples` image, instructions will be displayed on the screen.
266
-
267
-
## Using Dev Containers
268
-
269
-
Dev Container support is offered for VS Code, Gitpod, and GitHub Codespaces,
270
-
resulting in a fully working environment to develop forESP boardsin Rust,
271
-
flash and simulate projects with Wokwi from the container.
272
-
273
-
Template projects [esp-template](https://github.com/esp-rs/esp-template/) and
274
-
[esp-idf-template](https://github.com/esp-rs/esp-idf-template/) include a question for Dev Containers support.
275
-
276
-
## Release process
277
-
278
-
Before beginning preparation fora new release create branch `build/X.Y.Z.W` where `X.Y.Z` matches Rust release number and `W` is build number assigned by esp-rs. `W` has a tendency to bein the range 0-2 during one release.
279
-
280
-
On the branch change all version numbers from the previous release to the new one using replace function(e.g.in VS Code). Examples of replace: `1.63.0.1 -> 1.64.0.0`. Commit files including CI files to the branch.
281
-
282
-
### Building release
283
-
284
-
All build operations must be performed on custom runners, because of large storage required by the build process. Check Settings that all runners are online.
285
-
286
-
Perform custom dispatch. Change branch to `build/X.Y.Z.W`, change *Branch of rust-build to us* to `build/X.Y.Z.W`:
Send notification to Matrix channel about the pre-release.
303
-
304
-
### Finalization of release (about 2-3 days later)
305
-
306
-
Edit Release, turn off Pre-release flag, and Save
307
-
308
-
Send notification to Matrix channel about the pre-release.
309
-
310
-
### Rollback release
311
-
312
-
Rollback of the release is possible when a significant bug occurs that damages the release for all platforms.
313
-
314
-
First rule: Do not panic. :-) Just mark the release as Pre-release in GitHub releases.
315
-
316
-
If `build/X.Y.Z.W` branch was already merged to main, change the default version in main to `build/a.b.c.d` where `a.b.c.d` corresponds to previously known working release. E.g. from `build/1.63.0.1` to `build/1.63.0.0`.
317
-
318
-
### Uploading new image tags to [espressif/idf-rust](https://hub.docker.com/r/espressif/idf-rust)
319
-
320
-
Once the release is ready, [manually run the `Publish IDF-Rust Tags` workflow](https://github.com/esp-rs/rust-build/actions/workflows/publish-idf-rust-tags.yml) with:
321
-
- `Branch of rust-build to use` pointing to `main`if the `build/X.Y.Z.W` branch was already merged to `main`, or pointing to `build/X.Y.Z.W`if has not been merged yet, but the branch is ready and feature complete.
322
-
- `Version of Rust toolchain` should be `X.Y.Z.W`.
9
+
If you want to know more about the Rust ecosystem on Epressif targets and how to setup your development environment, see [The Rust on ESP Book chapter](https://esp-rs.github.io/book/installation/index.html)
0 commit comments