构建 API

[English]

构建 API

armino_build_get_property(var property [GENERATOR_EXPRESSION])

获取一个 构建属性，并存储在 var 中。 特定 GENERATOR_EXPRESSION 将获取该属性的生成器表达式字符串（不是实际值），它可与支持生成器表达式的 CMake 命令一起使用。

armino_build_set_property(property val [APPEND])

设置一个 构建属性 的值为 val。APPEND 将把指定的值添加到属性当前值之后。 如果属性不存在或为空，则指定的值将变为第一个元素/成员。

armino_build_component(component_dir)

向构建系统提交一个包含组件的 component_dir 目录。相对路径会被转换为相对于当前目录的绝对路径。 所有对该命令的调用必须在`armino_build_process`之前执行。

该命令并不保证组件在构建过程中会被处理（参见 armino_build_process 中 COMPONENTS 参数说明）

armino_build_process(target
                  [PROJECT_DIR project_dir]
                  [PROJECT_VER project_ver]
                  [PROJECT_NAME project_name]
                  [SDKCONFIG sdkconfig]
                  [SDKCONFIG_DEFAULTS sdkconfig_defaults]
                  [BUILD_DIR build_dir]
                  [COMPONENTS component1 component2 ...])

为导入 ARMINO 组件执行大量的幕后工作，包括组件配置、库创建、依赖性扩展和解析。在这些功能中，对于用户最重要的可能是通过调用每个组件的 armino_component_register 来创建库。该命令为每个组件创建库，这些库可以使用别名来访问，其形式为 armino::*component_name*。 这些别名可以用来将组件链接到用户自己的目标、库或可执行文件上。

该调用要求用 target 参数指定目标芯片。调用的可选参数包括：

  • PROJECT_DIR - 项目目录，默认为 CMAKE_SOURCE_DIR。

  • PROJECT_NAME - 项目名称，默认为 CMAKE_PROJECT_NAME。

  • PROJECT_VER - 项目的版本/版本号，默认为 “1”。

  • SDKCONFIG - 生成的 sdkconfig 文件的输出路径，根据是否设置 PROJECT_DIR，默认为 PROJECT_DIR/sdkconfig 或 CMAKE_SOURCE_DIR/sdkconfig。

  • SDKCONFIG_DEFAULTS - 包含默认配置的文件列表（列表中必须包含完整的路径），默认为空； 对于列表中的每个值 filename，如果存在的话，也会加载文件 filename.target 中的配置。 对于列表中的 filename 的每一个值，也会加载文件 filename.target （如果存在的话）中的配置。

  • BUILD_DIR - 用于放置 ARMINO 构建相关工具的目录，如生成的二进制文件、文本文件、组件；默认为CMAKE_BINARY_DIR。

  • COMPONENTS - 从构建系统已知的组件中选择要处理的组件（通过 armino_build_component 添加）。这个参数用于精简构建过程。 如果在依赖链中需要其它组件，则会自动添加，即自动添加这个列表中组件的公共和私有依赖项，进而添加这些依赖项的公共和私有依赖，以此类推。如果不指定，则会处理构建系统已知的所有组件。

armino_build_executable(executable)

指定 ARMINO 构建的可执行文件 executable。这将添加额外的目标，如与 flash 相关的依赖关系，生成额外的二进制文件等。应在 armino_build_process 之后调用。

armino_build_get_config(var config [GENERATOR_EXPRESSION])

获取指定配置的值。就像构建属性一样，特定 GENERATOR_EXPRESSION 将获取该配置的生成器表达式字符串，而不是实际值，即可以与支持生成器表达式的 CMake 命令一起使用。然而，实际的配置值只有在调用 armino_build_process 后才能知道。

构建属性

可以通过使用构建命令 armino_build_get_property 来获取构建属性的值。例如，以下命令可以获取构建过程中使用的 Python 解释器的相关信息。

