project¶

设置工程名称。

大纲¶

project(<PROJECT-NAME> [<language-name>...])
project(<PROJECT-NAME>
        [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-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>]]]，并设置以下变量

在 3.12 版中添加：如果从顶级 CMakeLists.txt 调用 project() 命令，那么版本也会存储在 CMAKE_PROJECT_VERSION 变量中。

DESCRIPTION <project-description-string>

在 3.9 版中添加。

可选。将变量

PROJECT_DESCRIPTION，<PROJECT-NAME>_DESCRIPTION

设置为 <project-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、DESCRIPTION 和 HOMEPAGE_URL 选项设置的变量旨在用作包元数据和文档中的默认值。

代码注入¶

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

project¶

大纲¶

选项¶

代码注入¶

用法¶

目录

上一主题

下一主题

本页