changelogs and migration guides

esp-rs · Sep 16, 2024 · 04396ba · 04396ba
1 parent 3b3db04
commit 04396ba
Show file tree

Hide file tree

Showing 6 changed files with 53 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
@@ -37,6 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The (previously undocumented) `ErasedPin` enum has been replaced with the `ErasedPin` struct. (#2094)
 - Renamed and merged `Rtc::get_time_us` and `Rtc::get_time_ms` into `Rtc::time_since_boot` (#1883)
 - ESP32: Added support for touch sensing on GPIO32 and 33 (#2109)
+- MSRV bump to 1.79 (#2156)
 
 ### Fixed
 
@@ -58,6 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Removed `Rtc::get_time_raw` (#1883)
 - Removed `_with_default_pins` UART constructors (#2132)
 - Removed `uart::{DefaultRxPin, DefaultTxPin}` (#2132)
+- 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
@@ -124,3 +124,14 @@ let rtc = Rtc::new(peripherals.LPWR);
 - let current_time_ms = rtc.get_time_ms();
 + let current_time_ms = rtc.current_time().and_utc().timestamp_millis(); // assuming UTC
 ```
+
+### 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
@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+- `cfg_toml` configuration system has been removed in favour of [esp-config](https://docs.rs/esp-config) (#2156)
+
 ## 0.9.1 - 2024-09-03
 
 ### Added

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
+```