mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/translate_ble_mesh_and_reproducible_builds' into 'master'
docs: Provide translation for ble-mesh and reproducible-builds Closes DOC-7553 See merge request espressif/esp-idf!30001
This commit is contained in:
Shen Meng Jing
commit
4166acb69c
@ -1,13 +1,15 @@
|
||||
ESP-BLE-MESH Feature List
|
||||
=========================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Supported Features
|
||||
------------------
|
||||
|
||||
Mesh Core
|
||||
"""""""""
|
||||
|
||||
* Provisioning:
|
||||
* Provisioning
|
||||
* PB-ADV, PB-GATT and PB-Remote
|
||||
* OOB Authentication
|
||||
* Certificate-based Provisioning
|
||||
@ -130,8 +132,8 @@ Mesh Models
|
||||
* Light LC Server
|
||||
* Light LC Setup Server
|
||||
|
||||
Mesh Applications
|
||||
"""""""""""""""""
|
||||
Mesh Examples
|
||||
"""""""""""""
|
||||
|
||||
* ESP-BLE-MESH Node
|
||||
* :example_file:`Tutorial <bluetooth/esp_ble_mesh/onoff_models/onoff_client/tutorial/BLE_Mesh_Node_OnOff_Client_Example_Walkthrough.md>`
|
||||
@ -149,18 +151,3 @@ Mesh Applications
|
||||
* :example_file:`Tutorial <bluetooth/esp_ble_mesh/wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>`
|
||||
* :example:`Example <bluetooth/esp_ble_mesh/wifi_coexist>`
|
||||
* `Demo Video <https://dl.espressif.com/BLE/public/ESP_BLE_MESH_WIFI_Coexistence.mp4>`__
|
||||
|
||||
|
||||
Future Release Features
|
||||
-----------------------
|
||||
|
||||
Mesh Core
|
||||
"""""""""
|
||||
|
||||
* Provisioner NVS Storage
|
||||
|
||||
Mesh Applications
|
||||
"""""""""""""""""
|
||||
|
||||
* Fast OTA
|
||||
* Friendship
|
||||
|
||||
@ -1,12 +1,14 @@
|
||||
Reproducible Builds
|
||||
===================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
ESP-IDF build system has support for `reproducible builds`_.
|
||||
ESP-IDF build system has support for `reproducible builds <https://reproducible-builds.org/docs/definition/>`_.
|
||||
|
||||
When reproducible builds are enabled, the application built with ESP-IDF does not depend on the build environment. Both the .elf file and .bin files of the application remains exactly the same, even if the following variables change:
|
||||
When reproducible builds are enabled, the application built with ESP-IDF does not depend on the build environment. Both the ``.elf`` file and ``.bin`` files of the application remains exactly the same, even if the following variables change:
|
||||
|
||||
- Directory where the project is located
|
||||
- Directory where ESP-IDF is located (``IDF_PATH``)
|
||||
@ -53,13 +55,15 @@ Reproducible Builds and Debugging
|
||||
|
||||
When reproducible builds are enabled, file names included in debug information sections are altered as shown in the previous section. Due to this fact, the debugger (GDB) is not able to locate the source files for the given code location.
|
||||
|
||||
This issue can be solved using GDB ``set substitute-path`` command. For example, by adding the following command to GDB init script, the altered paths can be reverted to the original ones::
|
||||
This issue can be solved using GDB ``set substitute-path`` command. For example, by adding the following command to GDB init script, the altered paths can be reverted to the original ones.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
set substitute-path /COMPONENT_FREERTOS_DIR /home/user/esp/esp-idf/components/freertos
|
||||
|
||||
ESP-IDF build system generates a file with the list of such ``set substitute-path`` commands automatically during the build process. The file is called ``prefix_map_gdbinit`` and is located in the project ``build`` directory.
|
||||
|
||||
When :ref:`idf.py gdb <jtag-debugging-with-idf-py>` is used to start debugging, this additional gdbinit file is automatically passed to GDB. When launching GDB manually or from and IDE, please pass this additional gdbinit script to GDB using ``-x build/prefix_map_gdbinit`` argument.
|
||||
When :ref:`idf.py gdb <jtag-debugging-with-idf-py>` is used to start debugging, this additional ``gdbinit`` file is automatically passed to GDB. When launching GDB manually or from IDE, please pass this additional ``gdbinit`` script to GDB using ``-x build/prefix_map_gdbinit`` argument.
|
||||
|
||||
Factors Which Still Affect Reproducible Builds
|
||||
----------------------------------------------
|
||||
@ -70,6 +74,3 @@ Note that the built application still depends on:
|
||||
- Versions of the build tools (CMake, Ninja) and the cross-compiler
|
||||
|
||||
:doc:`tools/idf-docker-image` can be used to ensure that these factors do not affect the build.
|
||||
|
||||
|
||||
.. _reproducible builds: https://reproducible-builds.org/docs/definition/
|
||||
|
||||
@ -1 +1,153 @@
|
||||
.. include:: ../../../en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst
|
||||
ESP-BLE-MESH 功能列表
|
||||
=====================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
支持的功能
|
||||
----------
|
||||
|
||||
Mesh 核心
|
||||
"""""""""
|
||||
|
||||
* 入网
|
||||
* PB-ADV，PB-GATT，PB-Remote
|
||||
* OOB 验证
|
||||
* 基于证书的入网
|
||||
* 远程入网
|
||||
* 增强入网验证
|
||||
|
||||
* 网络
|
||||
* 中继
|
||||
* 分包和重组
|
||||
* 密钥更新程序
|
||||
* IV 更新程序
|
||||
* 朋友节点
|
||||
* 低功耗节点
|
||||
* 代理服务器
|
||||
* 代理客户端
|
||||
* 定向转发
|
||||
* 私有信标
|
||||
* 子网桥
|
||||
* 次要增强
|
||||
|
||||
* 多个客户端模型同时运行
|
||||
* 支持多个客户端模型同时向不同节点发送数据包
|
||||
* 客户端模型与服务器模型之间无阻塞
|
||||
|
||||
* NVS 存储
|
||||
* 存储 ESP-BLE-MESH 节点的入网和配置信息
|
||||
|
||||
Mesh 模型
|
||||
"""""""""
|
||||
|
||||
* 基础模型
|
||||
* 配置服务器模型
|
||||
* 配置客户端模型
|
||||
* 健康服务器模型
|
||||
* 健康客户端模型
|
||||
* 远程供应服务器模型
|
||||
* 远程供应客户端模型
|
||||
* 定向转发配置服务器模型
|
||||
* 定向转发配置客户端模型
|
||||
* 桥接配置服务器模型
|
||||
* 桥接配置客户端模型
|
||||
* Mesh 专用信标服务器模型
|
||||
* Mesh 专用信标客户端模型
|
||||
* 按需提供的专用代理服务器模型
|
||||
* 按需提供的专用代理客户端模型
|
||||
* SAR 配置服务器模型
|
||||
* SAR 配置客户端模型
|
||||
* 请求 PDU RPL 配置服务器模型
|
||||
* 请求 PDU RPL 配置客户端模型
|
||||
* 操作码聚合器服务器模型
|
||||
* 操作码聚合器客户端模型
|
||||
* 大型合成数据服务器模型
|
||||
* 大型合成数据客户端模型
|
||||
|
||||
* 通用客户端模型
|
||||
* 通用开关客户端
|
||||
* 通用电平客户端
|
||||
* 通用默认过渡时间客户端
|
||||
* 通用电源开关客户端
|
||||
* 通用功率电平客户端
|
||||
* 通用电池客户端
|
||||
* 通用位置客户端
|
||||
* 通用属性客户端
|
||||
|
||||
* 传感器客户端模型
|
||||
* 传感器客户端
|
||||
|
||||
* 时间与场景客户端模型
|
||||
* 时间客户端
|
||||
* 场景客户端
|
||||
* 调度器客户端
|
||||
|
||||
* 照明客户端模型
|
||||
* 灯光亮度客户端
|
||||
* 灯光 CTL 客户端
|
||||
* 灯光 HSL 客户端
|
||||
* 灯光 xyL 客户端
|
||||
* 灯光 LC 客户端
|
||||
|
||||
* 通用服务器模型
|
||||
* 通用开关服务器
|
||||
* 通用电平服务器
|
||||
* 通用默认过渡时间服务器
|
||||
* 通用电源开关服务器
|
||||
* 通用电源开关设置服务器
|
||||
* 通用功率电平服务器
|
||||
* 通用功率电平设置服务器
|
||||
* 通用电池服务器
|
||||
* 通用位置服务器
|
||||
* 通用位置设置服务器
|
||||
* 通用用户属性服务器
|
||||
* 通用管理员属性服务器
|
||||
* 通用制造商属性服务器
|
||||
* 通用客户端属性服务器
|
||||
|
||||
* 传感器服务器模型
|
||||
* 传感器服务器
|
||||
* 传感器设置服务器
|
||||
|
||||
* 时间和场景服务器模型
|
||||
* 时间服务器
|
||||
* 时间设置服务器
|
||||
* 场景服务器
|
||||
* 场景设置服务器
|
||||
* 调度器服务器
|
||||
* 调度器设置服务器
|
||||
|
||||
* 照明服务器模型
|
||||
* 灯光亮度服务器
|
||||
* 灯光亮度设置服务器
|
||||
* 灯光 CTL 服务器
|
||||
* 灯光 CTL 温度服务器
|
||||
* 灯光 CTL 设置服务器
|
||||
* 灯光 HSL 服务器
|
||||
* 灯光 HSL 色调服务器
|
||||
* 灯光 HSL 饱和度服务器
|
||||
* 灯光 HSL 设置服务器
|
||||
* 灯光 xyL 服务器
|
||||
* 灯光 xyL 设置服务器
|
||||
* 灯光 LC 服务器
|
||||
* 灯光 LC 设置服务器
|
||||
|
||||
Mesh 示例
|
||||
"""""""""""
|
||||
|
||||
* ESP-BLE-MESH 节点
|
||||
* :example_file:`教程 <bluetooth/esp_ble_mesh/onoff_models/onoff_client/tutorial/BLE_Mesh_Node_OnOff_Client_Example_Walkthrough.md>`
|
||||
* :example_file:`教程 <bluetooth/esp_ble_mesh/onoff_models/onoff_server/tutorial/BLE_Mesh_Node_OnOff_Server_Example_Walkthrough.md>`
|
||||
* :example:`示例 <bluetooth/esp_ble_mesh/onoff_models>`
|
||||
* ESP-BLE-MESH 供应者
|
||||
* :example_file:`教程 <bluetooth/esp_ble_mesh/provisioner/tutorial/BLE_Mesh_Provisioner_Example_Walkthrough.md>`
|
||||
* :example:`示例 <bluetooth/esp_ble_mesh/provisioner>`
|
||||
* ESP-BLE-MESH 快速入网
|
||||
* :example_file:`客户端模型快速入网教程 <bluetooth/esp_ble_mesh/fast_provisioning/fast_prov_client/tutorial/BLE_Mesh_Fast_Prov_Client_Example_Walkthrough.md>`
|
||||
* :example_file:`服务器模型快速入网教程 <bluetooth/esp_ble_mesh/fast_provisioning/fast_prov_server/tutorial/BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md>`
|
||||
* :example:`示例 <bluetooth/esp_ble_mesh/fast_provisioning>`
|
||||
* `演示视频 <https://dl.espressif.com/BLE/public/ESP32_BLE_Mesh_Fast_Provision.mp4>`__
|
||||
* ESP-BLE-MESH 及 Wi-Fi 共存
|
||||
* :example_file:`教程 <bluetooth/esp_ble_mesh/wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>`
|
||||
* :example:`示例 <bluetooth/esp_ble_mesh/wifi_coexist>`
|
||||
* `演示视频 <https://dl.espressif.com/BLE/public/ESP_BLE_MESH_WIFI_Coexistence.mp4>`__
|
||||
|
||||
@ -1 +1,76 @@
|
||||
.. include:: ../../en/api-guides/reproducible-builds.rst
|
||||
可重复构建
|
||||
==========
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
简介
|
||||
----
|
||||
|
||||
ESP-IDF 构建系统支持 `可重复构建 <https://reproducible-builds.org/docs/definition/>`_。
|
||||
|
||||
启用可重复构建后，使用 ESP-IDF 构建的应用程序不再依赖构建环境。即使以下变量发生变化，应用程序的 ``.elf`` 文件和 ``.bin`` 文件仍然保持不变：
|
||||
|
||||
- 项目所在目录
|
||||
- ESP-IDF 所在目录 (``IDF_PATH``)
|
||||
- 构建时间
|
||||
|
||||
构建不可重复的原因
|
||||
------------------
|
||||
|
||||
即便使用相同的源代码和工具版本，以下几个原因依旧可能导致应用程序依赖构建环境：
|
||||
|
||||
- 在 C 代码中， ``__FILE__`` 预处理器宏展开为源文件的完整路径。
|
||||
- ``__DATE__`` 和 ``__TIME__`` 预处理器宏展开为编译日期和时间。
|
||||
- 当编译器生成目标文件时，会添加调试信息。这些信息能帮助 GDB 等调试器定位与机器代码中特定位置相对应的源代码，且通常包含相关源文件的路径。这些路径可能是绝对路径，并且包括前往 ESP-IDF 或项目的路径。
|
||||
|
||||
此外，输入顺序的不稳定性、构建系统的不确定性等因素也可能导致应用程序依赖构建环境。
|
||||
|
||||
在 ESP-IDF 中启用可重复构建
|
||||
---------------------------
|
||||
|
||||
启用 :ref:`CONFIG_APP_REPRODUCIBLE_BUILD` 选项，可在 ESP-IDF 中实现可重复构建。
|
||||
|
||||
此选项默认处于禁用状态，可在 ``menuconfig`` 中启用。
|
||||
|
||||
也可以将该选项添加到 ``sdkconfig.defaults`` 中，并删除 ``sdkconfig`` 文件、重新运行构建。更多信息，请参阅 :ref:`custom-sdkconfig-defaults`。
|
||||
|
||||
如何实现可重复构建
|
||||
------------------
|
||||
|
||||
ESP-IDF 可通过以下方式实现可重复构建：
|
||||
|
||||
- 在启用可重复构建时，ESP-IDF 的源代码不使用 ``__DATE__`` 和 ``__TIME__`` 宏。请注意，如果应用程序源代码使用了这些宏，则构建将无法重复。
|
||||
- ESP-IDF 构建系统传递一组 ``-fmacro-prefix-map`` 和 ``-fdebug-prefix-map`` 标志，并用占位符替换基本路径：
|
||||
|
||||
- 替换 ESP-IDF 的路径为 ``/IDF``
|
||||
- 替换项目路径为 ``/IDF_PROJECT``
|
||||
- 替换构建目录的路径为 ``/IDF_BUILD``
|
||||
- 替换组件路径为 ``/COMPONENT_NAME_DIR`` （其中 ``NAME`` 指的是组件的名称）
|
||||
|
||||
- 如果启用 :ref:`CONFIG_APP_REPRODUCIBLE_BUILD`，则不会将构建日期和时间包括在 :ref:`应用程序元数据结构 <app-image-format-application-description>` 和 :ref:`引导加载程序元数据结构 <image-format-bootloader-description>` 中。
|
||||
- ESP-IDF 构建系统在将源文件列表、组件列表和其他序列传递给 CMake 之前会对其进行排序。构建系统的其他各个部分，如链接器脚本生成器，也会先排序，从而确保无论环境如何，输出都一致。
|
||||
|
||||
可重复构建与调试
|
||||
----------------
|
||||
|
||||
如前文所述，启用可重复构建时，调试信息部分中包含的文件名会被更改。因此，调试器 (GDB) 无法定位给定代码位置的源文件。
|
||||
|
||||
可以使用 GDB 的 ``set substitute-path`` 命令来解决这个问题。例如，添加以下命令到 GDB 初始化脚本中，可以将更改后的路径恢复为原始路径。
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
set substitute-path /COMPONENT_FREERTOS_DIR /home/user/esp/esp-idf/components/freertos
|
||||
|
||||
ESP-IDF 构建系统在构建过程中会自动生成一个包含 ``set substitute-path`` 命令列表的文件。该文件名为 ``prefix_map_gdbinit``，位于项目 ``build`` 目录中。
|
||||
|
||||
当使用 :ref:`idf.py gdb <jtag-debugging-with-idf-py>` 开始调试时，此额外的 ``gdbinit`` 文件会自动传递给 GDB。当手动启动 GDB 或从 IDE 启动 GDB 时，请使用 ``-x build/prefix_map_gdbinit`` 参数将此额外的 ``gdbinit`` 脚本传递给 GDB。
|
||||
|
||||
仍可能影响可重复构建的因素
|
||||
--------------------------
|
||||
|
||||
请注意，构建应用程序还依赖于：
|
||||
|
||||
- ESP-IDF 版本
|
||||
- 构建工具 (CMake, Ninja) 及交叉编译器的版本
|
||||
|
||||
:doc:`tools/idf-docker-image` 可避免这些因素影响构建。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user