armino_build_get_property(python PYTHON)
message(STATUS "The Python intepreter is: ${python}")

  • BUILD_DIR - 构建目录；由 armino_build_process 的 BUILD_DIR 参数设置。

  • BUILD_COMPONENTS - 包含在构建中的组件列表；由 armino_build_process 设置。

  • BUILD_COMPONENT_ALIASES - 包含在构建中的组件的库别名列表；由 armino_build_process 设置。

  • C_COMPILE_OPTIONS - 适用于所有组件的 C 源代码文件的编译选项。

  • COMPILE_OPTIONS - 适用于所有组件的源文件（无论是 C 还是 C++）的编译选项。

  • COMPILE_DEFINITIONS - 适用于所有组件源文件的编译定义。

  • CXX_COMPILE_OPTIONS - 适用于所有组件的 C++ 源文件的编译选项。

  • EXECUTABLE - 项目可执行文件；通过调用 armino_build_executable 设置。

  • EXECUTABLE_NAME - 不含扩展名的项目可执行文件的名称；通过调用 armino_build_executable 设置。

  • EXECUTABLE_DIR - 输出的可执行文件的路径

  • ARMINO_PATH - ARMINO 路径；由 ARMINO_PATH 环境变量设置，或者从 armino.cmake 的位置推断。

  • ARMINO_SOC - 构建的目标芯片；由 armino_build_process 的目标参数设置。

  • ARMINO_VER - ARMINO 版本；由版本文件或 ARMINO_PATH 仓库的 Git 版本设置。

  • INCLUDE_DIRECTORIES - 包含所有组件源文件的目录。

  • KCONFIGS - 构建过程中组件里的 Kconfig 文件的列表；由 armino_build_process 设置。

  • KCONFIG_PROJBUILDS - 构建过程中组件中的 Kconfig.projbuild 文件的列表；由 armino_build_process 设置。

  • PROJECT_NAME - 项目名称；由 armino_build_process 的 PROJECT_NAME 参数设置。

  • PROJECT_DIR - 项目的目录；由 armino_build_process 的 PROJECT_DIR 参数设置。

  • PROJECT_VER - 项目的版本；由 armino_build_process 的 PROJECT_VER 参数设置。

  • PYTHON - 用于构建的 Python 解释器；如果有则从 PYTHON 环境变量中设置，如果没有，则使用 “python”。

  • SDKCONFIG - 输出的配置文件的完整路径；由 armino_build_process SDKCONFIG 参数设置。

  • SDKCONFIG_DEFAULTS - 包含默认配置的文件列表；由 armino_build_process SDKCONFIG_DEFAULTS 参数设置。

  • SDKCONFIG_HEADER - 包含组件配置的 C/C++ 头文件的完整路径；由 armino_build_process 设置。

  • SDKCONFIG_CMAKE - 包含组件配置的 CMake 文件的完整路径；由 armino_build_process 设置。

  • SDKCONFIG_JSON - 包含组件配置的 JSON 文件的完整路径；由 armino_build_process 设置。

  • SDKCONFIG_JSON_MENUS - 包含配置菜单的 JSON 文件的完整路径；由 armino_build_process 设置。

组件 API

armino_component_get_property(var component property [GENERATOR_EXPRESSION])

获取一个指定的 component 的 组件属性 property，并将其存储在当前作用域可访问的 var 中。指定 GENERATOR_EXPRESSION 将获取该属性的生成器表达式字符串（不是实际值），它可以在支持生成器表达式的 CMake 命令中使用。

armino_component_set_property(component property val [APPEND])

设置指定的 component 的 组件属性，property 的值为 val。特定 APPEND 将把指定的值追加到属性的当前值后。如果该属性之前不存在或当前为空，指定的值将成为第一个元素/成员。

