Variables#

XCommon CMake relies on named variables which can be set for application and library code. These variables must be set before calling the XCommon CMake Functions. The order in which the variables are set does not matter.

Applications#

Required application variables#

APP_HW_TARGET

The target name or filename of an XN file to define the target platform. If a filename is provided, the full path is not required; the child directories of the application directory will be searched and the first file matching this name is used. Examples:

set(APP_HW_TARGET XCORE-AI-EXPLORER)
set(APP_HW_TARGET xk-316-mc.xn)

Advanced: this variable is not required if exclusively performing Native CPU Builds.

XMOS_SANDBOX_DIR

The path to the root of the sandbox directory. This is only required if APP_DEPENDENT_MODULES is non-empty. See Sandbox Structure.

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../..)

Optional application variables#

APP_ASM_SRCS

List of assembly source files to compile. File paths are relative to the application directory. If not set, all *.S files in the src directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any assembly sources. Examples:

set(APP_ASM_SRCS src/feature0/f0.S src/feature1/f1.S)
set(APP_ASM_SRCS "")
APP_C_SRCS

List of C source files to compile. File paths are relative to the application directory. If not set, all *.c files in the src directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any C sources. Examples:

set(APP_C_SRCS src/feature0/f0.c src/feature1/f1.c)
set(APP_C_SRCS "")
APP_COMPILER_FLAGS

List of options to the compiler for use when compiling all source files, except those which have their own options via the APP_COMPILER_FLAGS_<filename> variable. This variable should also be used for compiler definitions via the -D option. Default: empty list which provides no compiler options. Example:

set(APP_COMPILER_FLAGS -g -O3 -Wall -DMY_DEF=123)
APP_COMPILER_FLAGS_<config>

List of options to the compiler for use when compiling all source files for the specified config, except those which have their own options via the APP_COMPILER_FLAGS_<filename> variable. This variable should also be used for compiler definitions via the -D option. Default: empty list which provides no compiler options. Example:

set(APP_COMPILER_FLAGS_config0 -g -O2 -DMY_DEF=456)
APP_COMPILER_FLAGS_<filename>

List of options to the compiler for use when compiling the specified file. Only the filename is required, not a full path to the file; these compiler options will be used when compiling all files in the application directory which have that filename. This variable should also be used for compiler definitions via the -D option. Default: empty list which provides no compiler options. Example:

set(APP_COMPILER_FLAGS_feature0.c -Os -DMY_DEF=789)
APP_CXX_SRCS

List of C++ source files to compile. File paths are relative to the application directory. If not set, all *.cpp files in the src directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any C++ sources. Examples:

set(APP_CXX_SRCS src/feature0/f0.cpp src/feature1/f1.cpp)
set(APP_CXX_SRCS "")
APP_DEPENDENT_ARCHIVES

List of static library archives to link into this application. The static library dependency must also be defined in the APP_DEPENDENT_MODULES variable. The items in this list can either be the name of the static library (if that static library only contains a single archive) or the name of an archive within a static library repository. Default: empty list, so the application does not attempt to link any static library archives. Examples:

set(APP_DEPENDENT_ARCHIVES lib_static0)
set(APP_DEPENDENT_ARCHIVES static0_archive1 static1_archive0)
APP_DEPENDENT_ARCHIVES_<config>

List of static library archives to link when building the specified application config. The static library dependency must also be defined in the APP_DEPENDENT_MODULES variable. The items in this list can either be the name of the static library (if that static library only contains a single archive) or the name of an archive within a static library repository. Default: empty list, so the application does not attempt to link any static library archives. Examples:

set(APP_DEPENDENT_ARCHIVES_config0 lib_static0)
APP_DEPENDENT_MODULES

List of this application’s dependencies, which must be present when compiling. See the separate dependency management section about the dependency fetching process and the acceptable format for values in this list. Unlike other variables, the values to set for APP_DEPENDENT_MODULES should be quoted, as this is required when the string contains parentheses. Default: empty list, so the application has no dependencies. Example:

set(APP_DEPENDENT_MODULES "lib_i2c(6.1.1)"
                          "lib_i2s(5.0.0)")
APP_INCLUDES

List of directories to add to the compiler’s include search path when compiling sources. Default: empty list, so no directories are added. Example:

set(APP_INCLUDES src src/feature0)
APP_PCA_ENABLE

Boolean option to enable Pre-Compilation Analysis for XC source files. Default: OFF. Example:

set(APP_PCA_ENABLE ON)
APP_XC_SRCS

List of XC source files to compile. File paths are relative to the application directory. If not set, all *.xc files in the src directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any XC sources. Examples:

set(APP_XC_SRCS src/feature0/f0.xc src/feature1/f1.xc)
set(APP_XC_SRCS "")
APP_XSCOPE_SRCS

List of xscope configuration files to use in the application. File paths are relative to the application directory. If not set, all *.xscope files in the src directory and its subdirectories will be used. An empty string can be set to avoid using any xscope configuration files. Examples:

set(APP_XSCOPE_SRCS src/config.xscope)
set(APP_XSCOPE_SRCS "")
SOURCE_FILES_<config>

