project

设置项目的名称。

概要

project(<PROJECT-NAME> [<language-name>...])
project(<PROJECT-NAME>
        [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
        [COMPAT_VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
        [DESCRIPTION <project-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(<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(<PROJECT-NAME> ...) 始终将 <PROJECT-NAME>_SOURCE_DIR、<PROJECT-NAME>_BINARY_DIR 和 <PROJECT-NAME>_IS_TOP_LEVEL 设置为普通变量。请参阅策略 CMP0180。同名的缓存条目始终像以前一样设置。

选项

选项包括

VERSION <version>

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

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

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

COMPAT_VERSION <version>

在 4.1 版本中新增。

注意

实验性。受 CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO 控制。

可选；需要同时设置 VERSION。

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

DESCRIPTION <project-description-string>

版本 3.9 中添加。

可选。设置变量

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

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

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

HOMEPAGE_URL <url-string>

3.12 版本新增。

可选。设置变量

为 <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、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 文件的顶部附近，但在调用 cmake_minimum_required() 之后调用 project() 命令。在调用可能影响其行为的其他命令之前建立版本和策略设置非常重要，因此如果未保持此顺序，project() 命令将发出警告。另请参阅策略 CMP0000。