armino_component_register([[SRCS src1 src2 ...] | [[SRC_DIRS dir1 dir2 ...] [EXCLUDE_SRCS src1 src2 ...]]
                       [INCLUDE_DIRS dir1 dir2 ...]
                       [PRIV_INCLUDE_DIRS dir1 dir2 ...]
                       [REQUIRES component1 component2 ...]
                       [PRIV_REQUIRES component1 component2 ...]
                       [LDFRAGMENTS ldfragment1 ldfragment2 ...]
                       [REQUIRED_ARMINO_SOCS target1 target2 ...]
                       [EMBED_FILES file1 file2 ...]
                       [EMBED_TXTFILES file1 file2 ...]
                       [KCONFIG kconfig]
                       [KCONFIG_PROJBUILD kconfig_projbuild])

将一个组件注册到构建系统中。就像 project() CMake 命令一样，该命令应该直接从组件的 CMakeLists.txt 中调用（而不是通过函数或宏），且建议在其他命令之前调用该命令。下面是一些关于在 armino_component_register 之前 不能 调用哪些命令的指南：

  • 在 CMake 脚本模式下无效的命令。

  • 在 project_include.cmake 中定义的自定义命令。

  • 除了 armino_build_get_property 之外，构建系统的 API 命令；但要考虑该属性是否有被设置。

对变量进行设置和操作的命令，一般可在 armino_component_register 之前调用。

armino_component_register 的参数包括：

  • SRCS - 组件的源文件，用于为组件创建静态库；如果没有指定，组件将被视为仅配置组件，从而创建接口库。

  • SRC_DIRS, EXCLUDE_SRCS - 用于通过指定目录来 glob 源文件 (.c、.cpp、.S)，而不是通过 SRCS 手动指定源文件。请注意，这受 :ref:CMake 中通配符的限制<cmake-file-globbing>。 在 EXCLUDE_SRCS 中指定的源文件会从被 glob 的文件中移除。

  • INCLUDE_DIRS - 相对于组件目录的路径，该路径将被添加到需要当前组件的所有其他组件的 include 搜索路径中。

  • PRIV_INCLUDE_DIRS - 必须是相对于组件目录的目录路径，它仅被添加到这个组件源文件的 include 搜索路径中。

  • REQUIRES - 组件的公共组件依赖项。

  • PRIV_REQUIRES - 组件的私有组件依赖项；在仅用于配置的组件上会被忽略。

  • LDFRAGMENTS - 组件链接器片段文件。

  • REQUIRED_ARMINO_SOCS - 指定该组件唯一支持的目标。

  • KCONFIG - 覆盖默认的 Kconfig 文件。

  • KCONFIG_PROJBUILD - 覆盖默认的 Kconfig.projbuild 文件。

以下内容用于 :ref:将数据嵌入到组件中<cmake_embed_data>，并在确定组件是否仅用于配置时被视为源文件。这意味着，即使组件没有指定源文件，如果组件指定了以下其中之一，仍然会在内部为组件创建一个静态库。

  • EMBED_FILES - 嵌入组件的二进制文件

  • EMBED_TXTFILES - 嵌入组件的文本文件

组件属性

组件的属性值可以通过使用构建命令 armino_component_get_property 来获取。例如，以下命令可以获取 freertos 组件的目录。

armino_component_get_property(dir freertos COMPONENT_DIR)
message(STATUS "The 'freertos' component directory is: ${dir}")

  • COMPONENT_ALIAS - COMPONENT_LIB 的别名，用于将组件链接到外部目标；由 armino_build_component 设置，别名库本身由 armino_component_register 创建。

  • COMPONENT_DIR - 组件目录；由 armino_build_component 设置。

  • COMPONENT_OVERRIDEN_DIR - 如果 :ref:这个组件覆盖了另一个组件<cmake-components-same-name>，则包含原组件的目录。

  • COMPONENT_LIB - 所创建的组件静态/接口库的名称；由 armino_build_component 设置，库本身由 armino_component_register 创建。

  • COMPONENT_NAME - 组件的名称；由 armino_build_component 根据组件的目录名设置。

  • COMPONENT_TYPE - 组件的类型（LIBRARY 或 CONFIG_ONLY）。如果一个组件指定了源文件或嵌入了一个文件，那么它的类型就是 LIBRARY。

  • EMBED_FILES - 要嵌入组件的文件列表；由 armino_component_register EMBED_FILES 参数设置。

  • EMBED_TXTFILES - 要嵌入组件的文本文件列表；由 armino_component_register EMBED_TXTFILES 参数设置。

  • INCLUDE_DIRS - 组件 include 目录列表；由 armino_component_register INCLUDE_DIRS 参数设置。

  • KCONFIG - 组件 Kconfig 文件；由 armino_build_component 设置。

  • KCONFIG_PROJBUILD - 组件 Kconfig.projbuild；由 armino_build_component 设置。

  • LDFRAGMENTS - 组件链接器片段文件列表；由 armino_component_register LDFRAGMENTS 参数设置。

  • PRIV_INCLUDE_DIRS - 组件私有 include 目录列表；在 LIBRARY 类型的组件 armino_component_register PRIV_INCLUDE_DIRS 参数中设置。

  • PRIV_REQUIRES - 私有组件依赖关系列表；由 armino_component_register PRIV_REQUIRES 参数设置。

  • REQUIRED_ARMINO_SOCS - 组件支持的目标列表；由 armino_component_register EMBED_TXTFILES 参数设置。

  • REQUIRES - 公共组件依赖关系列表；由 armino_component_register REQUIRES 参数设置。

  • SRCS - 组件源文件列表；由 armino_component_register 的 SRCS 或 SRC_DIRS/EXCLUDE_SRCS 参数设置。