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() 调用及其子作用域之外保持特定值的 <PROJECT-NAME>_SOURCE_DIR 或 <PROJECT-NAME>_BINARY_DIR。

3.30 版本变更: 如果在调用 project(<PROJECT-NAME> ...) 时已经将 <PROJECT-NAME>_SOURCE_DIR、<PROJECT-NAME>_BINARY_DIR 和 <PROJECT-NAME>_IS_TOP_LEVEL 设置为普通变量，则该调用会更新它们。同名的缓存条目始终会像以前一样被设置。详情请参阅 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 版本新增: 当从顶层 CMakeLists.txt 调用 project() 命令时，版本也会存储在变量 CMAKE_PROJECT_VERSION 中。

COMPAT_VERSION <version>

Added in version 4.3.

可选；要求同时也设置 VERSION。

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

• PROJECT_COMPAT_VERSION, <PROJECT-NAME>_COMPAT_VERSION。

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

SPDX_LICENSE <license-string>

Added in version 4.3.

可选。设置以下变量

• PROJECT_SPDX_LICENSE, <PROJECT-NAME>_SPDX_LICENSE

为 <license-string>，该字符串应为一个 系统软件包数据交换 (SPDX) 许可证表达式，用于描述整个项目的许可证，包括除软件工件外，随项目分发的文档、资源或其他材料。有关常用许可证及其标识符的列表，请参阅 SPDX 许可证列表。关于为单个软件工件指定许可证，请参阅 SPDX_LICENSE 属性。

注意

项目许可证不会用于初始化单个目标的 SPDX_LICENSE 属性。这使得在导出软件包信息时指定的软件包许可证和默认组件许可证更具意义。仅通用软件包规范导出使用此信息。

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

DESCRIPTION <description-string>

版本 3.9 中添加。

可选。设置以下变量

• PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION

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

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

3.12 版本新增: 添加了 <PROJECT-NAME>_DESCRIPTION 变量。

HOMEPAGE_URL <url-string>

3.12 版本新增。

可选。设置以下变量

• PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL

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

当从顶层 CMakeLists.txt 调用 project() 命令时，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() 命令在生成通用软件包规范软件包描述时会相应地使用这些值。

代码注入

用户可以定义多个变量来指定在 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。