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 <版本>

可選；除非政策 CMP0048 設定為 NEW，否則不得使用。

採用由非負整數組成的 <版本> 引數，即 <major>[.<minor>[.<patch>[.<tweak>]]]，並設定變數

在版本 3.12 中新增: 當從頂層 CMakeLists.txt 呼叫 project() 命令時，版本也會儲存在變數 CMAKE_PROJECT_VERSION 中。

DESCRIPTION <專案描述字串>

在版本 3.9 中新增。

可選。設定變數

為 <專案描述字串>。建議此描述是相對簡短的字串，通常不超過幾個字。

當從頂層 CMakeLists.txt 呼叫 project() 命令時，描述也會儲存在變數 CMAKE_PROJECT_DESCRIPTION 中。

在版本 3.12 中新增: 新增了 <PROJECT-NAME>_DESCRIPTION 變數。

HOMEPAGE_URL <url 字串>

在版本 3.12 中新增。

可選。設定變數

為 <url 字串>，應該是專案的標準首頁 URL。

當從頂層 CMakeLists.txt 呼叫 project() 命令時，URL 也會儲存在變數 CMAKE_PROJECT_HOMEPAGE_URL 中。

LANGUAGES <語言名稱>...

可選。根據第一個簡短簽名，也可以不用 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。