CMake指令：project

目录

1.简介

2.自动定义的变量

3.常见用法示例

4.与语言标准的关联

5.高级配置选项

6.结合其他指令使用

7.注意事项

8.总结

---

1.简介

  project 是 CMake 中用于定义项目基本信息的核心指令，通常位于顶级 CMakeLists.txt 的起始位置。它不仅声明项目名称，还能设置版本号、支持的编程语言，并初始化相关变量。

        基本语法：

project(<PROJECT_NAME>[VERSION <major>[.<minor>[.<patch>[.<tweak>]]]][LANGUAGES <language>...][DESCRIPTION <description>][HOMEPAGE_URL <url>][CXX_STANDARD <standard>]
)

• 必选参数：
  • <PROJECT_NAME>：项目名称（字母、数字、下划线，建议使用 PascalCase）。
• 可选参数：
  • VERSION：项目版本号（如 1.0.0），会自动定义 PROJECT_VERSION_* 变量。
  • LANGUAGES：支持的编程语言（如 C、CXX、Fortran、ASM 等），默认 C 和 CXX。
  • DESCRIPTION：项目描述（用于生成文档或打包）。
  • HOMEPAGE_URL：项目主页 URL。
  • CXX_STANDARD：C++ 标准（如 17、20，需 CMake 3.12+）。

2.自动定义的变量

project 指令会自动创建以下变量，方便后续使用：

变量名	描述
PROJECT_NAME	项目名称（与指令参数一致）
PROJECT_VERSION	完整版本号（如 1.0.0）
PROJECT_VERSION_MAJOR	主版本号（如 1）
PROJECT_VERSION_MINOR	次版本号（如 0）
PROJECT_VERSION_PATCH	修订号（如 0）
PROJECT_VERSION_TWEAK	微调号（若未指定则为空）
PROJECT_SOURCE_DIR	项目源目录（顶级 CMakeLists.txt 所在路径）
PROJECT_BINARY_DIR	项目构建目录（执行 cmake 命令的路径）
<PROJECT_NAME>_SOURCE_DIR	与 PROJECT_SOURCE_DIR 相同
<PROJECT_NAME>_BINARY_DIR	与 PROJECT_BINARY_DIR 相同

3.常见用法示例

1.最简形式

project(MyApp)  # 默认版本 0.1，支持 C 和 C++

2.指定版本号

project(MyLibraryVERSION 1.2.3LANGUAGES CXX  # 仅支持 C++
)message(STATUS "Project: ${PROJECT_NAME} v${PROJECT_VERSION}")
# 输出: Project: MyLibrary v1.2.3

3. 完整配置

project(MyAppVERSION 2.1.0LANGUAGES CXXDESCRIPTION "A cross-platform application"HOMEPAGE_URL "https://github.com/myorg/myapp"
)# 使用 C++20 标准
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

4.多项目嵌套

# 顶级项目
project(SuperProject VERSION 3.0.0)# 子项目（通过 add_subdirectory 包含）
add_subdirectory(libs/mylib)  # mylib/CMakeLists.txt 中定义子项目

4.与语言标准的关联

通过 CXX_STANDARD 参数可直接指定 C++ 标准，替代手动设置 CMAKE_CXX_STANDARD：

project(MyModernAppVERSION 1.0.0LANGUAGES CXXCXX_STANDARD 20  # 要求 C++20 标准CXX_STANDARD_REQUIRED ON  # 强制要求，不允许降级
)

5.高级配置选项

1.完整项目模板

cmake_minimum_required(VERSION 3.17)
project(MyAppVERSION 1.2.3LANGUAGES CXXDESCRIPTION "A modern C++ application"HOMEPAGE_URL "https://github.com/myorg/myapp"
)# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)# 配置构建类型
if(NOT CMAKE_BUILD_TYPE)set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
endif()# 添加编译选项
if(MSVC)add_compile_options(/W4 /WX)  # 启用所有警告并将警告视为错误
else()add_compile_options(-Wall -Wextra -Werror)
endif()# 添加可执行文件
add_executable(my_app src/main.cppsrc/utils.cpp
)# 安装规则
install(TARGETS my_app DESTINATION bin)
install(FILES config.ini DESTINATION etc)