List of source files to use only when building the specified application config. Each application config initially has the same source file list, which is created according to the behaviour of the language-specific source list variables. Then for each application config, sources are removed from their list if a different application config has specified that file in its SOURCE_FILES_<config> variable.

set(SOURCE_FILES_config0 src/config0.c)
XMOS_DEP_DIR_<module>

Directory containing the dependency <module> as an override to the default sandbox root directory in XMOS_SANDBOX_DIR. This is the path to the root of the module.

set(XMOS_DEP_DIR_lib_i2c /home/user/lib_i2c)

Modules#

Required module variables#

LIB_DEPENDENT_MODULES

List of this module’s dependencies, which must be present when compiling. See the separate dependency management section about the dependency fetching process and the acceptable format for values in this list. If this module has no dependencies, this variable must be set as an empty string. Unlike other variables, the values to set for LIB_DEPENDENT_MODULES should be quoted, as this is required when the string contains parentheses. Examples:

set(LIB_DEPENDENT_MODULES "lib_logging(3.1.1)"
                          "lib_xassert(4.1.0)")
set(LIB_DEPENDENT_MODULES "")
LIB_INCLUDES

List of directories to add to the compiler’s include search path when compiling sources. Example:

set(LIB_INCLUDES api src/feature0)
LIB_NAME

String of the name for this module. This string will be the name used by the dependent modules list variables for any applications/modules that require this module. Example:

set(LIB_NAME lib_logging)
LIB_VERSION

String of the three-part version number for this module. Example:

set(LIB_VERSION 3.1.1)

Optional module variables#

LIB_ASM_SRCS

List of assembly source files to compile. File paths are relative to the module directory. If not set, all *.S files in the src directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any assembly sources. Examples:

set(LIB_ASM_SRCS src/feature0/f0.S src/feature1/f1.S)
set(LIB_ASM_SRCS "")
LIB_C_SRCS

List of C source files to compile. File paths are relative to the module directory. If not set, all *.c files in the src directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any C sources. Examples:

set(LIB_C_SRCS src/feature0/f0.c src/feature1/f1.c)
set(LIB_C_SRCS "")
LIB_COMPILER_FLAGS

List of options to the compiler for use when compiling all source files, except those which have their own options via the LIB_COMPILER_FLAGS_<filename> variable. This variable should also be used for compiler definitions via the -D option. Default: empty list which provides no compiler options. Example:

set(LIB_COMPILER_FLAGS -g -O3 -Wall -DMY_DEF=123)
LIB_COMPILER_FLAGS_<filename>

List of options to the compiler for use when compiling the specified file. Only the filename is required, not a full path to the file; these compiler options will be used when compiling all files in the module directory which have that filename. This variable should also be used for compiler definitions via the -D option. Default: empty list which provides no compiler options. Example:

set(APP_COMPILER_FLAGS_feature0.c -Os -DMY_DEF=456)
LIB_CXX_SRCS

List of C++ source files to compile. File paths are relative to the module directory. If not set, all *.cpp files in the src directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any C++ sources. Examples:

set(LIB_CXX_SRCS src/feature0/f0.cpp src/feature1/f1.cpp)
set(LIB_CXX_SRCS "")
LIB_OPTIONAL_HEADERS

List of header files that can optionally be present in an application or module which requires this module. These files are not present in this module. If they are present in an application or module, the preprocessor macro __<name>_h_exists__ will be set. Files within this module can then contain code which is conditionally compiled based on the presence of these optional headers in other applications. Every module or static library has an automatic optional header; for a library named lib_foo, the optional header foo_conf.h will automatically be configured, so it doesn’t need to be set in this variable. Default: empty list which provides no optional headers. Example:

set(LIB_OPTIONAL_HEADERS abc_conf.h)
LIB_XC_SRCS

List of XC source files to compile. File paths are relative to the module directory. If not set, all *.xc files in the src directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any XC sources. Examples:

set(LIB_XC_SRCS src/feature0/f0.xc src/feature1/f1.xc)
set(LIB_XC_SRCS "")
LIB_XSCOPE_SRCS

List of xscope configuration files to use for this module. File paths are relative to the module directory. If not set, all *.xscope files in the src directory and its subdirectories will be used. An empty string can be set to avoid using any xscope configuration files for this module. Examples:

set(LIB_XSCOPE_SRCS src/config.xscope)
set(LIB_XSCOPE_SRCS "")

Static Libraries#

Static library repositories have two possible modes of use: building the static library archive from source, and linking the static library (with any additional sources) into an application. Most static library variables in the XCommon CMake API are used in just one of these two modes of use.

Variables for archive build#

LIB_ARCHIVES

List of archives to build. If not set, a single archive (per supported architecture) is built and is named by the LIB_NAME variable. Example:

set(LIB_ARCHIVES archive0 archive1)
LIB_ARCHIVE_ARCHS

List of architectures for which to build archives. If not set, and LIB_ARCHIVE_ARCHS_<archive> is also unset, then the default archive build architecture is xs3a. Example:

