mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: udpate CN translation for readme and build-system
This commit is contained in:
daiziyan
daiziyan
parent
dec3db6913
commit
ca57e121e2
@ -56,6 +56,7 @@
|
|||||||
/CONTRIBUTING.md @esp-idf-codeowners/docs
|
/CONTRIBUTING.md @esp-idf-codeowners/docs
|
||||||
/Kconfig @esp-idf-codeowners/build-config
|
/Kconfig @esp-idf-codeowners/build-config
|
||||||
/README*.md @esp-idf-codeowners/docs
|
/README*.md @esp-idf-codeowners/docs
|
||||||
|
/SUPPORT_POLICY*.md @esp-idf-codeowners/docs
|
||||||
/add_path.sh @esp-idf-codeowners/tools
|
/add_path.sh @esp-idf-codeowners/tools
|
||||||
/conftest.py @esp-idf-codeowners/ci
|
/conftest.py @esp-idf-codeowners/ci
|
||||||
/export.* @esp-idf-codeowners/tools
|
/export.* @esp-idf-codeowners/tools
|
||||||
|
|||||||
23
README_CN.md
23
README_CN.md
@ -4,18 +4,25 @@
|
|||||||
|
|
||||||
ESP-IDF 是乐鑫官方推出的物联网开发框架，支持 Windows、Linux 和 macOS 操作系统。
|
ESP-IDF 是乐鑫官方推出的物联网开发框架，支持 Windows、Linux 和 macOS 操作系统。
|
||||||
|
|
||||||
|
# ESP-IDF 版本支持期限
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- 请参考 [ESP-IDF 支持政策](SUPPORT_POLICY_CN.md) 以及 [相关文档](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/versions.html) 了解更多关于 ESP-IDF 版本的信息。
|
||||||
|
- 请参考 [ESP-IDF 版本停止维护 (EOL) 公告](https://www.espressif.com/zh-hans/support/documents/advisories?keys=&field_type_of_advisory_tid%5B%5D=817)。
|
||||||
|
|
||||||
# ESP-IDF 与乐鑫芯片
|
# ESP-IDF 与乐鑫芯片
|
||||||
|
|
||||||
下表总结了乐鑫芯片在 ESP-IDF 各版本中的支持状态，其中 ![alt text][supported] 代表已支持，![alt text][preview] 代表目前处于预览支持状态。预览支持状态通常有时间限制，而且仅适用于测试版芯片。请确保使用与芯片相匹配的 ESP-IDF 版本。
|
下表总结了乐鑫芯片在 ESP-IDF 各版本中的支持状态，其中 ![alt text][supported] 代表已支持，![alt text][preview] 代表目前处于预览支持状态。预览支持状态通常有时间限制，而且仅适用于测试版芯片。请确保使用与芯片相匹配的 ESP-IDF 版本。
|
||||||
|
|
||||||
| 芯片 | v3.3 | v4.1 | v4.2 | v4.3 | v4.4 | v5.0 | |
|
|芯片 | v4.1 | v4.2 | v4.3 | v4.4 | v5.0 | |
|
||||||
|:----------- |:---------------------: | :---------------------:| :---------------------:| :---------------------:| :---------------------:| :---------------------:|:---------------------------------------------------------- |
|
|:----------- |:---------------------:| :---------------------:| :---------------------:| :---------------------:| :---------------------:|:------------------------------------------------------------------------------------ |
|
||||||
|ESP32 | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | |
|
|ESP32 |![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | |
|
||||||
|ESP32-S2 | | | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | |
|
|ESP32-S2 | | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | |
|
||||||
|ESP32-C3 | | | | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | |
|
|ESP32-C3 | | | ![alt text][supported] | ![alt text][supported] | ![alt text][supported] | |
|
||||||
|ESP32-S3 | | | | | ![alt text][supported] | ![alt text][supported] | [芯片发布公告](https://www.espressif.com/en/news/ESP32_S3) |
|
|ESP32-S3 | | | | ![alt text][supported] | ![alt text][supported] | [芯片发布公告](https://www.espressif.com/en/news/ESP32_S3) |
|
||||||
|ESP32-C2 | | | | | | ![alt text][supported] | |
|
|ESP32-C2 | | | | | ![alt text][supported] | [芯片发布公告](https://blog.espressif.com/esp32-c2-and-why-it-matter-s-bcf4d7d0b2c6) |
|
||||||
|ESP32-H2 | | | | | ![alt text][preview] | ![alt text][preview] | [芯片发布公告](https://www.espressif.com/en/news/ESP32_H2) |
|
|ESP32-H2 | | | | ![alt text][preview] | ![alt text][preview] | [芯片发布公告](https://www.espressif.com/en/news/ESP32_H2) |
|
||||||
|
|
||||||
[supported]: https://img.shields.io/badge/-%E6%94%AF%E6%8C%81-green "supported"
|
[supported]: https://img.shields.io/badge/-%E6%94%AF%E6%8C%81-green "supported"
|
||||||
[preview]: https://img.shields.io/badge/-%E9%A2%84%E8%A7%88-orange "preview"
|
[preview]: https://img.shields.io/badge/-%E9%A2%84%E8%A7%88-orange "preview"
|
||||||
|
|||||||
@ -5,12 +5,9 @@ Support Period Policy
|
|||||||
|
|
||||||
* [中文版](./SUPPORT_POLICY_CN.md)
|
* [中文版](./SUPPORT_POLICY_CN.md)
|
||||||
|
|
||||||
Each ESP-IDF major and minor release (V4.1, V4.2, etc) is supported for
|
Each ESP-IDF major and minor release (V4.1, V4.2, etc) is supported for 30 months after the initial stable release date.
|
||||||
30 months after the initial stable release date.
|
|
||||||
|
|
||||||
Supported means that the ESP-IDF team will continue to apply bug fixes,
|
Supported means that the ESP-IDF team will continue to apply bug fixes, security fixes, etc to the release branch on GitHub, and periodically make new bugfix releases as needed.
|
||||||
security fixes, etc to the release branch on GitHub, and periodically
|
|
||||||
make new bugfix releases as needed.
|
|
||||||
|
|
||||||
Support period is divided into "Service" and "Maintenance" period:
|
Support period is divided into "Service" and "Maintenance" period:
|
||||||
|
|
||||||
@ -19,58 +16,36 @@ Support period is divided into "Service" and "Maintenance" period:
|
|||||||
| Service | 12 months | Yes |
|
| Service | 12 months | Yes |
|
||||||
| Maintenance | 18 months | No |
|
| Maintenance | 18 months | No |
|
||||||
|
|
||||||
During the Service period, bugfixes releases are more frequent. In some cases,
|
During the Service period, bugfixes releases are more frequent. In some cases, support for new features may be added during the Service period (this is reserved for features which are needed to meet particular regulatory requirements or standards for new products, and which carry a very low risk of introducing regressions.)
|
||||||
support for new features may be added during the Service period (this is
|
|
||||||
reserved for features which are needed to meet particular regulatory
|
|
||||||
requirements or standards for new products, and which carry a very low risk of
|
|
||||||
introducing regressions.)
|
|
||||||
|
|
||||||
During the Maintenance period, the version is still supported but only bugfixes
|
During the Maintenance period, the version is still supported but only bugfixes for high severity issues or security issues will be applied.
|
||||||
for high severity issues or security issues will be applied.
|
|
||||||
|
|
||||||
Using an “In Service” version is recommended when starting a new project.
|
Using an “In Service” version is recommended when starting a new project.
|
||||||
|
|
||||||
Users are encouraged to upgrade all projects to a newer ESP-IDF release before
|
Users are encouraged to upgrade all projects to a newer ESP-IDF release before the support period finishes and the release becomes End of Life (EOL). It is our policy to not continue fixing bugs in End of Life releases.
|
||||||
the support period finishes and the release becomes End of Life (EOL). It is our
|
|
||||||
policy to not continue fixing bugs in End of Life releases.
|
|
||||||
|
|
||||||
Pre-release versions (betas, previews, `-rc` and `-dev` versions, etc)
|
Pre-release versions (betas, previews, `-rc` and `-dev` versions, etc) are not covered by any support period. Sometimes a particular feature is marked as "Preview" in a release, which means it is also not covered by the support period.
|
||||||
are not covered by any support period. Sometimes a particular feature is
|
|
||||||
marked as "Preview" in a release, which means it is also not covered
|
|
||||||
by the support period.
|
|
||||||
|
|
||||||
ESP-IDF should be used in an up-to-date software environment. The operating system
|
ESP-IDF should be used in an up-to-date software environment. The operating system and other third-party tools should be supported by their maintainers. ESP-IDF cannot keep compatibility with unsupported third-party tools.
|
||||||
and other third-party tools should be supported by their maintainers.
|
|
||||||
ESP-IDF cannot keep compatibility with unsupported third-party tools.
|
|
||||||
|
|
||||||
The ESP-IDF Programming Guide has information about the
|
The ESP-IDF Programming Guide has information about the [different versions of ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/latest/versions.html) (major, minor, bugfix, etc).
|
||||||
[different versions of ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/latest/versions.html)
|
|
||||||
(major, minor, bugfix, etc).
|
|
||||||
|
|
||||||
Example
|
Example
|
||||||
-------
|
-------
|
||||||
|
|
||||||
ESP-IDF V3.3 was released in September 2019. It will be supported for 30 months
|
ESP-IDF V3.3 was released in September 2019. It was supported for 30 months until February 2022.
|
||||||
until February 2022.
|
|
||||||
|
|
||||||
- The first V3.3 release was `v3.3` in September 2019.
|
- The first V3.3 release was `v3.3` in September 2019.
|
||||||
- The ESP-IDF team continues to backport bug fixes, security fixes,
|
- The ESP-IDF team continues to backport bug fixes, security fixes, etc to the release branch `release/v3.3`.
|
||||||
etc to the release branch `release/v3.3`.
|
- Periodically stable bugfix releases are created from the release branch. For example `v3.3.1`, `v3.3.2`, etc. Users are encouraged to always update to the latest bugfix release.
|
||||||
- Periodically stable bugfix releases are created from the release
|
- V3.3 bugfix releases continue until February 2022, when all V3.3.x releases become End of Life.
|
||||||
branch. For example `v3.3.1`, `v3.3.2`, etc. Users are encouraged to
|
|
||||||
always update to the latest bugfix release.
|
|
||||||
- V3.3 bugfix releases continue until February 2022, when all V3.3.x
|
|
||||||
releases become End of Life.
|
|
||||||
|
|
||||||
Existing Releases
|
Existing Releases
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
ESP-IDF release V4.1 and all newer releases will follow this support period
|
ESP-IDF release V4.1 and all newer releases will follow this support period policy. The support period for each release will be announced when the release is made.
|
||||||
policy. The support period for each release will be announced when the release
|
|
||||||
is made.
|
|
||||||
|
|
||||||
For releases made before the current support period policy was announced, the
|
For releases made before the current support period policy was announced, the original support periods apply:
|
||||||
original support periods apply:
|
|
||||||
|
|
||||||
* ESP-IDF V4.0.x will be supported until October 2021
|
* ESP-IDF V4.0.x will be supported until October 2021
|
||||||
* ESP-IDF V3.3.x will be supported until February 2022
|
* ESP-IDF V3.3.x will be supported until February 2022
|
||||||
@ -79,8 +54,5 @@ original support periods apply:
|
|||||||
Policy History
|
Policy History
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
* September 2019. This policy split ESP-IDF releases into Standard and Long Term
|
* September 2019. This policy splits ESP-IDF releases into Standard and Long Term Support.
|
||||||
Support.
|
* July 2020. All releases from now will have the same support period, which is equal to the previous Long Term Support period. Added “In Service” period, during which versions will receive more updates.
|
||||||
* July 2020. All releases from now will have the same support period, which is
|
|
||||||
equal to the previous Long Term Support period. Added “In Service” period,
|
|
||||||
during which versions will receive more updates.
|
|
||||||
|
|||||||
@ -3,6 +3,8 @@
|
|||||||
支持期限政策
|
支持期限政策
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
|
* [英文版](./SUPPORT_POLICY.md)
|
||||||
|
|
||||||
ESP-IDF 的每个主要版本和次要版本（如 V4.1、V4.2 等）自其首次稳定版本发布之日起将支持 30 个月。
|
ESP-IDF 的每个主要版本和次要版本（如 V4.1、V4.2 等）自其首次稳定版本发布之日起将支持 30 个月。
|
||||||
|
|
||||||
支持意味着 ESP-IDF 团队将会对 GitHub 上的发布分支继续进行 bug 修复、安全修补等，并根据需求定期发布新的 bugfix 版本。
|
支持意味着 ESP-IDF 团队将会对 GitHub 上的发布分支继续进行 bug 修复、安全修补等，并根据需求定期发布新的 bugfix 版本。
|
||||||
@ -24,6 +26,8 @@ ESP-IDF 的每个主要版本和次要版本（如 V4.1、V4.2 等）自其首
|
|||||||
|
|
||||||
《支持期限政策》不适用于预发布版本（包括 beta、preview、-rc 和 -dev 版本等）。有时，在发布的版本中存在被标记为 "Preview" 的特定功能，则该功能也不在支持期限内。
|
《支持期限政策》不适用于预发布版本（包括 beta、preview、-rc 和 -dev 版本等）。有时，在发布的版本中存在被标记为 "Preview" 的特定功能，则该功能也不在支持期限内。
|
||||||
|
|
||||||
|
请确保在最新的软件环境中使用 ESP-IDF。操作系统和其他第三方工具应得到其维护者的支持。ESP-IDF 无法兼容不受支持的第三方工具。
|
||||||
|
|
||||||
有关 [ESP-IDF 不同版本](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/versions.html)（主要版本、次要版本、bugfix 版本等）信息，可参阅《ESP-IDF 编程指南》。
|
有关 [ESP-IDF 不同版本](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/versions.html)（主要版本、次要版本、bugfix 版本等）信息，可参阅《ESP-IDF 编程指南》。
|
||||||
|
|
||||||
示例
|
示例
|
||||||
@ -45,11 +49,10 @@ ESP-IDF V4.1 及所有后续更新版本都将遵守该《支持期限政策》
|
|||||||
|
|
||||||
* ESP-IDF V4.0.x 将支持至 2021 年 10 月。
|
* ESP-IDF V4.0.x 将支持至 2021 年 10 月。
|
||||||
* ESP-IDF V3.3.x 将支持至 2022 年 2 月。
|
* ESP-IDF V3.3.x 将支持至 2022 年 2 月。
|
||||||
* ESP-IDF V3.1.x 和 V3.2.x 都将在 2020 年 10 月停止支持。
|
* ESP-IDF v3.3 之前的版本已经停止支持。
|
||||||
* ESP-IDF v3.1.x 之前的版本已经停止支持。
|
|
||||||
|
|
||||||
政策历史
|
政策历史
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
* 2019 年 9 月。该政策将 ESP-IDF 版本发布分为标准支持版本和长期支持版本。
|
* 2019 年 9 月。该政策将 ESP-IDF 版本发布分为标准支持版本和长期支持版本。
|
||||||
* 2020 年 7 月。从现在开始，所有发布的版本都将有相同的支持周期，等同于之前的长期支持周期。新增了”服务周期“，期间版本的更新将较为频繁。
|
* 2020 年 7 月。从现在开始，所有发布的版本都将有相同的支持周期，即之前的长期支持周期。新增了”服务周期“，期间版本的更新将较为频繁。
|
||||||
|
|||||||
@ -313,7 +313,7 @@ There are other arguments that can be passed to ``idf_component_register``. Thes
|
|||||||
|
|
||||||
See `example component requirements`_ and `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples.
|
See `example component requirements`_ and `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples.
|
||||||
|
|
||||||
.. _component variables:
|
.. _preset_component_variables:
|
||||||
|
|
||||||
Preset Component Variables
|
Preset Component Variables
|
||||||
--------------------------
|
--------------------------
|
||||||
@ -692,7 +692,7 @@ Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions
|
|||||||
Example Component CMakeLists
|
Example Component CMakeLists
|
||||||
============================
|
============================
|
||||||
|
|
||||||
Because the build environment tries to set reasonable defaults that will work most of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality.
|
Because the build environment tries to set reasonable defaults that will work most of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `preset_component_variables`_ is usually required for some functionality.
|
||||||
|
|
||||||
Here are some more advanced examples of component CMakeLists files.
|
Here are some more advanced examples of component CMakeLists files.
|
||||||
|
|
||||||
|
|||||||
@ -50,83 +50,10 @@ idf.py
|
|||||||
``idf.py`` 命令行工具提供了一个前端，可以帮助您轻松管理项目的构建过程，它管理了以下工具：
|
``idf.py`` 命令行工具提供了一个前端，可以帮助您轻松管理项目的构建过程，它管理了以下工具：
|
||||||
|
|
||||||
- CMake_，配置待构建的项目
|
- CMake_，配置待构建的项目
|
||||||
- 命令行构建工具（Ninja_ 或 `GNU Make`）
|
- Ninja_，用于构建项目
|
||||||
- `esptool.py`_，烧录目标硬件设备
|
- `esptool.py`_，烧录目标硬件设备
|
||||||
|
|
||||||
:ref:`入门指南 <get-started-configure>` 简要介绍了如何设置 ``idf.py`` 用于配置、构建并烧录项目。
|
可通过 ``idf.py`` 配置构建系统，具体可参考 :doc:`相关文档 <tools/idf-py>`。
|
||||||
|
|
||||||
``idf.py`` 应运行在 ESP-IDF 的 ``项目`` 目录下，即包含 ``CMakeLists.txt`` 文件的目录。仅包含 Makefile 的老式项目并不支持 ``idf.py``。
|
|
||||||
|
|
||||||
运行 ``idf.py --help`` 查看完整的命令列表。下面总结了最常用的命令：
|
|
||||||
|
|
||||||
- ``idf.py set-target <target>`` 会设置构建项目的目标（芯片）。请参考 `选择目标芯片`_。
|
|
||||||
- ``idf.py menuconfig`` 会运行 ``menuconfig`` 工具来配置项目。
|
|
||||||
- ``idf.py build`` 会构建在当前目录下找到的项目，它包括以下步骤：
|
|
||||||
|
|
||||||
- 根据需要创建 ``build`` 构建目录，它用于保存构建过程的输出文件，可以使用 ``-B`` 选项修改默认的构建目录。
|
|
||||||
- 根据需要运行 CMake_ 来配置项目，为主构建工具生成构建文件。
|
|
||||||
- 运行主构建工具（Ninja_ 或 `GNU Make`）。默认情况下，构建工具会被自动检测，可以使用 ``-G`` 选项显式地指定构建工具。
|
|
||||||
|
|
||||||
构建过程是增量式的，如果自上次构建以来源文件或项目配置没有发生改变，则不会执行任何操作。
|
|
||||||
|
|
||||||
- ``idf.py clean`` 会把构建输出的文件从构建目录中删除，从而清理整个项目。下次构建时会强制“重新完整构建”这个项目。清理时，不会删除 CMake 配置输出及其他文件。
|
|
||||||
- ``idf.py fullclean`` 会将整个 ``build`` 目录下的内容全部删除，包括所有 CMake 的配置输出文件。下次构建项目时，CMake 会从头开始配置项目。请注意，该命令会递归删除构建目录下的 *所有文件*，请谨慎使用。项目配置文件不会被删除。
|
|
||||||
- ``idf.py flash`` 会在必要时自动构建项目，并将生成的二进制程序烧录进目标 {IDF_TARGET_NAME} 设备中。``-p`` 和 ``-b`` 选项可分别设置串口的设备名和烧录时的波特率。
|
|
||||||
- ``idf.py monitor`` 用于显示目标 {IDF_TARGET_NAME} 设备的串口输出。``-p`` 选项可用于设置主机端串口的设备名，按下 ``Ctrl-]`` 可退出监视器。更多有关监视器的详情，请参阅 :doc:`tools/idf-monitor`。
|
|
||||||
|
|
||||||
多个 ``idf.py`` 命令可合并成一个，例如，``idf.py -p COM4 clean flash monitor`` 会依次清理源码树，构建项目，烧录进目标 {IDF_TARGET_NAME} 设备，最后运行串口监视器。
|
|
||||||
|
|
||||||
对于 ``idf.py`` 不知道的指令，``idf.py`` 会尝试将其作为构建系统的目标来执行。
|
|
||||||
|
|
||||||
``idf.py`` 命令支持 bash、 zsh 以及 fish shell 的 `自动补全 <https://click.palletsprojects.com/shell-completion/>`_。
|
|
||||||
|
|
||||||
要实现实现 shell `自动补全 <https://click.palletsprojects.com/shell-completion/>`_，请先确保您安装了 Python 3.5 以及 `click <https://click.palletsprojects.com/>`_ 7.1 及以上版本（:ref:`请参考这里 <get-started-get-prerequisites>`)。
|
|
||||||
|
|
||||||
使用 ``export`` 命令来启用 ``idf.py`` 的自动补全功能（:ref:`请参考这里 <get-started-set-up-env>`）。按 TAB 键可实现自动补全。输入 “idf.py -” 后按 TAB 键可自动补全选项。
|
|
||||||
|
|
||||||
未来我们也会支持 PowerShell 的自动补全功能。
|
|
||||||
|
|
||||||
.. 注解:: 环境变量 ``ESPPORT`` 和 ``ESPBAUD`` 可分别用来设置 ``-p`` 和 ``-b`` 选项的默认值。在命令行中，重新为这两个选项赋值，会覆盖其默认值。
|
|
||||||
|
|
||||||
高级命令
|
|
||||||
^^^^^^^^
|
|
||||||
|
|
||||||
- ``idf.py app``，``idf.py bootloader``，``idf.py partition-table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。
|
|
||||||
- ``idf.py app-flash`` 等匹配命令，仅将项目的特定部分烧录至 {IDF_TARGET_NAME}。
|
|
||||||
- ``idf.py -p PORT erase-flash`` 会使用 esptool.py 擦除 {IDF_TARGET_NAME} 的整个 Flash。
|
|
||||||
- ``idf.py size`` 会打印应用程序相关的大小信息，``size-components`` 和 ``size-files`` 这两个命令相似，分别用于打印每个组件或源文件的详细信息。如果您在运行 CMake（或 ``idf.py``）时定义了变量 ``-DOUTPUT_JSON=1``，那么输出的格式会变成 JSON 而不是可读文本。详情请查看 ``idf.py-size``。
|
|
||||||
- ``idf.py reconfigure`` 命令会重新运行 CMake_ （即便无需重新运行）。正常使用时，并不需要运行此命令，但当源码树中添加/删除文件后或更改 CMake cache 变量时，此命令会非常有用，例如，``idf.py -DNAME='VALUE' reconfigure`` 会将 CMake cache 中的变量 ``NAME`` 的值设置为 ``VALUE``。
|
|
||||||
- ``idf.py python-clean`` 会从 IDF 目录中删除生成的 Python 字节码，Python 字节码可能会在切换 IDF 和 Python 版本时引发问题，因此建议在切换 Python 后运行该命令。
|
|
||||||
- ``idf.py docs`` 将在浏览器中直接打开项目目标芯片和对应版本的文档链接。请使用 ``idf.py docs --help`` 查看所有选项。
|
|
||||||
|
|
||||||
同时调用多个 ``idf.py`` 命令时，命令的输入顺序并不重要，它们会按照正确的顺序依次执行，并保证每一条命令都生效（即先构建后烧录，先擦除后烧录等）。
|
|
||||||
|
|
||||||
idf.py 选项
|
|
||||||
^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
运行 ``idf.py --help`` 命令列出所有根级选项。运行 ``idf.py <command> --help`` 命令列出针对某一子命令的选项，如 ``idf.py monitor --help``。下列是一些常用选项：
|
|
||||||
|
|
||||||
- ``-C <dir>`` 可用来从默认的当前工作目录覆盖项目目录。
|
|
||||||
- ``-B <dir>`` 可用来从项目目录默认的 ``build`` 子目录覆盖构建目录。
|
|
||||||
- ``--ccache`` 可用来在编译源文件时启用 CCache_，安装了 CCache_ 工具后可极大缩短编译时间。
|
|
||||||
|
|
||||||
请注意，一些旧版本的 CCache 在某些平台上可能会出现 bug，因此如果文件没有按预期重新构建，请尝试禁用 CCache 后再次构建。通过设置环境变量 ``IDF_CCACHE_ENABLE`` 为非零值，可以默认启用 CCache。
|
|
||||||
|
|
||||||
- ``-v`` 可以让 ``idf.py`` 和编译系统产生详细的编译输出，对于调试编译问题会非常有用。
|
|
||||||
- ``--cmake-warn-uninitialized``（或 ``-w``）会让 CMake 在项目目录内打印未初始化的变量警告（不包括在项目目录外的目录），这一选项只能控制 CMake 内部的 CMake 变量警告，不包括其它类型的编译警告。可以通过设置环境变量 ``IDF_CMAKE_WARN_UNINITIALIZED`` 为非零值，从而永久设置该选项。
|
|
||||||
|
|
||||||
开始新项目
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
运行 ``idf.py create-project`` 命令可以开始创建您的新项目，运行 ``idf.py create-project --help`` 命令获取更多相关信息。
|
|
||||||
|
|
||||||
例如：
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
idf.py create-project --path my_projects my_new_project
|
|
||||||
|
|
||||||
以上命令会直接在 my_projects 目录下创建一个名为 my_new_project 的新项目。
|
|
||||||
|
|
||||||
直接使用 CMake
|
直接使用 CMake
|
||||||
--------------
|
--------------
|
||||||
@ -386,19 +313,6 @@ ESP-IDF 在搜索所有待构建的组件时，会按照 ``COMPONENT_DIRS`` 指
|
|||||||
|
|
||||||
有关更完整的 ``CMakeLists.txt`` 示例，请参阅 `组件依赖示例`_ 和 `组件 CMakeLists 示例`_。
|
有关更完整的 ``CMakeLists.txt`` 示例，请参阅 `组件依赖示例`_ 和 `组件 CMakeLists 示例`_。
|
||||||
|
|
||||||
创建新组件
|
|
||||||
-------------
|
|
||||||
|
|
||||||
使用 ``idf.py create-component`` 命令创建新组件。 新组件将包含构建组件所需的一组文件。您可以将组件的头文件纳入到您的项目中，并使用其功能。请运行 ``idf.py create-component --help`` 命令获取更多信息。
|
|
||||||
|
|
||||||
示例:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
idf.py -C components create-component my_component
|
|
||||||
|
|
||||||
该示例将在当前工作目录下的子目录 components 中创建一个新的组件。更多关于组件的信息，请参考 :ref:`上文<component-directories>`。
|
|
||||||
|
|
||||||
.. _preset_component_variables:
|
.. _preset_component_variables:
|
||||||
|
|
||||||
预设的组件变量
|
预设的组件变量
|
||||||
@ -527,8 +441,8 @@ ESP-IDF 构建系统会在命令行中添加以下 C 预处理器定义：
|
|||||||
- engine.c
|
- engine.c
|
||||||
- include/ - engine.h
|
- include/ - engine.h
|
||||||
- spark_plug/ - CMakeLists.txt
|
- spark_plug/ - CMakeLists.txt
|
||||||
- plug.c
|
- spark_plug.c
|
||||||
- plug.h
|
- spark_plug.h
|
||||||
|
|
||||||
Car 组件
|
Car 组件
|
||||||
^^^^^^^^^
|
^^^^^^^^^
|
||||||
@ -1051,43 +965,10 @@ Flash 参数
|
|||||||
构建 Bootloader
|
构建 Bootloader
|
||||||
===============
|
===============
|
||||||
|
|
||||||
引导程序默认作为 ``idf.py build`` 的一部分被构建，也可以通过 ``idf.py bootloader`` 来单独构建。
|
|
||||||
|
|
||||||
引导程序是 :idf:`/components/bootloader/subproject` 内部独特的“子项目”，它有自己的项目 CMakeLists.txt 文件，能够构建独立于主项目的 ``.ELF`` 和 ``.BIN`` 文件，同时它又与主项目共享配置和构建目录。
|
引导程序是 :idf:`/components/bootloader/subproject` 内部独特的“子项目”，它有自己的项目 CMakeLists.txt 文件，能够构建独立于主项目的 ``.ELF`` 和 ``.BIN`` 文件，同时它又与主项目共享配置和构建目录。
|
||||||
|
|
||||||
子项目通过 :idf_file:`/components/bootloader/project_include.cmake` 文件作为外部项目插入到项目的顶层，主构建进程会运行子项目的 CMake，包括查找组件（主项目使用的组件的子集），生成引导程序专用的配置文件（从主 ``sdkconfig`` 文件中派生）。
|
子项目通过 :idf_file:`/components/bootloader/project_include.cmake` 文件作为外部项目插入到项目的顶层，主构建进程会运行子项目的 CMake，包括查找组件（主项目使用的组件的子集），生成引导程序专用的配置文件（从主 ``sdkconfig`` 文件中派生）。
|
||||||
|
|
||||||
..
|
|
||||||
Label removed here because of the conflict with the english docs restructuring.
|
|
||||||
When translating please follow the structure in the english docs.
|
|
||||||
|
|
||||||
选择目标芯片
|
|
||||||
====================
|
|
||||||
|
|
||||||
ESP-IDF 支持多款芯片，运行 `idf.py --list-targets` 可以查看当前 ESP-IDF 版本中支持目标的完整列表。
|
|
||||||
|
|
||||||
在构建项目前，请首先根据您的芯片选择正确的软件目标，具体命令为 ``idf.py set-target <target>``。举例 ::
|
|
||||||
|
|
||||||
idf.py set-target esp32s2
|
|
||||||
|
|
||||||
.. important::
|
|
||||||
|
|
||||||
运行 ``idf.py set-target`` 命令将清除 ``build`` 文件夹的内容，并重新生成一个 ``sdkconfig`` 文件。之前的 ``sdkconfig`` 将另存为 ``sdkconfig.old``。
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
运行 ``idf.py set-target`` 命令相当于分别运行以下几个命令：
|
|
||||||
|
|
||||||
1. 清除 ``build`` 文件夹 (``idf.py fullclean``)
|
|
||||||
2. 移除 ``sdkconfig`` 文件 (``mv sdkconfig sdkconfig.old``)
|
|
||||||
3. 根据选择的“目标”芯片配置项目 (``idf.py -DIDF_TARGET=esp32 reconfigure``)
|
|
||||||
|
|
||||||
您也可以将要用的 ``IDF_TARGET`` 设置为环境变量，比如：``export IDF_TARGET=esp32s2``；或设置为 CMake 变量，比如将 ``-DIDF_TARGET=esp32s2`` 以参数形式传递给 CMake 或 idf.py。如果您大多数时间仅使用一款芯片，则将 ``IDF_TARGET`` 配置为环境变量比较方便。
|
|
||||||
|
|
||||||
对于特定项目，您可以使用以下方式为 ``IDF_TARGET`` 配置 _default_ 值：把 ``CONFIG_IDF_TARGET`` 的值加入 ``sdkconfig.defaults``。举例而言，配置 ``CONFIG_IDF_TARGET="esp32s2"``。这样一来，除非特别设置（比如使用环境变量、CMake 变量或 ``idf.py set-target`` 命令），否则 ``IDF_TARGET`` 将默认采用 ``CONFIG_IDF_TARGET``。
|
|
||||||
|
|
||||||
如果您从未通过以上述任何方式配置过“目标”芯片，则构建系统会默认将 ``esp32`` 设定为“目标”芯片。
|
|
||||||
|
|
||||||
.. _write-pure-component:
|
.. _write-pure-component:
|
||||||
|
|
||||||
编写纯 CMake 组件
|
编写纯 CMake 组件
|
||||||
@ -1344,7 +1225,8 @@ idf 组件命令
|
|||||||
[EMBED_FILES file1 file2 ...]
|
[EMBED_FILES file1 file2 ...]
|
||||||
[EMBED_TXTFILES file1 file2 ...]
|
[EMBED_TXTFILES file1 file2 ...]
|
||||||
[KCONFIG kconfig]
|
[KCONFIG kconfig]
|
||||||
[KCONFIG_PROJBUILD kconfig_projbuild])
|
[KCONFIG_PROJBUILD kconfig_projbuild]
|
||||||
|
[WHOLE_ARCHIVE])
|
||||||
|
|
||||||
将一个组件注册到构建系统中。就像 ``project()`` CMake 命令一样，该命令应该直接从组件的 CMakeLists.txt 中调用（而不是通过函数或宏），且建议在其他命令之前调用该命令。下面是一些关于在 ``idf_component_register`` 之前 *不能* 调用哪些命令的指南：
|
将一个组件注册到构建系统中。就像 ``project()`` CMake 命令一样，该命令应该直接从组件的 CMakeLists.txt 中调用（而不是通过函数或宏），且建议在其他命令之前调用该命令。下面是一些关于在 ``idf_component_register`` 之前 *不能* 调用哪些命令的指南：
|
||||||
|
|
||||||
@ -1366,6 +1248,7 @@ idf 组件命令
|
|||||||
- REQUIRED_IDF_TARGETS - 指定该组件唯一支持的目标。
|
- REQUIRED_IDF_TARGETS - 指定该组件唯一支持的目标。
|
||||||
- KCONFIG - 覆盖默认的 Kconfig 文件。
|
- KCONFIG - 覆盖默认的 Kconfig 文件。
|
||||||
- KCONFIG_PROJBUILD - 覆盖默认的 Kconfig.projbuild 文件。
|
- KCONFIG_PROJBUILD - 覆盖默认的 Kconfig.projbuild 文件。
|
||||||
|
- WHOLE_ARCHIVE - 如果指定了此参数，链接时会在组件库的前后分别添加 ``-Wl,--whole-archive`` 和 ``-Wl,--no-whole-archive``。这与设置 ``WHOLE_ARCHIVE`` 组件属性的效果一致。
|
||||||
|
|
||||||
以下内容用于 :ref:`将数据嵌入到组件中<cmake_embed_data>`，并在确定组件是否仅用于配置时被视为源文件。这意味着，即使组件没有指定源文件，如果组件指定了以下其中之一，仍然会在内部为组件创建一个静态库。
|
以下内容用于 :ref:`将数据嵌入到组件中<cmake_embed_data>`，并在确定组件是否仅用于配置时被视为源文件。这意味着，即使组件没有指定源文件，如果组件指定了以下其中之一，仍然会在内部为组件创建一个静态库。
|
||||||
|
|
||||||
@ -1401,6 +1284,7 @@ idf 组件属性
|
|||||||
- REQUIRED_IDF_TARGETS - 组件支持的目标列表；由 ``idf_component_register`` EMBED_TXTFILES 参数设置。
|
- REQUIRED_IDF_TARGETS - 组件支持的目标列表；由 ``idf_component_register`` EMBED_TXTFILES 参数设置。
|
||||||
- REQUIRES - 公共组件依赖关系列表；由 ``idf_component_register`` REQUIRES 参数设置。
|
- REQUIRES - 公共组件依赖关系列表；由 ``idf_component_register`` REQUIRES 参数设置。
|
||||||
- SRCS - 组件源文件列表；由 ``idf_component_register`` 的 SRCS 或 SRC_DIRS/EXCLUDE_SRCS 参数设置。
|
- SRCS - 组件源文件列表；由 ``idf_component_register`` 的 SRCS 或 SRC_DIRS/EXCLUDE_SRCS 参数设置。
|
||||||
|
- WHOLE_ARCHIVE - 如果该属性被设置为 ``TRUE`` （或是其他 CMake 布尔“真”值：1、``ON``、``YES``、``Y`` 等），链接时会在组件库的前后分别添加 ``-Wl,--whole-archive`` 和 ``-Wl,--no-whole-archive`` 选项。这可以强制链接器将每个目标文件包含到可执行文件中，即使该目标文件没有解析来自应用程序其余部分的任何引用。当组件中包含依赖链接时注册的插件或模块时，通常会使用该方法。默认情况下，此属性为 ``FALSE``。可以从组件的 CMakeLists.txt 文件中将其设置为 ``TRUE``。
|
||||||
|
|
||||||
.. _cmake-file-globbing:
|
.. _cmake-file-globbing:
|
||||||
|
|
||||||
@ -1616,4 +1500,3 @@ CMake 中不可用的功能
|
|||||||
.. _quirc: https://github.com/dlbeer/quirc
|
.. _quirc: https://github.com/dlbeer/quirc
|
||||||
.. _pyenv: https://github.com/pyenv/pyenv#readme
|
.. _pyenv: https://github.com/pyenv/pyenv#readme
|
||||||
.. _virtualenv: https://virtualenv.pypa.io/en/stable/
|
.. _virtualenv: https://virtualenv.pypa.io/en/stable/
|
||||||
.. _CCache: https://ccache.dev/
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user