changelogs and migration guides

esp-rs · Sep 16, 2024 · cc5ad89 · cc5ad89
1 parent 1d750bf
commit cc5ad89
Show file tree

Hide file tree

Showing 6 changed files with 52 additions and 0 deletions.
diff --git a/esp-config/README.md b/esp-config/README.md
@@ -8,6 +8,32 @@
 
 ## [Documentation](https://docs.rs/crate/esp-config)
 
+## Usage
+
+`esp-config` takes a prefix (usually the crate name) and a set of configuration keys and default values to produce a configuration system that supports:
+
+- Emitting rustc cfg's for boolean keys
+- Emitting environment variables for numbers
+  - Along with decimal parsing, it supports Hex, Octal and Binary with the respective `0x`, `0o` and `0b` prefixes.
+- Emitting environment variables string values
+
+### Viewing the configuration
+
+The possible configuration values are output as a markdown table in the crates `OUT_DIR` with the format `{prefix}_config_table.md`, this can then be included into the crates top level documentation. Here is an example of the output:
+
+
+| Name | Description | Default value |
+|------|-------------|---------------|
+|**ESP_HAL_PLACE_SPI_DRIVER_IN_RAM**|Places the SPI driver in RAM for better performance|false|
+
+### Setting configuration options
+
+For any available configuration option, the environment variable or cfg is _always_ set based on the default value specified in the table. Users can override this by setting environment variables locally in their shell _or_ the preferred option is to utilize cargo's [`env` section](https://doc.rust-lang.org/cargo/reference/config.html#env).
+
+It's important to note that due to a [bug in cargo](https://github.com/rust-lang/cargo/issues/10358), any modifications to the environment, local or otherwise will only get picked up on a full clean build of the project.
+
+To see the final selected configuration another table is output to the `OUT_DIR` with the format `{prefix}_selected_config.md`.
+
 ## Minimum Supported Rust Version (MSRV)
 
 This crate is guaranteed to compile on stable Rust 1.79 and up. It _might_

diff --git a/esp-config/src/lib.rs b/esp-config/src/lib.rs
@@ -1,4 +1,5 @@
 #![cfg_attr(not(feature = "std"), no_std)]
+#![doc = include_str!("../README.md")]
 
 #[cfg(feature = "std")]
 mod generate;

diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md
@@ -42,6 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Changed the parameters of `Spi::with_pins` to no longer be optional (#2133)
 - Renamed `DummyPin` to `NoPin` and removed all internal logic from it. (#2133)
 - The `NO_PIN` constant has been removed. (#2133)
+- MSRV bump to 1.79 (#2156)
 
 ### Fixed
 
@@ -65,6 +66,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Removed `_with_default_pins` UART constructors (#2132)
 - Removed `uart::{DefaultRxPin, DefaultTxPin}` (#2132)
 - Removed `PcntSource` and `PcntInputConfig`. (#2134)
+- Removed the `place-spi-driver-in-ram` feature, this is now enabled via [esp-config](https://docs.rs/esp-config) (#2156)
 
 ## [0.20.1] - 2024-08-30
 

diff --git a/esp-hal/MIGRATING-0.20.md b/esp-hal/MIGRATING-0.20.md
@@ -159,3 +159,14 @@ You can pass `NoPin` or `Level` as inputs, and `NoPin` as output if you don't ne
 -    .with_pins(Some(sclk), Some(mosi), NO_PIN, NO_PIN);
 +    .with_pins(sclk, mosi, Level::Low, NoPin);
 ```
+
+### Placing drivers in RAM is now done via esp-config
+
+We've replaced some usage of features with [esp-config](https://docs.rs/esp-config). Please remove any reference to `place-spi-driver-in-ram` in your `Cargo.toml` and migrate to the `[env]` section of `.cargo/config.toml`.
+
+```diff
+# feature in Cargo.toml
+- esp-hal = { version = "0.20", features = ["place-spi-driver-in-ram"] }
+# key in .cargo/config.toml [env] section
++ ESP_HAL_PLACE_SPI_DRIVER_IN_RAM=true
+```
diff --git a/esp-wifi/CHANGELOG.md b/esp-wifi/CHANGELOG.md
@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 
 - Removed the `clocks` parameter from `esp_wifi::initialize` (#1999)
+- `cfg_toml` configuration system has been removed in favour of [esp-config](https://docs.rs/esp-config) (#2156)
 
 ## 0.9.1 - 2024-09-03
 

diff --git a/esp-wifi/MIGRATING-0.9.md b/esp-wifi/MIGRATING-0.9.md
@@ -88,3 +88,14 @@ pub extern "C" fn esp_wifi_allocate_from_internal_ram(size: usize) -> *mut u8 {
 ```
 
 It's important to allocate from internal memory (i.e. not PSRAM)
+
+### Tunable parameters are now set via esp-config
+
+We've replaced usage of `cfg_toml` with [esp-config](https://docs.rs/esp-config). Please remove any esp-wifi entries from `cfg.toml` and migrate the key value pairs to the `[env]` section of `.cargo/config.toml`.
+
+```diff
+# key in cfg.toml
+- rx_queue_size = 40
+# key in .cargo/config.toml [env] section
++ ESP_WIFI_RX_QUEUE_SIZE=40
+```