Build API

[English]

Build API

armino_build_get_property(var property [GENERATOR_EXPRESSION])

Get a build property and store it in var. Specifying GENERATOR_EXPRESSION will retrieve the generator expression string for that property (not the actual value), which can be used with CMake commands that support generator expressions.

armino_build_set_property(property val [APPEND])

Set the value of a build property to val. APPEND will append the specified value to the property’s current value. If the property does not exist or is empty, the specified value will become the first element/member.

armino_build_component(component_dir)

Submit a component_dir directory containing a component to the build system. Relative paths will be converted to absolute paths relative to the current directory. All calls to this command must be executed before armino_build_process.

This command does not guarantee that the component will be processed during the build (see the COMPONENTS parameter description in armino_build_process)

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 ...])

Performs a lot of behind-the-scenes work for importing ARMINO components, including component configuration, library creation, dependency expansion and resolution. Among these functions, the most important for users is probably creating libraries by calling each component’s armino_component_register. This command creates a library for each component, which can be accessed using aliases in the form armino::*component_name*. These aliases can be used to link components to the user’s own targets, libraries or executables.

This call requires specifying the target chip with the target parameter. Optional parameters for the call include:

  • PROJECT_DIR - Project directory, defaults to CMAKE_SOURCE_DIR.

  • PROJECT_NAME - Project name, defaults to CMAKE_PROJECT_NAME.

  • PROJECT_VER - Project version/version number, defaults to “1”.

  • SDKCONFIG - Output path for the generated sdkconfig file, defaults to PROJECT_DIR/sdkconfig or CMAKE_SOURCE_DIR/sdkconfig depending on whether PROJECT_DIR is set.

  • SDKCONFIG_DEFAULTS - List of files containing default configuration (must include full paths in the list), defaults to empty; For each value filename in the list, if it exists, the configuration in the file filename.target will also be loaded. For each value filename in the list, the configuration in the file filename.target (if it exists) will also be loaded.

  • BUILD_DIR - Directory for placing ARMINO build-related tools, such as generated binary files, text files, components; defaults to CMAKE_BINARY_DIR.

  • COMPONENTS - Select components to process from components known to the build system (added via armino_build_component). This parameter is used to streamline the build process. If other components are needed in the dependency chain, they will be automatically added, i.e., automatically add the public and private dependencies of components in this list, then add the public and private dependencies of these dependencies, and so on. If not specified, all components known to the build system will be processed.

armino_build_executable(executable)

Specify the executable executable built by ARMINO. This will add additional targets, such as flash-related dependencies, generate additional binary files, etc. Should be called after armino_build_process.

armino_build_get_config(var config [GENERATOR_EXPRESSION])

Get the value of the specified configuration. Like build properties, specifying GENERATOR_EXPRESSION will retrieve the generator expression string for that configuration rather than the actual value, i.e., can be used with CMake commands that support generator expressions. However, the actual configuration value is only known after calling armino_build_process.

Build Properties

Build property values can be obtained by using the build command armino_build_get_property. For example, the following command can get information about the Python interpreter used during the build process.

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

  • BUILD_DIR - Build directory; set by the BUILD_DIR parameter of armino_build_process.

  • BUILD_COMPONENTS - List of components included in the build; set by armino_build_process.

  • BUILD_COMPONENT_ALIASES - List of library aliases for components included in the build; set by armino_build_process.

  • C_COMPILE_OPTIONS - Compilation options for C source code files applicable to all components.

  • COMPILE_OPTIONS - Compilation options for all component source files (whether C or C++).

  • COMPILE_DEFINITIONS - Compilation definitions applicable to all component source files.

  • CXX_COMPILE_OPTIONS - Compilation options for C++ source files applicable to all components.

  • EXECUTABLE - Project executable; set by calling armino_build_executable.

  • EXECUTABLE_NAME - Name of the project executable without extension; set by calling armino_build_executable.

  • EXECUTABLE_DIR - Path to the output executable

  • ARMINO_PATH - ARMINO path; set by the ARMINO_PATH environment variable, or inferred from the location of armino.cmake.

  • ARMINO_SOC - Target chip to build; set by the target parameter of armino_build_process.

  • ARMINO_VER - ARMINO version; set by the version file or Git version of the ARMINO_PATH repository.

  • INCLUDE_DIRECTORIES - Directory containing all component source files.

  • KCONFIGS - List of Kconfig files in components during the build process; set by armino_build_process.

  • KCONFIG_PROJBUILDS - List of Kconfig.projbuild files in components during the build process; set by armino_build_process.

  • PROJECT_NAME - Project name; set by the PROJECT_NAME parameter of armino_build_process.

  • PROJECT_DIR - Project directory; set by the PROJECT_DIR parameter of armino_build_process.

  • PROJECT_VER - Project version; set by the PROJECT_VER parameter of armino_build_process.

  • PYTHON - Python interpreter used for building; set from the PYTHON environment variable if available, otherwise uses “python”.

  • SDKCONFIG - Full path to the output configuration file; set by the SDKCONFIG parameter of armino_build_process.

  • SDKCONFIG_DEFAULTS - List of files containing default configuration; set by the SDKCONFIG_DEFAULTS parameter of armino_build_process.

  • SDKCONFIG_HEADER - Full path to the C/C++ header file containing component configuration; set by armino_build_process.

  • SDKCONFIG_CMAKE - Full path to the CMake file containing component configuration; set by armino_build_process.

  • SDKCONFIG_JSON - Full path to the JSON file containing component configuration; set by armino_build_process.

  • SDKCONFIG_JSON_MENUS - Full path to the JSON file containing configuration menus; set by armino_build_process.

