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變數控制。安裝組件隨後可以被
cmake --install命令的--component選項和CPackComponent模組使用。全域目標list_install_components列出所有可用的組件。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 匯入函式庫（在包括 Cygwin 的所有基於 Windows 的系統上；它們的擴展名為
.lib，與進入RUNTIME的.dll函式庫相反）；在 AIX 上，為啟用
ENABLE_EXPORTS的可執行檔建立的連結器匯入檔案。在 macOS 上，為啟用
ENABLE_EXPORTS的共享函式庫建立的連結器匯入檔案（標記為FRAMEWORK時除外，請參閱下文）。
LIBRARY此類型的目標工件包括
共享函式庫，除了
DLL (這些進入
RUNTIME，請參閱下文)，macOS 上標記為
FRAMEWORK時（請參閱下文）。
RUNTIME此類型的目標工件包括
可執行檔（macOS 上標記為
MACOSX_BUNDLE時除外，請參閱下文BUNDLE）；DLL（在包括 Cygwin 的所有基於 Windows 的系統上；請注意，隨附的匯入函式庫類型為
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}binLIBRARY${CMAKE_INSTALL_LIBDIR}libARCHIVE${CMAKE_INSTALL_LIBDIR}libPRIVATE_HEADER${CMAKE_INSTALL_INCLUDEDIR}includePUBLIC_HEADER${CMAKE_INSTALL_INCLUDEDIR}includeFILE_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 系統上，函式庫預期在執行時套件中，而標頭和 namelink 預期在開發套件中。
NAMELINK_ONLY當安裝函式庫目標時，此選項僅安裝 namelink。在版本化共享函式庫沒有 namelink 的平台上，或者當函式庫未版本化時，
NAMELINK_ONLY選項不安裝任何內容。在LIBRARY區塊之外使用此參數是錯誤的。變更於 3.27 版本: 此參數也可用於
ARCHIVE區塊，以管理在 macOS 上為啟用ENABLE_EXPORTS的共享函式庫建立的連結器匯入檔案。當給定
NAMELINK_ONLY時，可以使用NAMELINK_COMPONENT或COMPONENT來指定 namelink 的安裝組件，但通常應優先使用COMPONENT。NAMELINK_SKIP與
NAMELINK_ONLY類似，但效果相反：當安裝函式庫目標時，它會安裝 namelink 以外的函式庫檔案。當未給定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此選項指定目錄列表，當透過
install(EXPORT)命令匯出時，這些目錄將新增到<targets>的INTERFACE_INCLUDE_DIRECTORIES目標屬性。如果指定相對路徑，則會將其視為相對於$<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)命令支援的以下任何關鍵字DIRECTORIESPRE_INCLUDE_REGEXESPRE_EXCLUDE_REGEXESPOST_INCLUDE_REGEXESPOST_EXCLUDE_REGEXESPOST_INCLUDE_FILESPOST_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可執行檔和BUNDLECFBundle 除外。）例如，與 DLL 相關聯的標頭和匯入函式庫不會被安裝。對於FRAMEWORK函式庫、MACOSX_BUNDLE可執行檔和BUNDLECFBundle，則會安裝整個目錄。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形式指定了安裝專案檔案的規則。以相對路徑給定的檔案名稱會根據目前的原始碼目錄進行解釋。預設情況下，以此形式安裝的檔案會被賦予權限OWNER_WRITE、OWNER_READ、GROUP_READ和WORLD_READ，如果沒有給定PERMISSIONS引數。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}binSBIN${CMAKE_INSTALL_SBINDIR}sbinLIB${CMAKE_INSTALL_LIBDIR}libINCLUDE${CMAKE_INSTALL_INCLUDEDIR}includeSYSCONF${CMAKE_INSTALL_SYSCONFDIR}etcSHAREDSTATE${CMAKE_INSTALL_SHARESTATEDIR}comLOCALSTATE${CMAKE_INSTALL_LOCALSTATEDIR}varRUNSTATE${CMAKE_INSTALL_RUNSTATEDIR}<LOCALSTATE dir>/runDATA${CMAKE_INSTALL_DATADIR}<DATAROOT dir>INFO${CMAKE_INSTALL_INFODIR}<DATAROOT dir>/infoLOCALE${CMAKE_INSTALL_LOCALEDIR}<DATAROOT dir>/localeMAN${CMAKE_INSTALL_MANDIR}<DATAROOT dir>/manDOC${CMAKE_INSTALL_DOCDIR}<DATAROOT dir>/docLIBEXEC${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選項來精細控制目錄的安裝。這些「比對」選項指定了 glob 模式或正則表達式，以比對輸入目錄中遇到的目錄或檔案。它們可以用於將某些選項（請參閱下文）應用於遇到的檔案和目錄的子集。每個輸入檔案或目錄的完整路徑（使用正斜線）都會與表達式進行比對。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。icons將獲得預設檔案權限，scripts將被賦予特定權限，並且任何CVS目錄都將被排除。必須提供
TYPE或DESTINATION，但不能同時提供兩者。TYPE引數指定了正在安裝的列出目錄中檔案的通用檔案類型。然後，將透過從GNUInstallDirs中取得對應的變數，或在使用內建預設值（如果未定義該變數）來自動設定目的地。請參閱下表，了解支援的檔案類型及其對應的變數和內建預設值。如果專案希望明確定義安裝目的地，則可以提供DESTINATION引數來代替檔案類型。TYPE引數GNUInstallDirs 變數
內建預設值
BIN${CMAKE_INSTALL_BINDIR}binSBIN${CMAKE_INSTALL_SBINDIR}sbinLIB${CMAKE_INSTALL_LIBDIR}libINCLUDE${CMAKE_INSTALL_INCLUDEDIR}includeSYSCONF${CMAKE_INSTALL_SYSCONFDIR}etcSHAREDSTATE${CMAKE_INSTALL_SHARESTATEDIR}comLOCALSTATE${CMAKE_INSTALL_LOCALSTATEDIR}varRUNSTATE${CMAKE_INSTALL_RUNSTATEDIR}<LOCALSTATE dir>/runDATA${CMAKE_INSTALL_DATADIR}<DATAROOT dir>INFO${CMAKE_INSTALL_INFODIR}<DATAROOT dir>/infoLOCALE${CMAKE_INSTALL_LOCALEDIR}<DATAROOT dir>/localeMAN${CMAKE_INSTALL_MANDIR}<DATAROOT dir>/manDOC${CMAKE_INSTALL_DOCDIR}<DATAROOT dir>/docLIBEXEC${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關鍵字（如果存在）會導致匯出符合(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?的屬性的內容，當策略CMP0022為NEW時。注意
已安裝的
<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)而停用，則會寫入一個find_dependency()呼叫，其中包含目標的相應套件名稱、一個REQUIRED參數，以及由export(SETUP)的EXTRA_ARGS參數指定的任何額外參數。即使匯出的目標不依賴於來自它們的任何目標，透過將ENABLED ON傳遞給export(SETUP)手動指定的任何套件依賴項也會被添加。find_dependency()呼叫會按照以下順序寫入在
export(SETUP)中列出的任何套件依賴項，無論它們是否包含匯出目標的INTERFACE依賴項，都會按照它們首次指定的順序寫入。任何包含匯出目標的
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 上，運行時依賴項集合中最多可以有一個此類 bundle 可執行檔。MACOSX_BUNDLE屬性在其他平台上沒有影響。請注意，file(GET_RUNTIME_DEPENDENCIES)僅支援收集 Windows、Linux 和 macOS 平台的運行時依賴項，因此install(RUNTIME_DEPENDENCY_SET)也具有相同的限制。以下子參數將作為對應的參數轉發到
file(GET_RUNTIME_DEPENDENCIES)（對於那些提供非空目錄列表、正則表達式或檔案的參數）。它們都支援generator expressions。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，此檔案由產生的 install 目標和 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。