install

指定在安裝時執行的規則。

概要

install(TARGETS <target>... [...])
install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])
install({FILES | PROGRAMS} <file>... [...])
install(DIRECTORY <dir>... [...])
install(SCRIPT <file> [...])
install(CODE <code> [...])
install(EXPORT <export-name> [...])
install(PACKAGE_INFO <package-name> [...])
install(RUNTIME_DEPENDENCY_SET <set-name> [...])

簡介

此命令為專案產生安裝規則。在原始碼目錄內呼叫 install() 命令指定的安裝規則，會在安裝期間依序執行。

在 3.14 版本中變更：透過呼叫 add_subdirectory() 命令新增的子目錄中的安裝規則，會與父目錄中的安裝規則交錯執行，以宣告的順序執行（請參閱原則 CMP0082）。

在 3.22 版本中變更：環境變數 CMAKE_INSTALL_MODE 可以覆寫 install() 的預設複製行為。

在 3.31 版本中變更：專案可以啟用 INSTALL_PARALLEL 來啟用平行安裝。使用平行安裝時，透過呼叫 add_subdirectory() 命令新增的子目錄會獨立安裝，且無法保證在不同子目錄中新增的安裝規則的執行順序。

此命令有多個簽名。其中一些定義了檔案和目標的安裝選項。多個簽名共有的選項在此說明，但它們僅對指定它們的簽名有效。常見選項包括

DESTINATION <dir>

指定檔案將安裝到的磁碟上的目錄。<dir> 應為相對路徑。允許使用絕對路徑，但不建議使用。

給定相對路徑時，會根據 CMAKE_INSTALL_PREFIX 變數的值來解譯。可以使用 DESTDIR 機制在安裝時重新定位前置詞，該機制在 CMAKE_INSTALL_PREFIX 變數文件中說明。

由於絕對路徑不適用於 cmake --install 命令的 --prefix 選項，或 cpack 安裝程式產生器，因此強烈建議在整個過程中都使用相對路徑，以獲得封裝維護人員的最佳支援。特別是，不需要在前面加上 CMAKE_INSTALL_PREFIX 來使路徑成為絕對路徑；如果 DESTINATION 是相對路徑，則預設會使用此前置詞。

如果給定絕對路徑（帶有前導斜線或磁碟機代號），則會逐字使用。

在 3.31 版本中變更：<dir> 將根據與 cmake_path() 命令相同的 正規化規則進行正規化。

PERMISSIONS <permission>...

指定已安裝檔案的權限。有效的權限包括 OWNER_READ、OWNER_WRITE、OWNER_EXECUTE、GROUP_READ、GROUP_WRITE、GROUP_EXECUTE、WORLD_READ、WORLD_WRITE、WORLD_EXECUTE、SETUID 和 SETGID。在某些平台上沒有意義的權限會在這些平台上被忽略。

如果此選項在單一呼叫中多次使用，則其權限清單會累加。如果 install(TARGETS) 呼叫使用 <artifact-kind> 引數，則會為每種構件累加個別的權限清單。

CONFIGURATIONS <config>...

指定安裝規則套用的組建配置清單（Debug、Release 等）。

如果此選項在單一呼叫中多次使用，則其配置清單會累加。如果 install(TARGETS) 呼叫使用 <artifact-kind> 引數，則會為每種構件累加個別的配置清單。

COMPONENT <component>

指定與安裝規則相關聯的安裝元件名稱，例如 Runtime 或 Development。在元件特定的安裝期間，只會執行與給定元件名稱相關聯的安裝規則。在完整安裝期間，會安裝所有元件，除非標記為 EXCLUDE_FROM_ALL。如果未提供 COMPONENT，則會建立預設元件「Unspecified」。預設元件名稱可以使用 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME 變數來控制。

EXCLUDE_FROM_ALL

在 3.6 版本中新增。

指定檔案會排除在完整安裝之外，並且僅作為元件特定安裝的一部分安裝

OPTIONAL

指定如果不存在要安裝的檔案，則不會發生錯誤。

在 3.1 版本中新增：安裝檔案的命令簽名可能會在安裝期間列印訊息。使用 CMAKE_INSTALL_MESSAGE 變數來控制列印哪些訊息。

在 3.11 版本中新增：許多 install() 變體會隱式建立包含已安裝檔案的目錄。如果設定了 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS，則會使用指定的權限建立這些目錄。否則，會根據類 Unix 平台上的 uname 規則建立這些目錄。Windows 平台不受影響。

簽名

install(TARGETS <target>... [...])

安裝目標 輸出構件 和相關檔案

install(TARGETS <target>... [EXPORT <export-name>]
        [RUNTIME_DEPENDENCIES <arg>...|RUNTIME_DEPENDENCY_SET <set-name>]
        [<artifact-option>...]
        [<artifact-kind> <artifact-option>...]...
        [INCLUDES DESTINATION [<dir> ...]]
        )

其中 <artifact-option>... 群組可能包含

[DESTINATION <dir>]
[PERMISSIONS <permission>...]
[CONFIGURATIONS <config>...]
[COMPONENT <component>]
[NAMELINK_COMPONENT <component>]
[OPTIONAL] [EXCLUDE_FROM_ALL]
[NAMELINK_ONLY|NAMELINK_SKIP]

第一個 <artifact-option>... 群組適用於目標 輸出構件，這些構件在同一個呼叫中稍後未指定專用群組。

每個 <artifact-kind> <artifact-option>... 群組適用於指定構件種類的 輸出構件

ARCHIVE

此種類的目標構件包括

  • 靜態函式庫 (macOS 上標記為 FRAMEWORK 的情況除外，請見下方說明)；

  • DLL 匯入函式庫 (在所有基於 Windows 的系統，包括 Cygwin；它們的副檔名為 .lib，與 .dll 函式庫相反，後者會放到 RUNTIME)；

  • 在 AIX 上，為啟用 ENABLE_EXPORTS 的可執行檔建立的連結器匯入檔案。

  • 在 macOS 上，為啟用 ENABLE_EXPORTS 的共享函式庫建立的連結器匯入檔案（標記為 FRAMEWORK 的情況除外，請見下方說明）。

