esp-config

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ on:
 env:
   CARGO_TERM_COLOR: always
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  MSRV: "1.77.0"
+  MSRV: "1.79.0"
   RUSTDOCFLAGS: -Dwarnings
   DEFMT_LOG: trace
 
@@ -179,3 +179,19 @@ jobs:
 
       # Check the formatting of all packages:
       - run: cargo xtask fmt-packages --check
+
+  # --------------------------------------------------------------------------
+  # host tests
+
+  host-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@v1
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@v2
+
+      # Check the formatting of all packages:
+      - run: cd esp-config && cargo test --features build

Cargo.toml

@@ -5,6 +5,7 @@ exclude  = [
     "esp-alloc",
     "esp-backtrace",
     "esp-build",
+    "esp-config",
     "esp-hal",
     "esp-hal-embassy",
     "esp-hal-procmacros",

esp-config/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "esp-config"
+version = "0.1.0"
+edition = "2021"
+rust-version  = "1.79.0"
+
+[dependencies]
+document-features        = "0.2.10"
+
+[dev-dependencies]
+temp-env = "0.3.6"
+
+[features]
+## Enable the generation and parsing of a config
+build = []

esp-config/README.md

@@ -0,0 +1,65 @@
+# esp-config
+
+[![Crates.io](https://img.shields.io/crates/v/esp-config?labelColor=1C2C2E&color=C96329&logo=Rust&style=flat-square)](https://crates.io/crates/esp-config)
+[![docs.rs](https://img.shields.io/docsrs/esp-config?labelColor=1C2C2E&color=C96329&logo=rust&style=flat-square)](https://docs.rs/esp-config)
+![MSRV](https://img.shields.io/badge/MSRV-1.79-blue?labelColor=1C2C2E&style=flat-square)
+![Crates.io](https://img.shields.io/crates/l/esp-config?labelColor=1C2C2E&style=flat-square)
+[![Matrix](https://img.shields.io/matrix/esp-rs:matrix.org?label=join%20matrix&labelColor=1C2C2E&color=BEC5C9&logo=matrix&style=flat-square)](https://matrix.to/#/#esp-rs:matrix.org)
+
+## [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`.
+
+### Capturing configuration values in the downstream crate
+
+For all supported data types, there are helper macros that emit `const` code for parsing the configuration values.
+
+- Numbers - `esp_config_int!(integer_type, "ENV")`
+- Strings - `esp_config_str!("ENV")`
+- Bool - `esp_config_bool!("ENV")`
+
+In addition to environment variables, for boolean types rust `cfg`'s are emitted in snake case _without_ the prefix.
+
+## Minimum Supported Rust Version (MSRV)
+
+This crate is guaranteed to compile on stable Rust 1.79 and up. It _might_
+compile with older versions but that may change in any new patch release.
+
+## License
+
+Licensed under either of:
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
+the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without
+any additional terms or conditions.