Packaging ESP-IDF Components

This tutorial will guide you through packaging a simple ESP-IDF component. You will learn how to create all the necessary files and upload your component to the ESP Component Registry.

Prerequisites

In this tutorial, we assume that you have already installed ESP-IDF. If it is not installed, please refer to our ESP-IDF Get Started Guide.

A Simple ESP-IDF Component

An ESP-IDF component can be created by running the following command:

idf.py create-component test_cmp

After running the command, your component's local file tree will look like this:

.
└── test_cmp
    ├── CMakeLists.txt
    ├── include
    │   └── test_cmp.h
    └── test_cmp.c

You have created your first bare minimum component. These files are sufficient for local use, however, to publish your component on the ESP Component Registry it is necessary to provide more details. Please navigate to the component directory and continue with the next steps.

Extra Packaging Files

In this section, you would add files that are used to help the ESP Component Registry know your component better. When this section is finished, the file structure would look like:

.
└── test_cmp
    ├── CMakeLists.txt
    ├── idf_component.yml
    ├── include
    │   └── test_cmp.h
    ├── LICENSE
    ├── README.md
    └── test_cmp.c

Create idf_component.yml

A manifest file idf_component.yml is required to let the ESP Component Registry recognize your ESP-IDF component.

Here's the minimal idf_component.yml:

version: "0.0.1"

The ESP Component Registry only requires the version of the component in the idf_component.yml. version must follow versioning scheme.

However, we recommend adding url and description. Otherwise, a warning will be printed.

version: "0.0.1"
description: "This is a test component"
url: "https://mycomponent.com"  # The homepage of the component. It can be a GitHub repository page.

For information about additional fields in the manifest please check the manifest file reference.

Create License File

Once you've uploaded your component, other users can discover, download, and use it. Including a license with your component is crucial to ensure proper usage.

If you need help choosing a license for your component, you can check the https://choosealicense.com website. Once you've selected your license, be sure to include the full text of the license in the LICENSE or LICENSE.txt file in your component's root directory. Better to check the "How to apply this license" section to see if there's additional action items to apply the license.

After selecting a license, you can add the license field in your idf_component.yml file. The value should be the SPDX license identifier of the chosen license. You may check the identifier list at https://spdx.org/licenses/. For example, if you choose MIT license, the idf_component.yml should look like:

version: "0.0.1"
license: "MIT"

Create README.md

A README file would help users know better about your component. Usually it includes a brief introduction, the installation steps, and a simple getting-started tutorial.

# Test Component

This is a simple example component.

## Installation

- step 1
- step 2

## Getting Started

- step 1
- step 2

Publish the Component

Authentication

To publish your component to the ESP Component Registry, you need to provide the authentication token. The simplest way is to set it via the environment variable IDF_COMPONENT_API_TOKEN.

All components would be published under their namespace. If --namespace is not passed, the default namespace is espressif.

Note

For now, creating custom namespace is not supported. Please contact us if you have such needs.

Added in version 1.2: New CLI, compote. Now you may skip install ESP-IDF for packaging your component. This would be helpful when publishing your component in CI/CD pipelines.

compote component upload --namespace [YOUR_NAMESPACE] --name test_cmp

Once uploaded, your component should be viewable on https://components.espressif.com/components/YOUR_NAMESPACE/test_cmp

Advanced Usages

What we mentioned above is the basic usage to upload a component. Here are more use cases and tips.

Authentication with a Config File

You can control which registry you upload to, and provide the authentication token via a config file. For detailed information, please refer to our config file reference.

Filter Component Files

As a component developer, you may want to choose which files from the component directory will be uploaded to the ESP Component Registry. There are two ways to achieve this, either by allowing the processing of .gitignore files or by specifying exclude and include filters directly in the idf_component.yml manifest file. You are not allowed to use both methods simultaneously.

Using .gitignore

First, you need to specify use_gitignore option in the idf_component.yml manifest file.

files:
   use_gitignore: true

Then patterns specified in the .gitignore file will be automatically excluded before packaging or uploading the component.

test_dir/   # Exclude files in all `test_dir` directories (including the directories themselves)

More information on how .gitignore works is in the official documentation.

Using manifest filters

In this case, your idf_component.yml manifest may have include and exclude filters. For example:

files:
   exclude:
      - "*.py"          # Exclude all Python files
      - "**/*.list"     # Exclude `.list` files in all directories
      - "big_dir/**/*"  # Exclude `big_dir` directory and its content
   include:
      - "**/.DS_Store"  # Include files excluded by default

Files and directories that are excluded by default can be found here.

Note

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

Add Dependencies

When your component depends on another component, you need to add this dependency relationship in your component's manifest file as well. Our version solver would collect all dependencies and calculate the final versioning solution. For example:

dependencies:
  idf:
    version: ">5.0.0"
  example/cmp:
    version: "^3.0.0"

Please refer to our version range specification for detailed information on the version field.

Note

Unlike the other dependencies, idf is a keyword that points to ESP-IDF itself, not a component.

Add example projects

You may want to provide example projects to help users get started with your component. You place them in the examples directory inside your component. Examples are discovered recursively in subdirectories at this path. A directory with CMakeLists.txt that registers a project is considered as an example.

When an archive with the component is uploaded to the registry all examples are repacked to individual archives. So every example must be self-sufficient, i.e. doesn't depend on any files in the examples directory except its own directory. For convenience the examples directory is available in the component archive too.

Adding dependency on the component for examples

When a component repo is cloned from a git repository, then it's essential that for the example in the examples directory to use the component that lays right here in the tree. However, when a single example is downloaded using CLI from the registry, and there is no dependency laying around it must be downloaded from the registry.

This behavior can be achieved by setting override_path for dependency in the manifest file. When override_path is defined for a dependency from the registry it will be used with higher priority. When you download an example from the registry, it doesn't contain override_path, because all override_path fields are automatically removed. During the build process, it won't try to look for the component nearby.

I.E. for a component named cmp published in the registry as watman/cmp the idf_component.yml manifest in the examples/hello_world/main may look like:

version: "1.2.7"
description: My hello_world example
dependencies:
watman/cmp:
  version: '~1.0.0'
  override_path: '../../../' # three levels up, pointing the directory with the component itself

Note

You shouldn't add your component's directory to EXTRA_COMPONENT_DIRS in example's CMakeLists.txt, because it will break the examples downloaded with the repository.

Upload Component with GitHub Action

We provide a GitHub action to help you upload your components to the registry as a part of your GitHub workflow.