LIBRARY

此種類的目標構件包括

  • 共享函式庫，除了

    • DLL (這些會放到 RUNTIME，請見下方說明)，

    • macOS 上標記為 FRAMEWORK 的情況 (請見下方說明)。

RUNTIME

此種類的目標構件包括

  • 可執行檔（macOS 上標記為 MACOSX_BUNDLE 的情況除外，請見下方的 BUNDLE）；

  • DLL (在所有基於 Windows 的系統，包括 Cygwin；請注意，隨附的匯入函式庫的種類為 ARCHIVE)。

OBJECTS

在 3.9 版本中新增。

與物件函式庫相關聯的物件檔案。

FRAMEWORK

在 macOS 上，標記為 FRAMEWORK 屬性的靜態和共享函式庫都會被視為 FRAMEWORK 目標。

BUNDLE

在 macOS 上，標記為 MACOSX_BUNDLE 屬性的可執行檔會被視為 BUNDLE 目標。

PUBLIC_HEADER

與函式庫相關聯的任何 PUBLIC_HEADER 檔案，在非 Apple 平台上會安裝到 PUBLIC_HEADER 引數指定的目的地。此引數定義的規則會被 Apple 平台上的 FRAMEWORK 函式庫忽略，因為相關檔案會安裝到框架資料夾內的適當位置。詳情請見 PUBLIC_HEADER。

PRIVATE_HEADER

與 PUBLIC_HEADER 類似，但用於 PRIVATE_HEADER 檔案。詳情請見 PRIVATE_HEADER。

RESOURCE

與 PUBLIC_HEADER 和 PRIVATE_HEADER 類似，但用於 RESOURCE 檔案。詳情請見 RESOURCE。

FILE_SET <set-name>

在 3.23 版本中新增。

檔案集合由 target_sources(FILE_SET) 命令定義。如果檔案集合 <set-name> 存在且為 PUBLIC 或 INTERFACE，則集合中的任何檔案都會安裝到目的地 (請見下方)。相對於檔案集合的基準目錄的目錄結構會保留。例如，以 /blah/include/myproj/here.h 加入檔案集合，且基準目錄為 /blah/include 的檔案會安裝到目的地下的 myproj/here.h。

CXX_MODULES_BMI

在 3.28 版本中新增。

來自類型為 CXX_MODULES 的檔案集合中 PUBLIC 來源的任何 C++ 模組檔案，都將安裝到指定的 DESTINATION。所有模組都會直接放置在目的地中，因為沒有目錄結構衍生自模組名稱。可以使用空的 DESTINATION 來抑制安裝這些檔案 (以用於通用程式碼)。

對於一般可執行檔、靜態函式庫和共享函式庫，不需要 DESTINATION 引數。對於這些目標類型，當省略 DESTINATION 時，預設目的地會取自 GNUInstallDirs 中的適當變數，如果未定義該變數，則會設定為內建預設值。對於檔案集合，以及透過 PUBLIC_HEADER 和 PRIVATE_HEADER 目標屬性與已安裝目標相關聯的公開和私有標頭也是如此。必須始終為模組函式庫、Apple 套件和框架提供目的地。可以省略介面和物件函式庫的目的地，但它們的處理方式不同 (請參閱本節結尾對此主題的討論)。

在 DLL 平台上的共享函式庫，如果未指定 RUNTIME 或 ARCHIVE 目的地，則 RUNTIME 和 ARCHIVE 元件都會安裝到其預設目的地。如果指定了 RUNTIME 或 ARCHIVE 目的地，則元件會安裝到該目的地，且不會安裝另一個元件。如果同時指定了 RUNTIME 和 ARCHIVE 目的地，則兩個元件都會安裝到各自的目的地。

下表顯示了目標類型及其相關聯的變數和內建預設值，這些預設值在未提供目的地時適用

目標類型

GNUInstallDirs 變數

內建預設值

RUNTIME

${CMAKE_INSTALL_BINDIR}

bin

LIBRARY

${CMAKE_INSTALL_LIBDIR}

lib

ARCHIVE

${CMAKE_INSTALL_LIBDIR}

lib

PRIVATE_HEADER

${CMAKE_INSTALL_INCLUDEDIR}

include

PUBLIC_HEADER

${CMAKE_INSTALL_INCLUDEDIR}

include

FILE_SET (類型 HEADERS)

${CMAKE_INSTALL_INCLUDEDIR}

include

希望遵循將標頭安裝到專案特定子目錄的常見做法的專案，可能偏好使用具有適當路徑和基準目錄的檔案集合。否則，它們必須提供 DESTINATION，而不是能夠依賴上述內容 (請參閱下一個範例)。

為了使套件符合發布檔案系統佈局原則，如果專案必須指定 DESTINATION，強烈建議它們使用以適當的相對 GNUInstallDirs 變數開頭的路徑。這允許套件維護人員透過設定適當的快取變數來控制安裝目的地。以下範例顯示如何將靜態函式庫安裝到 GNUInstallDirs 提供的預設目的地，但其標頭安裝到專案特定的子目錄，而未使用檔案集合

add_library(mylib STATIC ...)
set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
include(GNUInstallDirs)
install(TARGETS mylib
        PUBLIC_HEADER
          DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
)

除了上面列出的常用選項外，每個目標都可以接受以下附加引數

NAMELINK_COMPONENT

在 3.12 版本中新增。

在某些平台上，版本化的共享函式庫具有符號連結，例如

lib<name>.so -> lib<name>.so.1

