project

设置项目的名称。

概要

project(<PROJECT-NAME> [<language-name>...])
project(<PROJECT-NAME>
        [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
        [COMPAT_VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
        [SPDX_LICENSE <license-string>]
        [DESCRIPTION <description-string>]
        [HOMEPAGE_URL <url-string>]
        [LANGUAGES <language-name>...])

设置项目名称，并将其存储在变量 PROJECT_NAME 中。当从顶层 CMakeLists.txt 调用时，项目名称也会存储在变量 CMAKE_PROJECT_NAME 中。

同时设置变量

PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR

项目的源代码目录的绝对路径。

PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR

项目的二进制目录的绝对路径。

PROJECT_IS_TOP_LEVEL, <PROJECT-NAME>_IS_TOP_LEVEL

3.21 版本新增。

指示项目是否为顶层的布尔值。

更多变量由下面“选项”部分描述的可选参数设置。如果未提供选项，则其对应的变量将设置为空字符串。

请注意，形式为 <name>_SOURCE_DIR 和 <name>_BINARY_DIR 的变量也可能在调用 project() 命令之前被其他命令设置（例如 FetchContent_MakeAvailable() 命令）。项目不应依赖于 <PROJECT-NAME>_SOURCE_DIR 或 <PROJECT-NAME>_BINARY_DIR 在 project() 调用或其子作用域之外的特定值。

在 3.30 版本中更改： 如果 <PROJECT-NAME>_SOURCE_DIR、<PROJECT-NAME>_BINARY_DIR 和 <PROJECT-NAME>_IS_TOP_LEVEL 在调用 project(<PROJECT-NAME> ...) 时已被设置为普通变量，则此调用会更新它们。同名的缓存条目始终按原样设置。请参阅 3.30.3、3.30.4 和 3.30.5 的发布说明了解详情。

在 3.31 版本中更改： <PROJECT-NAME>_SOURCE_DIR、<PROJECT-NAME>_BINARY_DIR 和 <PROJECT-NAME>_IS_TOP_LEVEL 始终由 project(<PROJECT-NAME> ...) 作为普通变量设置。请参阅策略 CMP0180。同名的缓存条目始终按原样设置。

选项

选项包括

VERSION <version>

可选；除非策略 CMP0048 设置为 NEW，否则可能不会使用。

接受一个由非负整数组成的 <version> 参数，即 <major>[.<minor>[.<patch>[.<tweak>]]]，并设置变量

• PROJECT_VERSION, <PROJECT-NAME>_VERSION

• PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR

• PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR

• PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH

• PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK。

在 3.12 版本中添加： 当 project() 命令从顶层 CMakeLists.txt 调用时，版本也会存储在变量 CMAKE_PROJECT_VERSION 中。

COMPAT_VERSION <version>

在 4.1 版本中新增。

注意

实验性。受 CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO 控制。

可选；需要同时设置 VERSION。

接受一个由非负整数组成的 <version> 参数，即 <major>[.<minor>[.<patch>[.<tweak>]]]，并设置变量

• PROJECT_COMPAT_VERSION, <PROJECT-NAME>_COMPAT_VERSION

  当 project() 命令从顶层 CMakeLists.txt 调用时，兼容版本也会存储在变量 CMAKE_PROJECT_COMPAT_VERSION 中。

SPDX_LICENSE <license-string>

版本 4.2 中添加。

注意

实验性。受 CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO 控制。

可选。将变量

• PROJECT_SPDX_LICENSE, <PROJECT-NAME>_SPDX_LICENSE

设置为 <license-string>，它应该是一个 System Package Data Exchange (SPDX) License Expression，用于描述整个项目的许可证（包括与项目一起分发的文档、资源或其他材料），以及软件构件。请参阅 SPDX 许可证列表以获取常用许可证及其标识符列表。请参阅 SPDX_LICENSE 属性来指定单个软件构件的许可证。

注意

项目许可证不用于初始化单个目标的 SPDX_LICENSE 属性。这使得在导出包信息时指定的包许可证和默认组件许可证具有意义。只有 Common Package Specification 导出才会使用此信息。

在某些情况下，项目许可证会被继承为包许可证。有关更多信息，请参阅 PROJECT 选项以及 export() 和 install() 命令的相关文档。

DESCRIPTION <description-string>

版本 3.9 中添加。

可选。将变量

• PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION

设置为 <description-string>。建议此描述为相对较短的字符串，通常不超过几个词。

当 project() 命令从顶层 CMakeLists.txt 调用时，描述也会存储在变量 CMAKE_PROJECT_DESCRIPTION 中。

在 3.12 版本中添加： 添加了 <PROJECT-NAME>_DESCRIPTION 变量。

HOMEPAGE_URL <url-string>

3.12 版本新增。

可选。将变量

• PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL

设置为 <url-string>，它应该是项目的规范主页 URL。

当 project() 命令从顶层 CMakeLists.txt 调用时，URL 也会存储在变量 CMAKE_PROJECT_HOMEPAGE_URL 中。

LANGUAGES <language-name>...

可选。也可以根据第一个短签名省略 LANGUAGES 关键字指定。

选择构建项目所需的编程语言。

支持的语言有 C、CXX（即 C++）、CSharp（即 C#）、CUDA、OBJC（即 Objective-C）、OBJCXX（即 Objective-C++）、Fortran、HIP、ISPC、Swift、ASM、ASM_NASM、ASM_MARMASM、ASM_MASM 和 ASM-ATT。

在 3.8 版本中添加： 添加了 CSharp 和 CUDA 支持。

在 3.15 版本中添加： 添加了 Swift 支持。

在 3.16 版本中添加： 添加了 OBJC 和 OBJCXX 支持。

在 3.18 版本中添加： 添加了 ISPC 支持。

在 3.21 版本中添加： 添加了 HIP 支持。

在 3.26 版本中添加： 添加了 ASM_MARMASM 支持。

如果启用 ASM，请将其放在最后，以便 CMake 可以检查 C 等其他语言的编译器是否也适用于汇编。

默认情况下，如果未提供语言选项，则启用 C 和 CXX。指定语言 NONE，或使用 LANGUAGES 关键字但不列出任何语言，以跳过启用任何语言。

VERSION、COMPAT_VERSION、SPDX_LICENSE、DESCRIPTION 和 HOMEPAGE_URL 选项设置的变量旨在用作包元数据和文档中的默认值。export() 和 install() 命令在生成 Common Package Specification 包描述时会相应地使用这些变量。

代码注入

用户可以通过定义一些变量来指定在 project() 命令执行的不同点包含哪些文件。以下概述了 project() 调用期间执行的步骤

• 在 3.15 版本中添加： 对于每一次 project() 调用，无论项目名称如何，都会包含 CMAKE_PROJECT_INCLUDE_BEFORE（如果已设置）指定的任何文件和模块。

• 在 3.17 版本中添加： 如果 project() 命令将 <PROJECT-NAME> 指定为其项目名称，则包含 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE（如果已设置）指定的任何文件和模块。

• 设置上面“纲要”和“选项”部分详述的各种项目特定变量。

• 仅在第一次调用 project() 时

  • 如果设置了 CMAKE_TOOLCHAIN_FILE，则至少读取一次。它可能会被读取多次，并且在稍后启用语言时也可能再次读取（参见下文）。

  • 设置描述主机和目标平台的变量。特定语言的变量此时可能已设置，也可能未设置。在第一次运行时，可能定义的唯一特定语言变量是工具链文件可能已设置的那些。在后续运行时，可能设置从先前运行缓存的特定语言变量。

  • 在 3.24 版本中添加： 包含 CMAKE_PROJECT_TOP_LEVEL_INCLUDES（如果已设置）列出的每个文件。该变量之后会被 CMake 忽略。

• 启用调用中指定的任何语言，或在未提供任何语言时启用默认语言。首次启用语言时，工具链文件可能会被重新读取。

• 在 3.15 版本中添加： 对于每一次 project() 调用，无论项目名称如何，都会包含 CMAKE_PROJECT_INCLUDE（如果已设置）指定的任何文件和模块。

• 如果 project() 命令将 <PROJECT-NAME> 指定为其项目名称，则包含 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE（如果已设置）指定的任何文件和模块。

用法

项目的顶层 CMakeLists.txt 文件必须包含一个直接调用 project() 命令的字面值；通过 include() 命令加载它是不够的。如果不存在这样的调用，CMake 将发出警告并假装在顶部有一个 project(Project) 来启用默认语言（C 和 CXX）。

注意

在顶层 CMakeLists.txt 文件的开头调用 project() 命令，但在调用 cmake_minimum_required() 之后。建立版本和策略设置，然后再调用可能受其影响的其他命令是很重要的，为此 project() 命令将在未遵循此顺序时发出警告。另请参阅策略 CMP0000。