From 0e910067494fa1c152e997a3a53f9001b6a923cc Mon Sep 17 00:00:00 2001 From: Daniel Paul Date: Tue, 20 Jun 2023 16:18:55 +0200 Subject: [PATCH] docs(IDF Component Manager): Updates documentation for new Component Manager CLI commands in IDF --- .../tools/idf-component-manager.rst | 88 +++++++++++-------- 1 file changed, 53 insertions(+), 35 deletions(-) diff --git a/docs/en/api-guides/tools/idf-component-manager.rst b/docs/en/api-guides/tools/idf-component-manager.rst index fbe42bfcc0..d85bf94cbe 100644 --- a/docs/en/api-guides/tools/idf-component-manager.rst +++ b/docs/en/api-guides/tools/idf-component-manager.rst @@ -6,10 +6,30 @@ The IDF Component manager is a tool that downloads dependencies for any ESP-IDF A list of components can be found on ``_ -Using with a project +For detailed information about the IDF Component Manager, see the `IDF Component Manager and ESP Component Registry Documentation `_. + +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. +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 by running ``idf.py create-manifest``. By default, manifest file is created for the main component. You can explicitly either specify the directory where the manifest should be created using ``--path`` option or specify the component in your `components` folder using ``--component=my_component``. The ``create-manifest`` command can be run in the following ways: + +- ``idf.py create-manifest`` creates a manifest file for the main component +- ``idf.py create-manifest --component=my_component`` creates a manifest file for the component *my_component* in the ``components`` directory +- ``idf.py create-manifest --path="../../my_component"`` creates a manifest file for the component *my_component* in the directory ``my_component`` + +When a new manifest is added to one of the components in the project, it is necessary to reconfigure the project manually by running ``idf.py reconfigure``. Then build will then track changes in ``idf_component.yml`` manifests and automatically triggers CMake when necessary. + +To add a dependency to a component (e.g. ``my_component``) in your ESP-IDF project, you can run the command ``idf.py add-dependency DEPENDENCY``. "The ``DEPENDENCY`` argument represents an additional component managed by the IDF Component Manager that ``my_component`` depends on. It is defined in a format ``namespace/name=1.0.0``, where `namespace/name` is the name of the component and `=1.0.0` is a version range of the component (see the `Versioning Documentation `_). By default, dependencies are added to the main component. You can either explicitly specify a directory where the manifest is located using ``--path`` option, or specify the component in your `components` folder using ``--component=my_component``. The ``add-dependency`` command can be run in the following ways: + +- ``idf.py add-dependency example/cmp`` adds a dependency on the most recent version of ``example/cmp`` to the main component +- ``idf.py add-dependency --component=my_component example/cmp<=3.3.3`` adds a dependency on the version ``<=3.3.3`` of ``example/cmp`` to the component ``my_component`` in the ``components`` directory +- ``idf.py add-dependency --path="../../my_component" example/cmp^3.3.3`` adds a dependency on the version ``^3.3.3`` of ``example/cmp`` to the component ``my_component`` in the directory ``my_component`` + +.. note:: + + The command ``add-dependency`` adds dependencies to your project explicitly from the `Espressif Component Registry `_. + +To update dependencies of the ESP-IDF project, you can run the command ``idf.py update-dependencies``. You can also specify the path to the project directory using ``--project-dir PATH``. There is an example application: example:`build_system/cmake/component_manager` that uses components installed by the component manager. @@ -25,46 +45,44 @@ The lock-file ``dependencies.lock`` and content of ``managed_components`` direct You may set build property ``DEPENDENCIES_LOCK`` to specify the lock-file path in the top-level CMakeLists.txt. For example, adding ``idf_build_set_property(DEPENDENCIES_LOCK dependencies.lock.${IDF_TARGET})`` before ``project(PROJECT_NAME)`` could help generate different lock files for different targets. -Defining dependencies in the manifest +Creating Project From an Example +================================ + +Some components on the registry contain example projects. To create a new project from an example you can run the command ``idf.py create-project-from-example EXAMPLE``. The ``EXAMPLE`` argument should be in the format ``namespace/name=1.0.0:example`` where `namespace/name` is the name of the component, `=1.0.0` is a version range of the component (see the `Versioning Documentation `_) and `example` is the example's name. You can find the list of examples for every component and the command to start a project for it in the `Espressif Component Registry `_. + +Defining Dependencies in the Manifest ===================================== +You can easily define dependencies in the manifest file (idf_component.yml) by editing it directly in the text editor. Below are some basic examples that demonstrate how to define dependencies. + +You can define a dependency from the registry by specifying the component name and the version range: + .. code-block:: yaml dependencies: - # Required IDF version - idf: ">=4.1" - # Defining a dependency from the registry: - # https://components.espressif.com/component/example/cmp + # Define 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 +To define a dependency from a git repository, provide the path to the component within the repository and the repository's URL: + +.. code-block:: yaml + + dependencies: + # Define a dependency from a git repository + test_component: + path: test_component + git: ssh://git@gitlab.com/user/components.git + +During the development of components, you can use components from a local directory by specifying either a relative or an absolute path: + +.. code-block:: yaml + + dependencies: + # Define local dependency with relative path + some_local_component: + path: ../../projects/component + +For detailed information about the manifest file format, see the `Manifest File Format Documentation `_. Disabling the Component Manager ===============================