其中 lib<name>.so.1 是函式庫的 soname，而 lib<name>.so 是「namelink」，允許連結器在給定 -l<name> 時找到該函式庫。NAMELINK_COMPONENT 選項與 COMPONENT 選項類似，但如果生成共享函式庫的 namelink，則會變更其安裝元件。如果未指定，則預設為 COMPONENT 的值。在 LIBRARY 區塊之外使用此參數是錯誤的。

在 3.27 版本中變更：此參數也可用於 ARCHIVE 區塊，以管理在 macOS 上為啟用 ENABLE_EXPORTS 的共享函式庫建立的連結器匯入檔案。

請參閱範例：使用每個工件元件安裝目標，以了解使用 NAMELINK_COMPONENT 的範例。

此選項通常用於具有獨立執行階段和開發套件的套件管理器。例如，在 Debian 系統上，程式庫應位於執行階段套件中，而標頭和名稱連結應位於開發套件中。

請參閱 VERSION 和 SOVERSION 目標屬性，以了解建立版本化的共享程式庫的詳細資訊。

NAMELINK_ONLY

當安裝程式庫目標時，此選項僅安裝名稱連結。在版本化的共享程式庫沒有名稱連結的平台上，或當程式庫未版本化時，NAMELINK_ONLY 選項不會安裝任何內容。在 LIBRARY 區塊之外使用此參數是錯誤的。

在 3.27 版本中變更：此參數也可用於 ARCHIVE 區塊，以管理在 macOS 上，針對已啟用 ENABLE_EXPORTS 的共享程式庫所建立的連結器匯入檔案。

當提供 NAMELINK_ONLY 時，可以使用 NAMELINK_COMPONENT 或 COMPONENT 來指定名稱連結的安裝元件，但通常應優先使用 COMPONENT。

NAMELINK_SKIP

類似於 NAMELINK_ONLY，但效果相反：當安裝程式庫目標時，它會安裝名稱連結以外的程式庫檔案。當未提供 NAMELINK_ONLY 或 NAMELINK_SKIP 時，兩部分都會安裝。在版本化的共享程式庫沒有符號連結的平台上，或當程式庫未版本化時，NAMELINK_SKIP 會安裝程式庫。在 LIBRARY 區塊之外使用此參數是錯誤的。

在 3.27 版本中變更：此參數也可用於 ARCHIVE 區塊，以管理在 macOS 上，針對已啟用 ENABLE_EXPORTS 的共享程式庫所建立的連結器匯入檔案。

如果指定 NAMELINK_SKIP，則 NAMELINK_COMPONENT 無效。不建議將 NAMELINK_SKIP 與 NAMELINK_COMPONENT 結合使用。

install(TARGETS) 命令也可以在頂層接受以下選項

EXPORT

此選項將已安裝的目標檔案與名為 <export-name> 的匯出關聯。它必須出現在任何目標選項之前。要實際安裝匯出檔案本身，請呼叫 install(EXPORT)，如下所述。請參閱 EXPORT_NAME 目標屬性的文件，以變更匯出目標的名稱。

如果使用 EXPORT，且目標包含 PUBLIC 或 INTERFACE 檔案集，則所有檔案集都必須使用 FILE_SET 引數指定。與目標關聯的所有 PUBLIC 或 INTERFACE 檔案集都會包含在匯出中。

INCLUDES DESTINATION

此選項指定將新增至 INTERFACE_INCLUDE_DIRECTORIES 目標屬性中的目錄清單，這些目錄會在由 install(EXPORT) 命令匯出時，應用於 <targets>。如果指定了相對路徑，則會將其視為相對於 $<INSTALL_PREFIX>。

與各種 install() 子命令的其他 DESTINATION 引數不同，在 INCLUDES DESTINATION 之後給定的路徑會按原樣使用。它們不會被正規化，也不會假設它們已正規化，但建議以正規化形式提供它們（請參閱正規化）。

RUNTIME_DEPENDENCY_SET <set-name>

在 3.21 版本中新增。

此選項會將已安裝的可執行檔、共享程式庫和模組目標的所有執行階段相依性新增至指定的執行階段相依性集。然後，可以使用 install(RUNTIME_DEPENDENCY_SET) 命令安裝此集合。

此關鍵字和 RUNTIME_DEPENDENCIES 關鍵字是互斥的。

RUNTIME_DEPENDENCIES <arg>...

在 3.21 版本中新增。

此選項會將已安裝的可執行檔、共享程式庫和模組目標的所有執行階段相依性與目標本身一起安裝。RUNTIME、LIBRARY、FRAMEWORK 和一般引數用於判斷這些相依性的安裝屬性（DESTINATION、COMPONENT 等）。

RUNTIME_DEPENDENCIES 在語義上等同於以下一對呼叫

install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
install(RUNTIME_DEPENDENCY_SET <set-name> <arg>...)

其中 <set-name> 將會是一個隨機產生的集合名稱。<arg>... 可以包含 install(RUNTIME_DEPENDENCY_SET) 命令支援的下列任何關鍵字

  • DIRECTORIES

  • PRE_INCLUDE_REGEXES

  • PRE_EXCLUDE_REGEXES

  • POST_INCLUDE_REGEXES

  • POST_EXCLUDE_REGEXES

  • POST_INCLUDE_FILES

  • POST_EXCLUDE_FILES

RUNTIME_DEPENDENCIES 和 RUNTIME_DEPENDENCY_SET 關鍵字是互斥的。

可以在要安裝的目標中列出介面程式庫。它們不安裝任何工件，但會包含在相關聯的 EXPORT 中。如果列出了物件程式庫，但未提供其物件檔案的目的地，則會將它們匯出為介面程式庫。這足以滿足連結到其實作中的物件程式庫的其他目標的遞移使用需求。

安裝將 EXCLUDE_FROM_ALL 目標屬性設定為 TRUE 的目標，其行為未定義。

在 3.3 版本中新增： 作為 DESTINATION 引數給定的安裝目的地可以使用具有 $<...> 語法的「產生器運算式」。請參閱 cmake-generator-expressions(7) 手冊以了解可用的運算式。

