Skip to main content
欢迎来到PAWPAW技术文档网站，了解更多信息。

API 参考

函数​

CMake Header​

在应用程序或静态库的 CMakeLists.txt 文件中，必须调用以下 CMake 函数：

  • cmake_minimum_required：此函数用于设置 CMake 的最低版本要求，以便支持所使用的语言特性。您的 CMake 版本必须不低于此函数所设定的版本。合适的版本应为 XCommonCMake 支持的最低版本，具体请参见快速启动指南。

  • include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)：此行代码包含 xcore 工具链和 XCommonCMake 提供的函数。环境变量 XMOS_CMAKE_PATH 通过激活 XTCTools 环境来设置。

  • project：此函数接受一个参数，该参数将用作应用程序的基础名称。例如，如果此处设置为 my_app，则默认配置构建的 XE 可执行文件将命名为 my_app.xe。

这三行代码必须位于应用程序或静态库的 CMakeLists.txt 文件的开头。

cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(my_app)
# 现在，可以为应用程序或静态库编写 XCommon CMake 代码。

XCommon CMake Functions​

  • XMOS_REGISTER_APP()：在设置必需的应用程序变量和任何可选的应用程序变量之后调用此函数，以执行以下操作：

    • 定义应用程序构建目标。

    • 将应用程序源代码添加到可执行文件构建目标。

    • 为每个构建配置设置编译器选项。

    • 在清单中添加应用程序条目。

    • 检索任何缺失的依赖项。

    • 配置直接依赖项。

    • 检查可选头文件的存在。

    • 如果启用，创建预编译分析（PCA）命令。

      提示

      预编译分析（PCA）提供整个程序的优化，但仅适用于 XC 源文件。

  • XMOS_REGISTER_MODULE()：在设置必需的模块变量和任何可选的应用程序变量之后调用此函数，以执行以下操作：

    • 检查模块的主版本号以确保兼容性。
    • 检索模块的任何缺失依赖项。
    • 为模块源文件设置编译器选项。
    • 将模块源代码添加到可执行文件构建目标。
    • 在清单中添加模块条目。

    当添加使用此函数的模块依赖项时，将递归调用此函数。

  • XMOS_REGISTER_STATIC_LIB()：在设置必需的静态库变量和任何可选的静态库变量之后调用此函数，可采用以下两种方式之一：

    第一种方式，如果在静态库目录中运行 CMake，此函数将：

    • 定义静态库构建目标。
    • 将静态库源代码添加到构建目标。
    • 为静态库源代码设置编译器选项。
    • 在清单中添加静态库条目。
    • 检索任何缺失的依赖项。
    • 配置直接依赖项。

    另一种方式，如果静态库是应用程序的依赖项，那么在应用程序的依赖配置过程中将调用此函数。在这种情况下，它将将静态库链接到所有应用程序构建目标中。

变量​

XCommonCMake 依赖于可以为应用程序和库代码设置的命名变量。在调用 XCommon CMake Functions 之前，必须先设置这些变量。变量的设置顺序并不重要。

应用程序​

必需的应用程序变量​

  • APP_HW_TARGET

    XN 文件的目标名称或文件名，用于定义目标平台。如果提供文件名，不需要完整路径；系统将搜索应用程序目录的子目录，并使用找到的第一个匹配文件。例如：

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

    高级设置：如果仅执行 Native CPU Builds，则不需要此变量。

  • XMOS_SANDBOX_DIR

    沙箱目录的根路径。只有在 APP_DEPENDENT_MODULES 非空时才需要。参见 Sandbox Structure。

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

