From abddda342f0dfd64e75a49ad13335c3cc0e7f88c Mon Sep 17 00:00:00 2001 From: Frantisek Hrbata Date: Fri, 12 Sep 2025 18:07:10 +0200 Subject: [PATCH] fix(cmakev2/docs): reformat function arguments for API documentation The function arguments in the documentation comments were using field list, which caused text overflow in the generated documentation and generally resulted in poor formatting. Let's use paragraphs for the argument descriptions instead. The documentation comments are written in reStructuredText, but currently, they use inconsistent indentation. Standardize all the documentation comments to use a four-character indentation. Signed-off-by: Frantisek Hrbata --- tools/cmakev2/build.cmake | 425 +++++++++++++++++---------- tools/cmakev2/compat.cmake | 283 +++++++++++------- tools/cmakev2/component.cmake | 329 +++++++++++++-------- tools/cmakev2/idf.cmake | 191 ++++++------ tools/cmakev2/kconfig.cmake | 172 ++++++----- tools/cmakev2/ldgen.cmake | 55 ++-- tools/cmakev2/manager.cmake | 81 ++--- tools/cmakev2/project.cmake | 104 +++---- tools/cmakev2/utilities.cmake | 539 ++++++++++++++++++++++------------ 9 files changed, 1325 insertions(+), 854 deletions(-) diff --git a/tools/cmakev2/build.cmake b/tools/cmakev2/build.cmake index fecc1ccd5c..a331ad623e 100644 --- a/tools/cmakev2/build.cmake +++ b/tools/cmakev2/build.cmake @@ -10,18 +10,26 @@ include(CheckCXXCompilerFlag) #[[api .. cmakev2:function:: idf_build_set_property - .. code-block:: cmake + .. code-block:: cmake - idf_build_set_property( [APPEND]) + idf_build_set_property( [APPEND]) - :property[in]: Property name. - :value[in]: Property value. - :APPEND: Append the value to the property's current value instead of - replacing it. + *property[in]* - Set the value of the specified property related to the ESP-IDF build. The - property is also added to the internal list of build properties if it isn't - already there. + Property name. + + *value[in]* + + Property value. + + *APPEND* + + Append the value to the property's current value instead of replacing + it. + + Set the value of the specified property related to the ESP-IDF build. The + property is also added to the internal list of build properties if it isn't + already there. #]] function(idf_build_set_property property value) set(options APPEND) @@ -44,16 +52,24 @@ endfunction() #[[api .. cmakev2:function:: idf_build_get_property - .. code-block:: cmake + .. code-block:: cmake - idf_build_get_property( [GENERATOR_EXPRESSION]) + idf_build_get_property( [GENERATOR_EXPRESSION]) - :variable[out]: Variable to store the value in. - :property[in]: Property name to get the value of. - :GENERATOR_EXPRESSION: Obtain the generator expression for the property - rather than the actual value. + *variable[out]* - Get the value of the specified property related to the ESP-IDF build. + Variable to store the value in. + + *property[in]* + + Property name to get the value of. + + *GENERATOR_EXPRESSION[in]* + + Obtain the generator expression for the property rather than the actual + value. + + Get the value of the specified property related to the ESP-IDF build. #]] function(idf_build_get_property variable property) set(options GENERATOR_EXPRESSION) @@ -78,9 +94,9 @@ function(idf_build_get_property variable property) endfunction() #[[ - __dump_build_properties() + __dump_build_properties() - Dump all build properties. + Dump all build properties. #]] function(__dump_build_properties) idf_build_get_property(properties BUILD_PROPERTIES) @@ -92,15 +108,20 @@ function(__dump_build_properties) endfunction() #[[ - __get_library_interface_or_die(LIBRARY - OUTPUT ) + __get_library_interface_or_die(LIBRARY + OUTPUT ) - :LIBRARY[in]: Library interface or alias. - :OUTPUT[out]: Output variable to store the library interface. + *LIBRARY[in]* - Verify that "LIBRARY" is a known interface created by ``idf_build_library`` - or its alias. If it is, return the library interface; otherwise, terminate - the build process. + Library interface or alias. + + *OUTPUT[out]* + + Output variable to store the library interface. + + Verify that "LIBRARY" is a known interface created by ``idf_build_library`` + or its alias. If it is, return the library interface; otherwise, terminate + the build process. #]] function(__get_library_interface_or_die) set(options) @@ -128,19 +149,29 @@ endfunction() #[[api .. cmakev2:function:: idf_library_set_property - .. code-block:: cmake + .. code-block:: cmake - idf_library_set_property( [APPEND]) + idf_library_set_property( [APPEND]) - :library[in]: Library interface target or alias. - :property[in]: Property name. - :value[in]: Property value. - :APPEND: Append the value to the property's current value instead of - replacing it. + *library[in]* - Set the value of the specified library property. The property is also - added to the internal list of library properties if it isn't already - there. + Library interface target or alias. + + *property[in]* + + Property name. + + *value[in]* + + Property value. + + *APPEND* + + Append the value to the property's current value instead of replacing + it. + + Set the value of the specified library property. The property is also added + to the internal list of library properties if it isn't already there. #]] function(idf_library_set_property library property value) set(options APPEND) @@ -164,17 +195,28 @@ endfunction() #[[api .. cmakev2:function:: idf_library_get_property - .. code-block:: cmake + .. code-block:: cmake - idf_library_get_property( [GENERATOR_EXPRESSION]) + idf_library_get_property( [GENERATOR_EXPRESSION]) - :variable[out]: Variable to store the value in. - :library[in]: Library interface target or alias. - :property[in]: Property name to get the value of. - :GENERATOR_EXPRESSION: Obtain the generator expression for the property - rather than the actual value. + *variable[out]* - Retrieve the value of the specified library property. + Variable to store the value in. + + *library[in]* + + Library interface target or alias. + + *property[in]* + + Property name to get the value of. + + *GENERATOR_EXPRESSION* + + Obtain the generator expression for the property rather than the actual + value. + + Retrieve the value of the specified library property. #]] function(idf_library_get_property variable library property) set(options GENERATOR_EXPRESSION) @@ -196,11 +238,13 @@ function(idf_library_get_property variable library property) endfunction() #[[ - __dump_library_properties() + __dump_library_properties() - :libraries: List of library interfaces whose properties should be displayed. + *libraries* - Dump all properties for the libraries listed in ````. + List of library interfaces whose properties should be displayed. + + Dump all properties for the libraries listed in ````. #]] function(__dump_library_properties libraries) foreach(library IN LISTS libraries) @@ -216,26 +260,32 @@ endfunction() #[[api .. cmakev2:function:: idf_build_library - .. code-block:: cmake + .. code-block:: cmake - idf_build_library( - [COMPONENTS ...]) + idf_build_library( + [COMPONENTS ...]) - :library[in]: Name of the library interface to be created. - :COMPONENTS[in,opt]: List of component names to add to the library. + *library[in]* - Create a new library interface target with the name specified in the - ``library`` option and link component targets to it based on the component - names provided in the ``COMPONENTS`` option. If ``COMPONENTS`` option is not - set, link component targets of all discovered components. + Name of the library interface to be created. - List of library properties + *COMPONENTS[in,opt]* - :LIBRARY_COMPONENTS: List of component as specified by the ``COMPONENTS`` - option. - :LIBRARY_COMPONENTS_LINKED: List of components linked to the library based - on recursive evaluations of the INTERFACE_LINK_LIBRARIES - and LINK_LIBRARIES target properties. + List of component names to add to the library. + + Create a new library interface target with the name specified in the + ``library`` option and link component targets to it based on the component + names provided in the ``COMPONENTS`` option. If ``COMPONENTS`` option is + not set, link component targets of all discovered components. + + List of library properties + + LIBRARY_COMPONENTS + List of component as specified by the ``COMPONENTS`` option. + + LIBRARY_COMPONENTS_LINKED + List of components linked to the library based on recursive evaluations + of the INTERFACE_LINK_LIBRARIES and LINK_LIBRARIES target properties. #]] function(idf_build_library library) set(options) @@ -382,24 +432,35 @@ endfunction() #[[api .. cmakev2:function:: idf_build_executable - .. code-block:: cmake + .. code-block:: cmake - idf_build_executable( - [COMPONENTS ...] - [NAME ] - [SUFFIX ]) + idf_build_executable( + [COMPONENTS ...] + [NAME ] + [SUFFIX ]) - :executable[in]: Name of the executable target to be created. - :COMPONENTS[in,opt]: List of component names to add to the library. - :NAME[in,opt]: Optional preferred generated binary name. If not provided, - the ``executable`` name is used. - :SUFFIX[in,opt]: Optional ``executable`` suffix. + *executable[in]* - Create a new executable target using the name specified in the - ``executable`` argument, and link it to the library created with the - component names provided in the ``COMPONENTS`` option. If the ``COMPONENTS`` - option is not set, all discovered components are added to the library. - Optinaly set the executable name and suffix. + Name of the executable target to be created. + + *COMPONENTS[in,opt]* + + List of component names to add to the library. + + *NAME[in,opt]* + + Optional preferred generated binary name. If not provided, the + ``executable`` name is used. + + *SUFFIX[in,opt]* + + Optional ``executable`` suffix. + + Create a new executable target using the name specified in the + ``executable`` argument, and link it to the library created with the + component names provided in the ``COMPONENTS`` option. If the + ``COMPONENTS`` option is not set, all discovered components are added to + the library. Optinaly set the executable name and suffix. #]] function(idf_build_executable executable) set(options) @@ -436,14 +497,19 @@ function(idf_build_executable executable) endfunction() #[[ - __get_components_metadata(COMPONENTS ... - OUTPUT ) + __get_components_metadata(COMPONENTS ... + OUTPUT ) - :COMPONENTS[in]: List of components for which to generate metadata. - :OUTPUT[out]: Output variable to store JSON metadata. + *COMPONENTS[in]* - Generate metadata in JSON format from ``COMPONENTS`` and store it in the - ``OUTPUT`` variable. + List of components for which to generate metadata. + + *OUTPUT[out]* + + Output variable to store JSON metadata. + + Generate metadata in JSON format from ``COMPONENTS`` and store it in the + ``OUTPUT`` variable. #]] function(__get_components_metadata) set(options) @@ -530,19 +596,23 @@ endfunction() #[[api .. cmakev2:function:: idf_build_generate_metadata - .. code-block:: cmake + .. code-block:: cmake - idf_build_generate_metadata( - [FILE ]) + idf_build_generate_metadata( + [FILE ]) - :executable[in]: Executable target for which to generate a metadata file. - :OUTPUT_FILE[in,opt]: Optional output file path for storing the metadata. If not - provided, the default path ``/project_description.json`` - is used. + *executable[in]* - Generate metadata for the specified ``executable`` and store it in the - specified ``FILE``. If no ``FILE`` is provided, the default location - ``/project_description.json`` will be used. + Executable target for which to generate a metadata file. + + *OUTPUT_FILE[in,opt]* + + Optional output file path for storing the metadata. If not provided, + the default path ``/project_description.json`` is used. + + Generate metadata for the specified ``executable`` and store it in the + specified ``FILE``. If no ``FILE`` is provided, the default location + ``/project_description.json`` will be used. #]] function(idf_build_generate_metadata executable) set(options) @@ -626,23 +696,30 @@ endfunction() #[[api .. cmakev2:function:: idf_build_binary - .. code-block:: cmake + .. code-block:: cmake - idf_build_binary( - TARGET - OUTPUT_FILE ) + idf_build_binary( + TARGET + OUTPUT_FILE ) - :executable[in]: Executable target for which to generate a binary image - file. - :TARGET[in]: The name of the target that will be created for the generated - binary image. - :OUTPUT_FILE[in]: Output file path for storing the binary image file. + *executable[in]* - Create a binary image for the specified ``executable`` target and save it in - the file specified with the `OUTPUT_FILE` option. A custom target named - ``TARGET`` will be created for the generated binary image. The path of the - generated binary image will be also stored in the ``BINARY_PATH`` property - of the ``TARGET``. + Executable target for which to generate a binary image file. + + *TARGET[in]* + + The name of the target that will be created for the generated binary + image. + + *OUTPUT_FILE[in]* + + Output file path for storing the binary image file. + + Create a binary image for the specified ``executable`` target and save it + in the file specified with the ``OUTPUT_FILE`` option. A custom target + named ``TARGET`` will be created for the generated binary image. The path + of the generated binary image will be also stored in the ``BINARY_PATH`` + property of the ``TARGET``. #]] function(idf_build_binary executable) set(options) @@ -714,29 +791,39 @@ endfunction() #[[api .. cmakev2:function:: idf_sign_binary - .. code-block:: cmake + .. code-block:: cmake - idf_sign_binary( - TARGET - OUTPUT_FILE - [KEYFILE ]) + idf_sign_binary( + TARGET + OUTPUT_FILE + [KEYFILE ]) - :binary[in]: Binary image target for which to generate a signed binary image - file. The ``binary`` target is created by the ``idf_build_binary`` - function. - :TARGET[in]: The name of the target that will be created for the - signed binary image. - :OUTPUT_FILE[in]: Output file path for storing the signed binary image file. - :KEYFILE[in,opt]: Optional path to the key file that should be used for - signing. If not provided, the key file specified by the - ``CONFIG_SECURE_BOOT_SIGNING_KEY`` configuration option - will be used. + *binary[in]* - Sign binary image specified by ``binary`` target with ``KEYFILE`` and save - it in the file specified with the `OUTPUT_FILE` option. A custom target - named ``TARGET`` will be created for the signed binary image. The path of - the signed binary image will be also stored in the ``BINARY_PATH`` property - of the ``TARGET``. + Binary image target for which to generate a signed binary image file. + The ``binary`` target is created by the :cmakev2:ref:`idf_build_binary` + function. + + *TARGET[in]* + + The name of the target that will be created for the signed binary + image. + + *OUTPUT_FILE[in]* + + Output file path for storing the signed binary image file. + + *KEYFILE[in,opt]* + + Optional path to the key file that should be used for signing. If not + provided, the key file specified by the + ``CONFIG_SECURE_BOOT_SIGNING_KEY`` configuration option will be used. + + Sign binary image specified by ``binary`` target with ``KEYFILE`` and save + it in the file specified with the `OUTPUT_FILE` option. A custom target + named ``TARGET`` will be created for the signed binary image. The path of + the signed binary image will be also stored in the ``BINARY_PATH`` property + of the ``TARGET``. #]] function(idf_sign_binary binary) set(options) @@ -805,28 +892,38 @@ endfunction() #[[api .. cmakev2:function:: idf_flash_binary - .. code-block:: cmake + .. code-block:: cmake - idf_flash_binary( - TARGET - [NAME ] - [FLASH]) + idf_flash_binary( + TARGET + [NAME ] + [FLASH]) - :binary[in]: Binary image target for which to create flash target. - The ``binary`` target is created by the ``idf_build_binary`` - function or ``idf_sign_binary``. - :TARGET[in]: The name of the flash target that will be created for the - binary image. - :NAME[in,opt]: An optional name to be used as a prefix for the file - containing arguments for esptool, and as a logical name - for the binary in ``flasher_args.json``. If not specified, - the name of the ``TARGET`` is used. - :FLASH[in,opt]: If specified, the binary will also be added to the global - ``flash`` target. + *binary[in]* - Create a new flash target for ``binary`` using the name specified in the - ``TARGET`` option. The file path of the binary image should be stored in the - ``BINARY_PATH`` property of the ``binary`` target. + Binary image target for which to create flash target. The ``binary`` + target is created by the :cmakev2:ref:`idf_build_binary` function or + :cmakev2:ref:`idf_sign_binary`. + + *TARGET[in]* + + The name of the flash target that will be created for the binary image. + + *NAME[in,opt]* + + An optional name to be used as a prefix for the file containing + arguments for esptool, and as a logical name for the binary in + ``flasher_args.json``. If not specified, the name of the ``TARGET`` is + used. + + *FLASH[in,opt]* + + If specified, the binary will also be added to the global ``flash`` + target. + + Create a new flash target for ``binary`` using the name specified in the + ``TARGET`` option. The file path of the binary image should be stored in + the ``BINARY_PATH`` property of the ``binary`` target. #]] function(idf_flash_binary binary) set(options FLASH) @@ -876,17 +973,19 @@ endfunction() #[[api .. cmakev2:function:: idf_check_binary_size - .. code-block:: cmake + .. code-block:: cmake - idf_check_binary_size() + idf_check_binary_size() - :binary[in]: Binary image target to which to add a partition size check. - The ``binary`` target is created by the ``idf_build_binary`` - or ``idf_sign_binary`` function. + *binary[in]* - Ensure that the generated binary image fits within the smallest available - application partition. The file path of the binary image should be stored in - the ``BINARY_PATH`` property of the ``binary`` target. + Binary image target to which to add a partition size check. The + ``binary`` target is created by the :cmakev2:ref:`idf_build_binary` or + :cmakev2:ref:`idf_sign_binary` function. + + Ensure that the generated binary image fits within the smallest available + application partition. The file path of the binary image should be stored + in the ``BINARY_PATH`` property of the ``binary`` target. #]] function(idf_check_binary_size binary) if(NOT CONFIG_APP_BUILD_TYPE_APP_2NDBOOT) @@ -908,18 +1007,20 @@ endfunction() #[[api .. cmakev2:function:: idf_check_binary_signed - .. code-block:: cmake + .. code-block:: cmake - idf_check_binary_signed() + idf_check_binary_signed() - :binary[in]: Binary image target to which to add a partition size check. - The ``binary`` target is created by the ``idf_build_binary``. + *binary[in]* - If the binary is not signed and signed applications are required with - CONFIG_SECURE_SIGNED_APPS, print a note indicating that the binary needs to - be signed manually. This situation can occur if the binary images are not - signed during the build because CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES is - not set. + Binary image target to which to add a partition size check. The + ``binary`` target is created by the ``idf_build_binary``. + + If the binary is not signed and signed applications are required with + CONFIG_SECURE_SIGNED_APPS, print a note indicating that the binary needs to + be signed manually. This situation can occur if the binary images are not + signed during the build because CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES is + not set. #]] function(idf_check_binary_signed binary) if(NOT CONFIG_SECURE_SIGNED_APPS) diff --git a/tools/cmakev2/compat.cmake b/tools/cmakev2/compat.cmake index dd14a1c132..da1a50c2ee 100644 --- a/tools/cmakev2/compat.cmake +++ b/tools/cmakev2/compat.cmake @@ -4,10 +4,10 @@ include_guard(GLOBAL) #[[ - check_expected_tool_version() + check_expected_tool_version() - Function to verify if the tool is using the expected version and issue a - warning if it is not. + Function to verify if the tool is using the expected version and issue a + warning if it is not. #]] function(check_expected_tool_version tool_name tool_path) set(tool_version_warning "Check Getting Started documentation or proceed at own risk.\n") @@ -54,25 +54,36 @@ function(check_expected_tool_version tool_name tool_path) endfunction() #[[ - __get_component_sources([SRCS ...] - [SRC_DIRS ...] - [EXCLUDE_SRCS ...] - OUTPUT ) + __get_component_sources([SRCS ...] + [SRC_DIRS ...] + [EXCLUDE_SRCS ...] + OUTPUT ) - :SRCS[in,opt]: Optional list of sources. - :SRC_DIRS[in,opt]: Option list of source directories. - :EXCLUDE_SRCS[in,opt]: Optional list of sources to exclude. - :OUTPUT[out]: Output variable to store the list of component sources. + *SRCS[in,opt]* - This helper function gathers component sources from the arguments specified - in either ``SRCS`` or ``SRC_DIRS``. If both are provided, the ``SRC_DIRS`` option - is disregarded. The sources are collected as absolute paths relative to the - component's directory. If ``EXCLUDE_SRCS`` is specified, the source files - listed in it are excluded. The final list of component sources is returned - in the ``OUTPUT`` variable. + Optional list of sources. - The ``COMPONENT_NAME`` and ``COMPONENT_DIR`` variables are provided by the - build system when ``idf_component_register`` is called. + *SRC_DIRS[in,opt]* + + Option list of source directories. + + *EXCLUDE_SRCS[in,opt]* + + Optional list of sources to exclude. + + *OUTPUT[out]* + + Output variable to store the list of component sources. + + This helper function gathers component sources from the arguments specified + in either ``SRCS`` or ``SRC_DIRS``. If both are provided, the ``SRC_DIRS`` + option is disregarded. The sources are collected as absolute paths relative + to the component's directory. If ``EXCLUDE_SRCS`` is specified, the source + files listed in it are excluded. The final list of component sources is + returned in the ``OUTPUT`` variable. + + The ``COMPONENT_NAME`` and ``COMPONENT_DIR`` variables are provided by the + build system when ``idf_component_register`` is called. #]] function(__get_component_sources) set(options) @@ -129,29 +140,39 @@ endfunction() #[[api .. cmakev2:function:: target_linker_script - .. code-block:: cmake + .. code-block:: cmake - target_linker_script( ... - [PROCESS ]) + target_linker_script( ... + [PROCESS ]) - :target[in]: The component target to which linker script files should be - added. - :deptype[in]: This option is obsolete and maintained solely for backward - compatibility. - :scriptfile[in]: Specifies the linker script file ``scriptfile`` to be added - to the link. Multiple files can be specified. - :PROCESS[in,opt]: Specifies the ``output`` linker script, which is generated - from the ``linkerscript`` template. The ``linkerscript`` - is processed with ldgen to produce the ``output``. + *target[in]* - This function adds one or more linker scripts to the specified component - target, incorporating the linker script into the linking process. + The component target to which linker script files should be added. - If the ``PROCESS`` option is specified, the last ``scriptfile`` listed is - processed using the ldgen command, and the generated ``output`` file is used - as the linker script during the linking process. This implies that with the - ``PROCESS`` option, it is logical to provide only a single ``scriptfile`` as - a template. + *deptype[in]* + + This option is obsolete and maintained solely for backward + compatibility. + + *scriptfile[in]* + + Specifies the linker script file ``scriptfile`` to be added to the + link. Multiple files can be specified. + + *PROCESS[in,opt]* + + Specifies the ``output`` linker script, which is generated from the + ``linkerscript`` template. The ``linkerscript`` is processed with ldgen + to produce the ``output``. + + This function adds one or more linker scripts to the specified component + target, incorporating the linker script into the linking process. + + If the ``PROCESS`` option is specified, the last ``scriptfile`` listed is + processed using the ldgen command, and the generated ``output`` file is + used as the linker script during the linking process. This implies that + with the ``PROCESS`` option, it is logical to provide only a single + ``scriptfile`` as a template. #]] function(target_linker_script target deptype scriptfiles) # The linker script files, templates, and their output filenames are stored @@ -177,15 +198,21 @@ endfunction() #[[api .. cmakev2:function:: idf_component_optional_requires - .. code-block:: cmake + .. code-block:: cmake - idf_component_optional_requires( ...) + idf_component_optional_requires( ...) - :type[in]: Type of dependency: PRIVATE, PUBLIC or INTERFACE - :component[in]: The component name that should be added as a dependency to - the evaluated component. It may be provided multiple times. + *type[in]* - Add a dependency on a specific component only if it is included in the build. + Type of dependency: PRIVATE, PUBLIC or INTERFACE + + *component[in]* + + The component name that should be added as a dependency to the + evaluated component. It may be provided multiple times. + + Add a dependency on a specific component only if it is included in the + build. #]] function(idf_component_optional_requires req_type) set(optional_reqs ${ARGN}) @@ -203,21 +230,21 @@ function(idf_component_optional_requires req_type) endfunction() #[[ - __init_common_components() + __init_common_components() - Identify the commonly required components based on the target and - architecture, and store them in the __COMPONENT_REQUIRES_COMMON build - property. Their interfaces are stored in the __COMMON_COMPONENT_INTERFACES - build property. The commonly required component interfaces are automatically - linked to each cmakev1 component added through the idf_component_register - function. + Identify the commonly required components based on the target and + architecture, and store them in the __COMPONENT_REQUIRES_COMMON build + property. Their interfaces are stored in the __COMMON_COMPONENT_INTERFACES + build property. The commonly required component interfaces are + automatically linked to each cmakev1 component added through the + idf_component_register function. - This function is called from the idf_component_register function and is - evaluated only once per project, as ensured by the - __COMMON_COMPONENTS_INITIALIZED build property. The cmakev2 components are - expected to properly specify all their dependencies, rather than relying on - common components to be automatically linked to them. Therefore, the common - components are relevant only within the context of cmakev1 components. + This function is called from the idf_component_register function and is + evaluated only once per project, as ensured by the + __COMMON_COMPONENTS_INITIALIZED build property. The cmakev2 components are + expected to properly specify all their dependencies, rather than relying on + common components to be automatically linked to them. Therefore, the common + components are relevant only within the context of cmakev1 components. #]] function(__init_common_components) idf_build_get_property(common_components_initialized __COMMON_COMPONENTS_INITIALIZED) @@ -258,47 +285,84 @@ endfunction() #[[api .. cmakev2:function:: idf_component_register - .. code-block:: cmake + .. code-block:: cmake - idf_component_register([SRCS ..] - [SRC_DIRS ...] - [EXCLUDE_SRCS ...] - [INCLUDE_DIRS ...] - [PRIV_INCLUDE_DIRS ...] - [LDFRAGMENTS ...] - [REQUIRES ...] - [PRIV_REQUIRES ...] - [REQUIRED_IDF_TARGETS ...] - [EMBED_FILES ...] - [EMBED_TXTFILES ...] - [KCONFIG ] - [KCONFIG_PROJBUILD ] - [WHOLE_ARCHIVE]) + idf_component_register([SRCS ..] + [SRC_DIRS ...] + [EXCLUDE_SRCS ...] + [INCLUDE_DIRS ...] + [PRIV_INCLUDE_DIRS ...] + [LDFRAGMENTS ...] + [REQUIRES ...] + [PRIV_REQUIRES ...] + [REQUIRED_IDF_TARGETS ...] + [EMBED_FILES ...] + [EMBED_TXTFILES ...] + [KCONFIG ] + [KCONFIG_PROJBUILD ] + [WHOLE_ARCHIVE]) - :SRCS[in,opt]: List of source files for the component. - :SRC_DIRS[in,opt]: List of source directories to search for source files - (.c, .cpp, .S); ignored when SRCS is specified. - :EXCLUDE_SRCS[in,opt]: List of source files to exclude from the designated - source directories. - :INCLUDE_DIRS[in,opt]: List of public include directories for the created - component library. - :PRIV_INCLUDE_DIRS[in,opt]: List of private include directories for the - newly created component library. - :LDFRAGMENTS[in,opt]: List of linker script fragments for the component. - :REQUIRES[in,opt]: List of publicly required components based on usage - requirements. - :PRIV_REQUIRES[in,opt]: List of privately required components based on usage - requirements or components needed solely for functions - or values defined in project_include.cmake. - :REQUIRED_IDF_TARGETS[in,opt]: List of IDF build targets supported - exclusively by the component. - :EMBED_FILES[in,opt]: List of binary files to embed with the component. - :EMBED_TXTFILES[in,opt]: List of text files to embed with the component. - :WHOLE_ARCHIVE[in,opt]: Link the component as --whole-archive. - :KCONFIG[in,opt]: Obsolete. - :KCONFIG_PROJBUILD[in,opt]: Obsolete. + *SRCS[in,opt]* - Register a component with the build system. + List of source files for the component. + + *SRC_DIRS[in,opt]* + + List of source directories to search for source files (.c, .cpp, .S); + ignored when SRCS is specified. + + *EXCLUDE_SRCS[in,opt]* + + List of source files to exclude from the designated source directories. + + *INCLUDE_DIRS[in,opt]* + + List of public include directories for the created component library. + + *PRIV_INCLUDE_DIRS[in,opt]* + + List of private include directories for the newly created component + library. + + *LDFRAGMENTS[in,opt]* + + List of linker script fragments for the component. + + *REQUIRES[in,opt]* + + List of publicly required components based on usage requirements. + + *PRIV_REQUIRES[in,opt]* + + List of privately required components based on usage requirements or + components needed solely for functions or values defined in + project_include.cmake. + + *REQUIRED_IDF_TARGETS[in,opt]* + + List of IDF build targets supported exclusively by the component. + + *EMBED_FILES[in,opt]* + + List of binary files to embed with the component. + + *EMBED_TXTFILES[in,opt]* + + List of text files to embed with the component. + + *WHOLE_ARCHIVE[in,opt]* + + Link the component as --whole-archive. + + *KCONFIG[in,opt]* + + Obsolete. + + *KCONFIG_PROJBUILD[in,opt]* + + Obsolete. + + Register a component with the build system. #]] function(idf_component_register) set(options WHOLE_ARCHIVE) @@ -439,19 +503,28 @@ endfunction() #[[api .. cmakev2:function:: idf_build_component - .. code-block:: cmake + .. code-block:: cmake - idf_build_component( []) + idf_build_component( []) - :component_dir[in]: Directory path of the component. - :component_source[in,opt]: Source of the component. One of: - "idf_components", "project_managed_components", - "project_extra_components", "project_components". - Defaults to "project_components". + *component_dir[in]* - Compatibility shim used by generated files (e.g. managed_components_list) - that initializes the component in build system v2 by delegating to - ``__init_component``. + Directory path of the component. + + *component_source[in,opt]* + + Source of the component. One of: + + * ``idf_components`` + * ``project_managed_components`` + * ``project_extra_components`` + * ``project_components`` + + Defaults to ``project_components``. + + Compatibility shim used by generated files (e.g. managed_components_list) + that initializes the component in build system v2 by delegating to + ``__init_component``. #]] function(idf_build_component component_dir) if(${ARGC} EQUAL 1) diff --git a/tools/cmakev2/component.cmake b/tools/cmakev2/component.cmake index 0c0c053ad0..dcb72daca3 100644 --- a/tools/cmakev2/component.cmake +++ b/tools/cmakev2/component.cmake @@ -10,19 +10,29 @@ include(kconfig) #[[api .. cmakev2:function:: idf_component_set_property - .. code-block:: cmake + .. code-block:: cmake - idf_component_set_property( [APPEND]) + idf_component_set_property( [APPEND]) - :component[in]: Component name, target, target alias or interface. - :property[in]: Property name. - :value[in]: Property value. - :APPEND: Append the value to the property's current value instead of - replacing it. + *component[in]* - Set the value of the specified component property. The property is also - added to the internal list of component properties if it isn't already - there. + Component name, target, target alias or interface. + + *property[in]* + + Property name. + + *value[in]* + + Property value. + + *APPEND* + Append the value to the property's current value instead of replacing + it. + + Set the value of the specified component property. The property is also + added to the internal list of component properties if it isn't already + there. #]] function(idf_component_set_property component property value) set(options APPEND) @@ -46,17 +56,28 @@ endfunction() #[[api .. cmakev2:function:: idf_component_get_property - .. code-block:: cmake + .. code-block:: cmake - idf_component_get_property( [GENERATOR_EXPRESSION]) + idf_component_get_property( [GENERATOR_EXPRESSION]) - :variable[out]: Variable to store the value in. - :component[in]: Component name, target, target alias or interface. - :property[in]: Property name to get the value of. - :GENERATOR_EXPRESSION: Obtain the generator expression for the property - rather than the actual value. + *variable[out]* - Retrieve the value of the specified component property. + Variable to store the value in. + + *component[in]* + + Component name, target, target alias or interface. + + *property[in]* + + Property name to get the value of. + + *GENERATOR_EXPRESSION* + + Obtain the generator expression for the property rather than the actual + value. + + Retrieve the value of the specified component property. #]] function(idf_component_get_property variable component property) set(options GENERATOR_EXPRESSION) @@ -78,26 +99,39 @@ function(idf_component_get_property variable component property) endfunction() #[[ - __get_component_paths(PATHS ... - [EXCLUDE_PATHS ...] - [SOURCE ] - [CHECK] - OUTPUT ) + __get_component_paths(PATHS ... + [EXCLUDE_PATHS ...] + [SOURCE ] + [CHECK] + OUTPUT ) - :PATHS[in]: List of paths to search for component directories. - :EXCLUDE_PATHS[in,opt]: Optional list of paths to exclude from the search of - component directories. - :SOURCE[in,opt]: Source of the ``PATHS``. If provided, it will be included - in the error message when ``CHECK`` is specified. - :CHECK[in,opt]: Verify whether the paths listed in "PATHS" exist. If any - path is missing, abort the build process. - :OUTPUT[out]: Output variable to store the list of found component - directories. + *PATHS[in]* - Search for component directories in the specified ``PATHS``, excluding those - in ``EXCLUDE_PATHS``, and store the list of absolute component paths in the - ``OUTPUT`` variable. If ``CHECK`` is specified, ensure that the paths listed - in ``PATHS`` exist, and stop the build process if they do not. + List of paths to search for component directories. + + *EXCLUDE_PATHS[in,opt]* + + Optional list of paths to exclude from the search of component + directories. + + *SOURCE[in,opt]* + + Source of the ``PATHS``. If provided, it will be included in the error + message when ``CHECK`` is specified. + + *CHECK[in,opt]* + + Verify whether the paths listed in "PATHS" exist. If any path is + missing, abort the build process. + + *OUTPUT[out]* + + Output variable to store the list of found component directories. + + Search for component directories in the specified ``PATHS``, excluding + those in ``EXCLUDE_PATHS``, and store the list of absolute component paths + in the ``OUTPUT`` variable. If ``CHECK`` is specified, ensure that the + paths listed in ``PATHS`` exist, and stop the build process if they do not. #]] function(__get_component_paths) set(options CHECK) @@ -155,17 +189,22 @@ endfunction() __get_component_interface(COMPONENT OUTPUT ) - :COMPONENT[int]: Component name, target, target alias or interface. - :OUTPUT[out]: Output variable to store the component interface. + *COMPONENT[int]* - Identify the component interface target using the ```` value, - which could be a component name, target, target alias, or interface. Return - the component interface target, or NOTFOUND if the interface cannot be - located. + Component name, target, target alias or interface. - component interface: _ - component target: __ - component alias: :: + *OUTPUT[out]* + + Output variable to store the component interface. + + Identify the component interface target using the ```` value, + which could be a component name, target, target alias, or interface. Return + the component interface target, or NOTFOUND if the interface cannot be + located. + + component interface: _ + component target: __ + component alias: :: #]] function(__get_component_interface) set(options) @@ -227,11 +266,16 @@ endfunction() __get_component_interface_or_die(COMPONENT OUTPUT ) - :COMPONENT[in]: Component name, target, target alias or interface. - :OUTPUT[out]: Output variable to store the component interface. + *COMPONENT[in]* - A simple wrapper for ``__get_component_interface`` that aborts the build - process if the component interface is not found. + Component name, target, target alias or interface. + + *OUTPUT[out]* + + Output variable to store the component interface. + + A simple wrapper for ``__get_component_interface`` that aborts the build + process if the component interface is not found. #]] function(__get_component_interface_or_die) set(options) @@ -255,15 +299,20 @@ function(__get_component_interface_or_die) endfunction() #[[ - __get_component_priority(SOURCE - OUTPUT ) + __get_component_priority(SOURCE + OUTPUT ) - :SOURCE[in]: String identifying the component source. - :OUTPUT[out]: Output variable to store the component priority. + *SOURCE[in]* - Return the priority number of a component, where a higher number indicates a - higher priority, based on the given ``source`` string. If the ``source`` is - not valid, return ``NOTFOUND``. + String identifying the component source. + + *OUTPUT[out]* + + Output variable to store the component priority. + + Return the priority number of a component, where a higher number indicates + a higher priority, based on the given ``source`` string. If the ``source`` + is not valid, return ``NOTFOUND``. #]] function(__get_component_priority) set(options) @@ -295,36 +344,44 @@ function(__get_component_priority) endfunction() #[[ - __init_component(DIRECTORY - PREFIX - SOURCE ) + __init_component(DIRECTORY + PREFIX + SOURCE ) - :DIRECTORY[in]: ```` where the component is located. - :PREFIX[in]: Prefix for component target names. - :SOURCE[in]: String identifying the component source. + *DIRECTORY[in]* - Initialize the component by creating a component interface target, allowing - properties to be attached to it and also add initial component properties. - At this stage, the component is not included in the build. The actual - component target, named as specified in the `COMPONENT_LIB` property, is - created later when ``add_subdirectory`` is called for the component's - directory based on the project or other component requirements. + ```` where the component is located. - Components are identified by the directory name they reside in. This means - that components with the same name might exist in different directory paths. - In such cases, the component with the higher priority is used. Priority is - determined by the component's source, as defined in - ``__get_component_priority``. If a component with a higher priority than an - existing one is initialized, its name, targets, and other properties remain - the same. Only the directory, priority, and source are updated in the - already initialized component. + *PREFIX[in]* - The name of the initialized component is added to the - ``COMPONENTS_DISCOVERED`` build property, and its interface target is added - to the ``COMPONENT_INTERFACES`` build property. These two lists are used by - ``__get_component_interface``, which searches for a component interface - based on the component name, alias, or targets, enabling the setting and - retrieval of component properties. + Prefix for component target names. + + *SOURCE[in]* + + String identifying the component source. + + Initialize the component by creating a component interface target, allowing + properties to be attached to it and also add initial component properties. + At this stage, the component is not included in the build. The actual + component target, named as specified in the `COMPONENT_LIB` property, is + created later when ``add_subdirectory`` is called for the component's + directory based on the project or other component requirements. + + Components are identified by the directory name they reside in. This means + that components with the same name might exist in different directory + paths. In such cases, the component with the higher priority is used. + Priority is determined by the component's source, as defined in + ``__get_component_priority``. If a component with a higher priority than an + existing one is initialized, its name, targets, and other properties remain + the same. Only the directory, priority, and source are updated in the + already initialized component. + + The name of the initialized component is added to the + ``COMPONENTS_DISCOVERED`` build property, and its interface target is added + to the ``COMPONENT_INTERFACES`` build property. These two lists are used by + ``__get_component_interface``, which searches for a component interface + based on the component name, alias, or targets, enabling the setting and + retrieval of component properties. #]] function(__init_component) set(options) @@ -455,11 +512,13 @@ function(__init_component) endfunction() #[[ - __dump_component_properties() + __dump_component_properties() - :components: List of components whose properties should be displayed. + *components[in]* - Dump all properties for the components listed in ````. + List of components whose properties should be displayed. + + Dump all properties for the components listed in ``components``. #]] function(__dump_component_properties components) foreach(component IN LISTS components) @@ -473,16 +532,21 @@ function(__dump_component_properties components) endfunction() #[[ - __component_name_without_namespace(COMPONENT - OUTPUT ) + __component_name_without_namespace(COMPONENT + OUTPUT ) - :COMPONENT[in]: Component name that may include namespace. - :OUTPUT[out]: Output variable to store the component name without namespace. + *COMPONENT[in]* - Extract the component name without namespace. For example: - - "espressif__led_strip" -> "led_strip" - - "led_strip" -> "led_strip" - This follows the same logic as the component manager's name_without_namespace function. + Component name that may include namespace. + + *OUTPUT[out]* + + Output variable to store the component name without namespace. + + Extract the component name without namespace. For example: + - "espressif__led_strip" -> "led_strip" + - "led_strip" -> "led_strip" This follows the same logic as the component + manager's name_without_namespace function. #]] function(__component_name_without_namespace) set(options) @@ -512,25 +576,33 @@ function(__component_name_without_namespace) endfunction() #[[ - __resolve_component_name(COMPONENT - KNOWN_COMPONENTS - OUTPUT ) + __resolve_component_name(COMPONENT + KNOWN_COMPONENTS + OUTPUT ) - :COMPONENT[in]: Component name to resolve (may be short name or canonical). - :KNOWN_COMPONENTS[in]: List of known/discovered component names. - :OUTPUT[out]: Output variable to store the resolved component name. + *COMPONENT[in]* - Resolve a component name to its canonical form by checking against known components. - This implements the same logic as the component manager's _choose_component function: - 1. If the exact name exists in known components, return it - 2. If a namespaced version exists (e.g., "espressif__led_strip" for "led_strip"), return that - 3. If a non-namespaced version exists (e.g., "led_strip" for "espressif__led_strip"), return that - 4. If any known component has the same name without namespace , return that - 5. Otherwise, return the original name (will likely cause CMake error) + Component name to resolve (may be short name or canonical). - This function takes component priority into account by preferring components - with higher priority when multiple matches exist. This behavior differs from - the component manager's _choose_component function. + *KNOWN_COMPONENTS[in]* + + List of known/discovered component names. + + *OUTPUT[out]* + + Output variable to store the resolved component name. + + Resolve a component name to its canonical form by checking against known components. + This implements the same logic as the component manager's _choose_component function: + 1. If the exact name exists in known components, return it + 2. If a namespaced version exists (e.g., "espressif__led_strip" for "led_strip"), return that + 3. If a non-namespaced version exists (e.g., "led_strip" for "espressif__led_strip"), return that + 4. If any known component has the same name without namespace , return that + 5. Otherwise, return the original name (will likely cause CMake error) + + This function takes component priority into account by preferring + components with higher priority when multiple matches exist. This behavior + differs from the component manager's _choose_component function. #]] function(__resolve_component_name) set(options) @@ -622,27 +694,32 @@ endfunction() #[[api .. cmakev2:function:: idf_component_include - .. code-block:: cmake + .. code-block:: cmake - idf_component_include( - [INTERFACE ]) + idf_component_include( + [INTERFACE ]) - :name[in]: Component name. - :INTERFACE[out,opt]: Optional variable where the name of the target - interface for the included component will be stored. + *name[in]* - This is a core function of the build system, responsible for including the - specified component, as indicated by the ```` option, into the build - process. It does this by evaluating the component through the - ``add_subdirectory`` call for the component's directory. The component is - responsible for creating its own CMake target, with the target name provided - via the ``COMPONENT_TARGET`` variable. This target is linked to the - component's interface target, which is managed internally by the build - system. The component's interface target is used by other components to - establish their dependencies. + Component name. - When the "INTERFACE" variable is provided, the name of the included - component interface target will be stored in it. + *INTERFACE[out,opt]* + + Optional variable where the name of the target interface for the + included component will be stored. + + This is a core function of the build system, responsible for including the + specified component, as indicated by the ``name`` option, into the build + process. It does this by evaluating the component through the + ``add_subdirectory`` call for the component's directory. The component is + responsible for creating its own CMake target, with the target name + provided via the ``COMPONENT_TARGET`` variable. This target is linked to + the component's interface target, which is managed internally by the build + system. The component's interface target is used by other components to + establish their dependencies. + + When the ``INTERFACE`` variable is provided, the name of the included + component interface target will be stored in it. #]] function(idf_component_include name) set(options) diff --git a/tools/cmakev2/idf.cmake b/tools/cmakev2/idf.cmake index f84c595fa1..61bbe81874 100644 --- a/tools/cmakev2/idf.cmake +++ b/tools/cmakev2/idf.cmake @@ -41,10 +41,10 @@ include(GetGitRevisionDescription) include(ExternalProject) #[[ - __init_build_version() + __init_build_version() - Set the global variables IDF_BUILD_V2, IDF_BUILD_VER and IDF_BUILD_VER_TAG, - as well as the build properties and environmental variables. + Set the global variables IDF_BUILD_V2, IDF_BUILD_VER and IDF_BUILD_VER_TAG, + as well as the build properties and environmental variables. #]] function(__init_build_version) set(IDF_BUILD_V2 y PARENT_SCOPE) @@ -59,13 +59,13 @@ function(__init_build_version) endfunction() #[[ - __init_idf_path() + __init_idf_path() - Determine the IDF_PATH value, either from the IDF_PATH environmental - variable or based on the location of this file. Also check there is no - inconsistency between the two. + Determine the IDF_PATH value, either from the IDF_PATH environmental + variable or based on the location of this file. Also check there is no + inconsistency between the two. - Set the IDF_PATH global variable, environment variable and build property. + Set the IDF_PATH global variable, environment variable and build property. #]] function(__init_idf_path) get_filename_component(idf_path_infer "${CMAKE_CURRENT_LIST_DIR}/../.." REALPATH) @@ -91,11 +91,11 @@ function(__init_idf_path) endfunction() #[[ - __init_git() + __init_git() - Determine the executable. + Determine the executable. - Set the GIT build property. + Set the GIT build property. #]] function(__init_git) find_package(Git) @@ -109,13 +109,13 @@ function(__init_git) endfunction() #[[ - __init_idf_version() + __init_idf_version() - Determine the IDF version from the version.txt file. If it is not present, - use git-describe. If both previous attempts fail, use the IDF_VERSION from - the environment variables as a fallback. + Determine the IDF version from the version.txt file. If it is not present, + use git-describe. If both previous attempts fail, use the IDF_VERSION from + the environment variables as a fallback. - Set IDF_VER build property. + Set IDF_VER build property. #]] function(__init_idf_version) idf_build_get_property(idf_path IDF_PATH) @@ -138,16 +138,16 @@ function(__init_idf_version) endfunction() #[[ - __init_python() + __init_python() - Determine Python interpreter, either from the PYTHON CMake cache variable - or environmental variable or default it to "python". + Determine Python interpreter, either from the PYTHON CMake cache variable + or environmental variable or default it to "python". - If the PYTHON_DEPS_CHECKED CMake cache variable is not set, check if all - Python packages dependencies are satisfied. For instance, if a tool calling - CMake has already performed this check, it doesn't need to be repeated. + If the PYTHON_DEPS_CHECKED CMake cache variable is not set, check if all + Python packages dependencies are satisfied. For instance, if a tool calling + CMake has already performed this check, it doesn't need to be repeated. - Set the global PYTHON variable, environment variable and build property. + Set the global PYTHON variable, environment variable and build property. #]] function(__init_python) __get_default_value(VARIABLE PYTHON @@ -182,15 +182,15 @@ function(__init_python) endfunction() #[[ - __init_idf_target() + __init_idf_target() - Determine the IDF_TARGET value from the IDF_TARGET environment variable, the - CMake cache variable, or the sdkconfig files. If none of these are set, - use the default esp32 target. Ensure there are no inconsistencies in the - IDF_TARGET values set in different locations. + Determine the IDF_TARGET value from the IDF_TARGET environment variable, + the CMake cache variable, or the sdkconfig files. If none of these are set, + use the default esp32 target. Ensure there are no inconsistencies in the + IDF_TARGET values set in different locations. - Set the IDF_TARGET as a global variable, in the CMake cache, as an - environment variable, and as a build property. + Set the IDF_TARGET as a global variable, in the CMake cache, as an + environment variable, and as a build property. #]] function(__init_idf_target) set(sdkconfig_target "") @@ -256,18 +256,18 @@ function(__init_idf_target) endfunction() #[[ - __init_toolchain() + __init_toolchain() - Determine the IDF_TOOLCHAIN value from the IDF_TOOLCHAIN environment - variable or the CMake cache variable. If none of these are set, use the - default gcc toolchain. Ensure there are no inconsistencies in the - IDF_TOOLCHAIN values set in different locations. Also ensure that the - CMAKE_TOOLCHAIN_FILE is set to the correct file according to the current - IDF_TARGET. + Determine the IDF_TOOLCHAIN value from the IDF_TOOLCHAIN environment + variable or the CMake cache variable. If none of these are set, use the + default gcc toolchain. Ensure there are no inconsistencies in the + IDF_TOOLCHAIN values set in different locations. Also ensure that the + CMAKE_TOOLCHAIN_FILE is set to the correct file according to the current + IDF_TARGET. - Set the IDF_TOOLCHAIN and IDF_TOOLCHAIN_FILE build properties. Also, - configure the IDF_TOOLCHAIN CMake cache variable and set the - CMAKE_TOOLCHAIN_FILE global variable. + Set the IDF_TOOLCHAIN and IDF_TOOLCHAIN_FILE build properties. Also, + configure the IDF_TOOLCHAIN CMake cache variable and set the + CMAKE_TOOLCHAIN_FILE global variable. #]] function(__init_toolchain) set(cache_toolchain $CACHE{IDF_TOOLCHAIN}) @@ -317,9 +317,9 @@ function(__init_toolchain) endfunction() #[[ - __init_ccache() + __init_ccache() - Enable ccache if requested through CCACHE_ENABLE. + Enable ccache if requested through CCACHE_ENABLE. #]] function(__init_ccache) if(NOT CCACHE_ENABLE) @@ -336,25 +336,28 @@ function(__init_ccache) endfunction() #[[ - __init_components() + __init_components() - Search for possible component directories categorized by their source, which - could be ``idf_components``, ``project_extra_components``, or - ``project_components``. Components added by the component manager are - initialized later as ``project_managed_components`` after the component - manager is called. + Search for possible component directories categorized by their source, + which could be ``idf_components``, ``project_extra_components``, or + ``project_components``. Components added by the component manager are + initialized later as ``project_managed_components`` after the component + manager is called. - The search respects the variables set by the user e.g. in the project's - CMakeLists.txt file. These are maintained for backward compatibility. + The search respects the variables set by the user e.g. in the project's + CMakeLists.txt file. These are maintained for backward compatibility. - :COMPONENT_DIRS: If set, component directories are searched exclusively in - the paths provided in ``COMPONENT_DIRS``. - :EXTRA_COMPONENT_DIRS: Includes extra paths to search if ``COMPONENT_DIRS`` - is not specified. - :EXTRA_COMPONENT_EXCLUDE_DIRS: List of paths to exclude from searching the - component directories. + COMPONENT_DIRS + If set, component directories are searched exclusively in the paths + provided in ``COMPONENT_DIRS``. - Each component is initialized for every component directory found. + EXTRA_COMPONENT_DIRS + Includes extra paths to search if ``COMPONENT_DIRS`` is not specified. + + EXTRA_COMPONENT_EXCLUDE_DIRS + List of paths to exclude from searching the component directories. + + Each component is initialized for every component directory found. #]] function(__init_components) idf_build_get_property(idf_path IDF_PATH) @@ -407,10 +410,10 @@ function(__init_components) endfunction() #[[ - __init_submodules() + __init_submodules() - Initialize submodules that are not yet initialized, and issue a warning for - submodules that do not match the recorded hash in the git tree. + Initialize submodules that are not yet initialized, and issue a warning for + submodules that do not match the recorded hash in the git tree. #]] function(__init_submodules) idf_build_get_property(idf_path IDF_PATH) @@ -490,11 +493,11 @@ function(__init_submodules) endfunction() #[[ - __init_idf_target_arch() + __init_idf_target_arch() - Set the IDF_TARGET_ARCH value based on the sdkconfig. This means it must be - initialized after the sdkconfig is generated and its CMake version is - included. + Set the IDF_TARGET_ARCH value based on the sdkconfig. This means it must be + initialized after the sdkconfig is generated and its CMake version is + included. #]] function(__init_idf_target_arch) if(CONFIG_IDF_TARGET_ARCH_XTENSA) @@ -508,39 +511,41 @@ function(__init_idf_target_arch) endfunction() #[[ - The idf_build_properties interface target is exclusively used to store - information about global build properties and is not linked or used in any - other way. This is created very early so that all the initialization - functions can use it. + The idf_build_properties interface target is exclusively used to store + information about global build properties and is not linked or used in any + other way. This is created very early so that all the initialization + functions can use it. - List of build properties + List of build properties - :IDF_PATH: Path to esp-idf directory. - :PREFIX: Prefix used for component target names. - :COMPONENTS_DISCOVERED: List of component names identified by the build - system. These components are initialized and can - have properties attached to them. However, they - are not necessarily included in the build through - add_subdirectory. + IDF_PATH + Path to esp-idf directory. - :COMPONENT_INTERFACES: This is a list of component interface targets for - the components in ``COMPONENTS_DISCOVERED``. It is - used when searching for a component, such as by its - name, to set or retrieve the component's properties. + PREFIX + Prefix used for component target names. - :COMPONENTS_INCLUDED: This is a list of component names that were included - in the build, meaning their CMakeLists.txt files were - processed with an add_subdirectory call. Each - component is evaluated exactly once, and this list - serves as a record of which components have already - been evaluated. Although each component can only be - evaluated once, it can be used in multiple - idf_component_include calls. If a component is - requested to be included a second time, this list is - checked. If the component is already included, the - idf_component_include function simply returns, as - there is nothing further to do except add a new alias - target if requested. + COMPONENTS_DISCOVERED + List of component names identified by the build system. These + components are initialized and can have properties attached to them. + However, they are not necessarily included in the build through + add_subdirectory. + + COMPONENT_INTERFACES + This is a list of component interface targets for the components in + ``COMPONENTS_DISCOVERED``. It is used when searching for a component, + such as by its name, to set or retrieve the component's properties. + + COMPONENTS_INCLUDED + This is a list of component names that were included in the build, + meaning their CMakeLists.txt files were processed with an + add_subdirectory call. Each component is evaluated exactly once, and + this list serves as a record of which components have already been + evaluated. Although each component can only be evaluated once, it can + be used in multiple idf_component_include calls. If a component is + requested to be included a second time, this list is checked. If the + component is already included, the idf_component_include function + simply returns, as there is nothing further to do except add a new + alias target if requested. #]] add_library(idf_build_properties INTERFACE) diff --git a/tools/cmakev2/kconfig.cmake b/tools/cmakev2/kconfig.cmake index 65fb011aa4..54489161bf 100644 --- a/tools/cmakev2/kconfig.cmake +++ b/tools/cmakev2/kconfig.cmake @@ -11,16 +11,19 @@ include(build) include(component) #[[ - __init_kconfig() + __init_kconfig() - Initialize the Kconfig system infrastructure for the build. - This function performs the Kconfig initialization and setup by: - 1. Setting up SDKCONFIG and SDKCONFIG_DEFAULTS build properties - 2. Setting up ESP-IDF root Kconfig files and config directory - 3. Creating the default config directory + Initialize the Kconfig system infrastructure for the build. This function + performs the Kconfig initialization and setup by: + 1. Setting up SDKCONFIG and SDKCONFIG_DEFAULTS build properties + 2. Setting up ESP-IDF root Kconfig files and config directory + 3. Creating the default config directory - This should be called after component discovery but before component manager. - Note: Regular component Kconfig files are collected during component discovery. + This should be called after component discovery but before component + manager. + + Note: Regular component Kconfig files are collected during component + discovery. #]] function(__init_kconfig) idf_build_get_property(idf_path IDF_PATH) @@ -66,13 +69,13 @@ function(__init_kconfig) endfunction() #[[ - __generate_sdkconfig() + __generate_sdkconfig() - This function performs the complete Kconfig generation process: - 1. Collect Kconfig files from discovered components - 2. Collect Kconfig files from bootloader components - 3. Set up the Kconfig environment with all collected files - 4. Generate all output files (sdkconfig.h, sdkconfig.cmake, etc.) + This function performs the complete Kconfig generation process: + 1. Collect Kconfig files from discovered components + 2. Collect Kconfig files from bootloader components + 3. Set up the Kconfig environment with all collected files + 4. Generate all output files (sdkconfig.h, sdkconfig.cmake, etc.) #]] function(__generate_sdkconfig) idf_msg("Generating sdkconfig configuration...") @@ -97,12 +100,13 @@ endfunction() # ============================================================================= #[[ - __consolidate_component_kconfig_files() + __consolidate_component_kconfig_files() - Consolidate Kconfig files from discovered components into global build properties. - This scans the COMPONENTS_DISCOVERED build property and for each component, - retrieves its Kconfig files from component properties and adds them to the - global __KCONFIGS, __KCONFIG_PROJBUILDS, and __SDKCONFIG_RENAMES build properties. + Consolidate Kconfig files from discovered components into global build + properties. This scans the COMPONENTS_DISCOVERED build property and for + each component, retrieves its Kconfig files from component properties and + adds them to the global __KCONFIGS, __KCONFIG_PROJBUILDS, and + __SDKCONFIG_RENAMES build properties. #]] function(__consolidate_component_kconfig_files) idf_build_get_property(components_discovered COMPONENTS_DISCOVERED) @@ -153,11 +157,12 @@ function(__consolidate_component_kconfig_files) endfunction() #[[ - __collect_kconfig_files_from_bootloader_components() + __collect_kconfig_files_from_bootloader_components() - Collect Kconfig files from bootloader components and store them in build properties. - Bootloader components are located in the bootloader_components directory of the project. - This function only runs if the bootloader component is discovered. + Collect Kconfig files from bootloader components and store them in build + properties. Bootloader components are located in the bootloader_components + directory of the project. This function only runs if the bootloader + component is discovered. #]] function(__collect_kconfig_files_from_bootloader_components) # Check if bootloader component is discovered - only then collect bootloader components @@ -191,15 +196,29 @@ function(__collect_kconfig_files_from_bootloader_components) endfunction() #[[ - __collect_kconfig_files_from_directory(directory target out_kconfigs out_projbuilds out_renames) + __collect_kconfig_files_from_directory(directory target out_kconfigs out_projbuilds out_renames) - Collect Kconfig files from a single directory. + Collect Kconfig files from a single directory. - :directory[in]: Path to the directory to collect Kconfig files from. - :target[in]: Target name for target-specific files. - :out_kconfigs[out]: List of Kconfig files. - :out_projbuilds[out]: List of projbuild files. - :out_renames[out]: List of rename files. + *directory[in]* + + Path to the directory to collect Kconfig files from. + + *target[in]* + + Target name for target-specific files. + + *out_kconfigs[out]* + + List of Kconfig files. + + *out_projbuilds[out]* + + List of projbuild files. + + *out_renames[out]* + + List of rename files. #]] function(__collect_kconfig_files_from_directory directory target out_kconfigs out_projbuilds out_renames) file(GLOB all_files "${directory}/*") @@ -256,10 +275,10 @@ endfunction() # ============================================================================= #[[ - __setup_kconfig_environment() + __setup_kconfig_environment() - Setup the Kconfig environment for kconfgen. - This function creates the environment and prepares Kconfig source files. + Setup the Kconfig environment for kconfgen. This function creates the + environment and prepares Kconfig source files. #]] function(__setup_kconfig_environment) # Create the config.env file, which contains all environment variables for the python script @@ -293,13 +312,16 @@ endfunction() #[[ - __create_config_env_file(env_path) + __create_config_env_file(env_path) - Create config environment file for kconfgen. - This function gathers all necessary properties and creates the config.env file - used by the kconfgen Python script. + *env_path[in]* + + Path where to create the config.env file. + + Create config environment file for kconfgen. This function gathers all + necessary properties and creates the config.env file used by the kconfgen + Python script. - :env_path[in]: Path where to create the config.env file. #]] function(__create_config_env_file env_path) # Get all necessary build properties @@ -368,12 +390,12 @@ endfunction() # ============================================================================= #[[ - __generate_kconfig_outputs() + __generate_kconfig_outputs() - Generate all Kconfig output files. - Generates: sdkconfig.h, sdkconfig.cmake, sdkconfig.json, kconfig_menus.json + Generate all Kconfig output files. + Generates: sdkconfig.h, sdkconfig.cmake, sdkconfig.json, kconfig_menus.json - Must be called after __setup_kconfig_environment(). + Must be called after __setup_kconfig_environment(). #]] function(__generate_kconfig_outputs) # Get inputs from build properties @@ -435,12 +457,18 @@ function(__generate_kconfig_outputs) endfunction() #[[ - __create_base_kconfgen_command(sdkconfig sdkconfig_defaults) + __create_base_kconfgen_command(sdkconfig sdkconfig_defaults) - Create the base kconfgen command and store it as a build property for reuse. + *sdkconfig[in]* - :sdkconfig[in]: Path to sdkconfig file. - :sdkconfig_defaults[in]: List of sdkconfig defaults files. + Path to sdkconfig file. + + *sdkconfig_defaults[in]* + + List of sdkconfig defaults files. + + Create the base kconfgen command and store it as a build property for + reuse. #]] function(__create_base_kconfgen_command sdkconfig sdkconfig_defaults) # Get all necessary properties for base command @@ -476,15 +504,27 @@ function(__create_base_kconfgen_command sdkconfig sdkconfig_defaults) endfunction() #[[ - __run_kconfgen(header_path cmake_path json_path menus_path) + __run_kconfgen(header_path cmake_path json_path menus_path) - Run kconfgen and generate all output files using the stored base command. - Assumes that the base command is already created by __create_base_kconfgen_command(). + *header_path[in]* - :header_path[in]: Path for sdkconfig.h output. - :cmake_path[in]: Path for sdkconfig.cmake output. - :json_path[in]: Path for sdkconfig.json output. - :menus_path[in]: Path for kconfig_menus.json output. + Path for sdkconfig.h output. + + *cmake_path[in]* + + Path for sdkconfig.cmake output. + + *json_path[in]* + + Path for sdkconfig.json output. + + *menus_path[in]* + + Path for kconfig_menus.json output. + + Run kconfgen and generate all output files using the stored base command. + Assumes that the base command is already created by + __create_base_kconfgen_command(). #]] function(__run_kconfgen header_path cmake_path json_path menus_path) idf_build_get_property(base_kconfgen_cmd __BASE_KCONFGEN_CMD) @@ -510,15 +550,15 @@ endfunction() # ============================================================================= #[[ - __create_kconfig_targets() + __create_kconfig_targets() - Create Kconfig related targets. - This function must be called after all kconfig processing is complete, including - the component manager. It creates the following targets: + Create Kconfig related targets. This function must be called after all + kconfig processing is complete, including the component manager. It creates + the following targets: - - menuconfig - - confserver - - save-defconfig + - menuconfig + - confserver + - save-defconfig #]] function(__create_kconfig_targets) # Create Kconfig targets @@ -528,9 +568,9 @@ function(__create_kconfig_targets) endfunction() #[[ - __create_menuconfig_target() + __create_menuconfig_target() - Create menuconfig target. + Create menuconfig target. #]] function(__create_menuconfig_target) idf_build_get_property(python PYTHON) @@ -604,9 +644,9 @@ function(__create_menuconfig_target) endfunction() #[[ - __create_confserver_target() + __create_confserver_target() - Create confserver target. + Create confserver target. #]] function(__create_confserver_target) idf_build_get_property(python PYTHON) @@ -632,9 +672,9 @@ function(__create_confserver_target) endfunction() #[[ - __create_save_defconfig_target() + __create_save_defconfig_target() - Create save-defconfig target. + Create save-defconfig target. #]] function(__create_save_defconfig_target) idf_build_get_property(prepare_cmd __PREPARE_KCONFIG_CMD) diff --git a/tools/cmakev2/ldgen.cmake b/tools/cmakev2/ldgen.cmake index 07468a5144..4e30ce5b13 100644 --- a/tools/cmakev2/ldgen.cmake +++ b/tools/cmakev2/ldgen.cmake @@ -1,32 +1,41 @@ include_guard(GLOBAL) - set(one_value LIBRARY TEMPLATE SUFFIX OUTPUT) #[[ - __ldgen_process_template(LIBRARY - TEMPLATE