Version Solver

This document describes how the version solver works in IDF Component Manager. The version solver is responsible for finding the best version of a component that satisfies the constraints of the project.

Version Solving

An ESP-IDF project with component dependencies will specify those dependencies via one or more manifest files (e.g., idf_component.yml), where each dependency will have a range representing the component version(s) of that dependency. Version solving is the process of collecting all component dependencies of an ESP-IDF project and calculating the most appropriate component version for each dependency. The version solving process generally involves the following steps:

  1. Collect all the local manifest files from your main component and subcomponents.

  2. Collect all the root dependencies from the manifest files.

  3. Recursively collect all the available versions of each root dependency.

  4. Calculate the version solving solution.

In IDF Component Manager, the version solver uses the PubGrub algorithm to calculate the version solving solution. Once the version solving solution is calculated, the version solver generates a Dependencies.lock File that contains the exact versions of the components selected by the version solver.

When Will the Version Solver Run?

The version solver will be triggered by the ESP-IDF build system (i.e., idf.py reconfigure) in the following scenarios:

  1. When there is no dependencies.lock file present in the project root directory.

  2. When the manifest_hash recorded in the Dependencies.lock File does not match the current manifest hash.

    A common scenario is when the user adds or removes a component from the project or modifies the manifest file of a component.

  3. When the target recorded in the Dependencies.lock File does not match the current manifest target.

    A common scenario is when the user calls idf.py set-target to change the target.

  4. When the user runs the project with a different ESP-IDF version.

  5. When the user runs idf.py update-dependencies.

Please note that the dependencies.lock file will only be updated when the output of the version solver differs from the current dependencies.lock file.

Update Dependencies

By default, the version solver will prefer to reuse the existing version of a component if it satisfies the constraints of the project. This approach helps reduce network traffic and speeds up the version solving process. If version solving fails, the solver will run without the presets and try to find the best version of the components.

To update the dependencies of the project, you can run the following command explicitly:

$ idf.py update-dependencies

Environment Variables for Version Solver

Some environment variables can be used to control the behavior of the version solver.

IDF_COMPONENT_CHECK_NEW_VERSION

By default, the IDF Component Manager checks for new versions of dependencies while compiling the ESP-IDF project, even if the version solver is not triggered.

If new versions are available, the version solver will print the new versions in the console without updating the dependencies.lock file.

To disable the check, you can set the environment variable IDF_COMPONENT_CHECK_NEW_VERSION to 0.

To update the dependencies of the project, you may refer to the Update Dependencies section.