可选应用程序变量​

  • APP_ASM_SRCS

    编译所需的汇编源文件列表。文件路径相对于应用程序目录。若未指定，则默认编译 src 目录及其子目录下的所有 *.S 文件。设为空字符串则不编译任何汇编源文件。示例：

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

  • APP_C_SRCS

    编译所需的 C 源文件列表。文件路径相对于应用程序目录。若未指定，则默认编译 src 目录及其子目录下的所有 *.c 文件。设为空字符串则不编译任何 C 源文件。示例：

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

  • APP_COMPILER_FLAGS

    为编译所有源文件设定的编译器选项列表，不包括那些通过 APP_COMPILER_FLAGS_<filename> 变量已指定选项的文件。该变量也用于通过 -D 选项定义编译器。默认为空列表，不提供编译选项。示例：

    set(APP_COMPILER_FLAGS -g -O3 -Wall -DMY_DEF=123)

  • APP_COMPILER_FLAGS_<config>

    为编译指定配置的所有源文件设定的编译器选项列表，不包括那些通过 APP_COMPILER_FLAGS_<filename> 变量已指定选项的文件。该变量也用于通过 -D 选项定义编译器。默认为空列表，不提供编译选项。示例：

    set(APP_COMPILER_FLAGS_config0 -g -O2 -DMY_DEF=456)

  • APP_COMPILER_FLAGS_<filename>

    为编译指定文件设定的编译器选项列表。仅需文件名，无需完整路径；在编译应用程序目录中该文件名的所有文件时会使用这些选项。该变量也用于通过 -D 选项定义编译器。默认为空列表，不提供编译选项。示例：

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

  • APP_CXX_SRCS

    编译所需的 C++ 源文件列表。文件路径相对于应用程序目录。若未指定，则默认编译 src 目录及其子目录下的所有 *.cpp 文件。设为空字符串则不编译任何 C++ 源文件。示例：

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

  • APP_DEPENDENT_MODULES

    应用程序的依赖模块列表，编译时必须存在。关于依赖获取过程及列表值的格式，请参见依赖管理部分。与其他变量不同，设置 APP_DEPENDENT_MODULES 时应使用引号，尤其是当字符串中包含括号时。默认为空列表，表示无依赖。示例：

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

  • APP_INCLUDES

    编译源文件时，需加入到编译器的包含搜索路径中的目录列表。默认为空列表，不添加任何目录。示例：

    set(APP_INCLUDES src src/feature0)

  • APP_PCA_ENABLE

    是否启用 XC 源文件的预编译分析的布尔选项。默认关闭（OFF）。示例：

    set(APP_PCA_ENABLE ON)

  • APP_XC_SRCS

    编译所需的 XC 源文件列表。文件路径相对于应用程序目录。若未指定，则默认编译 src 目录及其子目录下的所有 *.xc 文件。设为空字符串则不编译任何 XC 源文件。示例：

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

  • APP_XSCOPE_SRCS

    应用程序中将使用的 xscope 配置文件列表。文件路径相对于应用程序目录。若未指定，则默认使用 src 目录及其子目录下的所有 *.xscope 文件。设为空字符串则不使用任何 xscope 配置文件。示例：

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

  • SOURCE_FILES_<config>

    仅在构建指定应用程序配置时使用的源文件列表。每个应用程序配置最初都有相同的源文件列表，根据特定语言的源列表变量的行为创建。然后，对于每个应用程序配置，如果其他应用程序配置已在其 SOURCE_FILES_<config> 变量中指定了该文件，则会从其列表中移除该源文件。

    set(SOURCE_FILES_config0 src/config0.c)

  • XMOS_DEP_DIR_<module>

    包含依赖模块 <module> 的目录，此路径覆盖了 XMOS_SANDBOX_DIR 默认的沙盒根目录。示例：

    set(XMOS_DEP_DIR_lib_i2c /home/user/lib_i2c)

模块​

必需模块变量​

  • LIB_DEPENDENT_MODULES

    此模块所依赖的其他模块列表，编译时必须存在。关于依赖获取过程及列表值的格式，请参见依赖管理部分。如果此模块无依赖，则此变量应设为空字符串。与其他变量不同，设置 LIB_DEPENDENT_MODULES 时应使用引号，尤其是当字符串中包含括号时。示例：

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

  • LIB_INCLUDES

    编译源文件时，需加入到编译器的包含搜索路径中的目录列表。示例：

    set(LIB_INCLUDES apisrc/feature0)

  • LIB_NAME

    此模块的名称。此名称将用于任何需要此模块的应用程序或其他模块的依赖模块列表变量中。示例：

    set(LIB_NAME lib_logging)

  • LIB_VERSION

    此模块的版本号，格式为三部分数字。示例：

    set(LIB_VERSION 3.1.1)

