-
Notifications
You must be signed in to change notification settings - Fork 768
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'docs/cmake_utilities' into 'master'
docs(cmake_utilities): add rst user guide Closes AEG-1005 See merge request ae_group/esp-iot-solution!1088
- Loading branch information
Showing
6 changed files
with
103 additions
and
23 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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>`__ | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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>`__ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -9,3 +9,4 @@ | |
通信总线 <bus> | ||
I2S LCD 驱动 <i2s_lcd> | ||
板级支持 <boards> | ||
CMake 工具集 <cmake_utilities> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" |