Manifest File `idf_component.yml` Format Reference

The idf_component.yml file is a YAML file that describes the component. The file is located in the root directory of the component.

The file contains the following fields:

dependencies: A dictionary of dependencies of the component. This field is optional and can be omitted if the component does not have any dependencies.
description: A brief description of the component. This field is highly recommended, if it’s missing, a warning message will appear when the component is uploaded to the registry.
examples: A list of directories with examples. This field is optional and can be omitted if all the component examples are located in the examples directory.
files: A dictionary containing two lists of include and exclude patterns. This field is optional and can be omitted if the component contains all files in the root directory with the default list of exceptions.
maintainers: A list of maintainers of the component, while format is not fixed, we recommend using the First Last <email@example.com> format. This field is optional.
tags: A list of tags related to the component functionality. This field is optional.
targets: A list of targets that the component supports. This field is optional and can be omitted if the component supports all targets.
version: The version of the component. This field is always present for a component in the ESP Component Registry. At the same time, it is optional for components in the local component directory or in git.
license: The license of the component. It should be a valid SPDX license identifier listed in https://spdx.org/licenses/. This field is optional. The license will be automatically detected if it’s not specified.

External Links:

discussion: The URL of the component discussion forum or chat, i.e., Discord, Gitter, etc. This field is optional.
documentation: The URL of the component documentation, if it is not included in the component itself. This field is optional.
issues: The URL of the component issue tracker. This field is optional.
repository: The URL of the component repository. This field is optional, but highly recommended.
url: The homepage of the component. This field is highly recommended, if it’s missing, a warning message will appear when the component is uploaded to the registry.

All links should be correct HTTP(S) URLs like https://example.com/path except for the repository field, which is expected to be a valid [Git remote](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) URL.

Dependencies

Dependencies are specified in the dependencies field of the manifest file. The field is a dictionary of dependencies, where the key is the name of the dependency.

Component manager supports several sources of dependencies: local directory, git repository, and ESP Component Registry.

Common Fields for All Dependency Types

version: The version of the dependency. This field is optional and can be omitted if the dependency is in a local directory.
pre_release: A boolean flag that indicates whether the prerelease versions of the dependency should be used.
require: Specifies component visibility. Possible values are:
- private: This is the default value. The required component is added as a private dependency. This is equivalent to adding the component to the PRIV_REQUIRES argument of idf_component_register in the component’s CMakeLists.txt file.
- public: Sets the transient dependency. This is equivalent to adding the component to the REQUIRES argument of idf_component_register in the component’s CMakeLists.txt file.
- no: Can be used to only download the component but not add it as a requirement.
matches: A list of if clauses that should be applied to the dependency. The dependency is only included when any of the if-clauses is true. More details on rules.
rules: A list of if clauses that should be applied to the dependency. The dependency is only included when all of the if-clauses are true. More details on rules.

Dependencies from the ESP Component Registry

Components in the ESP Component Registry are specified by their name in the namespace/component_name format. The version of the dependency is specified in the version field of the dependency.

dependencies:
  namespace/component_name:
    version: ">=1.0"

You can use the shorthand syntax to specify the version of the dependency:

dependencies:
  namespace/component_name: ">=1.0"

For components in the default namespace espressif, you can omit the namespace part:

dependencies:
  led_strip: "^2.0"

This will be equivalent to:

dependencies:
  espressif/led_strip: "^2.0"

Override Path

Dependencies from the ESP Component Registry may also contain the override_path field. You can specify a local path in this field, and it will be used instead of the one downloaded from the registry. This field is mainly used for example projects inside components.

Dependencies from Local Directory

If you work on a component that is not yet published to the ESP Component Registry, you can add it as a dependency from a local directory. The dependency is specified by the path field of the dependency. The path is relative to the idf_component.yml manifest file. You can use absolute paths as well.

dependencies:
  some_local_component:
    path: ../../projects/component

Dependencies from Git

You can add dependencies from a Git repository by specifying the git field of the dependency. It is possible to specify the Git repository by its URL or by its path on the local file system.

Dependencies from Git support two additional fields:

path field can be used to specify the path to the component in the Git repository. The path is relative to the root directory of the Git repository. If the path field is omitted, the root directory of the Git repository is used as the path to the component.
version field can be used to specify the version of the dependency. The version of a Git dependency can be specified by any valid Git reference: a tag, a branch, or a commit hash. If the version field is omitted, the default branch of the Git repository is used.

Note

version and path fields of Git dependencies have a different meaning than the same fields of dependencies from the ESP Component Registry or local dependencies.

dependencies:
  test_component:
    version: feature/test
    path: test_component
    git: ssh://git@gitlab.com/user/components.git

ESP-IDF Version

The idf dependency is a special case. It is used to specify the version of ESP-IDF that the component is compatible with. The version is specified in the version field of the idf dependency.

dependencies:
  idf:
    version: ">=5.0"

You can use the shorthand syntax to specify the version of ESP-IDF:

dependencies:
  idf: ">=5.0"

Matches and Rules

matches and rules are specified to control the dependency inclusion. The dependency is only included when:

any of the if clauses in matches is true
all of the if clauses in rules are true

