From 12c244db2b8a234692c214bf04c4d24826630790 Mon Sep 17 00:00:00 2001 From: Li Bo Date: Fri, 20 Sep 2024 18:26:13 +0800 Subject: [PATCH] docs(cmake_utilities): add rst user guide --- docs/en/basic/cmake_utilities.rst | 47 +++++++++++++++++++++++++ docs/en/basic/index.rst | 1 + docs/zh_CN/basic/cmake_utilities.rst | 43 ++++++++++++++++++++++ docs/zh_CN/basic/index.rst | 1 + tools/cmake_utilities/README.md | 31 +++++----------- tools/cmake_utilities/idf_component.yml | 3 +- 6 files changed, 103 insertions(+), 23 deletions(-) create mode 100644 docs/en/basic/cmake_utilities.rst create mode 100644 docs/zh_CN/basic/cmake_utilities.rst diff --git a/docs/en/basic/cmake_utilities.rst b/docs/en/basic/cmake_utilities.rst new file mode 100644 index 000000000..116a05076 --- /dev/null +++ b/docs/en/basic/cmake_utilities.rst @@ -0,0 +1,47 @@ +CMake Utilities +=================== + +:link_to_translation:`zh_CN:[中文]` + +``cmake_utilities`` is a collection of CMake utilities that are commonly used in the components of ``esp-iot-solution``. + +Supported Features: + +- ``project_include.cmake``: add additional features like ``DIAGNOSTICS_COLOR`` to the project. The file will be automatically parsed, for details, please refer `project-include-cmake `__. +- ``package_manager.cmake``: provides functions to manager components' versions, etc. +- ``gcc.cmake``: manager the GCC compiler options like ``LTO`` through menuconfig. +- ``relinker.cmake`` provides a way to move IRAM functions to flash to save RAM space. +- ``gen_compressed_ota.cmake``: add new command ``idf.py gen_compressed_ota`` to generate ``xz`` compressed OTA binary. please refer `xz `__. +- ``gen_single_bin.cmake``: add new command ``idf.py gen_single_bin`` to generate single combined bin file (combine app, bootloader, partition table, etc). + +How to Use +---------- + +Use +--- + +1. Add dependency of this component in your component or project’s ``idf_component.yml``. + + .. code:: yaml + + dependencies: + espressif/cmake_utilities: "0.*" + +2. Include the CMake Features/Script in your component’s or project’s ``CMakeLists.txt`` after ``idf_component_register``. + + .. code:: none + + // Note: should remove .cmake postfix when using include(), otherwise the requested file will not found + // Note: should place this line after `idf_component_register` function + // only include the one you needed. + include(package_manager) + +3. Then you can use the corresponding features provided by the CMake script. + +Detailed Reference +--------------------- + +1. `relinker `__ +2. `gen_compressed_ota `__ +3. `GCC Optimization `__ + diff --git a/docs/en/basic/index.rst b/docs/en/basic/index.rst index f7cc8dd3a..312ddd854 100644 --- a/docs/en/basic/index.rst +++ b/docs/en/basic/index.rst @@ -9,3 +9,4 @@ Basic Component Communication Bus I2S LCD Driver Boards Support + CMake Utilities diff --git a/docs/zh_CN/basic/cmake_utilities.rst b/docs/zh_CN/basic/cmake_utilities.rst new file mode 100644 index 000000000..26ed65b00 --- /dev/null +++ b/docs/zh_CN/basic/cmake_utilities.rst @@ -0,0 +1,43 @@ +CMake Utilities +=================== + +:link_to_translation:`en:[English]` + +``cmake_utilities`` 是 ``esp-iot-solution`` 组件中常用的 CMake 工具集合。 + +支持的功能： + +- ``project_include.cmake``: 为项目添加额外的功能，例如 ``DIAGNOSTICS_COLOR``。文件将被自动解析，详情请参考 `project-include-cmake `__。 +- ``package_manager.cmake``: 提供了管理组件版本等功能。 +- ``gcc.cmake``: 通过 menuconfig 管理 GCC 编译器选项，例如 ``LTO``。 +- ``relinker.cmake`` 提供了一种将 IRAM 函数移动到 Flash 以节省 RAM 空间的方法。 +- ``gen_compressed_ota.cmake``: 添加了新命令 ``idf.py gen_compressed_ota`` 以生成 ``xz`` 压缩的 OTA 二进制文件。详情请参考 `xz `__. +- ``gen_single_bin.cmake``: 添加了新命令 ``idf.py gen_single_bin`` 以生成单个组合 bin 文件（组合 app、bootloader、分区表等）。 + +如何使用 +---------- + +1. 在你的组件或项目的 ``idf_component.yml`` 中添加此组件的依赖。 + + .. code:: yaml + + dependencies: + espressif/cmake_utilities: "0.*" + +2. 在你的组件或项目的 ``CMakeLists.txt`` 中的 ``idf_component_register`` 后包含 CMake 功能/脚本。 + + .. code:: none + + // 注意：使用 include() 时应删除 .cmake 后缀，否则将找不到请求的文件 + // 注意：应在 `idf_component_register` 函数之后放置此行 + // 只包含你需要的功能。 + include(package_manager) + +3. 然后你可以使用 CMake 脚本提供的相应功能。 + +详细参考 +--------------------- + +1. `relinker `__ +2. `gen_compressed_ota `__ +3. `GCC Optimization `__ diff --git a/docs/zh_CN/basic/index.rst b/docs/zh_CN/basic/index.rst index 127949ce4..9096ed658 100644 --- a/docs/zh_CN/basic/index.rst +++ b/docs/zh_CN/basic/index.rst @@ -9,3 +9,4 @@ 通信总线 I2S LCD 驱动 板级支持 + CMake 工具集 diff --git a/tools/cmake_utilities/README.md b/tools/cmake_utilities/README.md index 834ab7308..4a26b6e2c 100644 --- a/tools/cmake_utilities/README.md +++ b/tools/cmake_utilities/README.md @@ -4,28 +4,15 @@ This component is aiming to provide some useful CMake utilities outside of ESP-IDF. -## Use +**Supported features:** -1. Add dependency of this component in your component or project's idf_component.yml. +- `project_include.cmake`: add additional features like `DIAGNOSTICS_COLOR` to the project. The file will be automatically parsed, for details, please refer [project-include-cmake](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/build-system.html#project-include-cmake>). +- `package_manager.cmake`: provides functions to manager components' versions, etc. +- `gcc.cmake`: manager the GCC compiler options like `LTO` through menuconfig. +- `relinker.cmake` provides a way to move IRAM functions to flash to save RAM space. +- `gen_compressed_ota.cmake`: add new command `idf.py gen_compressed_ota` to generate `xz` compressed OTA binary. please refer [xz](https://github.com/espressif/esp-iot-solution/tree/master/components/utilities/xz). +- `gen_single_bin.cmake`: add new command `idf.py gen_single_bin` to generate single combined bin file (combine app, bootloader, partition table, etc). - ```yml - dependencies: - espressif/cmake_utilities: "0.*" - ``` +## User Guide -2. Include the CMake file you need in your component's CMakeLists.txt after `idf_component_register`, or in your project's CMakeLists.txt - - ```cmake - // Note: should remove .cmake postfix when using include(), otherwise the requested file will not found - // Note: should place this line after `idf_component_register` function - // only include the one you needed. - include(package_manager) - ``` - -3. Then you can use the corresponding CMake function which is provided by the CMake file. - -## Supported features - -1. [relinker](https://github.com/espressif/esp-iot-solution/blob/master/tools/cmake_utilities/docs/relinker.md) -2. [gen_compressed_ota](https://github.com/espressif/esp-iot-solution/blob/master/tools/cmake_utilities/docs/gen_compressed_ota.md) -3. [GCC Optimization](https://github.com/espressif/esp-iot-solution/blob/master/tools/cmake_utilities/docs/gcc.md) +[cmake_utilities user guide](https://docs.espressif.com/projects/esp-iot-solution/zh_CN/latest/basic/cmake_utilities.html) diff --git a/tools/cmake_utilities/idf_component.yml b/tools/cmake_utilities/idf_component.yml index 69ff0d120..ebdc587aa 100644 --- a/tools/cmake_utilities/idf_component.yml +++ b/tools/cmake_utilities/idf_component.yml @@ -1,6 +1,7 @@ -version: "0.5.3" +version: "1.0.0" description: A collection of useful cmake utilities url: https://github.com/espressif/esp-iot-solution/tree/master/tools/cmake_utilities +documentation: https://docs.espressif.com/projects/esp-iot-solution/zh_CN/latest/basic/cmake_utilities.html issues: https://github.com/espressif/esp-iot-solution/issues dependencies: idf: ">=4.1"