Skip to content

Commit

Permalink
Merge branch 'docs/update_cn_trans_build_system' into 'master'
Browse files Browse the repository at this point in the history
Docs: Update CN trans for build-system.rst

Closes DOC-3758

See merge request espressif/esp-idf!20402
  • Loading branch information
suda-morris committed Oct 8, 2022
2 parents 8282dca + b03cc11 commit 7984552
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 3 deletions.
6 changes: 3 additions & 3 deletions docs/en/api-guides/build-system.rst
Original file line number Diff line number Diff line change
Expand Up @@ -654,7 +654,7 @@ Take care when adding configuration values in this file, as they will be include

``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".

Wrappers to redefine or extend existing functions
Wrappers to Redefine or Extend Existing Functions
-------------------------------------------------

Thanks to the linker's wrap feature, it is possible to redefine or extend the behavior of an existing ESP-IDF function. To do so, you will need to provide the following CMake declaration in your project's ``CMakeLists.txt`` file:
Expand All @@ -663,11 +663,11 @@ Thanks to the linker's wrap feature, it is possible to redefine or extend the be
target_link_libraries(${COMPONENT_LIB} INTERFACE "-Wl,--wrap=function_to_redefine")
Where ``function_to_redefine`` is the name of the function to redefine or extend. This option will let the linker replace all the calls to ``function_to_redefine`` functions in the binary libraries be changed to calls to ``__wrap_function_to_redefine`` function. Thus, you must define this new symbol in your application.
Where ``function_to_redefine`` is the name of the function to redefine or extend. This option will let the linker replace all the calls to ``function_to_redefine`` functions in the binary libraries with calls to ``__wrap_function_to_redefine`` function. Thus, you must define this new symbol in your application.

The linker will provide a new symbol named ``__real_function_to_redefine`` which points to the former implementation of the function to redefine. It can be called from the new implementation, making it an extension of the former one.

This mechanism is shown in the example :example:`build_system/wrappers`. Check its ``README.md`` for more details.
This mechanism is shown in the example :example:`build_system/wrappers`. Check :idf_file:`examples/build_system/wrappers/README.md` for more details.

.. _config_only_component:

Expand Down
15 changes: 15 additions & 0 deletions docs/zh_CN/api-guides/build-system.rst
Original file line number Diff line number Diff line change
Expand Up @@ -654,6 +654,21 @@ KConfig.projbuild

``project_include.cmake`` 文件在 ESP-IDF 内部使用,以定义项目范围内的构建功能,比如 ``esptool.py`` 的命令行参数和 ``bootloader`` 这个特殊的应用程序。

通过封装对现有函数进行重新定义或扩展
-------------------------------------

链接器具有封装功能,可以重新定义或扩展现有 ESP-IDF 函数的行为。如需封装函数,您需要在项目的 ``CMakeLists.txt`` 文件中提供以下 CMake 声明:

.. code-block:: cmake
target_link_libraries(${COMPONENT_LIB} INTERFACE "-Wl,--wrap=function_to_redefine")
其中,``function_to_redefine`` 为需要被重新定义或扩展的函数名称。启用此选项后,链接器将把二进制库中所有对 ``function_to_redefine`` 函数的调用改为对 ``__wrap_function_to_redefine`` 函数的调用。因此,您必须在应用程序中定义这一符号。

链接器会提供一个名为 ``__real_function_to_redefine`` 的新符号,指向将被重新定义的函数的原有实现。由此,可以从新的实现中调用该函数,从而对原有实现进行扩展。

请参考 :example:`build_system/wrappers` 示例,了解其详细原理。更多细节请参阅 :idf_file:`examples/build_system/wrappers/README.md`。

.. _config_only_component:

仅配置组件
Expand Down

0 comments on commit 7984552

Please sign in to comment.