在 3.13 版本中新增：install(TARGETS) 可以安裝在其他目錄中建立的目標。當使用此類跨目錄安裝規則時，從子目錄執行 make install（或類似命令）無法保證其他目錄中的目標是最新的。您可以使用 target_link_libraries() 或 add_dependencies() 來確保在執行子目錄特定安裝規則之前，先建置此類目錄外的目標。

install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])

在 3.21 版本中新增。

安裝導入目標的執行期產物

install(IMPORTED_RUNTIME_ARTIFACTS <target>...
        [RUNTIME_DEPENDENCY_SET <set-name>]
        [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
         [DESTINATION <dir>]
         [PERMISSIONS <permission>...]
         [CONFIGURATIONS <config>...]
         [COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
        ] [...]
        )

IMPORTED_RUNTIME_ARTIFACTS 形式指定了安裝導入目標之執行期產物的規則。如果專案想要將外部可執行檔或模組捆綁到它們的安裝中，就可以這樣做。LIBRARY、RUNTIME、FRAMEWORK 和 BUNDLE 參數具有與 TARGETS 模式中相同的語義。只有導入目標的執行期產物會被安裝（除了 FRAMEWORK 函式庫、MACOSX_BUNDLE 可執行檔和 BUNDLE CFBundles 的情況）。例如，與 DLL 相關聯的標頭和匯入函式庫不會被安裝。在 FRAMEWORK 函式庫、MACOSX_BUNDLE 可執行檔和 BUNDLE CFBundles 的情況下，整個目錄都會被安裝。

RUNTIME_DEPENDENCY_SET 選項會將導入的可執行檔、共享函式庫和模組函式庫 targets 的執行期產物加入到 <set-name> 執行期依賴集合。然後可以使用 install(RUNTIME_DEPENDENCY_SET) 命令安裝此集合。

install(FILES <file>... [...])
install(PROGRAMS <program>... [...])

注意

如果要安裝標頭檔，請考慮改用 target_sources(FILE_SET) 定義的檔案集。檔案集會將標頭與目標關聯，它們會作為目標的一部分進行安裝。

安裝檔案或程式

install(<FILES|PROGRAMS> <file>...
        TYPE <type> | DESTINATION <dir>
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [COMPONENT <component>]
        [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])

FILES 形式指定了安裝專案檔案的規則。以相對路徑給定的檔案名稱會根據目前的原始碼目錄進行解譯。如果沒有提供 PERMISSIONS 引數，則此形式安裝的檔案預設會被賦予 OWNER_WRITE、OWNER_READ、GROUP_READ 和 WORLD_READ 的權限。

PROGRAMS 形式與 FILES 形式相同，但安裝檔案的預設權限還包含 OWNER_EXECUTE、GROUP_EXECUTE 和 WORLD_EXECUTE。此形式旨在安裝非目標的程式，例如 shell 指令碼。使用 TARGETS 形式安裝專案內建置的目標。

提供給 FILES 或 PROGRAMS 的 files... 清單可以使用語法為 $<...> 的「產生器運算式」。請參閱 cmake-generator-expressions(7) 手冊，以取得可用的運算式。但是，如果任何項目以產生器運算式開頭，則它必須評估為完整路徑。

選用的 RENAME <name> 引數用於指定安裝檔案的名稱，該名稱與原始檔案名稱不同。僅當命令安裝單一檔案時才允許重新命名。

必須提供 TYPE 或 DESTINATION，但不能同時提供兩者。TYPE 引數指定要安裝檔案的通用檔案類型。然後，將會自動設定目的地，方法是從 GNUInstallDirs 中取得對應的變數，或者在未定義該變數時使用內建預設值。請參閱下表，以取得支援的檔案類型及其對應的變數和內建預設值。如果專案想要明確定義安裝目的地，則可以提供 DESTINATION 引數來取代檔案類型。

TYPE 引數

GNUInstallDirs 變數

內建預設值

BIN

${CMAKE_INSTALL_BINDIR}

bin

SBIN

${CMAKE_INSTALL_SBINDIR}

sbin

LIB

${CMAKE_INSTALL_LIBDIR}

lib

INCLUDE

${CMAKE_INSTALL_INCLUDEDIR}

include

SYSCONF

${CMAKE_INSTALL_SYSCONFDIR}

etc

SHAREDSTATE

${CMAKE_INSTALL_SHARESTATEDIR}

com

LOCALSTATE

${CMAKE_INSTALL_LOCALSTATEDIR}

var

RUNSTATE

${CMAKE_INSTALL_RUNSTATEDIR}

<LOCALSTATE dir>/run

DATA

${CMAKE_INSTALL_DATADIR}

<DATAROOT dir>

INFO

${CMAKE_INSTALL_INFODIR}

<DATAROOT dir>/info

LOCALE

${CMAKE_INSTALL_LOCALEDIR}

<DATAROOT dir>/locale

MAN

${CMAKE_INSTALL_MANDIR}

<DATAROOT dir>/man

DOC

${CMAKE_INSTALL_DOCDIR}

<DATAROOT dir>/doc

LIBEXEC

${CMAKE_INSTALL_LIBEXECDIR}

libexec

希望遵循將標頭安裝到專案特定子目錄的常見作法的專案，將需要提供目的地，而不是依賴上述內容。使用檔案集來處理標頭，而不是 install(FILES) 會更好（請參閱 target_sources(FILE_SET)）。

請注意，某些類型的內建預設值會使用 DATAROOT 目錄作為前置詞。DATAROOT 前置詞的計算方式與類型類似，其中 CMAKE_INSTALL_DATAROOTDIR 作為變數，而 share 作為內建預設值。您無法使用 DATAROOT 作為 TYPE 參數；請改用 DATA。

為了使套件符合發行版檔案系統版面配置原則，如果專案必須指定 DESTINATION，強烈建議它們使用以適當的相對 GNUInstallDirs 變數開頭的路徑。這允許套件維護人員透過設定適當的快取變數來控制安裝目的地。以下範例顯示如何在將映像安裝到專案特定的文件子目錄時遵循此建議

include(GNUInstallDirs)
install(FILES logo.png
        DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
)

版本 3.4 中新增: 以 DESTINATION 引數給定的安裝目的地可以使用語法為 $<...> 的「產生器運算式」。請參閱 cmake-generator-expressions(7) 手冊，以取得可用的運算式。

版本 3.20 中新增: 以 RENAME 引數給定的安裝重新命名可以使用語法為 $<...> 的「產生器運算式」。請參閱 cmake-generator-expressions(7) 手冊，以取得可用的運算式。

版本 3.31 中新增: TYPE 引數現在支援 LIBEXEC 類型。

install(DIRECTORY <dir>... [...])

注意

若要安裝標頭檔的目錄子樹，請考慮使用 target_sources(FILE_SET) 所定義的檔案集。檔案集不僅保留目錄結構，還將標頭檔與目標相關聯，並作為目標的一部分進行安裝。

安裝一個或多個目錄的內容

install(DIRECTORY dirs...
        TYPE <type> | DESTINATION <dir>
        [FILE_PERMISSIONS <permission>...]
        [DIRECTORY_PERMISSIONS <permission>...]
        [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
        [CONFIGURATIONS <config>...]
        [COMPONENT <component>] [EXCLUDE_FROM_ALL]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]
         [EXCLUDE] [PERMISSIONS <permission>...]] [...])

