From 775c65a6b7284d21b3a97e6e8060ec76f295c2cd Mon Sep 17 00:00:00 2001 From: Omar Chebib Date: Tue, 10 Sep 2024 15:10:34 +0800 Subject: [PATCH 1/5] feat(bootloader): add the possibility to specify extra components directories --- components/bootloader/project_include.cmake | 8 ++- .../bootloader/subproject/CMakeLists.txt | 4 +- docs/en/api-guides/build-system.rst | 17 +++++- .../bootloader_extra_dir/CMakeLists.txt | 11 ++++ .../bootloader_extra_dir/README.md | 56 +++++++++++++++++++ .../my_boot_hooks/CMakeLists.txt | 9 +++ .../my_boot_hooks/hooks.c | 17 ++++++ .../extra_component/CMakeLists.txt | 1 + .../extra_component/extra_component.c | 11 ++++ .../bootloader_extra_dir/main/CMakeLists.txt | 2 + .../main/bootloader_hooks_example_main.c | 11 ++++ .../pytest_bootloader_extra_dir.py | 10 ++++ .../ci/check_examples_extra_component_dirs.sh | 3 +- 13 files changed, 152 insertions(+), 8 deletions(-) create mode 100644 examples/custom_bootloader/bootloader_extra_dir/CMakeLists.txt create mode 100644 examples/custom_bootloader/bootloader_extra_dir/README.md create mode 100644 examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/CMakeLists.txt create mode 100644 examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/hooks.c create mode 100644 examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component/CMakeLists.txt create mode 100644 examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component/extra_component.c create mode 100644 examples/custom_bootloader/bootloader_extra_dir/main/CMakeLists.txt create mode 100644 examples/custom_bootloader/bootloader_extra_dir/main/bootloader_hooks_example_main.c create mode 100644 examples/custom_bootloader/bootloader_extra_dir/pytest_bootloader_extra_dir.py diff --git a/components/bootloader/project_include.cmake b/components/bootloader/project_include.cmake index 2afe2116d3..485a786f9b 100644 --- a/components/bootloader/project_include.cmake +++ b/components/bootloader/project_include.cmake @@ -116,8 +116,12 @@ idf_build_get_property(sdkconfig SDKCONFIG) idf_build_get_property(python PYTHON) idf_build_get_property(extra_cmake_args EXTRA_CMAKE_ARGS) -# We cannot pass lists are a parameter to the external project without modifying the ';' separator +# BOOTLOADER_EXTRA_COMPONENT_DIRS may have been set by the `main` component, do not overwrite it +list(APPEND BOOTLOADER_EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}") + +# We cannot pass lists as a parameter to the external project without modifying the ';' separator string(REPLACE ";" "|" BOOTLOADER_IGNORE_EXTRA_COMPONENT "${BOOTLOADER_IGNORE_EXTRA_COMPONENT}") +string(REPLACE ";" "|" BOOTLOADER_EXTRA_COMPONENT_DIRS "${BOOTLOADER_EXTRA_COMPONENT_DIRS}") externalproject_add(bootloader SOURCE_DIR "${CMAKE_CURRENT_LIST_DIR}/subproject" @@ -127,7 +131,7 @@ externalproject_add(bootloader LIST_SEPARATOR | CMAKE_ARGS -DSDKCONFIG=${sdkconfig} -DIDF_PATH=${idf_path} -DIDF_TARGET=${idf_target} -DPYTHON_DEPS_CHECKED=1 -DPYTHON=${python} - -DEXTRA_COMPONENT_DIRS=${CMAKE_CURRENT_LIST_DIR} + -DEXTRA_COMPONENT_DIRS=${BOOTLOADER_EXTRA_COMPONENT_DIRS} -DPROJECT_SOURCE_DIR=${PROJECT_SOURCE_DIR} -DIGNORE_EXTRA_COMPONENT=${BOOTLOADER_IGNORE_EXTRA_COMPONENT} ${sign_key_arg} ${ver_key_arg} diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt index f630bcc46c..34c7cded18 100644 --- a/components/bootloader/subproject/CMakeLists.txt +++ b/components/bootloader/subproject/CMakeLists.txt @@ -34,8 +34,8 @@ set(COMPONENTS esp_system newlib) -# Make EXTRA_COMPONENT_DIRS variable to point to the bootloader_components directory -# of the project being compiled +# EXTRA_COMPONENT_DIRS can be populated with directories containing one or several components. +# Make sure this variable contains `bootloader_components` directory of the project being compiled. set(PROJECT_EXTRA_COMPONENTS "${PROJECT_SOURCE_DIR}/bootloader_components") if(EXISTS ${PROJECT_EXTRA_COMPONENTS}) list(APPEND EXTRA_COMPONENT_DIRS "${PROJECT_EXTRA_COMPONENTS}") diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 37356c0ea8..ed9862198d 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -245,7 +245,9 @@ These variables all have default values that can be overridden for custom behavi - ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via the REQUIRES or PRIV_REQUIRES arguments on component registration will automatically have it added to this list, so the ``COMPONENTS`` list can be very short. -- ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``: A list of components, placed in ``bootloader_components/``, that should be ignored by the bootloader compilation. Use this variable if a bootloader component needs to be included conditionally inside the project. +- ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``: Optional list of components, placed in ``bootloader_components/``, that should be ignored by the bootloader compilation. Use this variable if a bootloader component needs to be included conditionally inside the project. + +- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components to be compiled as part of the bootloader. Paths can be relative to the project directory, or absolute. Any paths in these variables can be absolute paths, or set relative to the project directory. @@ -751,7 +753,7 @@ This mechanism is shown in the example :example:`build_system/wrappers`. Check : Override the Default Bootloader ------------------------------- -Thanks to the optional ``bootloader_components`` directory present in your ESP-IDf project, it is possible to override the default ESP-IDF bootloader. To do so, a new ``bootloader_components/main`` component should be defined, which will make the project directory tree look like the following: +Thanks to the optional ``bootloader_components`` directory present in your ESP-IDF project, it is possible to override the default ESP-IDF bootloader. To do so, a new ``bootloader_components/main`` component should be defined, which will make the project directory tree look like the following: - myProject/ - CMakeLists.txt @@ -765,7 +767,7 @@ Thanks to the optional ``bootloader_components`` directory present in your ESP-I - build/ -Here the ``my_bootloader.c`` file becomes source code for the new bootloader, which means that it will need to perform all the required operations to set up and load the ``main`` application from flash. +Here, the ``my_bootloader.c`` file becomes source code for the new bootloader, which means that it will need to perform all the required operations to set up and load the ``main`` application from flash. It is also possible to conditionally replace the bootloader depending on a certain condition, such as the target for example. This can be achieved thanks to the ``BOOTLOADER_IGNORE_EXTRA_COMPONENT`` CMake variable. This list can be used to tell the ESP-IDF bootloader project to ignore and not compile the given components present in ``bootloader_components``. For example, if one wants to use the default bootloader for ESP32 target, then ``myProject/CMakeLists.txt`` should look like the following:: @@ -781,6 +783,15 @@ It is important to note that this can also be used for any other bootloader comp See :example:`custom_bootloader/bootloader_override` for an example of overriding the default bootloader. +Similarly to regular applications, it is possible to include external components, not placed in `bootloader_component`, as part of the bootloader build thanks to the CMake variable ``BOOTLOADER_EXTRA_COMPONENT_DIRS``. It can either refer to a directory that contains several components, either refer to a single component. For example: + + include($ENV{IDF_PATH}/tools/cmake/project.cmake) + + set(BOOTLOADER_EXTRA_COMPONENT_DIRS "/path/to/extra/component/") + + project(main) + +See :example:`custom_bootloader/bootloader_extra_dir` for an example of adding extra components the bootloader build. .. _config_only_component: diff --git a/examples/custom_bootloader/bootloader_extra_dir/CMakeLists.txt b/examples/custom_bootloader/bootloader_extra_dir/CMakeLists.txt new file mode 100644 index 0000000000..64ae357407 --- /dev/null +++ b/examples/custom_bootloader/bootloader_extra_dir/CMakeLists.txt @@ -0,0 +1,11 @@ +# For more information about build system see +# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html +# The following five lines of boilerplate have to be in your project's +# CMakeLists in this exact order for cmake to work correctly +cmake_minimum_required(VERSION 3.16) + +include($ENV{IDF_PATH}/tools/cmake/project.cmake) + +set(BOOTLOADER_EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/extra_bootloader_components/") + +project(main) diff --git a/examples/custom_bootloader/bootloader_extra_dir/README.md b/examples/custom_bootloader/bootloader_extra_dir/README.md new file mode 100644 index 0000000000..03d842b76e --- /dev/null +++ b/examples/custom_bootloader/bootloader_extra_dir/README.md @@ -0,0 +1,56 @@ +| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-P4 | ESP32-S2 | ESP32-S3 | +| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- | -------- | + +# Bootloader extra component + +(See the README.md file in the upper level for more information about bootloader examples.) + +The purpose of this example is to show how to add a custom directory that contains a component to the bootloader build. + +Registering extra components for the bootloader can be done thanks to the CMake variable `BOOTLOADER_EXTRA_COMPONENT_DIRS`. It works the same way as the application's `EXTRA_COMPONENT_DIRS`, it can either refer to a directory that contains several components, either refer to a single component. + +## Usage of this example: + +Simply compile it: +``` +idf.py build +``` + +Then flash it and open the monitor with the following command: +``` +idf.py flash monitor +``` + +If everything went well, the bootloader should output the following message: +``` +I (60) EXTRA: This function is called from an extra component +``` + +And finally the application will start and show the message: +``` +User application is loaded and running. +``` + +## Organization of this example + +This project contains an application, in the `main` directory that represents an application. It also contains a `bootloader_components` that contains a component compiled and linked with the bootloader. This `bootloader_components` can contain several components, each of them would be in a different directory. + +The directory `extra_bootloader_components/extra_component/` contains a component that is meant to be included in the bootloader build. To do so, the variable `BOOTLOADER_EXTRA_COMPONENT_DIRS` is set from the `CMakeLists.txt` file. + +Below is a short explanation of files in the project folder. + +``` +├── CMakeLists.txt Defines the `BOOTLOADER_EXTRA_COMPONENT_DIRS` variable +├── main +│   ├── CMakeLists.txt +│   └── main.c User application +├── bootloader_components +│   └── my_boot_hooks +│   ├── CMakeLists.txt +│   └── hooks.c Implementation of the hooks to execute on boot +├── extra_bootloader_components +│   └── extra_component +│   ├── CMakeLists.txt +│   └── extra_component.c Implementation of the extra component +└── README.md This is the file you are currently reading +``` diff --git a/examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/CMakeLists.txt b/examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/CMakeLists.txt new file mode 100644 index 0000000000..6b620571a4 --- /dev/null +++ b/examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/CMakeLists.txt @@ -0,0 +1,9 @@ +idf_component_register(SRCS "hooks.c" + REQUIRES extra_component) + +# We need to force GCC to integrate this static library into the +# bootloader link. Indeed, by default, as the hooks in the bootloader are weak, +# the linker would just ignore the symbols in the extra. (i.e. not strictly +# required) +# To do so, we need to define the symbol (function) `bootloader_hooks_include` +# within hooks.c source file. diff --git a/examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/hooks.c b/examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/hooks.c new file mode 100644 index 0000000000..e72e4570a9 --- /dev/null +++ b/examples/custom_bootloader/bootloader_extra_dir/bootloader_components/my_boot_hooks/hooks.c @@ -0,0 +1,17 @@ +/* + * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Unlicense OR CC0-1.0 + */ + +extern void bootloader_extra_dir_function(void); + +/* Function used to tell the linker to include this file + * with all its symbols. + */ +void bootloader_hooks_include(void){ +} + +void bootloader_after_init(void) { + bootloader_extra_dir_function(); +} diff --git a/examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component/CMakeLists.txt b/examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component/CMakeLists.txt new file mode 100644 index 0000000000..ac58fa9c07 --- /dev/null +++ b/examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component/CMakeLists.txt @@ -0,0 +1 @@ +idf_component_register(SRCS "extra_component.c") diff --git a/examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component/extra_component.c b/examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component/extra_component.c new file mode 100644 index 0000000000..78b558c5e3 --- /dev/null +++ b/examples/custom_bootloader/bootloader_extra_dir/extra_bootloader_components/extra_component/extra_component.c @@ -0,0 +1,11 @@ +/* + * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Unlicense OR CC0-1.0 + */ +#include "esp_log.h" + +void bootloader_extra_dir_function(void) +{ + ESP_LOGI("EXTRA", "This function is called from an extra component"); +} diff --git a/examples/custom_bootloader/bootloader_extra_dir/main/CMakeLists.txt b/examples/custom_bootloader/bootloader_extra_dir/main/CMakeLists.txt new file mode 100644 index 0000000000..db0df98971 --- /dev/null +++ b/examples/custom_bootloader/bootloader_extra_dir/main/CMakeLists.txt @@ -0,0 +1,2 @@ +idf_component_register(SRCS "bootloader_hooks_example_main.c" + INCLUDE_DIRS ".") diff --git a/examples/custom_bootloader/bootloader_extra_dir/main/bootloader_hooks_example_main.c b/examples/custom_bootloader/bootloader_extra_dir/main/bootloader_hooks_example_main.c new file mode 100644 index 0000000000..293528a611 --- /dev/null +++ b/examples/custom_bootloader/bootloader_extra_dir/main/bootloader_hooks_example_main.c @@ -0,0 +1,11 @@ +/* + * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Unlicense OR CC0-1.0 + */ +#include + +void app_main(void) +{ + printf("User application is loaded and running.\n"); +} diff --git a/examples/custom_bootloader/bootloader_extra_dir/pytest_bootloader_extra_dir.py b/examples/custom_bootloader/bootloader_extra_dir/pytest_bootloader_extra_dir.py new file mode 100644 index 0000000000..217ce76f8e --- /dev/null +++ b/examples/custom_bootloader/bootloader_extra_dir/pytest_bootloader_extra_dir.py @@ -0,0 +1,10 @@ +# SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD +# SPDX-License-Identifier: CC0-1.0 +import pytest +from pytest_embedded import Dut + + +@pytest.mark.supported_targets +@pytest.mark.generic +def test_custom_bootloader_extra_component(dut: Dut) -> None: + dut.expect_exact('This function is called from an extra component') diff --git a/tools/ci/check_examples_extra_component_dirs.sh b/tools/ci/check_examples_extra_component_dirs.sh index ac71e5975a..dd2e311342 100755 --- a/tools/ci/check_examples_extra_component_dirs.sh +++ b/tools/ci/check_examples_extra_component_dirs.sh @@ -5,7 +5,8 @@ set -uo pipefail # Examples shouldn't use EXTRA_COMPONENT_DIRS, instead the dependencies should be specified in idf_component.yml files output=$(find ${IDF_PATH}/examples -name "CMakeLists.txt" -not -path "**/managed_components/**" -not -path "**/build/**") -files=$(egrep "EXTRA_COMPONENT_DIRS" ${output} | cut -d ":" -f 1) +# Make sure the regex doesn't match the text `BOOTLOADER_EXTRA_COMPONENT_DIRS` +files=$(egrep "[^A-Za-Z0-9_]EXTRA_COMPONENT_DIRS" ${output} | cut -d ":" -f 1) found_issues=0 for file in ${files} do From a1df6b818541aaa6b892f50f4b3c58ec76edacd1 Mon Sep 17 00:00:00 2001 From: renpeiying Date: Wed, 18 Sep 2024 16:57:39 +0800 Subject: [PATCH 2/5] docs: Update CN translation for api-guides/build-system.rst --- docs/en/api-guides/build-system.rst | 4 ++-- docs/zh_CN/api-guides/build-system.rst | 13 ++++++++++++- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index ed9862198d..66c821acdd 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -247,7 +247,7 @@ These variables all have default values that can be overridden for custom behavi - ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``: Optional list of components, placed in ``bootloader_components/``, that should be ignored by the bootloader compilation. Use this variable if a bootloader component needs to be included conditionally inside the project. -- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components to be compiled as part of the bootloader. Paths can be relative to the project directory, or absolute. +- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components to be compiled as part of the bootloader. Any paths in these variables can be absolute paths, or set relative to the project directory. @@ -791,7 +791,7 @@ Similarly to regular applications, it is possible to include external components project(main) -See :example:`custom_bootloader/bootloader_extra_dir` for an example of adding extra components the bootloader build. +See :example:`custom_bootloader/bootloader_extra_dir` for an example of adding extra components to the bootloader build. .. _config_only_component: diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 05620dded9..9f90e9c122 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -245,7 +245,9 @@ ESP-IDF 适用于 Python 3.8 以上版本。 - ``COMPONENTS``：要构建进项目中的组件名称列表，默认为 ``COMPONENT_DIRS`` 目录下检索到的所有组件。使用此变量可以“精简”项目以缩短构建时间。请注意，如果一个组件通过 ``COMPONENT_REQUIRES`` 指定了它依赖的另一个组件，则会自动将其添加到 ``COMPONENTS`` 中，所以 ``COMPONENTS`` 列表可能会非常短。 -- ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``：引导加载程序编译时应忽略的组件列表，位于 ``bootloader_components/`` 目录中。使用这一变量可以将一个组件有条件地包含在项目中。 +- ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``：可选组件列表，位于 ``bootloader_components/`` 目录中，引导加载程序编译时会被忽略。使用这一变量可以将一个组件有条件地包含在项目中。 + +- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``：可选目录列表，用于搜索要作为引导程序的一部分进行编译的组件。 以上变量中的路径可以是绝对路径，或者是相对于项目目录的相对路径。 @@ -781,6 +783,15 @@ KConfig.projbuild 请参考 :example:`custom_bootloader/bootloader_override` 查看覆盖默认引导加载程序的示例。 +与常规应用程序类似，通过 CMake 变量 ``BOOTLOADER_EXTRA_COMPONENT_DIRS`` 可以将不在 `bootloader_component` 中的外部组件作为引导加载程序的一部分进行构建。可以只引用一个组件，也可以引用包含多个组件的路径。例如： + + include($ENV{IDF_PATH}/tools/cmake/project.cmake) + + set(BOOTLOADER_EXTRA_COMPONENT_DIRS "/path/to/extra/component/") + + project(main) + +请参考 :example:`custom_bootloader/bootloader_extra_dir` 查看向引导加载程序构建过程添加额外组件的示例。 .. _config_only_component: From e33bcaa6d36374d44c0860f74bff62919f21e27a Mon Sep 17 00:00:00 2001 From: Omar Chebib Date: Thu, 26 Sep 2024 12:45:50 +0800 Subject: [PATCH 3/5] feat(bootloader): use idf property to specify extra components directories --- components/bootloader/project_include.cmake | 7 ++++--- .../custom_bootloader/bootloader_extra_dir/CMakeLists.txt | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/components/bootloader/project_include.cmake b/components/bootloader/project_include.cmake index 485a786f9b..12cf17dc70 100644 --- a/components/bootloader/project_include.cmake +++ b/components/bootloader/project_include.cmake @@ -117,11 +117,12 @@ idf_build_get_property(python PYTHON) idf_build_get_property(extra_cmake_args EXTRA_CMAKE_ARGS) # BOOTLOADER_EXTRA_COMPONENT_DIRS may have been set by the `main` component, do not overwrite it -list(APPEND BOOTLOADER_EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}") +idf_build_get_property(bootloader_extra_component_dirs BOOTLOADER_EXTRA_COMPONENT_DIRS) +list(APPEND bootloader_extra_component_dirs "${CMAKE_CURRENT_LIST_DIR}") # We cannot pass lists as a parameter to the external project without modifying the ';' separator string(REPLACE ";" "|" BOOTLOADER_IGNORE_EXTRA_COMPONENT "${BOOTLOADER_IGNORE_EXTRA_COMPONENT}") -string(REPLACE ";" "|" BOOTLOADER_EXTRA_COMPONENT_DIRS "${BOOTLOADER_EXTRA_COMPONENT_DIRS}") +string(REPLACE ";" "|" bootloader_extra_component_dirs "${bootloader_extra_component_dirs}") externalproject_add(bootloader SOURCE_DIR "${CMAKE_CURRENT_LIST_DIR}/subproject" @@ -131,7 +132,7 @@ externalproject_add(bootloader LIST_SEPARATOR | CMAKE_ARGS -DSDKCONFIG=${sdkconfig} -DIDF_PATH=${idf_path} -DIDF_TARGET=${idf_target} -DPYTHON_DEPS_CHECKED=1 -DPYTHON=${python} - -DEXTRA_COMPONENT_DIRS=${BOOTLOADER_EXTRA_COMPONENT_DIRS} + -DEXTRA_COMPONENT_DIRS=${bootloader_extra_component_dirs} -DPROJECT_SOURCE_DIR=${PROJECT_SOURCE_DIR} -DIGNORE_EXTRA_COMPONENT=${BOOTLOADER_IGNORE_EXTRA_COMPONENT} ${sign_key_arg} ${ver_key_arg} diff --git a/examples/custom_bootloader/bootloader_extra_dir/CMakeLists.txt b/examples/custom_bootloader/bootloader_extra_dir/CMakeLists.txt index 64ae357407..77e21c4ce6 100644 --- a/examples/custom_bootloader/bootloader_extra_dir/CMakeLists.txt +++ b/examples/custom_bootloader/bootloader_extra_dir/CMakeLists.txt @@ -6,6 +6,6 @@ cmake_minimum_required(VERSION 3.16) include($ENV{IDF_PATH}/tools/cmake/project.cmake) -set(BOOTLOADER_EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/extra_bootloader_components/") +idf_build_set_property(BOOTLOADER_EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/extra_bootloader_components/" APPEND) project(main) From a49454e3524c04b72d2379c90de4970457be139b Mon Sep 17 00:00:00 2001 From: renpeiying Date: Wed, 9 Oct 2024 15:46:34 +0800 Subject: [PATCH 4/5] docs: Update CN translation according to review --- docs/zh_CN/api-guides/build-system.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 9f90e9c122..76dd670404 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -245,9 +245,9 @@ ESP-IDF 适用于 Python 3.8 以上版本。 - ``COMPONENTS``：要构建进项目中的组件名称列表，默认为 ``COMPONENT_DIRS`` 目录下检索到的所有组件。使用此变量可以“精简”项目以缩短构建时间。请注意，如果一个组件通过 ``COMPONENT_REQUIRES`` 指定了它依赖的另一个组件，则会自动将其添加到 ``COMPONENTS`` 中，所以 ``COMPONENTS`` 列表可能会非常短。 -- ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``：可选组件列表，位于 ``bootloader_components/`` 目录中，引导加载程序编译时会被忽略。使用这一变量可以将一个组件有条件地包含在项目中。 +- ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``：可选组件列表，位于 ``bootloader_components/`` 目录中，引导加载程序编译时会忽略该列表。使用这一变量可以将一个组件有条件地包含在项目中。 -- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``：可选目录列表，用于搜索要作为引导程序的一部分进行编译的组件。 +- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``：可选的附加路径列表，引导加载程序编译时将从这些路径中搜索要编译的组件。 以上变量中的路径可以是绝对路径，或者是相对于项目目录的相对路径。 From 729c55b7906a1b74f3615e8be037b55abf7406ee Mon Sep 17 00:00:00 2001 From: Omar Chebib Date: Wed, 30 Oct 2024 16:16:48 +0800 Subject: [PATCH 5/5] docs: changed bootloader extra component to a property in build-system.rst --- docs/en/api-guides/build-system.rst | 6 +++--- docs/zh_CN/api-guides/build-system.rst | 10 +++++----- .../custom_bootloader/bootloader_extra_dir/README.md | 8 ++++---- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 66c821acdd..d38e905a13 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -247,7 +247,7 @@ These variables all have default values that can be overridden for custom behavi - ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``: Optional list of components, placed in ``bootloader_components/``, that should be ignored by the bootloader compilation. Use this variable if a bootloader component needs to be included conditionally inside the project. -- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components to be compiled as part of the bootloader. +- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components to be compiled as part of the bootloader. Please note that this is a build property. Any paths in these variables can be absolute paths, or set relative to the project directory. @@ -783,11 +783,11 @@ It is important to note that this can also be used for any other bootloader comp See :example:`custom_bootloader/bootloader_override` for an example of overriding the default bootloader. -Similarly to regular applications, it is possible to include external components, not placed in `bootloader_component`, as part of the bootloader build thanks to the CMake variable ``BOOTLOADER_EXTRA_COMPONENT_DIRS``. It can either refer to a directory that contains several components, either refer to a single component. For example: +Similarly to regular applications, it is possible to include external components, not placed in `bootloader_component`, as part of the bootloader build thanks to the build property ``BOOTLOADER_EXTRA_COMPONENT_DIRS``. It can either refer to a directory that contains several components, or refer to a single component. For example: include($ENV{IDF_PATH}/tools/cmake/project.cmake) - set(BOOTLOADER_EXTRA_COMPONENT_DIRS "/path/to/extra/component/") + idf_build_set_property(BOOTLOADER_EXTRA_COMPONENT_DIRS "/path/to/extra/component/" APPEND) project(main) diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 76dd670404..a4520ec8cf 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -245,9 +245,9 @@ ESP-IDF 适用于 Python 3.8 以上版本。 - ``COMPONENTS``：要构建进项目中的组件名称列表，默认为 ``COMPONENT_DIRS`` 目录下检索到的所有组件。使用此变量可以“精简”项目以缩短构建时间。请注意，如果一个组件通过 ``COMPONENT_REQUIRES`` 指定了它依赖的另一个组件，则会自动将其添加到 ``COMPONENTS`` 中，所以 ``COMPONENTS`` 列表可能会非常短。 -- ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``：可选组件列表，位于 ``bootloader_components/`` 目录中，引导加载程序编译时会忽略该列表。使用这一变量可以将一个组件有条件地包含在项目中。 +- ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``：可选组件列表，位于 ``bootloader_components/`` 目录中，引导加载程序编译时会忽略该列表中的组件。使用这一变量可以将一个组件有条件地包含在项目中。 -- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``：可选的附加路径列表，引导加载程序编译时将从这些路径中搜索要编译的组件。 +- ``BOOTLOADER_EXTRA_COMPONENT_DIRS``：可选的附加路径列表，引导加载程序编译时将从这些路径中搜索要编译的组件。注意，这是一个构建属性。 以上变量中的路径可以是绝对路径，或者是相对于项目目录的相对路径。 @@ -783,15 +783,15 @@ KConfig.projbuild 请参考 :example:`custom_bootloader/bootloader_override` 查看覆盖默认引导加载程序的示例。 -与常规应用程序类似，通过 CMake 变量 ``BOOTLOADER_EXTRA_COMPONENT_DIRS`` 可以将不在 `bootloader_component` 中的外部组件作为引导加载程序的一部分进行构建。可以只引用一个组件，也可以引用包含多个组件的路径。例如： +与常规应用程序类似，通过构建属性 ``BOOTLOADER_EXTRA_COMPONENT_DIRS`` 可以将不在 `bootloader_component` 中的外部组件作为引导加载程序的一部分进行构建。可以只引用一个组件，也可以引用包含多个组件的路径。例如： include($ENV{IDF_PATH}/tools/cmake/project.cmake) - set(BOOTLOADER_EXTRA_COMPONENT_DIRS "/path/to/extra/component/") + idf_build_set_property(BOOTLOADER_EXTRA_COMPONENT_DIRS "/path/to/extra/component/" APPEND) project(main) -请参考 :example:`custom_bootloader/bootloader_extra_dir` 查看向引导加载程序构建过程添加额外组件的示例。 +请参考示例 :example:`custom_bootloader/bootloader_extra_dir`，查看如何向引导加载程序构建过程添加额外的组件。 .. _config_only_component: diff --git a/examples/custom_bootloader/bootloader_extra_dir/README.md b/examples/custom_bootloader/bootloader_extra_dir/README.md index 03d842b76e..9d0b0021ac 100644 --- a/examples/custom_bootloader/bootloader_extra_dir/README.md +++ b/examples/custom_bootloader/bootloader_extra_dir/README.md @@ -7,7 +7,7 @@ The purpose of this example is to show how to add a custom directory that contains a component to the bootloader build. -Registering extra components for the bootloader can be done thanks to the CMake variable `BOOTLOADER_EXTRA_COMPONENT_DIRS`. It works the same way as the application's `EXTRA_COMPONENT_DIRS`, it can either refer to a directory that contains several components, either refer to a single component. +Registering extra components for the bootloader can be done thanks to the IDF property `BOOTLOADER_EXTRA_COMPONENT_DIRS`. It can either refer to a directory that contains several components, either refer to a single component. ## Usage of this example: @@ -33,14 +33,14 @@ User application is loaded and running. ## Organization of this example -This project contains an application, in the `main` directory that represents an application. It also contains a `bootloader_components` that contains a component compiled and linked with the bootloader. This `bootloader_components` can contain several components, each of them would be in a different directory. +This project contains a `main` directory that represents an application. It also has a `bootloader_components` directory that contains a component that will be compiled and linked with the bootloader. This `bootloader_components` can contain several components, each of them would be in a different directory. -The directory `extra_bootloader_components/extra_component/` contains a component that is meant to be included in the bootloader build. To do so, the variable `BOOTLOADER_EXTRA_COMPONENT_DIRS` is set from the `CMakeLists.txt` file. +The directory `extra_bootloader_components/extra_component/` contains a component that is meant to be included in the bootloader build. To do so, the CMake property `BOOTLOADER_EXTRA_COMPONENT_DIRS` is set from the `CMakeLists.txt` file. Below is a short explanation of files in the project folder. ``` -├── CMakeLists.txt Defines the `BOOTLOADER_EXTRA_COMPONENT_DIRS` variable +├── CMakeLists.txt Defines the `BOOTLOADER_EXTRA_COMPONENT_DIRS` property ├── main │   ├── CMakeLists.txt │   └── main.c User application