mirror of
https://github.com/esp-rs/esp-hal.git
synced 2025-09-27 12:20:56 +00:00
134 lines
6.1 KiB
Markdown
134 lines
6.1 KiB
Markdown
# esp-config
|
|
|
|
[](https://crates.io/crates/esp-config)
|
|
[](https://docs.espressif.com/projects/rust/esp-config/latest/)
|
|
|
|
|
|
[](https://matrix.to/#/#esp-rs:matrix.org)
|
|
|
|
## [Documentation](https://docs.espressif.com/projects/rust/esp-config/latest/)
|
|
|
|
## 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.
|
|
|
|
## Defining Configuration Options
|
|
|
|
Config options should be defined declaratively in a file called `esp_config.yml`.
|
|
|
|
Such a file looks like this:
|
|
```yaml
|
|
crate: esp-bootloader-esp-idf
|
|
|
|
options:
|
|
- name: mmu_page_size
|
|
description: ESP32-C2, ESP32-C6 and ESP32-H2 support configurable page sizes. This is currently only used to populate the app descriptor.
|
|
default:
|
|
- value: '"64k"'
|
|
stability: !Stable stable-since-version
|
|
constraints:
|
|
- if: true
|
|
type:
|
|
validator: enumeration
|
|
value:
|
|
- 8k
|
|
- 16k
|
|
- 32k
|
|
- 64k
|
|
|
|
- name: esp_idf_version
|
|
description: ESP-IDF version used in the application descriptor. Currently it's not checked by the bootloader.
|
|
default:
|
|
- if: 'chip == "esp32c6"'
|
|
value: '"esp32c6"'
|
|
- if: 'chip == "esp32"'
|
|
value: '"other"'
|
|
active: true
|
|
|
|
- name: partition-table-offset
|
|
description: "The address of partition table (by default 0x8000). Allows you to \
|
|
move the partition table, it gives more space for the bootloader. Note that the \
|
|
bootloader and app will both need to be compiled with the same \
|
|
PARTITION_TABLE_OFFSET value."
|
|
default:
|
|
- if: true
|
|
value: 32768
|
|
stability: Unstable
|
|
active: 'chip == "esp32c6"'
|
|
|
|
checks:
|
|
- 'ESP_BOOTLOADER_ESP_IDF_CONFIG_PARTITION_TABLE_OFFSET >= 32768'
|
|
```
|
|
|
|
`if` and `active` are [somni-expr](https://crates.io/crates/somni-expr) expressions evaluating to a boolean.
|
|
|
|
The expression supports these custom functions:
|
|
|Function|Description|
|
|
|---|---|
|
|
|feature(String)|`true` if the given chip feature is present|
|
|
|cargo_feature(String)|`true` if the given Cargo feature is active|
|
|
|ignore_feature_gates|Usually `false` but tooling will set this to `true` to hint that the expression is evaluated by e.g. a TUI|
|
|
|
|
`ignore_feature_gates` is useful to enable otherwise disabled functionality - e.g. to offer all possible options regardless of any active / non-active features.
|
|
|
|
The `chip` variable is populated with the name of the targeted chip (if the crate is using chip specific features).
|
|
|
|
The conditions for `default` and `constraints` are evaluated in order and the first match is taken no matter if there is more.
|
|
This way you could have a catch-all condition as the last item by just specifying `true`.
|
|
|
|
`checks` is a list of checks which needs to pass for a valid configuration and is checked after all config values for the current config are applied.
|
|
You can access the currently configured values to check them.
|
|
|
|
For more examples see the various `esp_config.yml` files in this repository.
|
|
|
|
## Minimum Supported Rust Version (MSRV)
|
|
|
|
This crate is guaranteed to compile when using the latest stable Rust version at the time of the crate's release. It _might_ compile with older versions, but that may change in any new release, including patches.
|
|
|
|
## 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.
|