Package name when using remote components in a virtual workspace?

[victorbnl]

In the ESP-IDF configuration section of BUILD-OPTIONS.md, there is the following 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 no root crate in case of a virtual workspace, its name can be specified with the ESP_IDF_SYS_ROOT_CRATE environment variable.

However I don’t understand the last sentence. I think it lacks precision. Maybe that’s a beginner’s question but, which should be set to which? Should I assign to the env variable the package’s name? Should I set the package name to the env variable? Currently I don’t seem to have ESP_IDF_SYS_ROOT_CRATE defined, should I set it to a custom value?

[N3xed]

In most cases setting ESP_IDF_SYS_ROOT_CRATE is not needed. It is only required if the build script of esp-idf-sys cannot determine a root crate (i.e. the crate that you build with cargo build, cargo check, etc.). Since there is currently no way to determine the root within a build script, we assume that it is the workspace root. We define it as the Cargo.toml of the directory containing the target directory. The most common crate structure.

There are (I think) two cases where this is not the case:

1. The workspace is a virtual workspace. With a directory structure like:

   .
   ├── Cargo.toml
   ├── Cargo.lock
   ├── some-crate/
   │   └── Cargo.toml
   └── target/
   

   Where the root Cargo.toml does not contain a [package] section (see the explanation in the Cargo reference). In this case the assumption does not hold and we don't know which crate in the workspace is the root for the current compilation, therefore it has to be specified manually (by setting the environment variable ESP_IDF_SYS_ROOT_CRATE to the name of the root crate).
2. The target directory is put somewhere else by setting CARGO_TARGET_DIR, specifying --target-dir, or other ways described here. In this case the parent directory of the target dir may not be the workspace directory and so the determined Cargo.toml may be wrong or may not exist. In this case the user must set the correct workspace directory with the CARGO_WORKSPACE_DIR environment variable (see the note on workspace directory in the build options). If further the root crate cannot be found (like in case 1), then ESP_IDF_SYS_ROOT_CRATE has to be specified too.

TLDR, ESP_IDF_SYS_ROOT_CRATE is only needed when no root crate is found. This only happens with untypical crate setups. If this is the case, this environment variable has to be set to the name of the root crate, the crate that is built with cargo build.

I hope this helps.