2.跨平台项目配置

project(CrossPlatformAppVERSION 1.0.0LANGUAGES CXX
)# 平台特定配置
if(WIN32)target_compile_definitions(my_app PRIVATE _WIN32_WINNT=0x0601)  # Windows 7+set(PLATFORM_LIBS ws2_32)  # Windows 网络库
elseif(APPLE)set(PLATFORM_LIBS "-framework Cocoa")  # macOS GUI 框架
else()set(PLATFORM_LIBS pthread)  # Linux 线程库
endif()# 链接平台相关库
target_link_libraries(my_app PRIVATE ${PLATFORM_LIBS})

6.结合其他指令使用

1.与 option 结合控制功能

project(MyFeatureRichApp VERSION 1.0.0)option(ENABLE_LOGGING "Enable logging feature" ON)
option(ENABLE_NETWORKING "Enable networking" OFF)if(ENABLE_LOGGING)target_compile_definitions(my_app PRIVATE ENABLE_LOGGING=1)target_link_libraries(my_app PRIVATE spdlog)
endif()if(ENABLE_NETWORKING)target_sources(my_app PRIVATE src/network.cpp)target_link_libraries(my_app PRIVATE boost_system)
endif()

2.与 find_package 结合管理依赖

project(MyQtApp VERSION 1.0.0)# 查找 Qt5 依赖
find_package(Qt5 COMPONENTS Widgets REQUIRED)# 添加可执行文件并链接 Qt
add_executable(my_qt_app src/main.cpp src/mainwindow.cpp)
target_link_libraries(my_qt_app PRIVATE Qt5::Widgets)# 自动处理 Qt 元对象系统
set_target_properties(my_qt_app PROPERTIESAUTOMOC ONAUTOUIC ON
)

7.注意事项

1.多次调用 project

• 一个 CMakeLists.txt 中可多次调用 project，但后续调用会创建新的项目上下文，覆盖之前的变量（如 PROJECT_NAME）。
• 推荐在顶级 CMakeLists.txt 中只调用一次 project，子目录使用 add_subdirectory 包含。

2.版本号格式

• VERSION 参数必须符合 major.minor.patch.tweak 的数字格式，否则会导致变量定义异常。

3.语言支持

• 指定 LANGUAGES NONE 可禁用默认语言检测，适用于纯配置或脚本项目。

LANGUAGE选项可以有两种调用方式，一种是直接跟在工程名后边，可以省略LANGUAGE关键字，如project (cmaketest “CXX”)另一种是跟在其他关键字后边，LANGUAGE关键字不能省略,如project (camketest VERSION 10.2.1.3 LANGUAGES “CXX”)

        LANGUAGE选择性支持的语言包括C、CXX(即C++)、CUDA、OBJC(即Objective-C)、OBJCXX、Fortran、HIP、ISPC和ASM，如果没有指定LANGUAGE选项，则默认为C和C++。
        指定LANGUAGE NONE或者仅添加LANGUAGE选项但没有列出任何语言，表示跳过所有语言。如果启用ASM，则将其放在最后，以便 CMake 可以检查其他语言的编译器如C语言是否也适用于汇编

4.project命令的非必要性

project命令并非必须的，如果没有project命令，cmake会自动生成工程名为project的工程。

示例代码：
# 设置最低Cmake版本要求
cmake_minimum_required(VERSION 3.5)message("ROJECT_NAME: ${PROJECT_NAME}")
add_executable(hello_cmake main.cpp)

输出结果：
ROJECT_NAME: Project

8.总结

project 指令是 CMake 项目的入口点，主要负责：

• 定义项目名称和版本号。
• 设置支持的编程语言。
• 初始化关键变量（如 PROJECT_SOURCE_DIR）。

通过合理配置 project，可提高项目的可维护性和跨平台兼容性。

相关链接

• CMake 官网 CMake - Upgrade Your Software Build System
• CMake 官方文档：CMake Tutorial — CMake 4.0.2 Documentation
• CMake 源码：GitHub - Kitware/CMake: Mirror of CMake upstream repository
• CMake 源码：Sign in · GitLab