Skip to content

Commit

Permalink
Add documentation in README
Browse files Browse the repository at this point in the history
  • Loading branch information
@N3xed
N3xed committed Aug 1, 2022
1 parent 3a13722 commit 8336bcd
Showing 1 changed file with 204 additions and 89 deletions.
293 changes: 204 additions & 89 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Rust bindings for ESP-IDF
(Espressif's IoT Development Framework)
(Espressif's IoT Development Framework)

[![CI](https://github.com/esp-rs/esp-idf-sys/actions/workflows/ci.yml/badge.svg)](https://github.com/esp-rs/esp-idf-sys/actions/workflows/ci.yml)
[![Documentation](https://img.shields.io/badge/docs-esp--rs-brightgreen)](https://esp-rs.github.io/esp-idf-sys/esp_idf_sys/index.html)
Expand Down Expand Up @@ -53,71 +53,104 @@ To enable Bluetooth, or do other configurations to the ESP-IDF sdkconfig you mig

## Configuration

Environment variables are used to configure how the ESP-IDF framework is compiled.
There are two ways to configure how the ESP-IDF framework is compiled.
1. Environment variables, denoted by `$VARIABLE`;

Note that instead of / in addition to specifying those on the command line, you can also put these in a `.cargo/config.toml` file inside your crate directory
(or a parent directory of your crate) by using the recently stabilized Cargo [configurable-env](https://doc.rust-lang.org/cargo/reference/config.html#env) feature.
> The environment variables can be passed on the command line, or put into the `[env]`
> section of a `.cargo/config.toml` file (see [cargo reference](https://doc.rust-lang.org/cargo/reference/config.html#env)).
The following environment variables are used by the build script:
2. The `[package.metadata.esp-idf-sys]` section of the `Cargo.toml`, denoted by *`field`*.

- `ESP_IDF_SDKCONFIG_DEFAULTS`:
> 🛈 **Note**
> Configuration can only come from the **root crate's** `Cargo.toml`. The root crate
> is the package in the *workspace directory*. If there is not root crate in case of a
> [virtual
> workspace](https://doc.rust-lang.org/cargo/reference/workspaces.html#virtual-manifest),
> its *name* can be specified with the `ESP_IDF_SYS_ROOT_CRATE` environment variable.
A `;`-separated list of paths to `sdkconfig.defaults` files to be used as base
values for the `sdkconfig`. If such a path is relative, it will be relative to the
cargo workspace directory (i.e. the directory that contains the `target` dir).

If unspecified `sdkconfig.defaults` is used as default.

For each defaults file in this list more specific version will also be searched and
used. This happens with the following patterns and order (least to most specific):
> ⚠️ Environment variables always take precedence over `Cargo.toml` metadata.
1. `<path>`
2. `<path>.<profile>`
3. `<path>.<mcu>`
4. `<path>.<profile>.<mcu>`

where `<profile>` is the current cargo profile used (`debug`/`release`) and `<mcu>`
specifies the mcu for which this is currently compiled for (see the `MCU`
configuration option below).
> &#128712; **Note**: *workspace directory*
>
> The workspace directory mentioned here is always the
> directory containing the `Cargo.lock` file and the `target` directory (where the build
> artifacts are stored).
> There is no need to explicitly add a
> [`[workspace]`](https://doc.rust-lang.org/cargo/reference/workspaces.html#the-workspace-section)
> section to the `Cargo.toml` of the workspace directory.

Also note that a setting contained in a more specific defaults file will override the
same setting specified in a less specific one.
The following configuration options are available:

- `ESP_IDF_SDKCONFIG`:
- ### *`esp_idf_sdkconfig_defaults`*, `$ESP_IDF_SDKCONFIG_DEFAULTS`

The base-path to the `sdkconfig` file used to [configure the
`esp-idf`](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig.html).
If this is a relative path, it is relative to the cargo workspace directory.
A single path or a list of paths to `sdkconfig.defaults` files to be used as base
values for the [`sdkconfig`](#espidfsdkconfig-espidfsdkconfig). If such a path is
relative, it will be relative to the *workspace directory*.

If unspecified `sdkconfig` is used as default.
Defaults to `sdkconfig.defaults`.

Similar to the `sdkconfig.defaults`-file a more specific `sdkconfig`-file will be
selected if available. This happens with the following patterns and precedence:

1. `<path>.<profile>.<mcu>`
2. `<path>.<mcu>`
3. `<path>.<profile>`
4. `<path>`

**Note** (*native* builder only):
The cargo optimization options (`debug` and `opt-level`) are used by default to
determine the compiler optimizations of the `esp-idf`, **however** if the compiler
optimization options are already set in the `sdkconfig` **they will be used instead.**


- `ESP_IDF_TOOLS_INSTALL_DIR`:

The location where the ESP-IDF framework tooling is assumed to be/will be installed. The
framework tooling is either PlatformIO (when the `pio` builder is used), or the ESP-IDF
native toolset (when the `native` builder is used).

This variable can take one of the following values:
- `workspace` (default) - the tooling will be installed/used in
`<crate-workspace-dir>/.embuild/platformio` for `pio`, and `<crate-workspace-dir>/.embuild/espressif` for the `native` builder;
- `out` - the tooling will be installed/used inside the crate's build output directory, and will be deleted when `cargo clean` is invoked;
- `global` - the tooling will be installed/used in its standard directory (`~/.platformio` for PlatformIO, and `~./espressif` for the native ESP-IDF toolset);
- `custom:<dir>` - the tooling will be installed/used in the directory specified by `<dir>`. If this directory is a relative location, it is assumed to be
relative to the crate's workspace dir;
> &#128712; **Note**
> For each defaults file in this list, a more specific file will also be searched and
> used. This happens with the following patterns and order (least to most specific):
>
> 1. `<path>`
> 2. `<path>.<profile>`
> 3. `<path>.<mcu>`
> 4. `<path>.<profile>.<mcu>`
>
> where `<profile>` is the current cargo profile used (`debug`/`release`) and `<mcu>`
> specifies the mcu for which this is currently compiled for (see the [*`mcu`*](#mcu-mcu)
> configuration option below).
> ⚠️
> A setting contained in a more specific defaults file will override the
> same setting specified in a less specific one.
- ### *`esp_idf_sdkconfig`*, `$ESP_IDF_SDKCONFIG`

The `sdkconfig` file used to [configure the
`esp-idf`](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig.html).
If this is a relative path, it is relative to the *workspace directory*.

Defaults to `sdkconfig`.

> &#128712; **Note**
> Similar to the `sdkconfig.defaults`-file a more specific `sdkconfig`-file will be
> selected if available. This happens with the following patterns and precedence:
>
> 1. `<path>.<profile>.<mcu>`
> 2. `<path>.<mcu>`
> 3. `<path>.<profile>`
> 4. `<path>`
>
> &nbsp;
> &#128712; **Note**: *native* builder only
> The cargo optimization options (`debug` and `opt-level`) are used by default to
> determine the compiler optimizations of the `esp-idf`, **however** if the compiler
> optimization options are already set in the `sdkconfig` **they will be used instead.**
- ### *`esp_idf_tools_install_dir`*, `$ESP_IDF_TOOLS_INSTALL_DIR`:

The install location for the ESP-IDF framework tooling.

> &#128712; **Note**
> The framework tooling is either [PlatformIO](https://platformio.org/) when the `pio` builder is used, or the ESP-IDF
> native toolset when the `native` builder is used (default).
This option can take one of the following values:
- `workspace` (default) - the tooling will be installed or used in
`<crate-workspace-dir>/.embuild/platformio` for `pio`, and
`<crate-workspace-dir>/.embuild/espressif` for the `native` builder;
- `out` - the tooling will be installed or used inside *esp-idf-sys*'s [build output
directory](https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script),
and will be deleted when `cargo clean` is invoked;
- `global` - the tooling will be installed or used in its standard directory
(`~/.platformio` for PlatformIO, and `~./espressif` for the native ESP-IDF toolset);
- `custom:<dir>` - the tooling will be installed or used in the directory specified by
`<dir>`. If this directory is a relative location, it is assumed to be relative to
the *workspace directory*;
- `fromenv` - use the build framework from the environment
- *native* builder: use activated esp-idf environment (see esp-idf docs
[unix](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#step-4-set-up-the-environment-variables)
Expand All @@ -127,18 +160,20 @@ The following environment variables are used by the build script:

and error if this is not possible.

**ATTENTION**: Please be extra careful with the `custom:<dir>` setting when switching from `pio` to `native` and the other way around, because
the builder will install the tooling in `<dir>` without using any additional `platformio` or `espressif` subdirectories, so if you are not careful, you might end up with
both PlatformIO, as well as the ESP-IDF native tooling intermingled together in a single folder.


Note that both builders (`native` and `pio`) clone the ESP-IDF GIT repository *inside* the tooling directory as well. This restriction might be lifted soon for the `native` builder, whereas the user would be able to point the build to a custom ESP-IDF repository location.

- `IDF_PATH` (*native* builder only):
A path to a user-provided local clone of the [`esp-idf`](https://github.com/espressif/esp-idf),
> ⚠️ Please be extra careful with the `custom:<dir>` setting when switching from `pio` to `native` and the other way around, because
> the builder will install the tooling in `<dir>` without using any additional `platformio` or `espressif` subdirectories, so if you are not careful, you might end up with
> both PlatformIO, as well as the ESP-IDF native tooling intermingled together in a single folder.
> &#128712; **Note**
> The [ESP-IDF git repository](https://github.com/espressif/esp-idf) will be cloned
> *inside* the tooling directory. The *native* builder will use the esp-idf at
> [*`idf_path`*](#idfpath-or-idfpath-native-builder-only) of available.
- ### *`idf_path`*, `$IDF_PATH` (*native* builder only)
A path to a user-provided local clone of the [esp-idf](https://github.com/espressif/esp-idf),
that will be used instead of the one downloaded by the build script.

- `ESP_IDF_VERSION` (*native* builder only):
- ### *`esp_idf_version`*, `$ESP_IDF_VERSION` (*native* builder only):

The version used for the `esp-idf`, can be one of the following:
- `commit:<hash>`: Uses the commit `<hash>` of the `esp-idf` repository.
Expand All @@ -148,21 +183,25 @@ The following environment variables are used by the build script:
- `v<major>.<minor>` or `<major>.<minor>`: Uses the tag `v<major>.<minor>` of the `esp-idf` repository.
- `<branch>`: Uses the branch `<branch>` of the `esp-idf` repository.

It defaults to `v4.4.1`.
Defaults to `v4.4.1`.


- `ESP_IDF_REPOSITORY` (*native* builder only):
- ### *`esp_idf_repository`*, `$ESP_IDF_REPOSITORY` (*native* builder only):

The URL to the git repository of the `esp-idf`, defaults to <https://github.com/espressif/esp-idf.git>.

Note that when the `pio` builder is used, it is possible to achieve something similar to `ESP_IDF_VERSION` and `ESP_IDF_REPOSITORY` by using
the [`platform_packages`](https://docs.platformio.org/en/latest/projectconf/section_env_platform.html#platform-packages) PlatformIO option as follows:
- `ESP_IDF_PIO_CONF="platform_packages = framework-espidf @ <git-url> [@ <git-branch>]"`
- The above approach however has the restriction that PlatformIO will always use the ESP-IDF build tooling from its own ESP-IDF distribution,
so the user-provided ESP-IDF branch may or may not compile. The current PlatformIO tooling is suitable for compiling ESP-IDF branches derived from versions 4.3.X .


- `ESP_IDF_GLOB[_XXX]_BASE` and `ESP_IDF_GLOB[_XXX]_YYY`:
> &#128712; **Note**
> When the `pio` builder is used, it is possible to achieve something similar to
> `ESP_IDF_VERSION` and `ESP_IDF_REPOSITORY` by using the
> [`platform_packages`](https://docs.platformio.org/en/latest/projectconf/section_env_platform.html#platform-packages)
> PlatformIO option as follows:
>
> `ESP_IDF_PIO_CONF="platform_packages = framework-espidf @ <git-url> [@ <git-branch>]"`
>
> The above approach however has the restriction that PlatformIO will always use the ESP-IDF build tooling from
> its own ESP-IDF distribution, so the user-provided ESP-IDF branch may or may not compile. The current
> PlatformIO tooling is suitable for compiling ESP-IDF branches derived from versions 4.3.X and 4.4.X.
- ### `$ESP_IDF_GLOB[_XXX]_BASE` and `$ESP_IDF_GLOB[_XXX]_YYY`:

A pair of environment variable prefixes that enable copying files and directory trees that match a certain glob mask into the native C project used for building the ESP-IDF framework:
- `ESP_IDF_GLOB[_XXX]_BASE` specifies the base directory which will be glob-ed for resources to be copied
Expand All @@ -175,25 +214,101 @@ The following environment variables are used by the build script:
Note also that `_HOMEDIR` in the above example is optional, and is just a mechanism allowing the user to specify more than base directory and its glob patterns.


- `ESP_IDF_PIO_CONF_XXX` (*pio* builder only):
- ### `$ESP_IDF_PIO_CONF_XXX` (*pio* builder only):

A PlatformIO setting (or multiple settings separated by a newline) that will be passed as-is to the `platformio.ini` file of the C project that compiles the ESP-IDF.
- Check [the PlatformIO documentation](https://docs.platformio.org/en/latest/projectconf/index.html) for more information as to what settings you can pass via this variable.
- Note also that this is not one variable - but rather - a family of variables all starting with `ESP_IDF_PIO_CONF_`. I.e., passing `ESP_IDF_PIO_CONF_1` as well as `ESP_IDF_PIO_CONF_FOO` is valid and all such variables will be honored
A PlatformIO setting (or multiple settings separated by a newline) that will be passed
as-is to the `platformio.ini` file of the C project that compiles the ESP-IDF.

Check [the PlatformIO
documentation](https://docs.platformio.org/en/latest/projectconf/index.html) for more
information as to what settings you can pass via this variable.

> &#128712; **Note**
> This is not one variable, but rather a family of variables all
> starting with `ESP_IDF_PIO_CONF_`. For example, passing `ESP_IDF_PIO_CONF_1` as well as
> `ESP_IDF_PIO_CONF_FOO` is valid and all such variables will be honored.
- `ESP_IDF_CMAKE_GENERATOR` (*native* builder only):
- ### *`esp_idf_cmake_generator`*, `$ESP_IDF_CMAKE_GENERATOR` (*native* builder only):

The CMake generator to be used when building the ESP-IDF SDK. If not specified or set to `default`, Ninja will be used on all platforms except Linux/aarch64, where
(for now) the Unix Makefiles generator will be used, as there are no Ninja builds for that platform provided by Espressif yet.
Possible values for this environment variable are [the names of all command-line generators that CMake supports](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#cmake-generators) with **spaces and hyphens removed**.
The CMake generator to be used when building the ESP-IDF.

If not specified or set to `default`, Ninja will be used on all platforms except
Linux/aarch64, where (for now) the Unix Makefiles generator will be used, as there are
no Ninja builds for that platform provided by Espressif yet.

Possible values for this environment variable are [the names of all command-line
generators that CMake
supports](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#cmake-generators)
with **spaces and hyphens removed**.

- `MCU`:
- ### *`mcu`*, `$MCU`:

The MCU name (i.e. `esp32`, `esp32s2`, `esp32s3` `esp32c3` and `esp32h2`).

- If not set this will be automatically detected from the cargo target.

- Note that [older ESP-IDF versions might not support all MCUs from above](https://github.com/espressif/esp-idf#esp-idf-release-and-soc-compatibility).
If not set this will be automatically detected from the cargo target.

> ⚠️
> [Older ESP-IDF versions might not support all MCUs from above](https://github.com/espressif/esp-idf#esp-idf-release-and-soc-compatibility).
## Extra esp-idf components

It is possible to let *esp-idf-sys* compile extra [esp-idf
components](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html#concepts)
and generate bindings for them.

This is possible by adding an object to the
`package.metadata.esp-idf-sys.extra_components` array of the `Cargo.toml`. *esp-idf-sys*
will honour all such extra components in the *root crate*'s and all **direct**
dependencies' `Cargo.toml`.

> &#128712; **Note**
> By only specifying the `bindings_header` field, one can extend the set of *esp-idf*
> bindings that were generated from
> [src/include/esp-idf/bindings.h](src/include/esp-idf/bindings.h).
An extra component can be specified like this:

```toml
[[package.metadata.esp-idf-sys.extra_components]]
# A single path or a list of paths to a component directory or directory containing components.
#
# Each path can be absolute or relative. Relative paths will be relative to the
# folder containg the defining `Cargo.toml`.
#
# **This field is optional.** No component will be built if this field is absent, though
# the bindings of the `[Self::bindings_header]` will still be generated.
component_dirs = ["dir1", "dir2"] # or "dir"

# The path to the C header to generate the bindings with. If this option is absent,
# **no** bindings will be generated.
#
# The path can be absolute or relative. A relative paths will be relative to the
# folder containg the defining `Cargo.toml`.
#
# This field is optional.
bindings_header = "bindings.h"

# If this field is present, the component bindings will be generated separately from
# the `esp-idf` bindings and put into their own module inside the `esp-idf-sys` crate.
# Otherwise, if absent, the component bindings will be added to the existing
# `esp-idf` bindings (which are available in the crate root).
#
# To put the bindings into its own module, a separate bindgen instance will generate
# the bindings. Note that this will result in duplicate `esp-idf` bindings if the
# same `esp-idf` headers that were already processed for the `esp-idf` bindings are
# included by the component(s).
#
# This field is optional.
bindings_module = "name"
```

and is equivalent to
```toml
[package.metadata.esp-idf-sys]
extra_components = [
{ component_dirs = [ "dir1", "dir2" ], bindings_header = "bindings.h", bindings_module = "name" }
]
```

## More info

Expand Down

0 comments on commit 8336bcd

Please sign in to comment.