DIRECTORY 形式將一個或多個目錄的內容安裝到給定的目的地。目錄結構會逐字複製到目的地。每個目錄名稱的最後一個部分會附加到目標目錄，但可以使用尾隨斜線來避免這種情況，因為它會使最後一個部分為空。以相對路徑給定的目錄名稱會相對於目前的原始碼目錄進行解釋。如果未給定任何輸入目錄名稱，則將會建立目標目錄，但不會安裝任何內容到其中。FILE_PERMISSIONS 和 DIRECTORY_PERMISSIONS 選項指定目的地中檔案和目錄的權限。如果指定了 USE_SOURCE_PERMISSIONS 且未指定 FILE_PERMISSIONS，則檔案權限將從原始碼目錄結構複製。如果未指定任何權限，則檔案將被賦予命令的 FILES 形式中指定的預設權限，而目錄將被賦予命令的 PROGRAMS 形式中指定的預設權限。

新增於 3.1 版本: MESSAGE_NEVER 選項會停用檔案安裝狀態輸出。

可以使用 PATTERN 或 REGEX 選項精細地控制目錄的安裝。這些「比對」選項指定 globbing 模式或正規表示式，以比對在輸入目錄中遇到的目錄或檔案。它們可用於將某些選項（請參閱下文）套用至所遇到檔案和目錄的子集。每個輸入檔案或目錄的完整路徑（使用正斜線）會與運算式進行比對。PATTERN 只會比對完整的檔案名稱：比對模式的完整路徑部分必須出現在檔案名稱的結尾，並以斜線作為前導。 REGEX 會比對完整路徑的任何部分，但可以使用 / 和 $ 來模擬 PATTERN 行為。預設情況下，無論是否比對，都會安裝所有檔案和目錄。可以在第一個比對選項之前給定 FILES_MATCHING 選項，以停用未被任何運算式比對的檔案（但不是目錄）的安裝。例如，下列程式碼

install(DIRECTORY src/ DESTINATION doc/myproj
        FILES_MATCHING PATTERN "*.png")

將會從原始碼樹擷取並安裝影像。

某些選項可能會在 PATTERN 或 REGEX 運算式之後，如 string(REGEX) 所述，並且僅適用於比對的檔案或目錄。EXCLUDE 選項會跳過比對的檔案或目錄。PERMISSIONS 選項會覆寫比對的檔案或目錄的權限設定。例如，下列程式碼

install(DIRECTORY icons scripts/ DESTINATION share/myproj
        PATTERN "CVS" EXCLUDE
        PATTERN "scripts/*"
        PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
                    GROUP_EXECUTE GROUP_READ)

會將 icons 目錄安裝到 share/myproj/icons，並將 scripts 目錄安裝到 share/myproj。圖示會取得預設檔案權限，指令碼會被賦予特定權限，而任何 CVS 目錄都會被排除。

必須提供 TYPE 或 DESTINATION，但不能同時提供兩者。TYPE 引數指定所安裝列出目錄中檔案的通用檔案類型。然後，將會自動設定目的地，方法是從 GNUInstallDirs 中取得對應的變數，如果該變數未定義，則使用內建預設值。請參閱下表以取得支援的檔案類型及其對應的變數和內建預設值。如果專案希望明確定義安裝目的地，則可以提供 DESTINATION 引數而不是檔案類型。

TYPE 引數

GNUInstallDirs 變數

內建預設值

BIN

${CMAKE_INSTALL_BINDIR}

bin

SBIN

${CMAKE_INSTALL_SBINDIR}

sbin

LIB

${CMAKE_INSTALL_LIBDIR}

lib

INCLUDE

${CMAKE_INSTALL_INCLUDEDIR}

include

SYSCONF

${CMAKE_INSTALL_SYSCONFDIR}

etc

SHAREDSTATE

${CMAKE_INSTALL_SHARESTATEDIR}

com

LOCALSTATE

${CMAKE_INSTALL_LOCALSTATEDIR}

var

RUNSTATE

${CMAKE_INSTALL_RUNSTATEDIR}

<LOCALSTATE dir>/run

DATA

${CMAKE_INSTALL_DATADIR}

<DATAROOT dir>

INFO

${CMAKE_INSTALL_INFODIR}

<DATAROOT dir>/info

LOCALE

${CMAKE_INSTALL_LOCALEDIR}

<DATAROOT dir>/locale

MAN

${CMAKE_INSTALL_MANDIR}

<DATAROOT dir>/man

