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-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、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。