set(LIB_ARCHIVE_ARCHS xs2a xs3a)
LIB_ARCHIVE_ARCHS_<archive>

List of architectures for which to build the named archive. If this is not set, the named archive will be built for the architectures in LIB_ARCHIVE_ARCHS, and if that is unset, the default is xs3a. Example:

set(LIB_ARCHIVE_ARCHS_archive0 xs2a xs3a)
LIB_ARCHIVE_ASM_SRCS

List of assembly source files to compile to create the archive. File paths are relative to the static library directory. If not set, all *.S files in the libsrc directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any assembly sources. Examples:

set(LIB_ARCHIVE_ASM_SRCS libsrc/feature0/f0.S libsrc/feature1/f1.S)
set(LIB_ARCHIVE_ASM_SRCS "")
LIB_ARCHIVE_COMPILER_FLAGS

List of options to the compiler for use when compiling all source files. This variable should also be used for compiler definitions via the -D option. Default: empty list which provides no compiler options. Example:

set(LIB_ARCHIVE_COMPILER_FLAGS -O3 -Wall -DMY_DEF=123)
LIB_ARCHIVE_COMPILER_FLAGS_<archive_name>

List of options to the compiler for use when compiling all source files when building the named archive. This variable should also be used for compiler definitions via the -D option. Default: empty list which provides no compiler options. Example:

set(LIB_ARCHIVE_COMPILER_FLAGS_archive0 -O3 -Wall -DMY_DEF=123)
LIB_ARCHIVE_CXX_SRCS

List of C++ source files to compile to create the archive. File paths are relative to the static library directory. If not set, all *.cpp files in the libsrc directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any C++ sources. Examples:

set(LIB_ARCHIVE_CXX_SRCS libsrc/feature0/f0.cpp libsrc/feature1/f1.cpp)
set(LIB_ARCHIVE_CXX_SRCS "")
LIB_ARCHIVE_C_SRCS

List of C source files to compile to create the archive. File paths are relative to the static library directory. If not set, all *.c files in the libsrc directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any C sources. Examples:

set(LIB_ARCHIVE_C_SRCS libsrc/feature0/f0.c libsrc/feature1/f1.c)
set(LIB_ARCHIVE_C_SRCS "")
LIB_ARCHIVE_DEPENDENT_MODULES

List of this static library’s dependencies, which must be present when compiling. See the separate dependency management section about the dependency fetching process and the acceptable format for values in this list. If this static library has no dependencies, this variable must be set as an empty string. Unlike other variables, the values to set for LIB_ARCHIVE_DEPENDENT_MODULES should be quoted, as this is required when the string contains parentheses. Examples:

set(LIB_ARCHIVE_DEPENDENT_MODULES "lib_logging(3.1.1)"
                                  "lib_xassert(4.1.0)")
set(LIB_ARCHIVE_DEPENDENT_MODULES "")
LIB_ARCHIVE_INCLUDES

List of directories to add to the compiler’s include search path when compiling sources. Example:

set(LIB_INCLUDES api src/feature0)
LIB_ARCHIVE_XC_SRCS

List of XC source files to compile to create the archive. File paths are relative to the static library directory. If not set, all *.xc files in the libsrc directory and its subdirectories will be compiled. An empty string can be set to avoid compiling any XC sources. Examples:

set(LIB_ARCHIVE_XC_SRCS libsrc/feature0/f0.xc libsrc/feature1/f1.xc)
set(LIB_ARCHIVE_XC_SRCS "")
XMOS_SANDBOX_DIR

The path to the root of the sandbox directory. This is only required if LIB_ARCHIVE_DEPENDENT_MODULES is non-empty. This must be set in the static library’s lib_build_info.cmake before the call to XMOS_REGISTER_STATIC_LIB. See Sandbox Structure.

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../..)

Variables for application build with archive#

Variables for this mode of use are the same as the Required module variables and Optional module variables. Variables that affect source files (eg. compiler flags, selection of source files) are only applied to any additional source files that may be present in the static library repository; the static library archive is not rebuilt.

Output Variables#

Experienced CMake users are able to add custom CMake code around the XCommon CMake build system. To support this, some variables are exposed from the XMOS_REGISTER_APP function.

APP_BUILD_ARCH

String of the architecture of the application being built. This variable allows the CMake code for a module to be conditionally configured based on the target architecture.

APP_BUILD_TARGETS

List of the target names for the applications which have been configured. This allows relationships to be defined with custom CMake targets that a user may create.

XCOMMON_CMAKE_VER

String containing the version number of XCommon CMake. This is printed as part of a version string message when run with --log-level=VERBOSE at the beginning of the CMake configuration stage. This can be used to write CMake code using knowledge of which versions of XCommon CMake include the required features. Version number comparisons must be performed with the VERSION_ binary tests in the if function for the correct interpretation of the version number sub-components. For example, if a feature is added in v1.1.0:

if(XCOMMON_CMAKE_VER VERSION_GREATER_EQUAL 1.1.0)
    # Use the supported feature
else()
    # Do something else as feature is not supported
endif()