matches and rules are optional fields. If they are omitted, the dependency is always included.

matches and rules support the same syntax. The field is a list of optional dependencies. Each optional dependency has an if field, and an optional version field.

The if field supports idf_version and target variables. The idf_version variable contains the version of ESP-IDF that is used to build the component. The target variable contains the current target selected for the project.

The if field supports all Range Specifications. It also supports the in and not in operators, which can be used to check if the value is in the list of values.

To make a more complex condition, you can use nested parentheses with boolean operators && and ||.

dependencies:
  optional_component:
   version: "~1.0.0"
   rules:
     - if: "idf_version >=3.3,<5.0"
     - if: "target in [esp32, esp32c3]"
     # the above two conditions equals to
     - if: idf_version >=3.3,<5.0 && target in [esp32, esp32c3]

The version field is optional, and it also supports all Range Specifications. The version specified here will override the version field of the dependency when the corresponding if clause is true.

For example,

dependencies:
  optional_component:
    matches:
      - if: "idf_version >=3.3"
        version: "~2.0.0"
      - if: "idf_version <3.3"
        version: "~1.0.0"

The optional_component will be included with version ~2.0.0 when the idf_version >=3.3, and it will be included with version ~1.0.0 when the idf_version <3.3.

Examples

Examples from the examples directory are handled automatically. If you want to add examples from other directories, you can specify them in the examples field of the manifest file.

The examples field is a list of directories with examples. Each directory is specified as a dictionary with the path field.

examples:
  - path: ../some/path
  - path: ../some/other_path

Please check the example projects guide for more details.

Choosing What Files to Upload

As a component developer, you may want to choose which files from the component directory will be uploaded to the registry. Your idf_component.yml manifest may include and exclude filters. For example:

files:
  exclude:
    - "*.py" # Exclude all Python files
    - "**/*.list" # Exclude `.list` files in all directories
    - "big_dir/**/*" # Exclude files in `big_dir` directory (but the empty directory will be added to the archive anyway)
  include:
    - "**/.DS_Store" # Include files excluded by default

List of files and directories excluded by default

[
     # Python files
     '**/__pycache__',
     '**/*.pyc',
     '**/*.pyd',
     '**/*.pyo',
     # macOS files
     '**/.DS_Store',
     # Git
     '**/.git/**/*',
     # SVN
     '**/.svn/**/*',
     # dist and build artefacts
     '**/dist/**/*',
     '**/build/**/*',
     # artifacts from example projects
     '**/managed_components/**/*',
     '**/dependencies.lock',
     # CI files
     '**/.github/**/*',
     '**/.gitlab-ci.yml',
     # IDE files
     '**/.idea/**/*',
     '**/.vscode/**/*',
     # Configs
     '**/.settings/**/*',
     '**/sdkconfig',
     '**/sdkconfig.old',
     # Hash file
     '**/.component_hash'
 ]

Note

The file field is only taken into account during the preparation of the archive before uploading to the registry.

Environment Variables in Manifest

You can use environment variables in values in idf_component.yml manifests. $VAR or ${VAR} is replaced with the value of the VAR environment variable. If the environment variable is not defined, the component manager will raise an error.

Variable names should be ASCII alphanumeric strings (including underscores) and start with an underscore or ASCII letter. The first non-identifier character after the $ terminates this placeholder specification. You can escape $ with one more $ character, i.e., $$ is replaced with $.

One possible use-case is providing authentication to Git repositories accessed through HTTPS:

dependencies:
 my_component:
   git: https://git:${ACCESS_TOKEN}@git.my_git.com/my_component.git

Note

Environment variables are not allowed in manifests of components and examples uploaded to the ESP Component Registry.

Special Rules

Ignore Prerelease Versions by Default

Normally, the version solver would skip the prerelease versions while collecting all the available versions of each dependency. To use the prerelease versions for one dependency, please either include the prerelease field in the range specification, or add the keyword pre_release: true.

For example:

dependencies:
  namespace/pre_release_component:
    version: "*"
    pre_release: true

Or

dependencies:
  namespace/pre_release_component:
    version: "~1.0.0-a1"

Local Dependencies First

Added in version 1.3.0.

While collecting the root dependencies, local file system components are given precedence.

For example, this is our main component idf_component.yml:

dependencies:
  test/dependency_b: "==1.0.0"
  test/dependency_a:
    path: '../test__dependency_a'

test/dependency_b 1.0.0 version depends on test/dependency_a. When a local component with the same name is defined, we would replace the dependency of all collected component versions with this local one. The final dependency chain would be:

root depends on test/dependency_a (local)
root depends on test/dependency_b (1.0.0)
test/dependency_b (1.0.0) replaces the original dependency test/dependency_a (2.0.0) with test/dependency_a (local)

Manifest File idf_component.yml Format Reference

Dependencies

Common Fields for All Dependency Types

Dependencies from the ESP Component Registry

Override Path

Dependencies from Local Directory

Dependencies from Git

ESP-IDF Version

Matches and Rules

Examples

Choosing What Files to Upload

Environment Variables in Manifest

Special Rules

Ignore Prerelease Versions by Default

Local Dependencies First

Manifest File `idf_component.yml` Format Reference