From 2bc4d5a47679c5b18fe4ee29f5569a00de8147ca Mon Sep 17 00:00:00 2001 From: Dominik Gschwind Date: Sun, 6 Aug 2023 23:55:31 +0200 Subject: [PATCH] Change to new github alert syntax --- BUILD_OPTIONS.md | 69 ++++++++++++++++++++++++++++-------------------- README.md | 28 ++++++++++---------- 2 files changed, 54 insertions(+), 43 deletions(-) diff --git a/BUILD_OPTIONS.md b/BUILD_OPTIONS.md index 8a375841838..50aaa92ec1e 100644 --- a/BUILD_OPTIONS.md +++ b/BUILD_OPTIONS.md @@ -34,7 +34,8 @@ The following are flags passed to `rustc` that influence the build. Similarly to the `native` builder, the `pio` builder also automatically installs all needed tools (PlatformIO packages and frameworks in this case) to compile this crate as well as the ESP-IDF framework itself. - > ⚠️ The `pio` builder is less flexible than the default `native` builder in that it can work with only **one, specific** version of ESP-IDF. At the time of writing, this is V4.3.2. + > [!WARNING] + > The `pio` builder is less flexible than the default `native` builder in that it can work with only **one, specific** version of ESP-IDF. At the time of writing, this is V4.3.2. - ### `binstart` @@ -74,9 +75,9 @@ TBD: Upcoming ### (*pio* builder only) Using cargo-pio to interactively modify ESP-IDF's `sdkconfig` file To enable Bluetooth, or do other configurations to the ESP-IDF sdkconfig you might take advantage of the cargo-pio Cargo subcommand: -* To install it, issue `cargo install cargo-pio --git https://github.com/ivmarkov/cargo-pio` -* To open the ESP-IDF interactive menuconfig system, issue `cargo pio espidf menuconfig` in the root of your **binary crate** project -* To use the generated/updated `sdkconfig` file, follow the steps described in the "Bluetooth Support" section +- To install it, issue `cargo install cargo-pio --git https://github.com/ivmarkov/cargo-pio` +- To open the ESP-IDF interactive menuconfig system, issue `cargo pio espidf menuconfig` in the root of your **binary crate** project +- To use the generated/updated `sdkconfig` file, follow the steps described in the "Bluetooth Support" section ## ESP-IDF configuration @@ -88,20 +89,24 @@ There are two ways to configure how the ESP-IDF framework is compiled: 2. The `[package.metadata.esp-idf-sys]` section of the `Cargo.toml`, denoted by *`field`*. - > **Note** + > [!NOTE] > Configuration can only come from the **root crate's** `Cargo.toml`. The root crate > is the package in the *workspace directory*. If there is not root crate in case of a > [virtual > workspace](https://doc.rust-lang.org/cargo/reference/workspaces.html#virtual-manifest), > its *name* can be specified with the `ESP_IDF_SYS_ROOT_CRATE` environment variable. - > ⚠️ Environment variables always take precedence over `Cargo.toml` metadata. + > [!WARNING] + > Environment variables always take precedence over `Cargo.toml` metadata. -> **Note**: *workspace directory* +> [!NOTE] +> ***workspace directory*** +> > The workspace directory mentioned here is always the directory containing the -> `Cargo.lock` file and the `target` directory (where the build artifacts are stored). It -> can be overridden with the `CARGO_WORKSPACE_DIR` environment variable, should this not -> be the right directory. +> `Cargo.lock` file and the `target` directory (unless configured otherwise, see the note +> below about `CARGO_TARGET_DIR`) where the build artifacts are stored. It can be +> overridden with the `CARGO_WORKSPACE_DIR` environment variable, should this not be the +> right directory. > (See > [`embuild::cargo::workspace_dir`](https://docs.rs/embuild/latest/embuild/cargo/fn.workspace_dir.html) > for more information). @@ -112,12 +117,13 @@ There are two ways to configure how the ESP-IDF framework is compiled: > > Please note that if you have set `CARGO_TARGET_DIR` and moved your `target` directory out of > the crate root, then embuild is not able to locate the crate root. This will result in it -> among other things ignoring your local `sdkconfig.defaults`. In this setup you must declare: +> among other things ignoring your local `sdkconfig.defaults`. In this case you must +> declare: > ``` > [env] > CARGO_WORKSPACE_DIR = { value = "", relative = true } > ``` -> to force it to look in the current directory. +> in the `.cargo/config.toml` file, to force it to look in the current directory. The following configuration options are available: @@ -132,7 +138,7 @@ The following configuration options are available: In case of the environment variable, multiple elements should be `;`-separated. - > **Note** + > [!NOTE] > For each defaults file in this list, a more specific file will also be searched and > used. This happens with the following patterns and order (least to most specific): > @@ -145,7 +151,7 @@ The following configuration options are available: > specifies the mcu for which this is currently compiled for (see the [*`mcu`*](#mcu-mcu) > configuration option below). - > ⚠️ + > [!WARNING] > A setting contained in a more specific defaults file will override the > same setting specified in a less specific one. For example, in a debug > build, flags in `sdkconfig.debug` override those in `sdkconfig.defaults`. @@ -159,7 +165,7 @@ The following configuration options are available: Defaults to `sdkconfig`. - > **Note** + > [!NOTE] > Similar to the `sdkconfig.defaults`-file a more specific `sdkconfig`-file will be > selected if available. This happens with the following patterns and precedence: > @@ -170,7 +176,8 @@ The following configuration options are available: > >   - > **Note**: *native* builder only + > [!NOTE] + > ***native* builder only:** > The cargo optimization options (`debug` and `opt-level`) are used by default to > determine the compiler optimizations of the `esp-idf`, **however** if the compiler > optimization options are already set in the `sdkconfig` **they will be used instead.** @@ -179,7 +186,7 @@ The following configuration options are available: The install location for the ESP-IDF framework tooling. - > **Note** + > [!NOTE] > The framework tooling is either [PlatformIO](https://platformio.org/) when the `pio` builder is used, or the ESP-IDF > native toolset when the `native` builder is used (default). @@ -204,11 +211,14 @@ The following configuration options are available: and error if this is not possible. - > ⚠️ Please be extra careful with the `custom:` setting when switching from `pio` to `native` and the other way around, because - > the builder will install the tooling in `` without using any additional `platformio` or `espressif` subdirectories, so if you are not careful, you might end up with - > both PlatformIO, as well as the ESP-IDF native tooling intermingled together in a single folder. - - > **Note** + > [!WARNING] + > Please be extra careful with the `custom:` setting when switching + > from `pio` to `native` and the other way around, because the builder will install the + > tooling in `` without using any additional `platformio` or `espressif` + > subdirectories, so if you are not careful, you might end up with both PlatformIO, as + > well as the ESP-IDF native tooling intermingled together in a single folder. + + > [!WARNING] > The [ESP-IDF git repository](https://github.com/espressif/esp-idf) will be cloned > *inside* the tooling directory. The *native* builder will use the esp-idf at > [*`idf_path`*](#idfpath-idfpath-native-builder-only) of available. @@ -233,11 +243,11 @@ The following configuration options are available: The URL to the git repository of the `esp-idf`, defaults to . - > **Note** + > [!NOTE] > When the `pio` builder is used, it is possible to achieve something similar to > `ESP_IDF_VERSION` and `ESP_IDF_REPOSITORY` by using the > [`platform_packages`](https://docs.platformio.org/en/latest/projectconf/section_env_platform.html#platform-packages) - > PlatformIO option as follows: + > PlatformIO option as follows: > > `ESP_IDF_PIO_CONF="platform_packages = framework-espidf @ [@ ]"` > @@ -267,7 +277,7 @@ The following configuration options are available: documentation](https://docs.platformio.org/en/latest/projectconf/index.html) for more information as to what settings you can pass via this variable. - > **Note** + > [!NOTE] > This is not one variable, but rather a family of variables all > starting with `ESP_IDF_PIO_CONF_`. For example, passing `ESP_IDF_PIO_CONF_1` as well as > `ESP_IDF_PIO_CONF_FOO` is valid and all such variables will be honored. @@ -291,7 +301,7 @@ The following configuration options are available: If not set this will be automatically detected from the cargo target. - > ⚠️ + > [!WARNING] > [Older ESP-IDF versions might not support all MCUs from above.](https://github.com/espressif/esp-idf#esp-idf-release-and-soc-compatibility) - ### *`esp_idf_components`*, `$ESP_IDF_COMPONENTS` (*native* builder only) @@ -302,7 +312,7 @@ The following configuration options are available: Defaults to all components being built. - > **Note** + > [!NOTE] > Some components must be explicitly enabled in the sdkconfig. > [Extra components](#extra-esp-idf-components) must also be added to this list if > they are to be built. @@ -331,7 +341,7 @@ This is possible by adding an object to the will honor all such extra components in the *root crate*'s and all **direct** dependencies' `Cargo.toml`. -> **Note** +> [!NOTE] > By only specifying the `bindings_header` field, one can extend the set of *esp-idf* > bindings that were generated from > [src/include/esp-idf/bindings.h](src/include/esp-idf/bindings.h). To do this you need to create @@ -388,7 +398,8 @@ extra_components = [ The *esp-idf-sys* build script will set [rustc *cfg*s](https://doc.rust-lang.org/reference/conditional-compilation.html) available for its sources. -> ⚠️ If an upstream crate also wants to have access to the *cfg*s it must: +> [!IMPORTANT] +> If an upstream crate also wants to have access to the *cfg*s it must: > - have `esp-idf-sys` as a dependency, and > - propagate the *cfg*s in its [build > script](https://doc.rust-lang.org/cargo/reference/build-scripts.html) with diff --git a/README.md b/README.md index 277b0be6a6e..449f19949d9 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,13 @@ ## Highlights -* Build is `cargo` driven and **automatically downloads & configures everything by default**; no need to download the ESP IDF SDK manually, or set up a C toolchain -* Supports both native ESP IDF build (default), as well as a PlatformIO build -* Option to use in a mixed Rust/C project. Check the documentation in the [esp-idf-template](https://github.com/esp-rs/esp-idf-template) crate +- Build is `cargo` driven and **automatically downloads & configures everything by default**; no need to download the ESP IDF SDK manually, or set up a C toolchain +- Supports both native ESP IDF build (default), as well as a PlatformIO build +- Option to use in a mixed Rust/C project. Check the documentation in the [esp-idf-template](https://github.com/esp-rs/esp-idf-template) crate **You might want to also check out the type safe Rust wrappes built on top of these raw bndings:** -* [Type safe wrappers for ESP IDF Services](https://github.com/esp-rs/esp-idf-svc) -* [Type safe wrappers for ESP IDF Drivers](https://github.com/esp-rs/esp-idf-hal) +- [Type safe wrappers for ESP IDF Services](https://github.com/esp-rs/esp-idf-svc) +- [Type safe wrappers for ESP IDF Drivers](https://github.com/esp-rs/esp-idf-hal) ## Build Prerequisites @@ -27,12 +27,12 @@ Read the [documentation here](BUILD_OPTIONS.md). ## More information For more information, check out: -* The [Rust on ESP Book](https://esp-rs.github.io/book/) -* The [ESP Embedded Training](https://github.com/esp-rs/espressif-trainings) -* The [esp-idf-template](https://github.com/esp-rs/esp-idf-template) project -* The [esp-idf-svc](https://github.com/esp-rs/esp-idf-svc) project -* The [esp-idf-hal](https://github.com/esp-rs/esp-idf-hal) project -* The [embedded-svc](https://github.com/esp-rs/embedded-svc) project -* The [embedded-hal](https://github.com/rust-embedded/embedded-hal) project -* The [Rust for Xtensa toolchain](https://github.com/esp-rs/rust-build) -* The [Rust-with-STD demo](https://github.com/ivmarkov/rust-esp32-std-demo) project +- The [Rust on ESP Book](https://esp-rs.github.io/book/) +- The [ESP Embedded Training](https://github.com/esp-rs/espressif-trainings) +- The [esp-idf-template](https://github.com/esp-rs/esp-idf-template) project +- The [esp-idf-svc](https://github.com/esp-rs/esp-idf-svc) project +- The [esp-idf-hal](https://github.com/esp-rs/esp-idf-hal) project +- The [embedded-svc](https://github.com/esp-rs/embedded-svc) project +- The [embedded-hal](https://github.com/rust-embedded/embedded-hal) project +- The [Rust for Xtensa toolchain](https://github.com/esp-rs/rust-build) +- The [Rust-with-STD demo](https://github.com/ivmarkov/rust-esp32-std-demo) project