mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Docs: provide CN translation for the rest docs of api-guides/tools
This commit is contained in:
Cai Xin Ying
morris
parent
c9adbe13d8
commit
9684acc482
@ -1,8 +1,10 @@
|
||||
**************
|
||||
IDF Clang Tidy
|
||||
**************
|
||||
******************
|
||||
ESP-IDF Clang-Tidy
|
||||
******************
|
||||
|
||||
The IDF Clang Tidy is a tool that uses `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`_ to run static analysis on your current app.
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The ESP-IDF Clang Tidy is a tool that uses `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__ to run static analysis on your current app.
|
||||
|
||||
.. warning::
|
||||
|
||||
@ -12,22 +14,22 @@ The IDF Clang Tidy is a tool that uses `clang-tidy <https://clang.llvm.org/extra
|
||||
|
||||
.. warning::
|
||||
|
||||
This tool does not support RISC-V based chips yet. For now, we don't provide clang based toolchain for RISC-V.
|
||||
This tool does not support RISC-V based chips yet. For now, we do not provide clang based toolchain for RISC-V.
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
If you have never run this tool before, take the following steps to get this tool prepared.
|
||||
|
||||
#. Run the export scripts (``export.sh`` / ``export.bat`` / ... ) to set up the environment variables.
|
||||
#. Run the export scripts (``export.sh``, ``export.bat``, or others) to set up the environment variables.
|
||||
#. Run ``pip install --upgrade pyclang`` to install this plugin. The extra commands would be activated in ``idf.py`` automatically.
|
||||
#. Run ``idf_tools.py install esp-clang`` to install the clang-tidy required binaries
|
||||
|
||||
.. note::
|
||||
|
||||
This toolchain is still under development. After the final release, you don't have to install them manually.
|
||||
This toolchain is still under development. After the final release, you do not have to install them manually.
|
||||
|
||||
#. Get file from the `llvm repository <https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/tool/run-clang-tidy.py>`_ and add the folder of this script to the ``$PATH``. Or you could pass an optional argument ``--run-clang-tidy-py`` later when you call ``idf.py clang-check``. Please don't forget to make the script executable.
|
||||
#. Get the file from the `llvm repository <https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/tool/run-clang-tidy.py>`__ and add the folder of this script to the ``$PATH``. Or you could pass an optional argument ``--run-clang-tidy-py`` later when you call ``idf.py clang-check``. Please do not forget to make the script executable.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -54,4 +56,4 @@ Run ``idf.py clang-check --help`` to see the full documentation.
|
||||
Bug Report
|
||||
==========
|
||||
|
||||
This tool is hosted in `espressif/clang-tidy-runner <https://github.com/espressif/clang-tidy-runner>`_. If you faced any bugs or have any feature request, please report them via `github issues <https://github.com/espressif/clang-tidy-runner/issues>`_.
|
||||
This tool is hosted in `espressif/clang-tidy-runner <https://github.com/espressif/clang-tidy-runner>`__. If you were to face any bugs or have any feature request, please report them via `Github issues <https://github.com/espressif/clang-tidy-runner/issues>`__
|
||||
|
||||
@ -1,59 +1,61 @@
|
||||
*********************
|
||||
IDF Component Manager
|
||||
*********************
|
||||
*************************
|
||||
ESP-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 <https://components.espressif.com>`_ or from a git repository.
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
A list of components can be found on `<https://components.espressif.com/>`_
|
||||
The ESP-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 <https://components.espressif.com>`__ or from a Git repository.
|
||||
|
||||
For detailed information about the IDF Component Manager, see the `IDF Component Manager and ESP Component Registry Documentation <https://docs.espressif.com/projects/idf-component-manager/en/latest/>`_.
|
||||
A list of components can be found on `<https://components.espressif.com/>`__.
|
||||
|
||||
Using With a Project
|
||||
For detailed information about the ESP-IDF Component Manager, see the `ESP-IDF Component Manager and ESP Component Registry Documentation <https://docs.espressif.com/projects/idf-component-manager/en/latest/>`__.
|
||||
|
||||
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 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:
|
||||
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, a manifest file is created for the main component. You can explicitly either specify the directory where the manifest should be created using the ``--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``
|
||||
- ``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 ``my_component`` directory
|
||||
|
||||
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.
|
||||
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``. The build will then track changes in ``idf_component.yml`` manifests and automatically trigger 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 <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/versioning.html>`_). 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:
|
||||
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 ESP-IDF Component Manager that ``my_component`` depends on. It is defined in the 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 <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/versioning.html>`__. By default, dependencies are added to the main component. You can either explicitly specify a directory where the manifest is located using the ``--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``
|
||||
- ``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 ``my_component`` directory
|
||||
|
||||
.. note::
|
||||
|
||||
The command ``add-dependency`` adds dependencies to your project explicitly from the `Espressif Component Registry <https://components.espressif.com/>`_.
|
||||
The command ``add-dependency`` adds dependencies to your project explicitly from the `Espressif Component Registry <https://components.espressif.com/>`__.
|
||||
|
||||
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``.
|
||||
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.
|
||||
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.
|
||||
It is not necessary to have a manifest for components that do not need any managed dependencies.
|
||||
|
||||
When CMake configures the project (e.g. ``idf.py reconfigure``) component manager does a few things:
|
||||
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
|
||||
- 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``
|
||||
The lock file ``dependencies.lock`` and the content of the ``managed_components`` directory are not supposed to be modified by a user. When the component manager runs, it always makes sure they are up to date. If these files were accidentally modified, it is possible to re-run the component manager by triggering CMake with ``idf.py reconfigure``.
|
||||
|
||||
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.
|
||||
You may set the 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.
|
||||
|
||||
Creating Project From an Example
|
||||
================================
|
||||
Creating a 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 <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/versioning.html>`_) 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 <https://components.espressif.com/>`_.
|
||||
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 <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/versioning.html>`__) 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 <https://components.espressif.com/>`__.
|
||||
|
||||
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 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:
|
||||
|
||||
@ -63,12 +65,12 @@ You can define a dependency from the registry by specifying the component name a
|
||||
# Define a dependency from the registry (https://components.espressif.com/component/example/cmp)
|
||||
example/cmp: ">=1.0.0"
|
||||
|
||||
To define a dependency from a git repository, provide the path to the component within the repository and the repository's URL:
|
||||
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
|
||||
# Define a dependency from a Git repository
|
||||
test_component:
|
||||
path: test_component
|
||||
git: ssh://git@gitlab.com/user/components.git
|
||||
@ -82,9 +84,9 @@ During the development of components, you can use components from a local direct
|
||||
some_local_component:
|
||||
path: ../../projects/component
|
||||
|
||||
For detailed information about the manifest file format, see the `Manifest File Format Documentation <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/manifest_file.html>`_.
|
||||
For detailed information about the manifest file format, see `Manifest File Format Documentation <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/manifest_file.html>`__.
|
||||
|
||||
Disabling the Component Manager
|
||||
===============================
|
||||
|
||||
The component manager can be explicitly disabled by setting ``IDF_COMPONENT_MANAGER`` environment variable to ``0``.
|
||||
The component manager can be explicitly disabled by setting the ``IDF_COMPONENT_MANAGER`` environment variable to ``0``.
|
||||
|
||||
@ -1,38 +1,40 @@
|
||||
IDF Windows Installer
|
||||
=====================
|
||||
ESP-IDF Windows Installer
|
||||
=========================
|
||||
|
||||
Command-line parameters
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Command-Line Parameters
|
||||
-----------------------
|
||||
|
||||
Windows Installer `esp-idf-tools-setup` provides the following command-line parameters:
|
||||
Windows Installer ``esp-idf-tools-setup`` provides the following command-line parameters:
|
||||
|
||||
* ``/CONFIG=[PATH]`` - Path to ``ini`` configuration file to override default configuration of the installer. Default: ``config.ini``.
|
||||
* ``/GITCLEAN=[yes|no]`` - Perform git clean and remove untracked directories in Offline mode installation. Default: yes.
|
||||
* ``/GITRECURSIVE=[yes|no]`` - Clone recursively all git repository submodules. Default: yes
|
||||
* ``/GITREPO=[URL|PATH]`` - URL of repository to clone ESP-IDF. Default: https://github.com/espressif/esp-idf.git
|
||||
* ``/GITRESET=[yes|no]`` - Enable/Disable git reset of repository during installation. Default: yes.
|
||||
* ``/GITCLEAN=[yes|no]`` - Perform ``git clean`` and remove untracked directories in offline-mode installation. Default: ``yes``.
|
||||
* ``/GITRECURSIVE=[yes|no]`` - Clone recursively all Git repository submodules. Default: yes.
|
||||
* ``/GITREPO=[URL|PATH]`` - URL of repository to clone ESP-IDF. Default: ``https://github.com/espressif/esp-idf.git``.
|
||||
* ``/GITRESET=[yes|no]`` - Enable/Disable ``git reset`` of repository during installation. Default: ``yes``.
|
||||
* ``/HELP`` - Display command line options provided by Inno Setup installer.
|
||||
* ``/IDFDIR=[PATH]`` - Path to directory where it will be installed. Default: ``{userdesktop}\esp-idf}``
|
||||
* ``/IDFVERSION=[v4.3|v4.1|master]`` - Use specific IDF version. E.g. v4.1, v4.2, master. Default: empty, pick the first version in the list.
|
||||
* ``/IDFVERSIONSURL=[URL]`` - Use URL to download list of IDF versions. Default: https://dl.espressif.com/dl/esp-idf/idf_versions.txt
|
||||
* ``/LOG=[PATH]`` - Store installation log file in specific directory. Default: empty.
|
||||
* ``/OFFLINE=[yes|no]`` - Execute installation of Python packages by PIP in offline mode. The same result can be achieved by setting the environment variable PIP_NO_INDEX. Default: no.
|
||||
* ``/USEEMBEDDEDPYTHON=[yes|no]`` - Use Embedded Python version for the installation. Set to ``no`` to allow Python selection screen in the installer. Default: yes.
|
||||
* ``/PYTHONNOUSERSITE=[yes|no]`` - Set PYTHONNOUSERSITE variable before launching any Python command to avoid loading Python packages from AppData\Roaming. Default: yes.
|
||||
* ``/PYTHONWHEELSURL=[URL]`` - Specify URLs to PyPi repositories for resolving binary Python Wheel dependencies. The same result can be achieved by setting the environment variable PIP_EXTRA_INDEX_URL. Default: https://dl.espressif.com/pypi
|
||||
* ``/SKIPSYSTEMCHECK=[yes|no]`` - Skip System Check page. Default: no.
|
||||
* ``/IDFDIR=[PATH]`` - Path to directory where it is installed. Default: ``{userdesktop}\esp-idf}``.
|
||||
* ``/IDFVERSION=[v4.3|v4.1|master]`` - Use specific ESP-IDF version. E.g., v4.1, v4.2, master. Default: ``empty``, pick the first version in the list.
|
||||
* ``/IDFVERSIONSURL=[URL]`` - Use URL to download list of ESP-IDF versions. Default: ``https://dl.espressif.com/dl/esp-idf/idf_versions.txt``.
|
||||
* ``/LOG=[PATH]`` - Store installation log file in specific directory. Default: ``empty``.
|
||||
* ``/OFFLINE=[yes|no]`` - Execute installation of Python packages by ``pip`` in offline mode. The same result can be achieved by setting the environment variable ``PIP_NO_INDEX``. Default: ``no``.
|
||||
* ``/USEEMBEDDEDPYTHON=[yes|no]`` - Use Embedded Python version for the installation. Set to ``no`` to allow the Python selection screen in the installer. Default: ``yes``.
|
||||
* ``/PYTHONNOUSERSITE=[yes|no]`` - Set ``PYTHONNOUSERSITE`` variable before launching any Python command to avoid loading Python packages from AppData\Roaming. Default: ``yes``.
|
||||
* ``/PYTHONWHEELSURL=[URL]`` - Specify URLs to PyPi repositories for resolving binary Python Wheel dependencies. The same result can be achieved by setting the environment variable ``PIP_EXTRA_INDEX_URL``. Default: ``https://dl.espressif.com/pypi``.
|
||||
* ``/SKIPSYSTEMCHECK=[yes|no]`` - Skip System Check page. Default: ``no``.
|
||||
* ``/VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL`` - Perform silent installation.
|
||||
|
||||
Unattended installation
|
||||
Unattended Installation
|
||||
-----------------------
|
||||
|
||||
The unattended installation of IDF can be achieved by following command-line parameters:
|
||||
The unattended installation of ESP-IDF can be achieved by following command-line parameters:
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL
|
||||
|
||||
The installer detaches its process from the command-line. Waiting for installation to finish could be achieved by following PowerShell script:
|
||||
When running the installer from the command line, it detaches its process from the command line and starts a separate process in the background to perform the installation without blocking the use of the command line. The following PowerShell script allows you to wait for the installer to complete:
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
@ -40,12 +42,12 @@ The installer detaches its process from the command-line. Waiting for installati
|
||||
$InstallerProcess = Get-Process esp-idf-tools-setup
|
||||
Wait-Process -Id $InstallerProcess.id
|
||||
|
||||
Custom Python and custom location of Python wheels
|
||||
Custom Python and Custom Location of Python Wheels
|
||||
--------------------------------------------------
|
||||
|
||||
The IDF installer is using by default embedded Python with reference to Python Wheel mirror.
|
||||
The ESP-IDF installer is using by default embedded Python with reference to the Python Wheel mirror.
|
||||
|
||||
Following parameters allows to select custom Python and custom location of Python wheels:
|
||||
The following parameters allow to select custom Python and custom location of Python wheels:
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
|
||||
@ -1 +1,59 @@
|
||||
.. include:: ../../../en/api-guides/tools/idf-clang-tidy.rst
|
||||
******************
|
||||
ESP-IDF clang-tidy
|
||||
******************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
ESP-IDF clang-tidy 是使用 `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__ 对当前应用程序进行静态分析的工具。
|
||||
|
||||
.. warning::
|
||||
|
||||
ESP-IDF clang-tidy 的功能及其依赖的工具链尚在开发中，最终版本发布前可能有重大变更。
|
||||
|
||||
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV
|
||||
|
||||
.. warning::
|
||||
|
||||
当前工具尚不支持基于 RISC-V 的芯片。目前，乐鑫尚未针对 RISC-V 提供基于 clang 的工具链。
|
||||
|
||||
准备工作
|
||||
=============
|
||||
|
||||
初次运行此工具时，请按照以下步骤准备该工具：
|
||||
|
||||
#. 运行导出脚本（如 ``export.sh``、``export.bat`` 等），设置环境变量。
|
||||
#. 运行 ``pip install --upgrade pyclang`` 安装插件，其他命令将在 ``idf.py`` 中自动激活。
|
||||
#. 运行 ``idf_tools.py install esp-clang`` 安装 clang-tidy 所需的二进制文件。
|
||||
|
||||
.. note::
|
||||
|
||||
该工具链尚在开发中，最终版本发布后，将无需手动安装工具链。
|
||||
|
||||
#. 从 `llvm 仓库 <https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/tool/run-clang-tidy.py>`__ 获取文件，并将该脚本所在的文件夹添加到 ``$PATH`` 中，或在调用 ``idf.py clang-check`` 时传递可选参数 ``--run-clang-tidy-py``。请将脚本设置为可执行。
|
||||
|
||||
.. note::
|
||||
|
||||
在未来工具链版本中，该文件将一并捆绑。目前为临时解决方案。
|
||||
|
||||
#. 再次运行导出脚本（如 ``export.sh``、``export.bat`` 等），刷新环境变量。
|
||||
|
||||
其他命令
|
||||
==============
|
||||
|
||||
``clang-check``
|
||||
---------------
|
||||
|
||||
运行 ``idf.py clang-check`` 可以重新生成编译数据库，并在当前项目文件夹下运行 ``clang-tidy``，所得输出写入 ``<project_dir>/warnings.txt``。
|
||||
|
||||
运行 ``idf.py clang-check --help`` 查看完整文档。
|
||||
|
||||
``clang-html-report``
|
||||
---------------------
|
||||
|
||||
#. 运行 ``pip install codereport`` 安装附加依赖关系。
|
||||
#. 运行 ``idf.py clang-html-report`` 会根据 ``warnings.txt`` 在 ``<project_dir>/html_report`` 文件夹内生成 HTML 报告。请在浏览器中打开 ``<project_dir>/html_report/index.html`` 查看报告。
|
||||
|
||||
错误报告
|
||||
==========
|
||||
|
||||
此工具托管在 `espressif/clang-tidy-runner <https://github.com/espressif/clang-tidy-runner>`__。如遇到任何错误，或有任何功能请求，请通过 `Github issues <https://github.com/espressif/clang-tidy-runner/issues>`__ 提交报告。
|
||||
|
||||
@ -1 +1,92 @@
|
||||
.. include:: ../../../en/api-guides/tools/idf-component-manager.rst
|
||||
*************************
|
||||
ESP-IDF 组件管理器
|
||||
*************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
ESP-IDF 组件管理器工具用于下载 ESP-IDF CMake 项目的依赖项，该下载在 CMake 运行期间自动完成。ESP-IDF 组件管理器可以从 `组件注册表 <https://components.espressif.com>`__ 或 Git 仓库获取组件。
|
||||
|
||||
要获取组件列表，请参阅 `<https://components.espressif.com/>`__.
|
||||
|
||||
有关 ESP-IDF 组件管理器的详细信息，请参阅 `ESP-IDF 组件管理器及 ESP 组件注册表文档 <https://docs.espressif.com/projects/idf-component-manager/en/latest/>`__。
|
||||
|
||||
在项目中使用 ESP-IDF 组件管理器
|
||||
===================================
|
||||
|
||||
项目中各组件的依赖项定义在单独的清单文件中，命名为 ``idf_component.yml``，位于组件根目录。运行 ``idf.py create-manifest`` 可以为组件创建清单文件模板。默认情况下将为 main 组件创建清单文件。使用 ``--path`` 选项，可以显式指定创建清单文件的目录路径。使用 ``--component=my_component`` 选项可以指定组件名称，这样系统将会在 ``components`` 文件夹下为该组件创建清单文件。``create-manifest`` 命令支持以下运行方式：
|
||||
|
||||
- ``idf.py create-manifest`` 为 main 组件创建清单文件
|
||||
- ``idf.py create-manifest --component=my_component`` 在 ``components`` 目录下，为组件 **my_component** 创建清单文件
|
||||
- ``idf.py create-manifest --path="../../my_component"`` 在 ``my_component`` 目录下，为组件 **my_component** 创建清单文件
|
||||
|
||||
在向项目的某个组件添加新的清单时，必须先运行 ``idf.py reconfigure``，手动重新配置项目。随后，构建过程将跟踪 ``idf_component.yml`` 清单的变更，并在必要时自动触发 CMake。
|
||||
|
||||
要为 ESP-IDF 项目中的组件（如 ``my_component``）添加依赖项，可以运行命令 ``idf.py add-dependency DEPENDENCY``。``DEPENDENCY`` 参数代表一个由 ESP-IDF 组件管理器管理的额外组件，而 ``my_component`` 也依赖于这个组件。``DEPENDENCY`` 参数的格式为 ``namespace/name=1.0.0``，`namespace/name` 代表组件名称，`=1.0.0` 是组件的版本范围，详情请参阅 `版本文档 <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/versioning.html>`__。默认情况下，依赖项会添加到 main 组件。通过使用 ``--path`` 选项，可以显式指定包含清单的目录，也可以使用 ``--component=my_component``，在 ``components`` 文件夹中指定组件。``add-dependency`` 命令支持以下运行方式：
|
||||
|
||||
- ``idf.py add-dependency example/cmp`` 为 main 组件添加依赖项，依赖项为 ``example/cmp`` 的最新版本
|
||||
- ``idf.py add-dependency --component=my_component example/cmp<=3.3.3`` 将依赖项添加到位于 ``components`` 目录下名为 ``my_component`` 的组件中，依赖项为版本号 ``<=3.3.3`` 的 ``example/cmp``
|
||||
- ``idf.py add-dependency --path="../../my_component" example/cmp^3.3.3`` 将依赖项添加到位于目录 ``my_component`` 下名为 ``my_component`` 的组件中，依赖项为版本号 ``^3.3.3`` 的 ``example/cmp``
|
||||
|
||||
.. note::
|
||||
|
||||
``add-dependency`` 命令会从 `乐鑫组件注册表 <https://components.espressif.com/>`__ 将依赖项显式添加到你的项目中。
|
||||
|
||||
要更新 ESP-IDF 项目的依赖项，请运行命令 ``idf.py update-dependencies``。你也可以使用 ``--project-dir PATH`` 选项，指定项目目录的路径。
|
||||
|
||||
应用程序示例 :example:`build_system/cmake/component_manager` 使用了由组件管理器安装的组件。
|
||||
|
||||
对于不需要受管理依赖项的组件，则无需提供清单文件。
|
||||
|
||||
在 CMake 配置项目（如 ``idf.py reconfigure``）时，组件管理器会执行以下操作：
|
||||
|
||||
- 处理项目中每个组件的 ``idf_component.yml`` 清单，并递归解析依赖项。
|
||||
- 在项目根目录中创建 ``dependencies.lock`` 文件，包含完整的依赖项列表。
|
||||
- 将所有依赖项下载至 ``managed_components`` 目录。
|
||||
|
||||
请勿更改 ``dependencies.lock`` 锁文件和 ``managed_components`` 目录的内容。组件管理器运行时，会始终确保这些文件处于最新状态。如果意外修改了这些文件，可以通过使用 ``idf.py reconfigure`` 触发 CMake，重新运行组件管理器。
|
||||
|
||||
设置构建属性 ``DEPENDENCIES_LOCK`` 可以指定顶层 CMakeLists.txt 文件中的锁文件路径。例如，在 ``project(PROJECT_NAME)`` 前添加 ``idf_build_set_property(DEPENDENCIES_LOCK dependencies.lock.${IDF_TARGET})``，可以为不同目标生成不同锁文件。
|
||||
|
||||
从示例创建项目
|
||||
================================
|
||||
|
||||
组件注册表中，部分组件包含示例项目。要从示例创建一个新项目，可以运行命令 ``idf.py create-project-from-example EXAMPLE``。``EXAMPLE`` 参数格式为 ``namespace/name=1.0.0:example``，`namespace/name` 代表组件名称，`=1.0.0` 是组件的版本范围（详情请参阅 `版本文档 <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/versioning.html>`__），而 `example` 代表示例名称。在 `乐鑫组件注册表 <https://components.espressif.com/>`__ 中，可以找到各组件的示例列表，以及启动组件示例的相应命令。
|
||||
|
||||
在清单文件中定义依赖项
|
||||
=====================================
|
||||
|
||||
通过在文本编辑器直接编辑，你可以轻松定义清单文件 ``idf_component.yml`` 中的依赖项。以下是有关定义依赖项的简单示例：
|
||||
|
||||
你可以通过指定组件名称和版本范围，定义来自注册表的依赖项：
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
dependencies:
|
||||
# 定义来自注册表 (https://components.espressif.com/component/example/cmp) 的依赖项
|
||||
example/cmp: ">=1.0.0"
|
||||
|
||||
要从 Git 仓库定义依赖关系，请提供组件在仓库中的路径和仓库的 URL：
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
dependencies:
|
||||
# 从 Git 仓库定义依赖项
|
||||
test_component:
|
||||
path: test_component
|
||||
git: ssh://git@gitlab.com/user/components.git
|
||||
|
||||
在开发组件时，可以通过指定相对或绝对路径，使用本地目录中的组件：
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
dependencies:
|
||||
# 通过相对路径定义本地依赖项
|
||||
some_local_component:
|
||||
path: ../../projects/component
|
||||
|
||||
有关清单文件格式的详细信息，请参阅 `清单文件格式文档 <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/manifest_file.html>`__。
|
||||
|
||||
禁用组件管理器
|
||||
===============================
|
||||
|
||||
将环境变量 ``IDF_COMPONENT_MANAGER`` 设置为 ``0``，可以显式禁用组件管理器。
|
||||
|
||||
@ -1 +1,54 @@
|
||||
.. include:: ../../../en/api-guides/tools/idf-windows-installer.rst
|
||||
ESP-IDF Windows 安装程序
|
||||
===========================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
命令行参数
|
||||
----------
|
||||
|
||||
ESP-IDF Windows 安装程序 ``esp-idf-tools-setup`` 提供以下命令行参数：
|
||||
|
||||
* ``/CONFIG=[PATH]`` - 指定 ``ini`` 配置文件的路径，覆盖安装程序的默认配置。默认值：``config.ini``。
|
||||
* ``/GITCLEAN=[yes|no]`` - 在以离线模式安装时，执行 ``git clean`` 命令，并删除未跟踪的目录。默认值：``yes``。
|
||||
* ``/GITRECURSIVE=[yes|no]`` - 递归克隆所有 Git 仓库子模块。默认值：``yes``。
|
||||
* ``/GITREPO=[URL|PATH]`` - 指定克隆 ESP-IDF 仓库的 URL。默认值：``https://github.com/espressif/esp-idf.git``。
|
||||
* ``/GITRESET=[yes|no]`` - 在安装过程中，启用或禁用对仓库的 ``git reset`` 操作。默认值：``yes``。
|
||||
* ``/HELP`` - 显示 Inno Setup 安装程序提供的命令行选项。
|
||||
* ``/IDFDIR=[PATH]`` - 指定安装目录的路径。默认值：``{userdesktop}\esp-idf}``。
|
||||
* ``/IDFVERSION=[v4.3|v4.1|master]`` - 使用指定的 ESP-IDF 版本，如 v4.1、v4.2、master。默认值：``empty``，选取列表中的第一个版本。
|
||||
* ``/IDFVERSIONSURL=[URL]`` - 使用 URL 下载 ESP-IDF 版本列表。默认值：``https://dl.espressif.com/dl/esp-idf/idf_versions.txt``。
|
||||
* ``/LOG=[PATH]`` - 在指定目录中存储安装日志文件。默认值：``empty``。
|
||||
* ``/OFFLINE=[yes|no]`` - 在离线模式下，使用 ``pip`` 执行。通过设置环境变量 ``PIP_NO_INDEX``，也可在离线模式下安装 Python 软件包。默认值：``no``。
|
||||
* ``/USEEMBEDDEDPYTHON=[yes|no]`` - 使用嵌入式 Python 版本完成安装。将此参数设置为 ``no``，可以在安装程序中选择 Python 版本。默认值：``yes``。
|
||||
* ``/PYTHONNOUSERSITE=[yes|no]`` - 在启动任意 Python 命令前，设置 ``PYTHONNOUSERSITE`` 变量，避免从 AppData\Roaming 加载 Python 软件包。默认值：``yes``。
|
||||
* ``/PYTHONWHEELSURL=[URL]`` - 指定 PyPi 存储库的 URL，以解析二进制 Python Wheel 依赖关系。设置环境变量 ``PIP_EXTRA_INDEX_URL`` 可以实现相同效果。默认值：``https://dl.espressif.com/pypi``。
|
||||
* ``/SKIPSYSTEMCHECK=[yes|no]`` - 跳过系统检查页面。默认值：``no``。
|
||||
* ``/VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL`` - 执行静默安装。
|
||||
|
||||
静默安装
|
||||
--------
|
||||
|
||||
通过设置以下命令行参数，可以静默安装 ESP-IDF：
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL
|
||||
|
||||
在命令行中运行安装程序时，它会在后台启动一个独立的进程执行安装操作，而不会阻塞命令行的使用。通过以下 PowerShell 脚本可以等待安装程序完成：
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL
|
||||
$InstallerProcess = Get-Process esp-idf-tools-setup
|
||||
Wait-Process -Id $InstallerProcess.id
|
||||
|
||||
自定义 Python 版本及 Python Wheel 位置
|
||||
--------------------------------------------------
|
||||
|
||||
ESP-IDF 安装程序默认使用嵌入的 Python 版本，并参考预定义的 Python Wheel 镜像获取所需软件包。
|
||||
|
||||
以下参数支持自定义 Python 版本及 Python Wheel 位置：
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
esp-idf-tools-setup-x.x.exe /USEEMBEDDEDPYTHON=no /PYTHONWHEELSURL=https://pypi.org/simple/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user