DOC

${CMAKE_INSTALL_DOCDIR}

<DATAROOT dir>/doc

LIBEXEC

${CMAKE_INSTALL_LIBEXECDIR}

libexec

請注意，某些類型的內建預設值會使用 DATAROOT 目錄作為前置詞。DATAROOT 前置詞的計算方式與類型類似，其中 CMAKE_INSTALL_DATAROOTDIR 作為變數，而 share 作為內建預設值。您無法使用 DATAROOT 作為 TYPE 參數；請改用 DATA。

為了使套件符合發行版檔案系統版面配置原則，如果專案必須指定 DESTINATION，強烈建議它們使用以適當的相對 GNUInstallDirs 變數開頭的路徑。這可讓套件維護者藉由設定適當的快取變數來控制安裝目的地。

新增於 3.4 版本: 作為 DESTINATION 引數給定的安裝目的地可以使用語法為 $<...> 的「產生器運算式」。如需可用的運算式，請參閱 cmake-generator-expressions(7) 手冊。

新增於 3.5 版本: 給定給 DIRECTORY 的 dirs... 清單也可以使用「產生器運算式」。

版本 3.31 中新增: TYPE 引數現在支援 LIBEXEC 類型。

install(SCRIPT <file> [...])
install(CODE <code> [...])

在安裝期間叫用 CMake 指令碼或程式碼

install([[SCRIPT <file>] [CODE <code>]]
        [ALL_COMPONENTS | COMPONENT <component>]
        [EXCLUDE_FROM_ALL] [...])

SCRIPT 形式將會在安裝期間叫用給定的 CMake 指令碼檔案。如果指令碼檔案名稱是相對路徑，則會相對於目前的原始碼目錄進行解釋。CODE 形式將會在安裝期間叫用給定的 CMake 程式碼。程式碼指定為雙引號字串中的單一引數。例如，下列程式碼

install(CODE "MESSAGE(\"Sample install message.\")")

將會在安裝期間列印訊息。

新增於 3.21 版本: 當給定 ALL_COMPONENTS 選項時，自訂安裝指令碼程式碼將會針對元件特定安裝的每個元件執行。此選項與 COMPONENT 選項互斥。

新增於 3.14 版本: <file> 或 <code> 可以使用語法為 $<...> 的「產生器運算式」（在 <file> 的情況下，這表示它們在檔案名稱中的使用，而不是檔案的內容）。如需可用的運算式，請參閱 cmake-generator-expressions(7) 手冊。

install(EXPORT <export-name> [...])

安裝 CMake 檔案，為相依專案匯出目標

install(EXPORT <export-name> DESTINATION <dir>
        [NAMESPACE <namespace>] [FILE <name>.cmake]
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [CXX_MODULES_DIRECTORY <directory>]
        [EXPORT_LINK_INTERFACE_LIBRARIES]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL]
        [EXPORT_PACKAGE_DEPENDENCIES])
install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])

EXPORT 形式會產生並安裝 CMake 檔案，其中包含將目標從安裝樹匯入另一個專案的程式碼。目標安裝會使用上方文件中記載的 install(TARGETS) 簽章的 EXPORT 選項與匯出 <export-name> 相關聯。NAMESPACE 選項會在將目標名稱寫入匯入檔案時，將 <namespace> 前置於目標名稱。預設情況下，產生的檔案將會被稱為 <export-name>.cmake，但可以使用 FILE 選項來指定不同的名稱。給定給 FILE 選項的值必須是具有 .cmake 副檔名的檔案名稱。

如果提供了 CONFIGURATIONS 選項，則只有在安裝其中一個指定的組態時才會安裝該檔案。此外，產生的導入檔案將只會參考符合的目標組態。請參閱 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> 變數，以將相依專案的組態對應到已安裝的組態。如果存在 EXPORT_LINK_INTERFACE_LIBRARIES 關鍵字，則在原則 CMP0022 為 NEW 時，會匯出符合 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? 的屬性內容。

注意

已安裝的 <export-name>.cmake 檔案可能會附帶額外的每個組態的 <export-name>-*.cmake 檔案，以供使用 globbing 載入。請勿使用與套件名稱相同的匯出名稱，並同時安裝 <package-name>-config.cmake 檔案，否則後者可能會被 glob 錯誤地比對並載入。

當提供 COMPONENT 選項時，列出的 <component> 會隱式地依賴匯出集中提到的所有元件。匯出的 <name>.cmake 檔案將要求每個匯出的元件都存在，才能讓相依專案正確建置。例如，專案可能會定義 Runtime 和 Development 元件，其中共享程式庫進入 Runtime 元件，而靜態程式庫和標頭進入 Development 元件。匯出集通常也會是 Development 元件的一部分，但它會匯出 Runtime 和 Development 元件的目標。因此，如果安裝了 Development 元件，則需要安裝 Runtime 元件，反之則不然。如果安裝了 Development 元件但沒有安裝 Runtime 元件，嘗試連結它的相依專案將會發生建置錯誤。套件管理器（例如 APT 和 RPM）通常會透過在套件中繼資料中將 Runtime 元件列為 Development 元件的相依性來處理此問題，確保如果標頭和 CMake 匯出檔案存在，則始終會安裝程式庫。

在 3.7 版本中新增：除了 cmake 語言檔案之外，EXPORT_ANDROID_MK 模式可用於指定匯出到 android ndk 建置系統。此模式接受與正常匯出模式相同的選項。Android NDK 支援使用預先建置的程式庫，包括靜態和共享程式庫。這允許 cmake 建置專案的程式庫，並使其可用於 ndk 建置系統，並完整包含使用程式庫所需的遞移相依性、包含標誌和定義。

CXX_MODULES_DIRECTORY

在 3.28 版本中新增。

指定一個子目錄，用於儲存匯出集中目標的 C++ 模組資訊。此目錄將會填入檔案，這些檔案會將必要的目標屬性資訊新增到相關的目標。請注意，如果沒有此資訊，則匯出集中目標的任何 C++ 模組都不會支援在取用目標中導入。

