docs(cmake_utilities): add rst user guide

espressif · Sep 20, 2024 · 12c244d · 12c244d
1 parent f27a924
commit 12c244d
Show file tree

Hide file tree

Showing 6 changed files with 103 additions and 23 deletions.
diff --git a/docs/en/basic/cmake_utilities.rst 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 <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).
+
+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 <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>`__
+
diff --git a/docs/en/basic/index.rst b/docs/en/basic/index.rst
@@ -9,3 +9,4 @@ Basic Component
     Communication Bus <bus>
     I2S LCD Driver <i2s_lcd>
     Boards Support<boards>
+    CMake Utilities <cmake_utilities>
diff --git a/docs/zh_CN/basic/cmake_utilities.rst 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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/build-system.html#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 <https://github.com/espressif/esp-iot-solution/tree/master/components/utilities/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 <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>`__
diff --git a/docs/zh_CN/basic/index.rst b/docs/zh_CN/basic/index.rst
@@ -9,3 +9,4 @@
     通信总线 <bus>
     I2S LCD 驱动 <i2s_lcd>
     板级支持 <boards>
+    CMake 工具集 <cmake_utilities>
diff --git 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
@@ -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"