From 5717288cd71a8eed23ecebfcd1a0763b4534651f Mon Sep 17 00:00:00 2001 From: Sergei Silnov Date: Sat, 3 Jul 2021 10:30:52 +0200 Subject: [PATCH] docs: Add component manager documentation --- .../tools/idf-component-manager.rst | 72 +++++++++++++++++++ docs/en/api-guides/tools/index.rst | 1 + .../tools/idf-component-manager.rst | 1 + docs/zh_CN/api-guides/tools/index.rst | 1 + 4 files changed, 75 insertions(+) create mode 100644 docs/en/api-guides/tools/idf-component-manager.rst create mode 100644 docs/zh_CN/api-guides/tools/idf-component-manager.rst diff --git a/docs/en/api-guides/tools/idf-component-manager.rst b/docs/en/api-guides/tools/idf-component-manager.rst new file mode 100644 index 0000000000..3700256194 --- /dev/null +++ b/docs/en/api-guides/tools/idf-component-manager.rst @@ -0,0 +1,72 @@ +********************* +IDF Component Manager +********************* + +The IDF Component manager is a tool that downloads dependencies for any ESP-IDF CMake project. The download happens automatically during a run of CMake. It can source components either from `the component registry `_ or from a git repository. + +A list of components can be found on ``_ + +Activating the Component Manager +================================ + +If CMake is started using ``idf.py`` or `ESP-IDF VSCode Extension `_ then the component manager will be activated by default. + +If CMake is used directly or with some CMake-based IDE like CLion, it's necessary to set the ``IDF_COMPONENT_MANAGER`` environment variable to ``1`` to enable the component manager integration with the build system. + +Using with a project +==================== + +Dependencies for each component in the project are defined in a separate manifest file named ``idf_component.yml`` placed in the root of the component. The manifest file template can be created for a component by running ``idf.py create-manifest --component=my_component``. When a new manifest is added to one of the components in the project it's necessary to reconfigure it manually by running ``idf.py reconfigure``. Then build will track changes in ``idf_component.yml`` manifests and automatically triggers CMake when necessary. + +There is an example application: example:`build_system/cmake/component_manager` that uses components installed by the component manager. + +It's not necessary to have a manifest for components that don't need any managed dependencies. + +When CMake configures the project (e.g. ``idf.py reconfigure``) component manager does a few things: + +- Processes ``idf_component.yml`` manifests for every component in the project and recursively solves dependencies +- Creates a ``dependencies.lock`` file in the root of the project with a full list of dependencies +- Downloads all dependencies to the ``managed_components`` directory + +The lock-file ``dependencies.lock`` and content of ``managed_components`` directory is not supposed to be modified by a user. When the component manager runs it always make sure they are up to date. If these files were accidentally modified it's possible to re-run the component manager by triggering CMake with ``idf.py reconfigure`` + +Defining dependencies in the manifest +===================================== + +.. code-block:: yaml + + dependencies: + # Required IDF version + idf: ">=4.1" + # Defining a dependency from the registry: + # https://components.espressif.com/component/example/cmp + example/cmp: ">=1.0.0" + + # # Other ways to define dependencies + # + # # For components maintained by Espressif only name can be used. + # # Same as `espressif/cmp` + # component: "~1.0.0" + # + # # Or in a longer form with extra parameters + # component2: + # version: ">=2.0.0" + # + # # For transient dependencies `public` flag can be set. + # # `public` flag doesn't affect the `main` component. + # # All dependencies of `main` are public by default. + # public: true + # + # # For components hosted on non-default registry: + # service_url: "https://componentregistry.company.com" + # + # # For components in git repository: + # test_component: + # path: test_component + # git: ssh://git@gitlab.com/user/components.git + # + # # For test projects during component development + # # components can be used from a local directory + # # with relative or absolute path + # some_local_component: + # path: ../../projects/component diff --git a/docs/en/api-guides/tools/index.rst b/docs/en/api-guides/tools/index.rst index 80f496fee9..205451d5d9 100644 --- a/docs/en/api-guides/tools/index.rst +++ b/docs/en/api-guides/tools/index.rst @@ -6,3 +6,4 @@ Tools IDF Monitor IDF Docker image + IDF Component Manager diff --git a/docs/zh_CN/api-guides/tools/idf-component-manager.rst b/docs/zh_CN/api-guides/tools/idf-component-manager.rst new file mode 100644 index 0000000000..8017f17fbc --- /dev/null +++ b/docs/zh_CN/api-guides/tools/idf-component-manager.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-guides/tools/idf-component-manager.rst diff --git a/docs/zh_CN/api-guides/tools/index.rst b/docs/zh_CN/api-guides/tools/index.rst index 37d559c5d3..fc5e1dea4f 100644 --- a/docs/zh_CN/api-guides/tools/index.rst +++ b/docs/zh_CN/api-guides/tools/index.rst @@ -6,3 +6,4 @@ IDF 监视器 IDF Docker image + IDF Component Manager