alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-12-27 05:37:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(cmakev2/docs): reformat function arguments for API documentation

Browse Source 
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 <frantisek.hrbata@espressif.com>
This commit is contained in:
Frantisek Hrbata
2025-09-12 18:07:10 +02:00
committed by BOT
parent 17d7507f29
commit abddda342f
9 changed files with 1325 additions and 854 deletions
Download Patch File Download Diff File Expand all files Collapse all files

425
tools/cmakev2/build.cmake
View File

@@ -10,18 +10,26 @@ include(CheckCXXCompilerFlag)
#[[api
.. cmakev2:function:: idf_build_set_property
.. code-block:: cmake
.. code-block:: cmake
idf_build_set_property(<property> <value> [APPEND])
idf_build_set_property(<property> <value> [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(<var> <property> [GENERATOR_EXPRESSION])
idf_build_get_property(<var> <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 <library>
OUTPUT <variable>)
__get_library_interface_or_die(LIBRARY <library>
OUTPUT <variable>)
: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(<library> <property> <value> [APPEND])
idf_library_set_property(<library> <property> <value> [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(<variable> <library> <property> [GENERATOR_EXPRESSION])
idf_library_get_property(<variable> <library> <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(<libraries>)
__dump_library_properties(<libraries>)
:libraries: List of library interfaces whose properties should be displayed.
*libraries*
Dump all properties for the libraries listed in ``<libraries>``.
List of library interfaces whose properties should be displayed.
Dump all properties for the libraries listed in ``<libraries>``.
#]]
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(<library>
[COMPONENTS <component>...])
idf_build_library(<library>
[COMPONENTS <component>...])
: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(<executable>
[COMPONENTS <component>...]
[NAME <name>]
[SUFFIX <suffix>])
idf_build_executable(<executable>
[COMPONENTS <component>...]
[NAME <name>]
[SUFFIX <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 <component>...
OUTPUT <variable>)
__get_components_metadata(COMPONENTS <component>...
OUTPUT <variable>)
: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(<executable>
[FILE <file>])
idf_build_generate_metadata(<executable>
[FILE <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 ``<build>/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
``<build>/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 ``<build>/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
``<build>/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(<executable>
TARGET <target>
OUTPUT_FILE <file>)
idf_build_binary(<executable>
TARGET <target>
OUTPUT_FILE <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(<binary>
TARGET <target>
OUTPUT_FILE <file>
[KEYFILE <file>])
idf_sign_binary(<binary>
TARGET <target>
OUTPUT_FILE <file>
[KEYFILE <file>])
: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(<binary>
TARGET <target>
[NAME <name>]
[FLASH])
idf_flash_binary(<binary>
TARGET <target>
[NAME <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(<binary>)
idf_check_binary_size(<binary>)
: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(<binary>)
idf_check_binary_signed(<binary>)
: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)

283
tools/cmakev2/compat.cmake
View File

@@ -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>...]
[SRC_DIRS <dir>...]
[EXCLUDE_SRCS <exclude>...]
OUTPUT <var>)
__get_component_sources([SRCS <src>...]
[SRC_DIRS <dir>...]
[EXCLUDE_SRCS <exclude>...]
OUTPUT <var>)
: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(<target> <deptype> <scriptfile>...
[PROCESS <output>])
target_linker_script(<target> <deptype> <scriptfile>...
[PROCESS <output>])
: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(<type> <component>...)
idf_component_optional_requires(<type> <component>...)
: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 <file>..]
[SRC_DIRS <dir>...]
[EXCLUDE_SRCS <file>...]
[INCLUDE_DIRS <dir>...]
[PRIV_INCLUDE_DIRS <dir>...]
[LDFRAGMENTS <file>...]
[REQUIRES <component>...]
[PRIV_REQUIRES <component>...]
[REQUIRED_IDF_TARGETS <target>...]
[EMBED_FILES <file>...]
[EMBED_TXTFILES <file>...]
[KCONFIG <file>]
[KCONFIG_PROJBUILD <file>]
[WHOLE_ARCHIVE])
idf_component_register([SRCS <file>..]
[SRC_DIRS <dir>...]
[EXCLUDE_SRCS <file>...]
[INCLUDE_DIRS <dir>...]
[PRIV_INCLUDE_DIRS <dir>...]
[LDFRAGMENTS <file>...]
[REQUIRES <component>...]
[PRIV_REQUIRES <component>...]
[REQUIRED_IDF_TARGETS <target>...]
[EMBED_FILES <file>...]
[EMBED_TXTFILES <file>...]
[KCONFIG <file>]
[KCONFIG_PROJBUILD <file>]
[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(<component_dir> [<component_source>])
idf_build_component(<component_dir> [<component_source>])
: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)

329
tools/cmakev2/component.cmake
View File

@@ -10,19 +10,29 @@ include(kconfig)
#[[api
.. cmakev2:function:: idf_component_set_property
.. code-block:: cmake
.. code-block:: cmake
idf_component_set_property(<component> <property> <value> [APPEND])
idf_component_set_property(<component> <property> <value> [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(<variable> <component> <property> [GENERATOR_EXPRESSION])
idf_component_get_property(<variable> <component> <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 <path>...
[EXCLUDE_PATHS <path>...]
[SOURCE <source>]
[CHECK]
OUTPUT <var>)
__get_component_paths(PATHS <path>...
[EXCLUDE_PATHS <path>...]
[SOURCE <source>]
[CHECK]
OUTPUT <var>)
: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 <component>
OUTPUT <variable>)
: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 ``<component>`` 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_prefix>_<component name>
component target: _<component_prefix>_<component name>
component alias: <component_prefix>::<component name>
*OUTPUT[out]*
Output variable to store the component interface.
Identify the component interface target using the ``<component>`` 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_prefix>_<component name>
component target: _<component_prefix>_<component name>
component alias: <component_prefix>::<component name>
#]]
function(__get_component_interface)
set(options)
@@ -227,11 +266,16 @@ endfunction()
__get_component_interface_or_die(COMPONENT <component>
OUTPUT <variable>)
: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 <source>
OUTPUT <variable>)
__get_component_priority(SOURCE <source>
OUTPUT <variable>)
: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 <path>
PREFIX <prefix>
SOURCE <source>)
__init_component(DIRECTORY <path>
PREFIX <prefix>
SOURCE <source>)
:DIRECTORY[in]: ``<path>`` 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.
``<path>`` 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(<components>)
__dump_component_properties(<components>)
:components: List of components whose properties should be displayed.
*components[in]*
Dump all properties for the components listed in ``<components>``.
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 <component_name>
OUTPUT <variable>)
__component_name_without_namespace(COMPONENT <component_name>
OUTPUT <variable>)
: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 <component_name>
KNOWN_COMPONENTS <known_components_list>
OUTPUT <variable>)
__resolve_component_name(COMPONENT <component_name>
KNOWN_COMPONENTS <known_components_list>
OUTPUT <variable>)
: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(<name>
[INTERFACE <variable>])
idf_component_include(<name>
[INTERFACE <variable>])
: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 ``<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.
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)

191
tools/cmakev2/idf.cmake
View File

@@ -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)

172
tools/cmakev2/kconfig.cmake
View File

@@ -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)

55
tools/cmakev2/ldgen.cmake
View File

@@ -1,32 +1,41 @@
include_guard(GLOBAL)
set(one_value LIBRARY TEMPLATE SUFFIX OUTPUT)
#[[
__ldgen_process_template(LIBRARY <target>
TEMPLATE <template>
OUTPUT <output>
[SUFFIX <suffix>])
__ldgen_process_template(LIBRARY <target>
TEMPLATE <template>
OUTPUT <output>
[SUFFIX <suffix>])
:TARGET[in]: A library interface target that already has the properties
__LDGEN_LIBRARIES, __LDGEN_FRAGMENT_FILES, and __LDGEN_DEPENDS
set. These properties include libraries and fragment files for
components linked to the library interface.
:TEMPLATE[in]: Linker script template to process.
:OUTPUT[in]: The output filename where the generated linker script will be
saved.
:SUFFIX[in,opt]: Optional suffix for the generated files containing the list
of linked library archives.
*TARGET[in]*
Pass the linker script ``TEMPLATE`` to the linker script generation tool,
ldgen, for processing. The processed linker script is stored in the file
specified by the ``OUTPUT`` option.
A library interface target that already has the properties
__LDGEN_LIBRARIES, __LDGEN_FRAGMENT_FILES, and __LDGEN_DEPENDS set.
These properties include libraries and fragment files for components
linked to the library interface.
This function can be called multiple times to generate multiple linker
scripts from a single template. For example, a component like esp_system may
be linked to multiple library interface targets, each with a different set
of components. This results in different sets of fragment files and library
archives. The suffix is used to ensure that the files listing the archives
are not overwritten.
*TEMPLATE[in]*
Linker script template to process.
*OUTPUT[in]*
The output filename where the generated linker script will be saved.
*SUFFIX[in,opt]*
Optional suffix for the generated files containing the list of linked
library archives.
Pass the linker script ``TEMPLATE`` to the linker script generation tool,
ldgen, for processing. The processed linker script is stored in the file
specified by the ``OUTPUT`` option.
This function can be called multiple times to generate multiple linker
scripts from a single template. For example, a component like esp_system
may be linked to multiple library interface targets, each with a different
set of components. This results in different sets of fragment files and
library archives. The suffix is used to ensure that the files listing the
archives are not overwritten.
#]]
function(__ldgen_process_template)
set(options)

81
tools/cmakev2/manager.cmake
View File

@@ -8,9 +8,9 @@ include(build)
include(kconfig)
#[[
__init_component_manager()
__init_component_manager()
Initialize component manager related build properties and defaults.
Initialize component manager related build properties and defaults.
#]]
function(__init_component_manager)
# Set IDF_COMPONENT_MANAGER build property to 1 if not explicitly set to 0
@@ -41,17 +41,17 @@ function(__init_component_manager)
endfunction()
#[[
__fetch_components_from_registry()
__fetch_components_from_registry()
Iteratively run the component manager and Kconfig until stable or error out.
This routine allows 1 re-run if the manager fails with a missing kconfig
option. This behavior is similar to the build system v1.
Iteratively run the component manager and Kconfig until stable or error
out. This routine allows 1 re-run if the manager fails with a missing
kconfig option. This behavior is similar to the build system v1.
This routine performs the following steps:
1. Initialize the component manager.
2. Run the component manager for all discovered components.
3. Re-collect Kconfig and regenerate sdkconfig with managed components included.
4. If the component manager run failed, error out.
This routine performs the following steps:
1. Initialize the component manager.
2. Run the component manager for all discovered components.
3. Re-collect Kconfig and regenerate sdkconfig with managed components included.
4. If the component manager run failed, error out.
#]]
function(__fetch_components_from_registry)
# Initialize the component manager.
@@ -86,16 +86,24 @@ function(__fetch_components_from_registry)
endfunction()
#[[
__download_managed_component(COMPONENTS_LIST_FILE <file>
MANAGED_OUTPUT_FILE <file>
RESULT <variable>)
__download_managed_component(COMPONENTS_LIST_FILE <file>
MANAGED_OUTPUT_FILE <file>
RESULT <variable>)
Utility function to run the component manager with a specific components list
and generate managed components output.
*COMPONENTS_LIST_FILE[in]*
:COMPONENTS_LIST_FILE[in]: Path to the local components list file
:MANAGED_OUTPUT_FILE[in]: Path where managed components CMake file will be written
:RESULT[out]: Exit code returned by the manager. 0 success, 10 re-run.
Path to the local components list file
*MANAGED_OUTPUT_FILE[in]*
Path where managed components CMake file will be written
*RESULT[out]*
Exit code returned by the manager. 0 success, 10 re-run.
Utility function to run the component manager with a specific components
list and generate managed components output.
#]]
function(__download_managed_component)
set(options)
@@ -151,11 +159,13 @@ function(__download_managed_component)
endfunction()
#[[
__download_component_level_managed_components(RESULT <variable>)
__download_component_level_managed_components(RESULT <variable>)
Download component-level managed components
*RESULT[out]*
:RESULT[out]: Exit code returned by the manager. 0 success, 10 re-run.
Exit code returned by the manager. 0 success, 10 re-run.
Download component-level managed components
#]]
function(__download_component_level_managed_components)
set(options)
@@ -209,10 +219,10 @@ function(__download_component_level_managed_components)
endfunction()
#[[
__component_manager_warn_if_disabled_and_manifests_exist()
__component_manager_warn_if_disabled_and_manifests_exist()
When the component manager is disabled, warn if any discovered component
contains an idf_component.yml manifest.
When the component manager is disabled, warn if any discovered component
contains an idf_component.yml manifest.
#]]
function(__component_manager_warn_if_disabled_and_manifests_exist)
idf_build_get_property(idf_component_manager IDF_COMPONENT_MANAGER)
@@ -228,13 +238,14 @@ function(__component_manager_warn_if_disabled_and_manifests_exist)
endfunction()
#[[
__component_set_property(target property value)
__component_set_property(target property value)
Shim for setting component properties, primarily for use by the component manager
in build system v2. This function only processes dependency-related properties
(MANAGED_REQUIRES and MANAGED_PRIV_REQUIRES) produced by the component manager's
injection file. Other properties are ignored to avoid interfering with the
cmakev2 build flow. Target names with triple underscores are normalized.
Shim for setting component properties, primarily for use by the component
manager in build system v2. This function only processes dependency-related
properties(MANAGED_REQUIRES and MANAGED_PRIV_REQUIRES) produced by the
component manager's injection file. Other properties are ignored to avoid
interfering with the cmakev2 build flow. Target names with triple
underscores are normalized.
#]]
function(__component_set_property target property value)
# If the target has 3 underscores, remove all of them and normalize the target
@@ -263,11 +274,11 @@ function(__component_set_property target property value)
endfunction()
#[[
__inject_requirements_for_component_from_manager(<component_name>)
__inject_requirements_for_component_from_manager(<component_name>)
Managed dependency injection for a single component in build system v2.
Calls the Component Manager to compute manifest-derived dependencies and
updates the component's MANAGED_* properties.
Managed dependency injection for a single component in build system v2.
Calls the Component Manager to compute manifest-derived dependencies and
updates the component's MANAGED_* properties.
#]]
function(__inject_requirements_for_component_from_manager component_name)
# Skip if already injected

104
tools/cmakev2/project.cmake
View File

@@ -4,10 +4,10 @@
include_guard(GLOBAL)
#[[
__init_project_name()
__init_project_name()
Initialize the PROJECT_NAME build property, using CMAKE_PROJECT_NAME as a
fallback.
Initialize the PROJECT_NAME build property, using CMAKE_PROJECT_NAME as a
fallback.
#]]
function(__init_project_name)
__get_default_value(VARIABLE PROJECT_NAME
@@ -17,19 +17,20 @@ function(__init_project_name)
endfunction()
#[[
__init_project_version()
__init_project_version()
Initialize the PROJECT_VER build property based on the following precedence.
Initialize the PROJECT_VER build property based on the following
precedence.
1. The PROJECT_VER environment or CMake variable.
2. The version.txt file located in the top-level project directory.
3. The VERSION argument, if provided, in the project() macro.
4. The output of git describe if the project is within a Git repository.
5. Defaults to 1 if none of the above conditions are met.
1. The PROJECT_VER environment or CMake variable.
2. The version.txt file located in the top-level project directory.
3. The VERSION argument, if provided, in the project() macro.
4. The output of git describe if the project is within a Git repository.
5. Defaults to 1 if none of the above conditions are met.
The value of PROJECT_VER will be overridden later if
CONFIG_APP_PROJECT_VER_FROM_CONFIG is defined. For more details, refer to
components/esp_app_format/CMakeLists.txt.
The value of PROJECT_VER will be overridden later if
CONFIG_APP_PROJECT_VER_FROM_CONFIG is defined. For more details, refer to
components/esp_app_format/CMakeLists.txt.
#]]
function(__init_project_version)
idf_build_get_property(project_dir PROJECT_DIR)
@@ -69,10 +70,10 @@ function(__init_project_version)
endfunction()
#[[
__init_project_configuration()
__init_project_configuration()
Configure the build settings in one location, incorporating preset
compilation flags, definitions, and settings based on sdkconfig.
Configure the build settings in one location, incorporating preset
compilation flags, definitions, and settings based on sdkconfig.
#]]
function(__init_project_configuration)
set(compile_definitions)
@@ -506,10 +507,10 @@ function(__init_project_configuration)
endfunction()
#[[
__create_project_flash_targets()
__create_project_flash_targets()
Add placeholder flash targets to the build. This is used by components to
declare dependencies on the flash target.
Add placeholder flash targets to the build. This is used by components to
declare dependencies on the flash target.
#]]
function(__create_project_flash_targets)
if(NOT TARGET flash)
@@ -527,13 +528,13 @@ function(__create_project_flash_targets)
endfunction()
#[[
__init_project_flash_targets()
__init_project_flash_targets()
If binary generation is enabled, initialize the esptool component and enable
the generation of esptool flash argument files for the flash and
encrypted-flash targets. Note that this is done after including the
project_include.cmake files, as we need the functions defined in the
esptool_py component.
If binary generation is enabled, initialize the esptool component and
enable the generation of esptool flash argument files for the flash and
encrypted-flash targets. Note that this is done after including the
project_include.cmake files, as we need the functions defined in the
esptool_py component.
#]]
function(__init_project_flash_targets)
if(CONFIG_APP_BUILD_GENERATE_BINARIES)
@@ -546,22 +547,23 @@ endfunction()
#[[api
.. cmakev2:macro:: idf_project_init
.. code-block:: cmake
.. code-block:: cmake
idf_project_init()
idf_project_init()
Initialize settings that need to be configured after the project() function
is called. This must occur after the project() function and before any other
build system functions. It initializes the PROJECT_NAME and PROJECT_VER
build properties, as well as all default C, CXX, and ASM compile options,
link options, and compile definitions.
Initialize settings that need to be configured after the ``project()``
function is called. This must occur after the ``project()`` function and
before any other build system functions. It initializes the
``PROJECT_NAME`` and ``PROJECT_VER`` build properties, as well as all
default C, CXX, and ASM compile options, link options, and compile
definitions.
This macro also includes project_include.cmake files for the discovered
components, as these files define project-wide functionality that needs to
be available before any component's CMakeLists.txt is evaluated. The
project_include.cmake files should be evaluated in the global scope.
Therefore, this is defined as a macro and should be called only from the
global scope or from within another macro.
This macro also includes ``project_include.cmake`` files for the discovered
components, as these files define project-wide functionality that needs to
be available before any component's ``CMakeLists.txt`` is evaluated. The
``project_include.cmake`` files should be evaluated in the global scope.
Therefore, this is defined as a macro and should be called only from the
global scope or from within another macro.
#]]
macro(idf_project_init)
idf_build_get_property(project_initialized __PROJECT_INITIALIZED)
@@ -643,14 +645,14 @@ macro(idf_project_init)
endmacro()
#[[api
.. cmakev2:macro:: idf_build_generate_flasher_args
.. cmakev2:function:: idf_build_generate_flasher_args
.. code-block:: cmake
.. code-block:: cmake
idf_build_generate_flasher_args()
idf_build_generate_flasher_args()
Generate the flasher_args.json file for the global flash target for tools
that require it.
Generate the flasher_args.json file for the global flash target for tools
that require it.
#]]
function(idf_build_generate_flasher_args)
# The variables listed below are used to configure the template
@@ -694,17 +696,17 @@ endfunction()
#[[api
.. cmakev2:macro:: idf_project_default
.. code-block:: cmake
.. code-block:: cmake
idf_project_default()
idf_project_default()
Create a default project executable based on the main component and its
transitive dependencies. The executable name is derived from the
PROJECT_NAME variable, which by default uses the CMAKE_PROJECT_NAME value
specified in the CMake's project() call.
Create a default project executable based on the main component and its
transitive dependencies. The executable name is derived from the
``PROJECT_NAME`` variable, which by default uses the ``CMAKE_PROJECT_NAME``
value specified in the CMake's ``project()`` call.
Generate the binary image for the executable, signed or unsigned based on
the configuration, and add flash targets for it.
Generate the binary image for the executable, signed or unsigned based on
the configuration, and add flash targets for it.
#]]
macro(idf_project_default)
idf_project_init()

539
tools/cmakev2/utilities.cmake
View File

@@ -13,14 +13,16 @@
#[[api
.. cmakev2:function:: idf_die
.. code-block:: cmake
.. code-block:: cmake
idf_die(<msg>...)
idf_die(<msg>...)
:msg[in]: Message to print.
*msg[in]*
Print error ``<msg>`` and abort the build process. Multiple messages are
concatenated into a single message with no separator between them.
Message to print.
Print error ``<msg>`` and abort the build process. Multiple messages are
concatenated into a single message with no separator between them.
#]]
function(idf_die)
@@ -35,14 +37,16 @@ endfunction()
#[[api
.. cmakev2:function:: idf_warn
.. code-block:: cmake
.. code-block:: cmake
idf_warn(<msg>...)
idf_warn(<msg>...)
:msg[in]: Message to print.
*msg[in]*
Print warning ``<msg>``. Multiple messages are concatenated into a single
message with no separator between them.
Message to print.
Print warning ``<msg>``. Multiple messages are concatenated into a single
message with no separator between them.
#]]
function(idf_warn)
set(joined "")
@@ -56,14 +60,16 @@ endfunction()
#[[api
.. cmakev2:function:: idf_msg
.. code-block:: cmake
.. code-block:: cmake
idf_msg(<msg>...)
idf_msg(<msg>...)
:msg[in]: Message to print.
*msg[in]*
Print status ``<msg>``. Multiple messages are concatenated into a single
message with no separator between them.
Message to print.
Print status ``<msg>``. Multiple messages are concatenated into a single
message with no separator between them.
#]]
function(idf_msg)
set(joined "")
@@ -77,14 +83,16 @@ endfunction()
#[[api
.. cmakev2:function:: idf_dbg
.. code-block:: cmake
.. code-block:: cmake
idf_dbg(<msg>...)
idf_dbg(<msg>...)
:msg[in]: Message to print.
*msg[in]*
Print debug ``<msg>``. Multiple messages are concatenated into a single
message with no separator between them.
Message to print.
Print debug ``<msg>``. Multiple messages are concatenated into a single
message with no separator between them.
#]]
function(idf_dbg)
set(joined "")
@@ -96,15 +104,20 @@ function(idf_dbg)
endfunction()
#[[
__get_real_target(TARGET <target>
OUTPUT <variable>)
__get_real_target(TARGET <target>
OUTPUT <variable>)
:TARGET[int]: Target name or target alias name.
:OUTPUT[out]: Output variable to store the real target name.
*TARGET[int]*
For a given ``<target>``, return the actual target if ``<target>`` is an
alias. If ``<target>`` is the target itself, return it. If ``<target>`` is
not a target at all, return ``NOTFOUND``.
Target name or target alias name.
*OUTPUT[out]*
Output variable to store the real target name.
For a given ``<target>``, return the actual target if ``<target>`` is an
alias. If ``<target>`` is the target itself, return it. If ``<target>`` is
not a target at all, return ``NOTFOUND``.
#]]
function(__get_real_target)
set(options)
@@ -133,17 +146,24 @@ function(__get_real_target)
endfunction()
#[[
__get_absolute_paths(PATHS <path>...
BASE_DIR <base_dir>
OUTPUT <variable>)
__get_absolute_paths(PATHS <path>...
BASE_DIR <base_dir>
OUTPUT <variable>)
:PATHS[in]: List of paths to convert to absolute paths.
:BASE_DIR[in,opt]: Evaluate relative paths based on the specified
``<base_dir>``. If not provided, use CMAKE_CURRENT_SOURCE_DIR
instead.
:OUTPUT[out]: Output variable to store absolute paths.
*PATHS[in]*
For a given ``PATHS``, return the absolute paths in ``OUTPUT``.
List of paths to convert to absolute paths.
*BASE_DIR[in,opt]*
Evaluate relative paths based on the specified ``<base_dir>``. If not
provided, use CMAKE_CURRENT_SOURCE_DIR instead.
*OUTPUT[out]*
Output variable to store absolute paths.
For a given ``PATHS``, return the absolute paths in ``OUTPUT``.
#]]
function(__get_absolute_paths)
set(options)
@@ -173,21 +193,28 @@ function(__get_absolute_paths)
endfunction()
#[[
__get_default_value(VARIABLE <variable>
DEFAULT <value>)
OUTPUT <result>)
__get_default_value(VARIABLE <variable>
DEFAULT <value>)
OUTPUT <result>)
:VARIABLE[in]: The name of the variable for which to obtain its default
value.
:DEFAULT[in]: Default variable value.
:OUTPUT[out]: Variable to store the default value of ``<variable>``.
*VARIABLE[in]*
Set the ``<result>`` to the value of ``<variable>`` based on the following
order of precedence, with the first having the highest precedence.
The name of the variable for which to obtain its default value.
1. environmental variable
2. CMake variable or value stored in CMake's cache
3. ``<value>`` as specified with the ``DEFAULT`` option
*DEFAULT[in]*
Default variable value.
*OUTPUT[out]*
Variable to store the default value of ``<variable>``.
Set the ``<result>`` to the value of ``<variable>`` based on the following
order of precedence, with the first having the highest precedence.
1. environmental variable
2. CMake variable or value stored in CMake's cache
3. ``<value>`` as specified with the ``DEFAULT`` option
#]]
function(__get_default_value)
set(options)
@@ -220,16 +247,25 @@ function(__get_default_value)
endfunction()
#[[
__get_config_option(OPTION <option>
SDKCONFIG <path>)
OUTPUT <variable>)
__get_config_option(OPTION <option>
SDKCONFIG <path>)
OUTPUT <variable>)
:OPTION[in]: Option name in sdkconfig to obtain the value of.
:SDKCONFIG[in]: Sdkconfig file path.
:OUTPUT[out]: Variable to store the value of sdkconfig ``<option>``.
*OPTION[in]*
Search for the ``<option>`` in the sdkconfig file specified by ``<path>`` and store
its value in ``<variable>``. If the option is not found, return ``NOTFOUND``.
Option name in sdkconfig to obtain the value of.
*SDKCONFIG[in]*
Sdkconfig file path.
*OUTPUT[out]*
Variable to store the value of sdkconfig ``<option>``.
Search for the ``<option>`` in the sdkconfig file specified by ``<path>``
and store its value in ``<variable>``. If the option is not found, return
``NOTFOUND``.
#]]
function(__get_sdkconfig_option)
set(options)
@@ -270,18 +306,32 @@ function(__get_sdkconfig_option)
endfunction()
#[[
__set_property(TARGET <target>
PROPERTY <property>)
PROPERTIES <properties>
VALUE <value>
APPEND)
__set_property(TARGET <target>
PROPERTY <property>)
PROPERTIES <properties>
VALUE <value>
APPEND)
:TARGET[in]: The target name to attach the property.
:PROPERTY[in]: Property name.
:PROPERTIES[in]: The target property containing list of properties.
:VALUE[in]: Property value.
:APPEND: Append the value to the property's current value instead of
replacing it.
*TARGET[in]*
The target name to attach the property.
*PROPERTY[in]*
Property name.
*PROPERTIES[in]*
The target property containing list of properties.
*VALUE[in]*
Property value.
*APPEND*
Append the value to the property's current value instead of replacing
it.
Set the ``PROPERTY`` to ``VALUE`` for the ``TARGET``, and also record the
``PROPERTY`` name in the list of all properties for the ``TARGET``. The
@@ -328,19 +378,30 @@ function(__set_property)
endfunction()
#[[
__get_property(TARGET <target>
PROPERTY <property>)
OUTPUT <variable>
GENERATOR_EXPRESSION)
__get_property(TARGET <target>
PROPERTY <property>)
OUTPUT <variable>
GENERATOR_EXPRESSION)
:TARGET[in]: The target from which to obtain the property value.
:PROPERTY[in]: Property name.
:OUTPUT[out]: Output variable to store the property value.
:GENERATOR_EXPRESSION: Obtain the generator expression for the property
rather than the actual value.
*TARGET[in]*
Get the value of the specified ``PROPERTY`` from ``TARGET`` and store it in
the ``OUTPUT`` variable.
The target from which to obtain the property value.
*PROPERTY[in]*
Property name.
*OUTPUT[out]*
Output variable to store the property value.
*GENERATOR_EXPRESSION*
Obtain the generator expression for the property rather than the actual
value.
Get the value of the specified ``PROPERTY`` from ``TARGET`` and store it in
the ``OUTPUT`` variable.
#]]
function(__get_property)
set(options GENERATOR_EXPRESSION)
@@ -370,10 +431,10 @@ function(__get_property)
endfunction()
#[[
__dump_all_properties()
__dump_all_properties()
Dump all properties, including build properties, component properties, and
library properties.
Dump all properties, including build properties, component properties, and
library properties.
#]]
function(__dump_all_properties)
__dump_build_properties()
@@ -384,25 +445,38 @@ function(__dump_all_properties)
endfunction()
#[[
__split(STRING <string>
OUTPUT <variable>
[SEPARATOR <sep>]
[REMOVE_EMPTY]
[STRIP])
__split(STRING <string>
OUTPUT <variable>
[SEPARATOR <sep>]
[REMOVE_EMPTY]
[STRIP])
:STRING[in]: Input string to be split.
:OUTPUT[out]: Output variable where the split strings will be stored.
:SEPARATOR[in,opt]: The separator string used to split the string.
By default split the string using newlines:
"\r\n", "\n", and "\r".
:REMOVE_EMPTY[opt]: Remove empty split strings.
:STRIP[opt]: Remove leading and trailing spaces from split strings.
*STRING[in]*
Split the ``STRING`` using the ``SEPARATOR`` and store the resulting list of
split strings in ``OUTPUT``. If ``SEPARATOR`` is not provided, the split
will be based on newlines. When ``STRIP`` is specified, leading and trailing
whitespaces will be removed. If ``REMOVE_EMPTY`` is specified, empty strings
will be removed from the ``OUTPUT`` list.
Input string to be split.
*OUTPUT[out]*
Output variable where the split strings will be stored.
*SEPARATOR[in,opt]*
The separator string used to split the string. By default split the
string using newlines: "\r\n", "\n", and "\r".
*REMOVE_EMPTY[opt]*
Remove empty split strings.
*STRIP[opt]*
Remove leading and trailing spaces from split strings.
Split the ``STRING`` using the ``SEPARATOR`` and store the resulting list
of split strings in ``OUTPUT``. If ``SEPARATOR`` is not provided, the split
will be based on newlines. When ``STRIP`` is specified, leading and
trailing whitespaces will be removed. If ``REMOVE_EMPTY`` is specified,
empty strings will be removed from the ``OUTPUT`` list.
#]]
function(__split)
set(options STRIP REMOVE_EMPTY)
@@ -445,15 +519,16 @@ function(__split)
endfunction()
#[[
__get_compile_options(OUTPUT <variable>)
__get_compile_options(OUTPUT <variable>)
:OUTPUT[out]: List of generator expressions for C, CXX, and ASM compile
options
*OUTPUT[out]*
Gather the compilation options from COMPILE_OPTIONS, C_COMPILE_OPTIONS,
CXX_COMPILE_OPTIONS, and ASM_COMPILE_OPTIONS build properties into a single
list using generator expressions. This list can then be used with the
target_compile_options call.
List of generator expressions for C, CXX, and ASM compile options
Gather the compilation options from COMPILE_OPTIONS, C_COMPILE_OPTIONS,
CXX_COMPILE_OPTIONS, and ASM_COMPILE_OPTIONS build properties into a single
list using generator expressions. This list can then be used with the
target_compile_options call.
#]]
function(__get_compile_options)
set(options)
@@ -482,12 +557,17 @@ function(__get_compile_options)
endfunction()
#[[
remove_duplicated_flags(<flags> <uniq_flags>)
remove_duplicated_flags(<flags> <uniq_flags>)
:flags[in]: Input string with compilation flags.
:uniq_flags[out]: Output string with unified compilation flags.
*flags[in]*
Remove duplicate entries from a string of compilation flags.
Input string with compilation flags.
*uniq_flags[out]*
Output string with unified compilation flags.
Remove duplicate entries from a string of compilation flags.
#]]
function(remove_duplicated_flags FLAGS UNIQFLAGS)
set(FLAGS_LIST "${FLAGS}")
@@ -502,17 +582,19 @@ function(remove_duplicated_flags FLAGS UNIQFLAGS)
endfunction()
#[[
spaces2list(<variable>)
spaces2list(<variable>)
:variable[in,out]: String with space-delimited values.
*variable[in,out]*
Take a variable containing space-delimited values and convert it into a
CMake list with semicolon-delimited values.
String with space-delimited values.
Note: do not use this for directories or full paths, as they may contain
spaces.
Take a variable containing space-delimited values and convert it into a
CMake list with semicolon-delimited values.
TODO: look at cmake separate_arguments, which is quote-aware
Note: do not use this for directories or full paths, as they may contain
spaces.
TODO: look at cmake separate_arguments, which is quote-aware
#]]
function(spaces2list variable_name)
string(REPLACE " " ";" tmp "${${variable_name}}")
@@ -520,13 +602,21 @@ function(spaces2list variable_name)
endfunction()
#[[
add_prefix(<variable> <prefix> <item>...)
add_prefix(<variable> <prefix> <item>...)
:variable[out]: Output variable with list of prefixed items.
:prefix[in]: Prefix string.
:item[in]: Items to be prefixed.
*variable[out]*
Add a prefix to each item in the given list.
Output variable with list of prefixed items.
*prefix[in]*
Prefix string.
*item[in]*
Items to be prefixed.
Add a prefix to each item in the given list.
#]]
function(add_prefix var prefix)
foreach(elm ${ARGN})
@@ -536,16 +626,24 @@ function(add_prefix var prefix)
endfunction()
#[[
fail_target(<target> <line0> [<line>...])
fail_target(<target> <line0> [<line>...])
:target[in]: Fail target name.
:line0[in]: First line of the failed message.
:line[in,opt]: Optional additional message lines.
*target[in]*
Create a phony target which fails when invoked. This is used when the
necessary conditions for a target are not met, such as configuration. Rather
than omitting the target altogether, we fail execution with a helpful
message.
Fail target name.
*line0[in]*
First line of the failed message.
*line[in,opt]*
Optional additional message lines.
Create a phony target which fails when invoked. This is used when the
necessary conditions for a target are not met, such as configuration.
Rather than omitting the target altogether, we fail execution with a
helpful message.
#]]
function(fail_target target_name message_line0)
idf_build_get_property(idf_path IDF_PATH)
@@ -564,16 +662,24 @@ function(fail_target target_name message_line0)
endfunction()
#[[
file_generate(<output>
[INPUT <file>]
[CONTENT <string>])
file_generate(<output>
[INPUT <file>]
[CONTENT <string>])
:output[in]: Output file name.
:INPUT[in]: Input file name.
:CONTENT[in]: Input string.
*output[in]*
Utility to generate file and have the output automatically added to cleaned
files.
Output file name.
*INPUT[in]*
Input file name.
*CONTENT[in]*
Input string.
Utility to generate file and have the output automatically added to cleaned
files.
#]]
function(file_generate output)
cmake_parse_arguments(_ "" "INPUT;CONTENT" "" ${ARGN})
@@ -591,12 +697,17 @@ function(file_generate output)
endfunction()
#[[
add_deprecated_target_alias(<old_target> <new_target>)
add_deprecated_target_alias(<old_target> <new_target>)
:old_target[in]: Old target name.
:new_target[in]: New target name.
*old_target[in]*
Create an alias for the existing target and display a deprecation warning.
Old target name.
*new_target[in]*
New target name.
Create an alias for the existing target and display a deprecation warning.
#]]
function(add_deprecated_target_alias old_target new_target)
add_custom_target(${old_target}
@@ -608,23 +719,35 @@ function(add_deprecated_target_alias old_target new_target)
endfunction()
#[[
target_add_binary_data(<target> <embed_file> <embed_type>
[RENAME_TO <symbol>])
[DEPENDS <dependency>...])
target_add_binary_data(<target> <embed_file> <embed_type>
[RENAME_TO <symbol>])
[DEPENDS <dependency>...])
:target[in]: Attach the source file with embedded data to the specified
target.
:embed_file[in]: File containing the embedded data.
:embed_type[in]: BINARY or TEXT
:RENAME_TO[in,opt]: Use the given symbol name for the embedded data. If no
symbol name is provided, the embed_file file name will
be used instead.
:DEPENDS[in,opt]: List of additional dependencies for the generated file
containing embedded data.
*target[in]*
Add binary data into the build target by converting it into a generated
source file, which is then compiled into a binary object as part of the
build process.
Attach the source file with embedded data to the specified target.
*embed_file[in]*
File containing the embedded data.
*embed_type[in]*
BINARY or TEXT
*RENAME_TO[in,opt]*
Use the given symbol name for the embedded data. If no symbol name is
provided, the embed_file file name will be used instead.
*DEPENDS[in,opt]*
List of additional dependencies for the generated file containing
embedded data.
Add binary data into the build target by converting it into a generated
source file, which is then compiled into a binary object as part of the
build process.
#]]
function(target_add_binary_data target embed_file embed_type)
cmake_parse_arguments(_ "" "RENAME_TO" "DEPENDS" ${ARGN})
@@ -659,17 +782,28 @@ function(target_add_binary_data target embed_file embed_type)
endfunction()
#[[
add_prebuilt_library(<target> <lib>
[REQUIRES <component>...])
[PRIV_REQUIRES <component>...])
add_prebuilt_library(<target> <lib>
[REQUIRES <component>...])
[PRIV_REQUIRES <component>...])
:target[in]: Target name for the imported library.
:library[in]: Imported library path.
:REQUIRES[in,opt]: Optional dependency on other components.
:PRIV_REQUIRES[in,opt]: Optional private dependency on other components.
*target[in]*
Add prebuilt library with support for adding dependencies on ESP-IDF
components.
Target name for the imported library.
*library[in]*
Imported library path.
*REQUIRES[in,opt]*
Optional dependency on other components.
*PRIV_REQUIRES[in,opt]*
Optional private dependency on other components.
Add prebuilt library with support for adding dependencies on ESP-IDF
components.
#]]
function(add_prebuilt_library target_name lib_path)
cmake_parse_arguments(_ "" "" "REQUIRES;PRIV_REQUIRES" ${ARGN})
@@ -694,13 +828,18 @@ function(add_prebuilt_library target_name lib_path)
endfunction()
#[[
__get_target_dependencies(TARGET <target>
OUTPUT <variable>)
__get_target_dependencies(TARGET <target>
OUTPUT <variable>)
:TARGET[in]: Target for which to get dependencies.
:OUTPUT[out]: Output variable where the list of dependencies will be stored.
*TARGET[in]*
Recursively retrieve the list of dependencies for ``TARGET``.
Target for which to get dependencies.
*OUTPUT[out]*
Output variable where the list of dependencies will be stored.
Recursively retrieve the list of dependencies for ``TARGET``.
#]]
function(__get_target_dependencies)
set(options)
@@ -765,17 +904,23 @@ function(__get_target_dependencies)
endfunction()
#[[
__get_executable_library_or_die(TARGET <executable>
OUTPUT <library>)
__get_executable_library_or_die(TARGET <executable>
OUTPUT <library>)
:TARGET[in]: Executable target.
:OUTPUT[out]: Output variable to store the library interface target linked
to the executable.
*TARGET[in]*
Search for the library interface target created with the idf_build_library()
function and linked to the executable, examine the LINK_LIBRARIES for the
executable and the LIBRARY_INTERFACES build property, which stores all
library interface targets created by the idf_build_library() function.
Executable target.
*OUTPUT[out]*
Output variable to store the library interface target linked to the
executable.
Search for the library interface target created with the
idf_build_library() function and linked to the executable, examine the
LINK_LIBRARIES for the executable and the LIBRARY_INTERFACES build
property, which stores all library interface targets created by the
idf_build_library() function.
#]]
function(__get_executable_library_or_die)
set(options)
@@ -814,14 +959,17 @@ function(__get_executable_library_or_die)
endfunction()
#[[
__make_json_list(<list> OUTPUT <variable>)
__make_json_list(<list> OUTPUT <variable>)
:list[in]: CMake string containing a list to be converted into JSON
format.
:OUTPUT[out]: Output variable name to store the JSON list.
*list[in]*
Convert a CMake list to a JSON list and store it in a OUTPUT
variable.
CMake string containing a list to be converted into JSON format.
*OUTPUT[out]*
Output variable name to store the JSON list.
Convert a CMake list to a JSON list and store it in a OUTPUT variable.
#]]
function(__make_json_list input)
set(options)
@@ -843,16 +991,21 @@ function(__make_json_list input)
endfunction()
#[[
fail_at_build_time(<target> <message>...)
fail_at_build_time(<target> <message>...)
:target[in]: Target name to create and add to ALL.
:message[in]: Error message to display. Multiple messages may be provided.
*target[in]*
Create a phony target that intentionally fails the build, displaying the
error messages specified in the message arguments. An empty CMake file is
created and included, which is then deleted when the target is executed.
This forces CMake to rerun, as the file is added to the CMake rerun
dependencies.
Target name to create and add to ALL.
*message[in]*
Error message to display. Multiple messages may be provided.
Create a phony target that intentionally fails the build, displaying the
error messages specified in the message arguments. An empty CMake file is
created and included, which is then deleted when the target is executed.
This forces CMake to rerun, as the file is added to the CMake rerun
dependencies.
#]]
function(fail_at_build_time target_name message_line0)
idf_build_get_property(idf_path IDF_PATH)