Configuration
The esp-config
crate provides a way to manage additional configuration settings that don't fit into cargo features, for esp-*
crates.
Finding Available Configuration
The full list of available options can be found in the documentation of the crate you are interested. For example, these are esp-hal's configuration options for the ESP32-C6.
Usage
While creating your project, you may need to configure some additional advanced parameters, for example, place a peripheral in RAM for better performance or change the size of RX/TX queue in some crate. In order to do so you will need to configure some settings provided by the esp-config
.
You are free to do this in two ways:
-
By setting the environment variable. For example, in
esp-hal
if you want to place anonymous symbols in the RAM (ESP_HAL_CONFIG_PLACE_ANON_IN_RAM
), which is set tofalse
as default, you need to create an environment variable with the same name and modify its value. -
By setting the required parameter in
.cargo/config.toml
(this method also sets the environment variable):# .cargo/config.toml [env] ESP_HAL_CONFIG_PLACE_ANON_IN_RAM="true"
After modifying the
.cargo/config.toml
and[env]
section, clean build is recommended.
⚠️ Note: Setting the environment variables on the command line will have precedence over env section.
Multiple Configurations
Depending on your application, you may find yourself wanting to support different boards/chips/targets in the same project. In this case, you may have specific options to set for each target. To do this, we recommend the following setup.
- A baseline
.cargo/config.toml
which has your typical build modifying flags (Cargo will always read and respect this file, regardless of other--config
's passed) - A config file for each configuration in
.cargo/
- (Recommended) A Cargo alias to build with the given config, for example
run-config-a = "run --config=./.cargo/config_a.toml --release"
, but for simple cases you can pass--config
on the CLI.
Checkout this example repo for a more comprehensive look at multi-config projects.
Defining Your Own Config Options
You may also want to define certain configuration options in your project. To do so, it is necessary to declaratively define these options, their default values, and other parameters and checks inside a esp_config.yml
file. Details can be found in the Defining Configuration Options section of the project repository.