Use two underscores to separate prefix

esp-rs · Dec 20, 2024 · a87f6c3 · a87f6c3
1 parent c2de8a1
commit a87f6c3
Show file tree

Hide file tree

Showing 13 changed files with 133 additions and 51 deletions.
diff --git a/esp-config/CHANGELOG.md b/esp-config/CHANGELOG.md
@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Crate prefixes and configuration keys are now separated by two underscores (`__`) (#2848)
+
 ### Removed
 
 ## 0.2.0 - 2024-11-20

diff --git a/esp-config/src/generate.rs b/esp-config/src/generate.rs
@@ -249,7 +249,7 @@ fn integer_in_range(range: &Range<i128>, value: &Value) -> Result<(), Error> {
 ///
 /// Unknown keys with the supplied prefix will cause this function to panic.
 pub fn generate_config(
-    prefix: &str,
+    crate_name: &str,
     config: &[(&str, &str, Value, Option<Validator>)],
     emit_md_tables: bool,
 ) -> HashMap<String, Value> {
@@ -264,7 +264,7 @@ pub fn generate_config(
     let mut selected_config = String::from(SELECTED_TABLE_HEADER);
 
     // Ensure that the prefix is `SCREAMING_SNAKE_CASE`:
-    let prefix = screaming_snake_case(prefix);
+    let prefix = format!("{}__", screaming_snake_case(crate_name));
 
     // Build a lookup table for any provided validators; we must prefix the
     // name of the config and transform it to SCREAMING_SNAKE_CASE so that
@@ -273,7 +273,7 @@ pub fn generate_config(
         .iter()
         .flat_map(|(name, _description, _default, validator)| {
             if let Some(validator) = validator {
-                let name = format!("{prefix}_{}", screaming_snake_case(name));
+                let name = format!("{prefix}{}", screaming_snake_case(name));
                 Some((name, validator))
             } else {
                 None
@@ -293,7 +293,7 @@ pub fn generate_config(
     emit_configuration(&prefix, &configs, &mut selected_config);
 
     if emit_md_tables {
-        let file_name = snake_case(&prefix);
+        let file_name = snake_case(crate_name);
         write_config_tables(&file_name, doc_table, selected_config);
     }
 
@@ -341,7 +341,7 @@ fn create_config(
     let mut configs = HashMap::new();
 
     for (name, description, default, _validator) in config {
-        let name = format!("{prefix}_{}", screaming_snake_case(name));
+        let name = format!("{prefix}{}", screaming_snake_case(name));
         configs.insert(name.clone(), default.clone());
 
         // Write documentation table line:
@@ -361,7 +361,7 @@ fn capture_from_env(prefix: &str, configs: &mut HashMap<String, Value>) {
 
     // Try and capture input from the environment:
     for (var, value) in env::vars() {
-        if var.strip_prefix(prefix).is_some() {
+        if var.starts_with(prefix) {
             let Some(cfg) = configs.get_mut(&var) else {
                 unknown.push(var);
                 continue;
@@ -388,7 +388,7 @@ fn emit_configuration(
     selected_config: &mut String,
 ) {
     for (name, value) in configs.iter() {
-        let cfg_name = snake_case(name.trim_start_matches(&format!("{prefix}_")));
+        let cfg_name = snake_case(name.trim_start_matches(prefix));
         println!("cargo:rustc-check-cfg=cfg({cfg_name})");
 
         if let Value::Bool(true) = value {
@@ -464,10 +464,10 @@ mod test {
     fn env_override() {
         temp_env::with_vars(
             [
-                ("ESP_TEST_NUMBER", Some("0xaa")),
-                ("ESP_TEST_NUMBER_SIGNED", Some("-999")),
-                ("ESP_TEST_STRING", Some("Hello world!")),
-                ("ESP_TEST_BOOL", Some("true")),
+                ("ESP_TEST__NUMBER", Some("0xaa")),
+                ("ESP_TEST__NUMBER_SIGNED", Some("-999")),
+                ("ESP_TEST__STRING", Some("Hello world!")),
+                ("ESP_TEST__BOOL", Some("true")),
             ],
             || {
                 let configs = generate_config(
@@ -491,28 +491,28 @@ mod test {
 
                 // some values have changed
                 assert_eq!(
-                    match configs.get("ESP_TEST_NUMBER").unwrap() {
+                    match configs.get("ESP_TEST__NUMBER").unwrap() {
                         Value::Integer(num) => *num,
                         _ => unreachable!(),
                     },
                     0xaa
                 );
                 assert_eq!(
-                    match configs.get("ESP_TEST_NUMBER_SIGNED").unwrap() {
+                    match configs.get("ESP_TEST__NUMBER_SIGNED").unwrap() {
                         Value::Integer(num) => *num,
                         _ => unreachable!(),
                     },
                     -999
                 );
                 assert_eq!(
-                    match configs.get("ESP_TEST_STRING").unwrap() {
+                    match configs.get("ESP_TEST__STRING").unwrap() {
                         Value::String(val) => val,
                         _ => unreachable!(),
                     },
                     "Hello world!"
                 );
                 assert_eq!(
-                    match configs.get("ESP_TEST_BOOL").unwrap() {
+                    match configs.get("ESP_TEST__BOOL").unwrap() {
                         Value::Bool(val) => *val,
                         _ => unreachable!(),
                     },
@@ -521,21 +521,21 @@ mod test {
 
                 // the rest are the defaults
                 assert_eq!(
-                    match configs.get("ESP_TEST_NUMBER_DEFAULT").unwrap() {
+                    match configs.get("ESP_TEST__NUMBER_DEFAULT").unwrap() {
                         Value::Integer(num) => *num,
                         _ => unreachable!(),
                     },
                     999
                 );
                 assert_eq!(
-                    match configs.get("ESP_TEST_STRING_DEFAULT").unwrap() {
+                    match configs.get("ESP_TEST__STRING_DEFAULT").unwrap() {
                         Value::String(val) => val,
                         _ => unreachable!(),
                     },
                     "Demo"
                 );
                 assert_eq!(
-                    match configs.get("ESP_TEST_BOOL_DEFAULT").unwrap() {
+                    match configs.get("ESP_TEST__BOOL_DEFAULT").unwrap() {
                         Value::Bool(val) => *val,
                         _ => unreachable!(),
                     },
@@ -549,10 +549,10 @@ mod test {
     fn builtin_validation_passes() {
         temp_env::with_vars(
             [
-                ("ESP_TEST_POSITIVE_NUMBER", Some("7")),
-                ("ESP_TEST_NEGATIVE_NUMBER", Some("-1")),
-                ("ESP_TEST_NON_NEGATIVE_NUMBER", Some("0")),
-                ("ESP_TEST_RANGE", Some("9")),
+                ("ESP_TEST__POSITIVE_NUMBER", Some("7")),
+                ("ESP_TEST__NEGATIVE_NUMBER", Some("-1")),
+                ("ESP_TEST__NON_NEGATIVE_NUMBER", Some("0")),
+                ("ESP_TEST__RANGE", Some("9")),
             ],
             || {
                 generate_config(
@@ -591,7 +591,7 @@ mod test {
 
     #[test]
     fn custom_validation_passes() {
-        temp_env::with_vars([("ESP_TEST_NUMBER", Some("13"))], || {
+        temp_env::with_vars([("ESP_TEST__NUMBER", Some("13"))], || {
             generate_config(
                 "esp-test",
                 &[(
@@ -615,7 +615,7 @@ mod test {
     #[test]
     #[should_panic]
     fn builtin_validation_bails() {
-        temp_env::with_vars([("ESP_TEST_POSITIVE_NUMBER", Some("-99"))], || {
+        temp_env::with_vars([("ESP_TEST__POSITIVE_NUMBER", Some("-99"))], || {
             generate_config(
                 "esp-test",
                 &[(
@@ -632,7 +632,7 @@ mod test {
     #[test]
     #[should_panic]
     fn custom_validation_bails() {
-        temp_env::with_vars([("ESP_TEST_NUMBER", Some("37"))], || {
+        temp_env::with_vars([("ESP_TEST__NUMBER", Some("37"))], || {
             generate_config(
                 "esp-test",
                 &[(
@@ -658,8 +658,8 @@ mod test {
     fn env_unknown_bails() {
         temp_env::with_vars(
             [
-                ("ESP_TEST_NUMBER", Some("0xaa")),
-                ("ESP_TEST_RANDOM_VARIABLE", Some("")),
+                ("ESP_TEST__NUMBER", Some("0xaa")),
+                ("ESP_TEST__RANDOM_VARIABLE", Some("")),
             ],
             || {
                 generate_config(
@@ -674,7 +674,18 @@ mod test {
     #[test]
     #[should_panic]
     fn env_invalid_values_bails() {
-        temp_env::with_vars([("ESP_TEST_NUMBER", Some("Hello world"))], || {
+        temp_env::with_vars([("ESP_TEST__NUMBER", Some("Hello world"))], || {
+            generate_config(
+                "esp-test",
+                &[("number", "NA", Value::Integer(999), None)],
+                false,
+            );
+        });
+    }
+
+    #[test]
+    fn env_unknown_prefix_is_ignored() {
+        temp_env::with_vars([("ESP_TEST_OTHER__NUMBER", Some("Hello world"))], || {
             generate_config(
                 "esp-test",
                 &[("number", "NA", Value::Integer(999), None)],

diff --git a/esp-hal-embassy/CHANGELOG.md b/esp-hal-embassy/CHANGELOG.md
@@ -14,6 +14,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Bump MSRV to 1.83 (#2615)
 
+- Config: Crate prefixes and configuration keys are now separated by two underscores (`__`) (#2848)
+
 ### Fixed
 
 ### Removed

diff --git a/esp-hal-embassy/MIGRATING-0.5.md b/esp-hal-embassy/MIGRATING-0.5.md
@@ -1 +1,15 @@
 # Migration Guide from 0.5.x to v0.6.x
+
+## Crate configuration changes
+
+To prevent ambiguity between configurations, we had to change the naming format of configuration
+keys. Before, we used `{prefix}_{key}`, which meant that esp-hal and esp-hal-* configuration keys
+were impossible to tell apart. To fix this issue, we are changing the separator from one to two
+underscore characters. This also means that users will have to change their `config.toml`
+configurations to match the new format.
+
+```diff
+ [env]
+-ESP_HAL_EMBASSY_LOW_POWER_WAIT="false"
++ESP_HAL_EMBASSY__LOW_POWER_WAIT="false"
+```
diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md
@@ -179,6 +179,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The `Camera` and `I8080` drivers' constructors now only accepts blocking-mode DMA channels. (#2519)
 - Many peripherals are now disabled by default and also get disabled when the driver is dropped (#2544)
 
+- Config: Crate prefixes and configuration keys are now separated by two underscores (`__`) (#2848)
+
 ### Fixed
 
 - Fix conflict between `RtcClock::get_xtal_freq` and `Rtc::disable_rom_message_printing` (#2360)

diff --git a/esp-hal/MIGRATING-0.22.md b/esp-hal/MIGRATING-0.22.md
@@ -343,3 +343,17 @@ The reexports that were previously part of the prelude are available through oth
 - uart0.set_at_cmd(AtCmdConfig::new(None, None, None, b'#', None));
 + uart0.set_at_cmd(AtCmdConfig::default().with_cmd_char(b'#'));
 ```
+
+## Crate configuration changes
+
+To prevent ambiguity between configurations, we had to change the naming format of configuration
+keys. Before, we used `{prefix}_{key}`, which meant that esp-hal and esp-hal-* configuration keys
+were impossible to tell apart. To fix this issue, we are changing the separator from one to two
+underscore characters. This also means that users will have to change their `config.toml`
+configurations to match the new format.
+
+```diff
+ [env]
+-ESP_HAL_PLACE_SPI_DRIVER_IN_RAM="true"
++ESP_HAL__PLACE_SPI_DRIVER_IN_RAM="true"
+```
diff --git a/esp-ieee802154/CHANGELOG.md b/esp-ieee802154/CHANGELOG.md
@@ -14,6 +14,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Bump MSRV to 1.83 (#2615)
 
+- Config: Crate prefixes and configuration keys are now separated by two underscores (`__`) (#2848)
+
 ### Fixed
 
 ### Removed

diff --git a/esp-ieee802154/MIGRATING-0.4.md b/esp-ieee802154/MIGRATING-0.4.md
@@ -0,0 +1,15 @@
+# Migration Guide from 0.4.x to v0.5.x
+
+## Crate configuration changes
+
+To prevent ambiguity between configurations, we had to change the naming format of configuration
+keys. Before, we used `{prefix}_{key}`, which meant that esp-hal and esp-hal-* configuration keys
+were impossible to tell apart. To fix this issue, we are changing the separator from one to two
+underscore characters. This also means that users will have to change their `config.toml`
+configurations to match the new format.
+
+```diff
+ [env]
+-ESP_IEEE802154_RX_QUEUE_SIZE = "50"
++ESP_IEEE802154__RX_QUEUE_SIZE = "50"
+```
diff --git a/esp-ieee802154/src/lib.rs b/esp-ieee802154/src/lib.rs
@@ -67,7 +67,7 @@ struct QueueConfig {
 }
 
 pub(crate) const CONFIG: QueueConfig = QueueConfig {
-    rx_queue_size: esp_config_int!(usize, "ESP_IEEE802154_RX_QUEUE_SIZE"),
+    rx_queue_size: esp_config_int!(usize, "ESP_IEEE802154__RX_QUEUE_SIZE"),
 };
 
 /// IEEE 802.15.4 driver configuration

diff --git a/esp-wifi/CHANGELOG.md b/esp-wifi/CHANGELOG.md
@@ -38,6 +38,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `phy_enable_usb` is enabled by default (#2446)
 - Removed `get_` prefixes from functions (#2528)
 
+- Config: Crate prefixes and configuration keys are now separated by two underscores (`__`) (#2848)
+
 ### Fixed
 
 - Fixed a possible crash when parsing results from a radius server (#2380)

diff --git a/esp-wifi/MIGRATING-0.11.md b/esp-wifi/MIGRATING-0.11.md
@@ -1 +1,19 @@
 # Migration Guide from 0.11.x to v0.12.x
+
+## Crate configuration changes
+
+To prevent ambiguity between configurations, we had to change the naming format of configuration
+keys. Before, we used `{prefix}_{key}`, which meant that esp-hal and esp-hal-* configuration keys
+were impossible to tell apart. To fix this issue, we are changing the separator from one to two
+underscore characters. This also means that users will have to change their `config.toml`
+configurations to match the new format.
+
+```diff
+ [env]
+-ESP_WIFI_RX_QUEUE_SIZE = "16"
+-ESP_WIFI_STATIC_RX_BUF_NUM = "32"
+-ESP_WIFI_DYNAMIC_RX_BUF_NUM = "16"
++ESP_WIFI__RX_QUEUE_SIZE = "16"
++ESP_WIFI__STATIC_RX_BUF_NUM = "32"
++ESP_WIFI__DYNAMIC_RX_BUF_NUM = "16"
+```
diff --git a/esp-wifi/src/lib.rs b/esp-wifi/src/lib.rs
@@ -185,27 +185,27 @@ struct Config {
 }
 
 pub(crate) const CONFIG: config::EspWifiConfig = config::EspWifiConfig {
-    rx_queue_size: esp_config_int!(usize, "ESP_WIFI_RX_QUEUE_SIZE"),
-    tx_queue_size: esp_config_int!(usize, "ESP_WIFI_TX_QUEUE_SIZE"),
-    static_rx_buf_num: esp_config_int!(usize, "ESP_WIFI_STATIC_RX_BUF_NUM"),
-    dynamic_rx_buf_num: esp_config_int!(usize, "ESP_WIFI_DYNAMIC_RX_BUF_NUM"),
-    static_tx_buf_num: esp_config_int!(usize, "ESP_WIFI_STATIC_TX_BUF_NUM"),
-    dynamic_tx_buf_num: esp_config_int!(usize, "ESP_WIFI_DYNAMIC_TX_BUF_NUM"),
-    csi_enable: esp_config_bool!("ESP_WIFI_CSI_ENABLE"),
-    ampdu_rx_enable: esp_config_bool!("ESP_WIFI_AMPDU_RX_ENABLE"),
-    ampdu_tx_enable: esp_config_bool!("ESP_WIFI_AMPDU_TX_ENABLE"),
-    amsdu_tx_enable: esp_config_bool!("ESP_WIFI_AMSDU_TX_ENABLE"),
-    rx_ba_win: esp_config_int!(usize, "ESP_WIFI_RX_BA_WIN"),
-    max_burst_size: esp_config_int!(usize, "ESP_WIFI_MAX_BURST_SIZE"),
-    country_code: esp_config_str!("ESP_WIFI_COUNTRY_CODE"),
-    country_code_operating_class: esp_config_int!(u8, "ESP_WIFI_COUNTRY_CODE_OPERATING_CLASS"),
-    mtu: esp_config_int!(usize, "ESP_WIFI_MTU"),
-    tick_rate_hz: esp_config_int!(u32, "ESP_WIFI_TICK_RATE_HZ"),
-    listen_interval: esp_config_int!(u16, "ESP_WIFI_LISTEN_INTERVAL"),
-    beacon_timeout: esp_config_int!(u16, "ESP_WIFI_BEACON_TIMEOUT"),
-    ap_beacon_timeout: esp_config_int!(u16, "ESP_WIFI_AP_BEACON_TIMEOUT"),
-    failure_retry_cnt: esp_config_int!(u8, "ESP_WIFI_FAILURE_RETRY_CNT"),
-    scan_method: esp_config_int!(u32, "ESP_WIFI_SCAN_METHOD"),
+    rx_queue_size: esp_config_int!(usize, "ESP_WIFI__RX_QUEUE_SIZE"),
+    tx_queue_size: esp_config_int!(usize, "ESP_WIFI__TX_QUEUE_SIZE"),
+    static_rx_buf_num: esp_config_int!(usize, "ESP_WIFI__STATIC_RX_BUF_NUM"),
+    dynamic_rx_buf_num: esp_config_int!(usize, "ESP_WIFI__DYNAMIC_RX_BUF_NUM"),
+    static_tx_buf_num: esp_config_int!(usize, "ESP_WIFI__STATIC_TX_BUF_NUM"),
+    dynamic_tx_buf_num: esp_config_int!(usize, "ESP_WIFI__DYNAMIC_TX_BUF_NUM"),
+    csi_enable: esp_config_bool!("ESP_WIFI__CSI_ENABLE"),
+    ampdu_rx_enable: esp_config_bool!("ESP_WIFI__AMPDU_RX_ENABLE"),
+    ampdu_tx_enable: esp_config_bool!("ESP_WIFI__AMPDU_TX_ENABLE"),
+    amsdu_tx_enable: esp_config_bool!("ESP_WIFI__AMSDU_TX_ENABLE"),
+    rx_ba_win: esp_config_int!(usize, "ESP_WIFI__RX_BA_WIN"),
+    max_burst_size: esp_config_int!(usize, "ESP_WIFI__MAX_BURST_SIZE"),
+    country_code: esp_config_str!("ESP_WIFI__COUNTRY_CODE"),
+    country_code_operating_class: esp_config_int!(u8, "ESP_WIFI__COUNTRY_CODE_OPERATING_CLASS"),
+    mtu: esp_config_int!(usize, "ESP_WIFI__MTU"),
+    tick_rate_hz: esp_config_int!(u32, "ESP_WIFI__TICK_RATE_HZ"),
+    listen_interval: esp_config_int!(u16, "ESP_WIFI__LISTEN_INTERVAL"),
+    beacon_timeout: esp_config_int!(u16, "ESP_WIFI__BEACON_TIMEOUT"),
+    ap_beacon_timeout: esp_config_int!(u16, "ESP_WIFI__AP_BEACON_TIMEOUT"),
+    failure_retry_cnt: esp_config_int!(u8, "ESP_WIFI__FAILURE_RETRY_CNT"),
+    scan_method: esp_config_int!(u32, "ESP_WIFI__SCAN_METHOD"),
 };
 
 // Validate the configuration at compile time

diff --git a/examples/.cargo/config.toml b/examples/.cargo/config.toml
@@ -33,7 +33,7 @@ PASSWORD = "PASSWORD"
 STATIC_IP = "1.1.1.1 "
 GATEWAY_IP = "1.1.1.1"
 HOST_IP = "1.1.1.1"
-ESP_WIFI_CSI_ENABLE = "true"
+ESP_WIFI__CSI_ENABLE = "true"
 
 [unstable]
 build-std = ["alloc", "core"]