EXPORT_PACKAGE_DEPENDENCIES

注意

實驗性功能。由 CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES 閘控。

指定應匯出 find_dependency() 呼叫。如果指定了此引數，CMake 會檢查匯出集中的所有目標，並收集其 INTERFACE 連結目標。如果任何此類目標是使用 find_package() 找到的，或者設定了 EXPORT_FIND_PACKAGE_NAME 屬性，並且此類套件相依性未被傳遞 ENABLED OFF 給 export(SETUP) 停用，則會使用目標的對應套件名稱、REQUIRED 引數和 export(SETUP) 的 EXTRA_ARGS 引數指定的任何額外引數來寫入 find_dependency() 呼叫。任何透過傳遞 ENABLED ON 給 export(SETUP) 手動指定的套件相依性也會被新增，即使匯出的目標不依賴於它們的任何目標。

find_dependency() 呼叫會依以下順序寫入

  1. 在 export(SETUP) 中列出的任何套件相依性都會依照它們首次指定的順序寫入，無論它們是否包含匯出目標的 INTERFACE 相依性。

  2. 包含匯出目標的 INTERFACE 連結相依性且從未在 export(SETUP) 中指定的任何套件相依性都會依照它們首次找到的順序寫入。

EXPORT 形式有助於外部專案使用目前專案建置和安裝的目標。例如，程式碼

install(TARGETS myexe EXPORT myproj DESTINATION bin)
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)

會將可執行檔 myexe 安裝到 <prefix>/bin，並將程式碼匯入到檔案 <prefix>/lib/myproj/myproj.cmake 和 <prefix>/share/ndk-modules/Android.mk。外部專案可以使用 include 命令載入此檔案，並從安裝樹狀結構使用匯入的目標名稱 mp_myexe 參考 myexe 可執行檔，就好像該目標是在其自己的樹狀結構中建置的一樣。

install(PACKAGE_INFO <package-name> [...])

在 3.31 版本中新增。

注意

實驗性功能。由 CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO 閘控。

安裝 Common Package Specification 檔案，以匯出用於相依專案的目標

install(PACKAGE_INFO <package-name> EXPORT <export-name>
        [APPENDIX <appendix-name>]
        [DESTINATION <dir>]
        [LOWER_CASE_FILE]
        [VERSION <version>
         [COMPAT_VERSION <version>]
         [VERSION_SCHEMA <string>]]
        [DEFAULT_TARGETS <target>...]
        [DEFAULT_CONFIGURATIONS <config>...]
        [PERMISSIONS <permission>...]
        [CONFIGURATIONS <config>...]
        [COMPONENT <component>]
        [EXCLUDE_FROM_ALL])

PACKAGE_INFO 形式會產生並安裝 Common Package Specification 檔案，該檔案描述已安裝的目標，以便另一個專案可以使用它們。目標安裝會使用上述 install(TARGETS) 簽章的 EXPORT 選項與匯出 <export-name> 相關聯。與 install(EXPORT) 不同，此資訊不是以 CMake 程式碼表示的，並且可以由 CMake 以外的工具使用。當匯入另一個 CMake 專案時，匯入的目標將以 <package-name>:: 作為前置詞。依預設，產生的檔案將被命名為 <package-name>[-<appendix-name>].cps。如果給定了 LOWER_CASE_FILE，則套件名稱在磁碟上顯示時（無論是在檔案名稱還是在安裝目的地）都將首先轉換為小寫。

如果未指定 DESTINATION，則會使用平台特定的預設值。

如果指定了 APPENDIX，則指定的目標將會匯出為指定套件的附錄，而不是產生頂層的套件規格。附錄可用於將較少使用的目標（及其外部相依性）與套件的其餘部分分開。這使取用者能夠忽略他們不使用的目標的遞移相依性，並且還允許將單一邏輯「套件」組成由多個建置樹狀結構產生的成品。

附加檔案不得變更基本套件的中繼資料；因此，不得將 VERSION、COMPAT_VERSION、VERSION_SCHEMA、DEFAULT_TARGETS 或 DEFAULT_CONFIGURATIONS 與 APPENDIX 組合使用。此外，強烈建議 LOWER_CASE_FILE 的使用應在主要套件和任何附加檔案之間保持一致。

install(RUNTIME_DEPENDENCY_SET <set-name> [...])

在 3.21 版本中新增。

安裝執行階段相依性集合

