CMD#49 : install 指定在安裝時要運行的規則。
該命令為一個工程生成安裝規則。在某一源文件路徑中,調用這條命令所指定的規則會在安裝時按順序執行。在不同路徑之間的順序未定義。
該命令有諸多版本。其中的一些版本定義了文件以及目標的安裝屬性。這多個版本的公共屬性都有所涉及,但是只有在指定它們的版本中,這些屬性才是合法的(下面的DESTIONATION到OPTIONAL的選項列表是公共屬性。——譯注)。
DESTINATION選項指定了一個文件會安裝到磁盤的哪個路徑下。若果給出的是全路徑(以反斜杠或者驅動器名開頭),它會被直接使用。如果給出的是相對路徑,它會被解釋為相對於CMAKE_INSTALL_PREFIX的值的相對路徑。
PERMISSIONS選項制定了安裝文件需要的權限。合法的權限有:OWNER_READ,OWNER_WRITE,OWNER_EXECUTE,GROUP_READ,GROUP_WRITE,GROUP_EXECUTE,WORLD_READ,WORLD_WRITE,WORLD_EXECUTE,SETUID和SETGID。對於在某些特定的平台上沒有意義的權限,在這些平台上會忽略這些選項。
CONFIGURATIONS選項指定了該安裝規則將會加諸之上的一系列的構建配置(Debug,Release,等等)。
COMPONENT選項指定了該安裝規則相關的一個安裝部件的名字,比如“runtime”或“development”。對於那些指定安裝部件的安裝過程來說,在安裝時只有與給定的部件名相關的安裝規則會被執行。對於完整安裝,所有部件都會被安裝。
RENAME選項為一個可能不同於原始文件的已經安裝的文件指定另一個名字。重命名只有在該命令正在安裝一個單一文件時才被允許(猜測是為了防止文件名沖突時覆蓋掉舊文件。——譯注)。
OPTIONAL選項表示要安裝的文件不存在不會導致錯誤。
TARGETS版本的install命令
install(TARGETS targets... [EXPORT <export-name>]
[[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
[DESTINATION <dir>]
[PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]]
[COMPONENT <component>]
[OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
] [...])
TARGETS格式的install命令規定了安裝工程中的目標(targets)的規則。有5中可以被安裝的目標文件:ARCHIVE,LIBRARY,RUNTIME,FRAMEWORK,和BUNDLE。除了被標記為MACOSX_BUNDLE屬性的可執行文件被當做OS X上的BUNDLE目標外,其他的可執行文件都被當做RUNTIME目標。靜態鏈接的庫文件總是被當做ARCHIVE目標。模塊庫總是被當做LIBRARY目標。對於動態庫不是DLL格式的平台來說,動態庫會被當做LIBRARY目標來對待,被標記為FRAMEWORK的動態庫是例外,它們被當做OS X上的FRAMEWORK目標。對於DLL平台而言,動態庫的DLL部分被當做一個RUNTIME目標而對應的導出庫被當做是一個ARCHIVE目標。所有基於Windows的系統,包括Cygwin,都是DLL平台。ARCHIVE,LIBRARY,RUNTIME和FRAMEWORK參數改變了后續屬性會加諸之上的目標的類型。如果只給出了一種類型,那么只有那種類型的目標會被安裝(這樣通常只會安裝一個DLL或者一個導出庫。)
PRIVATE_HEADER,PUBLIC_HEADER,和RESOURCE選項的功能是,在非蘋果平台上,將后續的屬性應用在待安裝的一個FRAMEWORK共享庫目標的相關文件上。這些選項定義的規則在蘋果系統上會被忽略掉,因為相關的文件將會被安裝到framework文件夾內的合適位置。參見PRIVATE_HEADER,PUBLIC_HEADER和RESOURCE目標屬性中更為詳細的解釋。
可以指定NAMELINK_ONLY或者NAMELINK_SKIP選項作為LIBRARY選項。在一些平台上,版本化的共享庫有一個符號鏈接,比如lib<name>.so -> lib<name>.so.1,其中“lib<name>.so.1”是so庫文件名(soname)而“lib<name>.so”是一個符號鏈接,當指定“-l<name>”選項時,鏈接器將會查找這個符號鏈接。如果一個庫目標已經被安裝,NAMELINK_ONLY選項表示僅僅安裝符號鏈接;而NAME_SKIP選項則表示僅僅安裝庫文件而不是符號鏈接。當兩種選項都沒有給出時,動態庫的兩個部分都會被安裝。在那些版本化的共享庫沒有符號鏈接或者庫沒有被版本化的平台,選項NAMELINK_SKIP安裝這個庫,而NAMELINK_ONLY選項什么都不會安裝。參見VERSION和SOVERSION目標屬性,獲取關於創建版本化共享庫的更多細節。
在該命令的TARGETS版本的一次調用中,可以一次性指定一個或多個屬性組。一個目標也可以被多次安裝到不同的位置。假設有三個目標myExe,mySharedLib和myStaticLib,下面的代碼
install(TARGETS myExe mySharedLib myStaticLib
RUNTIME DESTINATION bin
LIBRARY DESTINATION lib
ARCHIVE DESTINATION lib/static)
install(TARGETS mySharedLib DESTINATION /some/full/path)
將會把myExe安裝到<prefix>/bin目錄下,把myStaticLib安裝到<prefix>/lib/static目錄下。在非-DLL平台上,mySharedLib將會被安裝到<prefix>/lib和/some/full/path下。在DLL平台上,mySharedLib DLL將會被安裝到<prefix>/bin和/some/full/path路徑下,它的導出庫會被安裝到<prefix>/lib/static和/some/full/path路徑下。
EXPORT選項將已經安裝的目標文件和一個名為<export-name>的導出文件關聯起來。它必須出現在所有RUNTIME,LIBRARY或者ARCHIVE選項之前。為了實際安裝導出文件本身(export file),調用install(EXPORT)。參見下述install命令EXPORT版本的文檔獲取更多的細節。
將EXCLUDE_FROM_ALL設置為true時,安裝一個目標會造成未定義的行為。
FILES版本的install命令
install(FILES files... DESTINATION <dir>
[PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]]
[COMPONENT <component>]
[RENAME <name>] [OPTIONAL])
FILES版本的install命令指定了為一個工程安裝文件的規則。在命令中,以相對路徑方式給出的文件名是相對於當前源代碼路徑而言的。以這個版本安裝的文件,如果沒有指定PERMISSIONS選項,默認會具有OWNER_WRITE,OWNER_READ,GROUP_READ,和WORLD_READ的權限。
PROGRAMS版本的install命令
install(PROGRAMS files... DESTINATION <dir>
[PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]]
[COMPONENT <component>]
[RENAME <name>] [OPTIONAL])
PROGRAMS版本與FILES版本一樣,只在默認權限上有所不同:它還包括了OWNER_EXECUTE,GROUP_EXECUTE和WORLD_EXECUTE選項。INSTALL的這個版本用來安裝不是目標的程序,比如shell腳本。使用TARGETS格式安裝該工程內部構建的目標。
DIRECTORY版本的install命令
install(DIRECTORY dirs... DESTINATION <dir>
[FILE_PERMISSIONS permissions...]
[DIRECTORY_PERMISSIONS permissions...]
[USE_SOURCE_PERMISSIONS] [OPTIONAL]
[CONFIGURATIONS [Debug|Release|...]]
[COMPONENT <component>] [FILES_MATCHING]
[[PATTERN <pattern> | REGEX <regex>]
[EXCLUDE] [PERMISSIONS permissions...]] [...])
INSTALL的DIRECTORY版本將一個或者多個路徑下的內容安裝到指定的目標地址下。目錄結構會原封不動地(verbatim)拷貝到目標地址。每個路徑名的最后一部分會追加到目標路徑下,但是結尾反斜杠(trailing slash)可以用來避免這一點,因為這樣最后一部分就是空的。給定的相對路徑名被解釋成相對於當前源路徑的路徑。如果沒有指定輸入目錄名字,目標目錄會被創建,但是不會安裝任何東西。FILE_PERMISSIONS和DIRECTORY_PERMISSIONS選項指定了賦予目標路徑和目標文件的權限。如果指定了USE_SOURCE_PERMISSIONS選項,但沒有指定FILE_PERMISSIONS選項,文件權限將沿襲源目錄結構的權限,而且這個路徑會被賦予PAROGRAMS版本中指定的默認權限。
通過使用PATTERN或REGEX選項可以對路徑安裝做出細粒度的控制。這些用於匹配的選項指定了一個查詢模式或正則表達式來匹配輸入路徑內的路徑或文件。它們可以用來將特定的選項(見下文)加諸於遇到的文件和路徑的一個子集上。每個輸入文件或路徑的完整路徑(反斜杠/開頭的路徑)將用來匹配該表達式。PATTERN僅僅用來匹配完全文件名:匹配該模式的全路徑的那部分必須出現在文件名的結尾,並且必須以一個反斜杠開始。
正則表達式會用來匹配一個完全路徑的任何部分,但是它也可以使用'/'和'$'模仿PATTERN的行為。默認情況下,所有文件和路徑不管是否匹配都會被安裝。可以在第一個匹配選項之前指定FILE_MATCHING選項,這樣就能禁止安裝那些不與任何表達式匹配的文件。比如,代碼
install(DIRECTORY src/ DESTINATION include/myproj
FILES_MATCHING PATTERN "*.h")
將會精確匹配並安裝從源碼樹上得到的頭文件。
有些選項后面可以跟在PATTERN或者REGEX表達式的后面,這樣這些選項只能加諸於匹配PATTERN/REGEX的文件或路徑上。EXCLUDE選項將會指示安裝過程跳過那些匹配的文件或者路徑。PERMISSIONS選項可以覆蓋那些匹配PATTERN/REGEX的文件的權限設定。例如,代碼
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/myproject/icons下,同時把scripts目錄安裝到share/myproj路徑下。icons將具備默認的文件權限,scripts將會被給與指定的權限,但是所有CVS路徑排除在外。
SCRIPT和CODE版本的install命令
install([[SCRIPT <file>] [CODE <code>]] [...])
SCRIPT格式將會在安裝期調用給定的腳本文件。如果腳本文件名是一個相對路徑,它會被解釋為相對於當前的源路徑。CODE格式將會在安裝期調用給定的CMake代碼。code被指定為一個雙引號括起來的單獨的參數。例如,代碼
install(CODE "MESSAGE(\"Sample install message.\")")
會在安裝時打印一條消息。
EXPORT版本的install命令
install(EXPORT <export-name> DESTINATION <dir>
[NAMESPACE <namespace>] [FILE <name>.cmake]
[PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]]
[COMPONENT <component>])
EXPORT格式的install命令生成並安裝一個包含將安裝過程的安裝樹導入到另一個工程中的CMake文件。Target格式的安裝過程與上文提及的使用EXPORT選項的install(TARGET ...)格式的命令中的EXPORT <export-name>選項是相關的。NAMESPACE選項會在它們被寫入到導入文件時加到目標名字之前。缺省時,生成的文件就是<export-name>.cmake;但是FILE選項可以用來指定不同於次的文件名。FILE選項后面的參數必須是一“.cmake”為擴展名的文件。如果指定了CONFIGURATIONS選項,那么只有那些具名的配置中的一個被安裝時,這個文件才會被安裝。而且,生成的導入文件只能涉及到匹配的目標配置版本。如果指定了一個COMPONENT選項,並且<component>與那個<export-name>相關的目標指定的部件不匹配,那么行為是未定義的。如果一個庫目標被包含在export之中,但是與之關聯的庫卻沒有背包含,那么結果是未指定的。
EXPORT格式可以協助外部工程使用當前工程構建出來並安裝的目標。例如,代碼
install(TARGETS myexe EXPORT myproj DESTINATION bin)
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
將會把可執行文件myexe安裝到<prefix>/bin下,並且將導入它的代碼寫到文件"<prefix>/lib/myproj/myproj.cmake"中。一個外部工程可以用include命令加載這個文件,並且可以在安裝樹上使用導入的目標名mp_myexe(前綴_目標名——譯注)引用myexe可執行文件,如同這個目標是它自身的構建樹的內置目標一樣。
注意:這個命令會取代INSTALL_TARGETS命令以及PRE_INSTALL_SCRIPT和POST_INSTALL_SCRIPT兩個目標屬性。它也可以取代FILES格式的INSTALL_FILES命令和INSTALL_PROGRAMS命令。由INSTALL命令生成的安裝規則相對於那些由INSTALL_TARGETS,INSTALL_FILES和INSTALL_PROGRAMS命令生成的安裝規則處理順序是未定義的。
CMD#50 : link_directories 指定
連接器查找庫的路徑。
link_directories(directory1 directory2 ...)
指定連接器搜索庫文件時的路徑。該命令僅僅能用在那些在它被調用后才生成的目標上。由於歷史上的原因,為該命令指定的相對路徑將會不加改變地傳遞給連接器(不像許多其他CMake命令那樣解釋為相對於當前源路徑的相對路徑。)