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