install(RUNTIME_DEPENDENCY_SET <set-name>
        [[LIBRARY|RUNTIME|FRAMEWORK]
         [DESTINATION <dir>]
         [PERMISSIONS <permission>...]
         [CONFIGURATIONS <config>...]
         [COMPONENT <component>]
         [NAMELINK_COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
        ] [...]
        [PRE_INCLUDE_REGEXES <regex>...]
        [PRE_EXCLUDE_REGEXES <regex>...]
        [POST_INCLUDE_REGEXES <regex>...]
        [POST_EXCLUDE_REGEXES <regex>...]
        [POST_INCLUDE_FILES <file>...]
        [POST_EXCLUDE_FILES <file>...]
        [DIRECTORIES <dir>...]
        )

安裝先前由一個或多個 install(TARGETS) 或 install(IMPORTED_RUNTIME_ARTIFACTS) 命令建立的執行階段相依性集合。屬於執行階段相依性集合的目標相依性會安裝在 DLL 平台的 RUNTIME 目的地和元件中，以及非 DLL 平台的 LIBRARY 目的地和元件中。macOS 框架會安裝在 FRAMEWORK 目的地和元件中。除非目標本身使用 install(TARGETS) 安裝，否則在建置樹狀結構中建立的目標永遠不會安裝為執行階段相依性，其自身的相依性也不會安裝。

產生的安裝指令碼會在建置樹狀結構檔案上呼叫 file(GET_RUNTIME_DEPENDENCIES)，以計算執行階段相依性。建置樹狀結構的可執行檔案會作為 EXECUTABLES 引數傳遞，建置樹狀結構的共享程式庫會作為 LIBRARIES 引數傳遞，而建置樹狀結構的模組則作為 MODULES 引數傳遞。在 macOS 上，如果其中一個可執行檔是 MACOSX_BUNDLE，則該可執行檔會作為 BUNDLE_EXECUTABLE 引數傳遞。在 macOS 上，執行階段相依性集合中最多只能有一個此類套件可執行檔。MACOSX_BUNDLE 屬性在其他平台上沒有作用。請注意，file(GET_RUNTIME_DEPENDENCIES) 僅支援收集 Windows、Linux 和 macOS 平台的執行階段相依性，因此 install(RUNTIME_DEPENDENCY_SET) 也有相同的限制。

下列子引數會作為對應的引數轉送到 file(GET_RUNTIME_DEPENDENCIES) (適用於提供非空目錄、規則運算式或檔案清單的引數)。它們都支援 產生器 運算式。

  • DIRECTORIES <dir>...

  • PRE_INCLUDE_REGEXES <regex>...

  • PRE_EXCLUDE_REGEXES <regex>...

  • POST_INCLUDE_REGEXES <regex>...

  • POST_EXCLUDE_REGEXES <regex>...

  • POST_INCLUDE_FILES <file>...

  • POST_EXCLUDE_FILES <file>...

注意

此命令會取代 install_targets() 命令，以及 PRE_INSTALL_SCRIPT 和 POST_INSTALL_SCRIPT 目標屬性。它也會取代 install_files() 和 install_programs() 命令的 FILES 形式。這些安裝規則相對於由 install_targets()、install_files() 和 install_programs() 命令產生的安裝規則的處理順序未定義。

範例

範例：使用每個成品元件安裝目標

考慮一個使用不同成品種類定義目標的專案

add_executable(myExe myExe.c)
add_library(myStaticLib STATIC myStaticLib.c)
target_sources(myStaticLib PUBLIC FILE_SET HEADERS FILES myStaticLib.h)
add_library(mySharedLib SHARED mySharedLib.c)
target_sources(mySharedLib PUBLIC FILE_SET HEADERS FILES mySharedLib.h)
set_property(TARGET mySharedLib PROPERTY SOVERSION 1)

我們可以使用 <artifact-kind> 引數呼叫 install(TARGETS)，為每種成品指定不同的選項

install(TARGETS
          myExe
          mySharedLib
          myStaticLib
        RUNTIME           # Following options apply to runtime artifacts.
          COMPONENT Runtime
        LIBRARY           # Following options apply to library artifacts.
          COMPONENT Runtime
          NAMELINK_COMPONENT Development
        ARCHIVE           # Following options apply to archive artifacts.
          COMPONENT Development
          DESTINATION lib/static
        FILE_SET HEADERS  # Following options apply to file set HEADERS.
          COMPONENT Development
        )

這將會

  • 將 myExe 安裝到 <prefix>/bin，這是 RUNTIME 成品的預設目的地，作為 Runtime 元件的一部分。

  • 在非 DLL 平台上

    • 將 libmySharedLib.so.1 安裝到 <prefix>/lib，這是 LIBRARY 成品的預設目的地，作為 Runtime 元件的一部分。

    • 將 libmySharedLib.so「名稱連結」(符號連結) 安裝到 <prefix>/lib，這是 LIBRARY 成品的預設目的地，作為 Development 元件的一部分。

  • 在 DLL 平台上

    • 將 mySharedLib.dll 安裝到 <prefix>/bin，這是 RUNTIME 成品的預設目的地，作為 Runtime 元件的一部分。

    • 將 mySharedLib.lib 安裝到 <prefix>/lib/static，這是指定的 ARCHIVE 成品目的地，作為 Development 元件的一部分。

  • 將 myStaticLib 安裝到 <prefix>/lib/static，這是指定的 ARCHIVE 成品目的地，作為 Development 元件的一部分。

  • 將 mySharedLib.h 和 myStaticLib.h 安裝到 <prefix>/include，這是 HEADERS 類型檔案集的預設目的地，作為 Development 元件的一部分。

範例：將目標安裝到每個組態的目的地

每個 install(TARGETS) 呼叫最多會將給定目標的輸出成品安裝到一個 DESTINATION，但安裝規則本身可能會受到 CONFIGURATIONS 選項的篩選。為了針對每個組態安裝到不同的目的地，每個組態需要一個呼叫。例如，以下程式碼

install(TARGETS myExe
        CONFIGURATIONS Debug
        RUNTIME
          DESTINATION Debug/bin
        )
install(TARGETS myExe
        CONFIGURATIONS Release
        RUNTIME
          DESTINATION Release/bin
        )

會在 Debug 組態中將 myExe 安裝到 <prefix>/Debug/bin，並在 Release 組態中安裝到 <prefix>/Release/bin。

產生的安裝指令碼

注意

不建議使用此功能。請考慮改用 cmake --install。

install() 指令會在建置目錄內產生一個名為 cmake_install.cmake 的檔案，這個檔案會被產生的安裝目標和 CPack 內部使用。您也可以使用 cmake -P 手動執行這個腳本。這個腳本接受數個變數。

COMPONENT

設定此變數以僅安裝單個 CPack 組件，而不是全部安裝。例如，如果您只想安裝 Development 組件，請執行 cmake -DCOMPONENT=Development -P cmake_install.cmake。

BUILD_TYPE

如果您使用的是多配置產生器，請設定此變數以變更建置類型。例如，要使用 Debug 配置進行安裝，請執行 cmake -DBUILD_TYPE=Debug -P cmake_install.cmake。

DESTDIR

這是一個環境變數，而不是 CMake 變數。它允許您在 UNIX 系統上變更安裝前綴。詳細資訊請參閱 DESTDIR。