Component API

armino_component_get_property(var component property [GENERATOR_EXPRESSION])

Get the component property property of the specified component and store it in var accessible in the current scope. Specifying GENERATOR_EXPRESSION will retrieve the generator expression string for that property (not the actual value), which can be used in CMake commands that support generator expressions.

armino_component_set_property(component property val [APPEND])

Set the component property property of the specified component to value val. Specifying APPEND will append the specified value to the property’s current value. If the property did not exist before or is currently empty, the specified value will become the first element/member.

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

Register a component into the build system. Like the project() CMake command, this command should be called directly from the component’s CMakeLists.txt (not through a function or macro), and it is recommended to call this command before other commands. Here are some guidelines about which commands cannot be called before armino_component_register:

  • Commands that are invalid in CMake script mode.

  • Custom commands defined in project_include.cmake.

  • Build system API commands other than armino_build_get_property; but consider whether that property has been set.

Commands that set and manipulate variables can generally be called before armino_component_register.

Parameters for armino_component_register include:

  • SRCS - Source files for the component, used to create a static library for the component; if not specified, the component will be treated as a configuration-only component, thereby creating an interface library.

  • SRC_DIRS, EXCLUDE_SRCS - Used to glob source files (.c, .cpp, .S) by specifying directories, rather than manually specifying source files through SRCS. Note that this is subject to :ref:limitations of wildcards in CMake<cmake-file-globbing>. Source files specified in EXCLUDE_SRCS will be removed from the globbed files.

  • INCLUDE_DIRS - Paths relative to the component directory that will be added to the include search path of all other components that require the current component.

  • PRIV_INCLUDE_DIRS - Must be directory paths relative to the component directory, which are only added to this component’s source file include search path.

  • REQUIRES - Public component dependencies of the component.

  • PRIV_REQUIRES - Private component dependencies of the component; ignored on configuration-only components.

  • LDFRAGMENTS - Component linker fragment files.

  • REQUIRED_ARMINO_SOCS - Specifies the targets uniquely supported by this component.

  • KCONFIG - Override the default Kconfig file.

  • KCONFIG_PROJBUILD - Override the default Kconfig.projbuild file.

The following are used for :ref:embedding data into components<cmake_embed_data> and are treated as source files when determining whether a component is configuration-only. This means that even if a component does not specify source files, if the component specifies one of the following, a static library will still be created internally for the component.

  • EMBED_FILES - Binary files to embed in the component

  • EMBED_TXTFILES - Text files to embed in the component

Component Properties

Component property values can be obtained by using the build command armino_component_get_property. For example, the following command can get the directory of the freertos component.

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

  • COMPONENT_ALIAS - Alias for COMPONENT_LIB, used to link components to external targets; set by armino_build_component, the alias library itself is created by armino_component_register.

  • COMPONENT_DIR - Component directory; set by armino_build_component.

  • COMPONENT_OVERRIDEN_DIR - If :ref:this component overrides another component<cmake-components-same-name>, contains the directory of the original component.

  • COMPONENT_LIB - Name of the created component static/interface library; set by armino_build_component, the library itself is created by armino_component_register.

  • COMPONENT_NAME - Component name; set by armino_build_component based on the component’s directory name.

  • COMPONENT_TYPE - Component type (LIBRARY or CONFIG_ONLY). If a component specifies source files or embeds a file, its type is LIBRARY.

  • EMBED_FILES - List of files to embed in the component; set by the armino_component_register EMBED_FILES parameter.

  • EMBED_TXTFILES - List of text files to embed in the component; set by the armino_component_register EMBED_TXTFILES parameter.

  • INCLUDE_DIRS - List of component include directories; set by the armino_component_register INCLUDE_DIRS parameter.

  • KCONFIG - Component Kconfig file; set by armino_build_component.

  • KCONFIG_PROJBUILD - Component Kconfig.projbuild; set by armino_build_component.

  • LDFRAGMENTS - List of component linker fragment files; set by the armino_component_register LDFRAGMENTS parameter.

  • PRIV_INCLUDE_DIRS - List of component private include directories; set in the armino_component_register PRIV_INCLUDE_DIRS parameter for LIBRARY type components.

  • PRIV_REQUIRES - List of private component dependencies; set by the armino_component_register PRIV_REQUIRES parameter.

  • REQUIRED_ARMINO_SOCS - List of targets supported by the component; set by the armino_component_register EMBED_TXTFILES parameter.

  • REQUIRES - List of public component dependencies; set by the armino_component_register REQUIRES parameter.

  • SRCS - List of component source files; set by the SRCS or SRC_DIRS/EXCLUDE_SRCS parameters of armino_component_register.