可选模块变量​

  • LIB_ASM_SRCS

    汇编源文件列表，用于编译。文件路径是相对于模块目录的。若未设定，则默认编译 src 目录及其子目录下的所有 *.S 文件。设置为空字符串可以避免编译任何汇编源文件。示例：

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

  • LIB_C_SRCS

    C 语言源文件列表，用于编译。文件路径是相对于模块目录的。若未设定，则默认编译 src 目录及其子目录下的所有 *.c 文件。设置为空字符串可以避免编译任何 C 源文件。示例：

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

  • LIB_COMPILER_FLAGS

    编译器选项列表，用于编译所有源文件（特定文件除外，这些文件通过 LIB_COMPILER_FLAGS_<filename> 变量单独设置选项）。此变量也用于通过 -D 选项定义编译器宏。默认为空列表，不提供任何编译器选项。示例：

    set(LIB_COMPILER_FLAGS -g -O3 -Wall -DMY_DEF=123)

  • LIB_COMPILER_FLAGS_<filename>

    编译特定文件时的编译器选项列表。此处只需提供文件名，无需完整路径；编译模块目录中所有同名文件时将使用这些选项。此变量也用于通过 -D 选项定义编译器宏。默认为空列表，不提供任何编译器选项。示例：

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

  • LIB_CXX_SRCS

    C++ 源文件列表，用于编译。文件路径是相对于模块目录的。若未设定，则默认编译 src 目录及其子目录下的所有 *.cpp 文件。设置为空字符串可以避免编译任何 C++ 源文件。示例：

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

  • LIB_OPTIONAL_HEADERS

    可选的头文件列表，这些文件可以在需要此模块的应用程序或其他模块中存在。这些文件不在本模块中。如果在应用程序或其他模块中存在这些文件，则会设置预处理宏 _<name>h_exists。本模块中的文件可以包含基于这些可选头文件的存在与否来条件编译的代码。默认为空列表，不提供任何可选头文件。示例：

    set(LIB_OPTIONAL_HEADERS abc_conf.h)

  • LIB_XC_SRCS

    XC 源文件列表，用于编译。文件路径是相对于模块目录的。若未设定，则默认编译 src 目录及其子目录下的所有 *.xc 文件。设置为空字符串可以避免编译任何 XC 源文件。示例：

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

  • LIB_XSCOPE_SRCS

    xscope 配置文件列表，用于此模块。文件路径是相对于模块目录的。若未设定，则默认使用 src 目录及其子目录中的所有 *.xscope 文件。设置为空字符串可以避免为此模块使用任何 xscope 配置文件。示例：

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

静态库​

必需的静态库变量​

与“必需的模块变量”相同，还包括：

  • XMOS_SANDBOX_DIR

    沙箱目录的根路径。仅在 LIB_DEPENDENT_MODULES 非空时才需要。在包含 lib_build_info.cmake 之前，必须在静态库的 CMakeLists.txt 文件中设置此变量。参见“沙箱结构”。

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

可选的静态库变量​

与“可选的模块变量”相同，还包括：

  • LIB_ARCH

    要构建静态库的 xcore 架构列表。对于每种架构，将构建单独的静态库存档。如果为空或未定义，默认为 xs3a。示例：

    set(LIB_ARCH xs2a)
    set(LIB_ARCH xs2a xs3a)

输出变量​

有经验的 CMake 用户能够在 XCommon CMake 构建系统周围添加自定义 CMake 代码。为支持此功能，一些变量从 XMOS_REGISTER_APP 函数中公开。

  • APP_BUILD_TARGETS：已配置的应用程序的目标名称列表。这允许定义与用户可能创建的自定义 CMake 目标之间的关系。

  • APP_BUILD_ARCH：正在构建的应用程序的架构字符串。此变量允许根据目标架构有条件地配置模块的 CMake 代码。

依赖格式​

变量 APP_DEPENDENT_MODULES 和 LIB_DEPENDENT_MODULES 存储了应用程序、模块或静态库的模块依赖列表。该格式灵活，既支持向外部用户发布，也适应内部开发的实践。

外部发布时采用以下格式：

  1. lib_abc(1.2.3)：从 github.com/xmos 获取带有标签 v1.2.3 的 lib_abc；系统会先检查是否可以通过 SSH 密钥访问，如果不行则改用 HTTPS。发布的标签前会加上字符 'v'，即必须为 v1.2.3。

在内部开发中，可以指定资源位置和版本。

首先，资源位置可以在字符串开头指定：

  1. lib_abc：从 github.com/xmos 克隆 lib_abc；采用与第1种格式相同的 SSH/HTTPS 访问方式。
  2. myuser/lib_abc：从 github.com/myuser 克隆 lib_abc；采用与第1种格式相同的 SSH/HTTPS 访问方式。
  3. othergitserver.com:myuser/lib_abc：通过 SSH 访问克隆 git@othergitserver.com:myuser/lib_abc。
  4. https://othergitserver.com/myuser/lib_abc：通过 HTTPS 克隆此 URL，不进行 SSH 访问检查。

然后，版本可以在字符串末尾指定：

  1. lib_abc：未指定版本，将获取配置为默认的分支的最新代码。
  2. lib_abc(v1.2.3)：与第1种格式等效，获取标签 v1.2.3。
  3. lib_abc(develop)：获取 develop 分支的最新代码。
  4. lib_abc(4fa35fe)：获取指定的提交 4fa35fe。

可以将第2至5种格式与第6至9种格式结合使用，以同时指定资源位置和版本。例如：

set(APP_DEPENDENT_MODULES "myuser/lib_abc(develop)" "othergitserver.com:myuser/lib_foo(1.0.0)")
  • 从 github.com/myuser 使用 SSH 密钥（如果可用的话，否则使用 HTTPS）检出 lib_abc 的 develop 分支的最新代码。
  • 通过 othergitserver.com/myuser 的 SSH 访问克隆 lib_foo 并检出标签 v1.0.0。
编辑此页
本文最后由 Vergil Wong 更新于