CMake命令大全——CMake構建系統的骨架

轉自:http://www.cnblogs.com/coderfenghc/archive/2012/06/16/CMake_ch_01.html#2996205

CMD#1add_custom_command爲生成的構建系統添加一條自定義的構建規則。

add_custom_command命令有兩種主要的功能;第一種是爲了生成輸出文件,添加一條自定義命令。

複製代碼
add_custom_command(OUTPUT output1 [output2 ...]
                     COMMAND command1 [ARGS] [args1...]
                     [COMMAND command2 [ARGS] [args2...] ...]
                     [MAIN_DEPENDENCY depend]
                     [DEPENDS [depends...]]
                     [IMPLICIT_DEPENDS <lang1> depend1 ...]
                     [WORKING_DIRECTORY dir]
                     [COMMENT comment] [VERBATIM] [APPEND])
複製代碼

  這種命令格式定義了一條生成指定的文件(文件組)的生成命令。在相同路徑下創建的目標(CMakeLists.txt文件)——任何自定義命令的輸出都作爲它的源文件——被設置了一條規則:在構建的時候,使用指定的命令來生成這些文件。如果一個輸出文件名是相對路徑,它將被解釋成相對於構建樹路徑的相對路徑,並且與當前源碼路徑是對應的。注意,MAIN_DEPENDENCY完全是可選的,它用來向visual studio建議在何處停止自定義命令。對於各種類型的makefile而言,這條命令創建了一個格式如下的新目標:

OUTPUT: MAIN_DEPENDENCY DEPENDS
COMMAND

  如果指定了多於一條的命令,它們會按順序執行。ARGS參數是可選的,它的存在是爲了保持向後兼容,以後會被忽略掉。

  第二種格式爲一個目標——比如一個庫文件或者可執行文件——添加一條自定義命令。這種格式可以用於目標構建前或構建後的一些操作。這條命令會成爲目標的一部分,並且只有目標被構建時纔會執行。如果目標已經構建了,該目標將不會執行。

複製代碼
add_custom_command(TARGET target
PRE_BUILD | PRE_LINK | POST_BUILD
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM])
複製代碼

  這條命令定義了一個與指定目標的構建過程相關的新命令。新命令在何時執行,由下述的選項決定:

PRE_BUILD - 在所有其它的依賴之前執行;
PRE_LINK - 在所有其它的依賴之後執行;
POST_BUILD - 在目標被構建之後執行;

  注意,只有Visual Studio 7或更高的版本才支持PRE_BUILD。對於其他的生成器,PRE_BUILD會被當做PRE_LINK來對待。

  如果指定了WORKING_DIRECTORY選項,這條命令會在給定的路徑下執行。如果設置了COMMENT選項,後跟的參數會在構建時、以構建信息的形式、在命令執行之前顯示出來。如果指定了APPEND選項,COMMAND以及DEPENDS選項的值會附加到第一個輸出文件的自定義命令上。在此之前,必須有一次以相同的輸出文件作爲參數的對該命令的調用。在當前版本下,如果指定了APPEND選項,COMMENT, WORKING_DIRECTORY和MAIN_DEPENDENCY選項會被忽略掉,不過未來有可能會用到。

  如果指定了VERBATIM選項,所有該命令的參數將會合適地被轉義,以便構建工具能夠以原汁原味的參數去調用那些構建命令。注意,在add_custom_command能看到這些參數之前,CMake語言處理器會對這些參數做一層轉義處理。推薦使用VERBATIM參數,因爲它能夠保證正確的行爲。當VERBATIM未指定時,CMake的行爲依賴於平臺,因爲CMake沒有針對某一種工具的特殊字符采取保護措施。

  如果自定義命令的輸出並不是實際的磁盤文件,應該使用SET_SOURCE_FILES_PROPERTIES命令將該輸出的屬性標記爲SYMBOLIC。

IMPLICIT_DEPENDS選項請求掃描一個輸入文件的隱含依賴關係。給定的語言參數(文中的lang1—譯註)指定了應該使用哪種編程語言的依賴掃描器。目前爲止,僅支持C和CXX語言掃描器。掃描中發現的依賴文件將會在編譯時添加到自定義命令中。注意,IMPLICIT_DEPENDS選項目前僅僅直至Makefile生成器,其它的生成器會忽略之。

  如果COMMAND選項指定了一個可執行目標(由ADD_EXECUTABLE命令創建的目標),在構建時,它會自動被可執行文件的位置所替換。而且,一個目標級的依賴性將會被添加進去,這樣這個可執行目標將會在所有依賴於該自定義命令的結果的目標之前被構建。不過,任何時候重編譯這個可執行文件,這種特性並不會引入一個會引起自定義命令重新運行的文件級依賴。

DEPENDS選項指定了該命令依賴的文件。如果依賴的對象是同一目錄(CMakeLists.txt文件)下另外一個自定義命令的輸出,CMake會自動將其它自定義命令帶到這個命令中來。如果DEPENDS指定了任何類型的目標(由ADD_*命令創建),一個目標級的依賴性將會被創建,以保證該目標在任何其它目標使用這個自定義命令的輸出之前,該目標已經被創建了。而且,如果該目標是可執行文件或庫文件,一個文件級依賴將會被創建,用來引發自定義命令在目標被重編譯時的重新運行。

CMD#2: add_custom_target添加一個目標,它沒有輸出;這樣它就總是會被構建。

複製代碼
add_custom_target(Name [ALL] [command1 [args1...]]
[COMMAND command2 [args2...] ...]
[DEPENDS depend depend depend ... ]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM]
[SOURCES src1 [src2...]])
複製代碼

  用Name選項給定的名字添加一個目標,這個目標會引發給定的那些命令。這個目標沒有輸出文件,並且總是被認爲是過時的,即使那些命令試圖去創建一個與該目標同名的文件。使用ADD_CUSTOM_COMMAND命令可以生成一個帶有依賴性的文件。默認情況下,沒有目標會依賴於自定義目標。使用ADD_DEPENDENCIES命令可以添加依賴於該目標或者被該目標依賴的目標。如果指定了ALL選項,這表明這個目標應該被添加到默認的構建目標中,這樣它每次都會被構建(命令的名字不能是ALL)。命令和選項是可選的;如果它們沒有被指定,將會產生一個空目標。如果設定了WORKING_DIRECTORY參數,該命令會在它指定的路徑下執行。如果指定了COMMENT選項,後跟的參數將會在構件的時候,在命令執行之前,被顯示出來。DEPENDS選項後面列出來的依賴目標可以引用add_custom_command命令在相同路徑下(CMakeLists.txt)生成的輸出和文件。

  如果指定了VERBATIM選項,所有傳遞到該命令的選項將會被合適地轉義;這樣,該命令調用的構建工具會接收到未經改變的參數。注意,CMake語言處理器會在add_custom_target命令在看到這些參數之前對它們進行一層轉義。推薦使用該參數,因爲它保證了正確的行爲。當未指定該參數時,轉義的行爲依賴於平臺,因爲CMake沒有針對於特定工具中特殊字符的保護措施。

SOURCES選項指定了會被包含到自定義目標中的附加的源文件。指定的源文件將會被添加到IDE的工程文件中,方便在沒有構建規則的情況下能夠編輯。

CMD#3:add_definitions 爲源文件的編譯添加由-D引入的define flag。

add_definitions(-DFOO -DBAR ...)

  在編譯器的命令行上,爲當前路徑以及下層路徑的源文件加入一些define flag。這個命令可以用來引入任何flag,但是它的原意是用來引入預處理器的定義。那些以-D或/D開頭的、看起來像預處理器定義的flag,會被自動加到當前路徑的COMPILE_DEFINITIONS屬性中。爲了後向兼容,非簡單值(non-trival,指的是什麼?)的定義會被留在flags組(flags set)裏,而不會被轉換。關於在特定的域以及配置中增加預處理器的定義,參考路徑、目標以及源文件的COMPILE_DEFINITIONS屬性來獲取更多的細節。

CMD#4:add_dependencies 爲頂層目標引入一個依賴關係。

add_dependencies(target-name depend-target1
depend-target2 ...)

  讓一個頂層目標依賴於其他的頂層目標。一個頂層目標是由命令ADD_EXECUTABLE,ADD_LIBRARY,或者ADD_CUSTOM_TARGET產生的目標。爲這些命令的輸出引入依賴性可以保證某個目標在其他的目標之前被構建。查看ADD_CUSTOM_TARGET和ADD_CUSTOM_COMMAND命令的DEPENDS選項,可以瞭解如何根據自定義規則引入文件級的依賴性。查看SET_SOURCE_FILES_PROPERTIES命令的OBJECT_DEPENDS選項,可以瞭解如何爲目標文件引入文件級的依賴性。

CMD#5:add_executable: 使用給定的源文件,爲工程引入一個可執行文件。

add_executable(<name> [WIN32] [MACOSX_BUNDLE]
[EXCLUDE_FROM_ALL]
source1 source2 ... sourceN)

  引入一個名爲<name>的可執行目標,該目標會由調用該命令時在源文件列表中指定的源文件來構建。<name>對應於邏輯目標名字,並且在工程範圍內必須是全局唯一的。被構建的可執行目標的實際文件名將根據具體的本地平臺創建出來(比如<name>.exe或者僅僅是<name>)。

  默認情況下,可執行文件將會在構建樹的路徑下被創建,對應於該命令被調用的源文件樹的路徑。如果要改變這個位置,查看RUNTIME_OUTPUT_DIRECTORY目標屬性的相關文檔。如果要改變最終文件名的<name>部分,查看OUTPUT_NAME目標屬性的相關文檔。

  如果指定了MACOSX_BUNDLE選項,對應的屬性會附加在創建的目標上。查看MACOSX_BUNDLE目標屬性的文檔可以找到更多的細節。

  如果指定了EXCLUDE_FROM_ALL選項,對應的屬性將會設置在被創建的目標上。查看EXCLUDE_FROM_ALL目標屬性的文檔可以找到更多的細節。

  使用下述格式,add_executable命令也可以用來創建導入的(IMPORTED)可執行目標:

add_executable(<name> IMPORTED)

一個導入的可執行目標引用了一個位於工程之外的可執行文件。該格式不會生成構建這個目標的規則。該目標名字的作用域在它被創建的路徑以及底層路徑有效。它可以像在該工程內的其他任意目標一樣被引用。導入可執行文件爲類似於add_custom_command之類的命令引用它提供了便利。

  關於導入的可執行文件的細節可以通過設置以IMPORTED_開頭的屬性來指定。這類屬性中最重要的是IMPORTED_LOCATION(以及它對應於具體配置的版本IMPORTED_LOCATION_<CONFIG>);該屬性指定了執行文件主文件在磁盤上的位置。查看IMPORTED_*屬性的文檔來獲得更多信息。

CMD#6:add_library 使用指定的源文件向工程中添加一個庫。

add_library(<name> [STATIC | SHARED | MODULE]
[EXCLUDE_FROM_ALL]
source1 source2 ... sourceN)

  添加一個名爲<name>的庫文件,該庫文件將會根據調用的命令裏列出的源文件來創建。<name>對應於邏輯目標名稱,而且在一個工程的全局域內必須是唯一的。待構建的庫文件的實際文件名根據對應平臺的命名約定來構造(比如lib<name>.a或者<name>.lib)。指定STATIC,SHARED,或者MODULE參數用來指定要創建的庫的類型。STATIC庫是目標文件的歸檔文件,在鏈接其它目標的時候使用。SHARED庫會被動態鏈接,在運行時被加載。MODULE庫是不會被鏈接到其它目標中的插件,但是可能會在運行時使用dlopen-系列的函數動態鏈接。如果沒有類型被顯式指定,這個選項將會根據變量BUILD_SHARED_LIBS的當前值是否爲真決定是STATIC還是SHARED。

  默認狀態下,庫文件將會在於源文件目錄樹的構建目錄樹的位置被創建,該命令也會在這裏被調用。查閱ARCHIVE_OUTPUT_DIRECTORY,LIBRARY_OUTPUT_DIRECTORY,和RUNTIME_OUTPUT_DIRECTORY這三個目標屬性的文檔來改變這一位置。查閱OUTPUT_NAME目標屬性的文檔來改變最終文件名的<name>部分。

  如果指定了EXCLUDE_FROM_ALL屬性,對應的一些屬性會在目標被創建時被設置。查閱EXCLUDE_FROM_ALL的文檔來獲取該屬性的細節。

  使用下述格式,add_library命令也可以用來創建導入的庫目標:

add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED)

  導入的庫目標是引用了在工程外的一個庫文件的目標。沒有生成構建這個庫的規則。這個目標名字的作用域在它被創建的路徑及以下有效。他可以向任何在該工程內構建的目標一樣被引用。導入庫爲類似於target_link_libraries命令中引用它提供了便利。關於導入庫細節可以通過指定那些以IMPORTED_的屬性設置來指定。其中最重要的屬性是IMPORTED_LOCATION(以及它的具體配置版本,IMPORTED_LOCATION_<CONFIG>),它指定了主庫文件在磁盤上的位置。查閱IMPORTED_*屬性的文檔獲取更多的信息。

CMD#7:add_subdirectory 爲構建添加一個子路徑。

add_subdirectory(source_dir [binary_dir] 
[EXCLUDE_FROM_ALL])

  這條命令的作用是爲構建添加一個子路徑。source_dir選項指定了CMakeLists.txt源文件和代碼文件的位置。如果source_dir是一個相對路徑,那麼source_dir選項會被解釋爲相對於當前的目錄,但是它也可以是一個絕對路徑。binary_dir選項指定了輸出文件的路徑。如果binary_dir是相對路徑,它將會被解釋爲相對於當前輸出路徑,但是它也可以是一個絕對路徑。如果沒有指定binary_dir,binary_dir的值將會是沒有做任何相對路徑展開的source_dir,這也是通常的用法。在source_dir指定路徑下的CMakeLists.txt將會在當前輸入文件的處理過程執行到該命令之前,立即被CMake處理。

  如果指定了EXCLUDE_FROM_ALL選項,在子路徑下的目標默認不會被包含到父路徑的ALL目標裏,並且也會被排除在IDE工程文件之外。用戶必須顯式構建在子路徑下的目標,比如一些示範性的例子工程就是這樣。典型地,子路徑應該包含它自己的project()命令調用,這樣會在子路徑下產生一份完整的構建系統(比如VS IDE的solution文件)。注意,目標間的依賴性要高於這種排除行爲。如果一個被父工程構建的目標依賴於在這個子路徑下的目標,被依賴的目標會被包含到父工程的構建系統中,以滿足依賴性的要求。

CMD#8:add_test 以指定的參數爲工程添加一個測試。

add_test(testname Exename arg1 arg2 ... )

  如果已經運行過了ENABLE_TESTING命令,這個命令將爲當前路徑添加一個測試目標。如果ENABLE_TESTING還沒有運行過,該命令啥事都不做。測試是由測試子系統運行的,它會以指定的參數執行Exename文件。Exename或者是由該工程構建的可執行文件,也可以是系統上自帶的任意可執行文件(比如tclsh)。該測試會在CMakeList.txt文件的當前工作路徑下運行,這個路徑與二進制樹上的路相對應。

add_test(NAME <name> [CONFIGURATIONS [Debug|Release|...]]
COMMAND <command> [arg1 [arg2 ...]])

  如果COMMAND選項指定了一個可執行目標(用add_executable創建),它會自動被在構建時創建的可執行文件所替換。如果指定了CONFIGURATIONS選項,那麼該測試只有在列出的某一個配置下才會運行。

  在COMMAND選項後的參數可以使用“生成器表達式”,它的語法是"$<...>"。這些表達式會在構建系統生成期間,以及構建配置的專有信息的產生期間被評估。合法的表達式是:

$<CONFIGURATION> = 配置名稱
$<TARGET_FILE:tgt> = 主要的二進制文件(.exe, .so.1.2, .a)
$<TARGET_LINKER_FILE:tgt> = 用於鏈接的文件(.a, .lib, .so)
$<TARGET_SONAME_FILE:tgt> = 帶有.so.的文件(.so.3)

  其中,"tgt"是目標的名稱。目標文件表達式TARGET_FILE生成了一個完整的路徑,但是它的_DIR和_NAME版本可以生成目錄以及文件名部分:

$<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
$<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
$<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>

  用例:

1 add_test(NAME mytest

2 COMMAND testDriver --config $<CONFIGURATION>

3 --exe $<TARGET_FILE:myexe>)

  這段代碼創建了一個名爲mytest的測試,它執行的命令是testDriver工具,傳遞的參數包括配置名,以及由目標生成的可執行文件myexe的完整路徑。

CMD#9:aux_source_directory 查找在某個路徑下的所有源文件。

aux_source_directory(<dir> <variable>)

  蒐集所有在指定路徑下的源文件的文件名,將輸出結果列表儲存在指定的<variable>變量中。該命令主要用在那些使用顯式模板實例化的工程上。模板實例化文件可以存儲在Templates子目錄下,然後可以使用這條命令自動收集起來;這樣可以避免手工羅列所有的實例。

  使用該命令來避免爲一個庫或可執行目標寫源文件的清單,是非常具有吸引力的。但是如果該命令貌似可以發揮作用,那麼CMake就不需要生成一個感知新的源文件何時被加進來的構建系統了(也就是說,新文件的加入,並不會導致CMakeLists.txt過時,從而不能引起CMake重新運行。)。正常情況下,生成的構建系統能夠感知它何時需要重新運行CMake,因爲需要修改CMakeLists.txt來引入一個新的源文件。當源文件僅僅是加到了該路徑下,但是沒有修改這個CMakeLists.txt文件,使用者只能手動重新運行CMake來產生一個包含這個新文件的構建系統。

CMD#10:break 從一個包圍該命令的foreach或while循環中跳出。

break()

  從包圍它的foreach循環或while循環中跳出。

CMD#11:build_command 獲取構建該工程的命令行。

build_command(<variable>
[CONFIGURATION <config>]
[PROJECT_NAME <projname>]
[TARGET <target>])

  把給定的變量<variable>設置成一個字符串,其中包含使用由變量CMAKE_GENERATOR確定的項目構建工具,去構建某一個工程的某一個目標配置的命令行。

  對於多配置生成器,如果忽略CONFIGURATION選項,CMake將會選擇一個合理的默認值;而對於單配置生成器,該選項會被忽略。

  如果PROJECT_NAME選項被忽略,得到的命令行用來構建當前構建樹上的頂層工程。

  如果TARGET選項被忽略,得到的命令行可以用來構建所有目標,比較高效的用法是構建目標all或者ALL_BUILD。

build_command(<cachevariable> <makecommand>)

  不推薦使用以上的這種格式,但對於後相兼容還是有用的。只要可以,就要使用第一種格式。

  這種格式將變量<cachevariable>設置爲一個字符串,其中包含從構建樹的根目錄,用<makecommand>指定的構建工具構建這個工程的命令。<makecommand>應該是指向msdev,devenv,nmake,make或者是一種最終用戶指定的構建工具的完整路徑。

CMD#12:cmake_minimum_required 設置一個工程所需要的最低CMake版本。

cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
[FATAL_ERROR])

  如果CMake的當前版本低於指定的版本,它會停止處理工程文件,並報告錯誤。當指定的版本高於2.4時,它會隱含調用:

cmake_policy(VERSION major[.minor[.patch[.tweak]]])

  從而將cmale的策略版本級別設置爲指定的版本。當指定的版本是2.4或更低時,這條命令隱含調用:

cmake_policy(VERSION 2.4)

  這將會啓用對於CMake 2.4及更低版本的兼容性。

FATAL_ERROR選項是可以接受的,但是CMake 2.6及更高的版本會忽略它。如果它被指定,那麼CMake 2.4及更低版本將會以錯誤告終而非僅僅給出個警告。

CMD#13:cmake_policy 管理CMake的策略設置。
  隨着CMake的演變,有時爲了搞定bug或改善現有特色的實現方法,改變現有的行爲是必須的。CMake的策略機制是在新的CMake版本帶來行爲上的改變時,用來幫助保持現有項目的構建的一種設計。每個新的策略(行爲改變)被賦予一個"CMP<NNNN>"格式的識別符,其中"<NNNN>"是一個整數索引。每個策略相關的文檔都會描述“舊行爲”和“新行爲”,以及引入該策略的原因。工程可以設置各種策略來選擇期望的行爲。當CMake需要了解要用哪種行爲的時候,它會檢查由工程指定的一種設置。如果沒有可用的設置,工程假定使用“舊行爲”,並且會給出警告要求你設置工程的策略。

cmake_policy是用來設置“新行爲”或“舊行爲”的命令。如果支持單獨設置策略,我們鼓勵各項目根據CMake的版本來設置策略。

cmake_policy(VERSION major.minor[.patch[.tweak]])

  上述命令指定當前的CMakeLists.txt是爲給定版本的CMake書寫的。所有在指定的版本或更早的版本中引入的策略會被設置爲使用“新行爲”。所有在指定的版本之後引入的策略將會變爲無效(unset)。該命令有效地爲一個指定的CMake版本請求優先採用的行爲,並且告知更新的CMake版本給出關於它們新策略的警告。命令中指定的策略版本必須至少是2.4,否則命令會報告一個錯誤。爲了得到支持早於2.4版本的兼容性特性,查閱策略CMP0001的相關文檔。

cmake_policy(SET CMP<NNNN> NEW)

cmake_policy(SET CMP<NNNN> OLD)

  對於某種給定的策略,該命令要求CMake使用新的或者舊的行爲。對於一個指定的策略,那些依賴於舊行爲的工程,通過設置策略的狀態爲OLD,可以禁止策略的警告。或者,用戶可以讓工程採用新行爲,並且設置策略的狀態爲NEW。

cmake_policy(GET CMP<NNNN> <variable>)

  該命令檢查一個給定的策略是否設置爲舊行爲或新行爲。如果策略被設置,輸出的變量值會是“OLD”或“NEW”,否則爲空。

CMake將策略設置保存在一個棧結構中,因此,cmake_policy命令產生的改變僅僅影響在棧頂端的元素。在策略棧中的一個新條目由各子路徑自動管理,以此保護它的父路徑及同層路徑的策略設置。CMake也管理通過include()和find_package()命令加載的腳本中新加入的條目,除非調用時指定了NO_POLICY_SCOPE選項(另外可參考CMP0011)。cmake_policy命令提供了一種管理策略棧中自定義條目的接口:

cmake_policy(PUSH)
       cmake_policy(POP)

  每個PUSH必須有一個配對的POP來去掉撤銷改變。這對於臨時改變策略設置比較有用。

  函數和宏會在它們被創建的時候記錄策略設置,並且在它們被調用的時候使用記錄前的策略。如果函數或者宏實現設置了策略,這個變化會通過調用者(caller)一直上傳,自動傳遞到嵌套的最近的策略棧條目。

CMD#14:configure_file: 將一份文件拷貝到另一個位置並修改它的內容。

configure_file(<input> <output>
[COPYONLY] [ESCAPE_QUOTES] [@ONLY])

  將文件<input>拷貝到<output>然後替換文件內容中引用到的變量值。如果<input>是相對路徑,它被評估的基礎路徑是當前源碼路徑。<input>必須是一個文件,而不是個路徑。如果<output>是一個相對路徑,它被評估的基礎路徑是當前二進制文件路徑。如果<output>是一個已有的路徑,那麼輸入文件將會以它原來的名字放到那個路徑下。

  該命令替換掉在輸入文件中,以${VAR}格式或@VAR@格式引用的任意變量,如同它們的值是由CMake確定的一樣。 如果一個變量還未定義,它會被替換爲空。如果指定了COPYONLY選項,那麼變量就不會展開。如果指定了ESCAPE_QUOTES選項,那麼所有被替換的變量將會按照C語言的規則被轉義。該文件將會以CMake變量的當前值被配置。如果指定了@ONLY選項,只有@VAR@格式的變量會被替換而${VAR}格式的變量則會被忽略。這對於配置使用${VAR}格式的腳本文件比較有用。任何類似於#cmakedefine VAR的定義語句將會被替換爲#define VAR或者/* #undef VAR */,視CMake中對VAR變量的設置而定。任何類似於#cmakedefine01 VAR的定義語句將會被替換爲#define VAR 1或#define VAR 0,視VAR被評估爲TRUE或FALSE而定。

(configure_file的作用是讓普通文件也能使用CMake中的變量。)

CMD#15:create_test_sourcelist: 爲構建測試程序創建一個測試驅動器和源碼列表。

create_test_sourcelist(sourceListName driverName
test1 test2 test3
EXTRA_INCLUDE include.h
FUNCTION function)

  測試驅動器是一個將很多小的測試代碼連接爲一個單一的可執行文件的程序。這在爲了縮減總的需用空間而用很多大的庫文件去構建靜態可執行文件的時候,特別有用。構建測試驅動所需要的源文件列表會在變量sourceListName中。DriverName變量是測試驅動器的名字。其它的參數還包括一個測試源代碼文件的清單,中間可以用分號隔開。每個測試源碼文件中應該有一個與去掉擴展名的文件名同名的函數(比如foo.cxx 文件裏應該有int foo(int, char*[]);)(和main的函數簽名一樣)。DriverName可以在命令行中按名字調用這些測試中的每一個。如果指定了EXTRA_INCLUDE,那麼它後面的參數(即include.h)會被包含到生成的文件裏。如果指定了FUNCTION選項,那麼它後面的參數(即function)會被認爲是一個函數名,傳遞給它的參數是一個指向argc的指針和argv。這個選項可以用來爲每個測試函數添加額外的命令行參數處理過程。CMake變量CMAKE_TESTDRIVER_BEFORE_TESTMAIN用來設置在調用測試的main函數之前調用的代碼。

CMD#16:define_property:定義並描述(Document)自定義屬性。

define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                    TEST | VARIABLE | CACHED_VARIABLE>
                    PROPERTY <name> [INHERITED]
                    BRIEF_DOCS <brief-doc> [docs...]
                    FULL_DOCS <full-doc> [docs...])

  在一個域(scope)中定義一個可以用set_property和get_property命令訪問的屬性。這個命令對於把文檔和可以通過get_property命令得到的屬性名稱關聯起來非常有用。第一個參數確定了這個屬性可以使用的範圍。它必須是下列值中的一個:

GLOBAL = 與全局命名空間相關聯
DIRECTORY = 與某一個目錄相關聯
TARGET = 與一個目標相關聯
SOURCE = 與一個源文件相關聯
TEST = 與一個以add_test命名的測試相關聯
VARIABLE = 描述(document)一個CMake語言變量
CACHED_VARIABLE = 描述(document)一個CMake語言緩存變量

  注意,與set_property和get_property不相同,不需要給出實際的作用域;只有作用域的類型纔是重要的。PROPERTY選項必須有,它後面緊跟要定義的屬性名。如果指定了INHERITED選項,那麼如果get_property命令所請求的屬性在該作用域中未設置,它會沿着鏈條向更高的作用域去搜索。DIRECTORY域向上是GLOBAL。TARGET,SOURCE和TEST向上是DIRECTORY。

BRIEF_DOCS和FULL_DOCS選項後面的參數是和屬性相關聯的字符串,分別作爲變量的簡單描述和完整描述。在使用get_property命令時,對應的選項可以獲取這些描述信息。

CMD#17:else 開始一個if語句塊的else部分。

else(expression)

參見if命令。

CMD#18: elseif 開始 if 塊的 elseif 部分。

elseif(expression)

參見if命令。

CMD#19: enable_language 支持某種語言(CXX/C/Fortran/等)

enable_language(languageName [OPTIONAL] )

  該命令打開了CMake對參數中指定的語言的支持。這與project命令相同,但是不會創建任何project命令會產生的額外變量。可以選用的語言的類型有CXX,C,Fortran等。如果指定了OPTIONAL選項,用CMAKE_<languageName>_COMPILER_WORKS變量來判斷該語言是否被成功支持。

CMD#20: enable_testing 打開當前及以下目錄中的測試功能。

enable_testing()

  爲當前及其下級目錄打開測試功能。也可參見add_test命令。注意,ctest需要在構建跟目錄下找到一個測試文件。因此,這個命令應該在源文件目錄的根目錄下。

CMD#21endforeach 結束foreach語句塊中的一系列命令。

endforeach(expression)

  參見FOREACH命令。

CMD#22endfunction 結束一個function語句塊中的一系列命令。

endfunction(expression)

  參見function命令。

CMD#23: endif 結束一個if語句塊中的一系列命令。

endif(expression)

  參見if命令。

CMD#24: endmacro 結束一個macro語句塊中的一系列命令。

endmacro(expression)

  參見macro命令。

CMD#25:endwhile結束一個while語句塊中的一系列命令。

endwhile(expression)

  參見while命令。

CMD#26: execute_process 執行一個或更多個子進程。

複製代碼
execute_process(COMMAND <cmd1> [args1...]]
[COMMAND <cmd2> [args2...] [...]]
[WORKING_DIRECTORY <directory>]
[TIMEOUT <seconds>]
[RESULT_VARIABLE <variable>]
[OUTPUT_VARIABLE <variable>]
[ERROR_VARIABLE <variable>]
[INPUT_FILE <file>]
[OUTPUT_FILE <file>]
[ERROR_FILE <file>]
[OUTPUT_QUIET]
[ERROR_QUIET]
[OUTPUT_STRIP_TRAILING_WHITESPACE]
[ERROR_STRIP_TRAILING_WHITESPACE])
複製代碼

  運行一條或多條命令,使得前一條命令的標準輸出以管道的方式成爲下一條命令的標準輸入。所有進程公用一個單獨的標準錯誤管道。如果指定了WORKING_DIRECTORY選項,後面的路徑選項將會設置爲子進程的當前工作路徑。如果指定了TIMEOUT選項,如果子進程沒有在指定的秒數(允許分數)裏完成,子進程會自動終止。如果指定了RESULT_VARIABLE選項,該變量將保存爲正在運行的進程的結果;它可以是最後一個子進程的整數返回代碼,也可以是一個描述錯誤狀態的字符串。如果指定了OUTPUT_VARIABLE或者ERROR_VARIABLE,後面的變量將會被分別設置爲標準輸出和標準錯誤管道的值。如果兩個管道都是用了相同的變量,它們的輸出將會按產生的順序被合併。如果指定了INPUT_FILE,OUTPUT_FILE 或 ERROR_FILE選項,其後的文件將會分別被附加到第一個進程的標準輸入、最後一個進程的標準輸出,或者所有進程的標準錯誤管道上。如果指定了OUTPUT_QUIET後者ERROR_QUIET選項,那麼標準輸出或標準錯誤的結果將會被靜靜的忽略掉。如果爲同一個管道指定了多於一個的OUTPUT_*或ERROR_* 選項,優先級是沒有指定的。如果沒有指定OUTPUT_*或者ERROR_*選項,輸出將會與CMake進程自身對應的管道共享。

execute_process命令是exec_program命令的一個較新的功能更加強大的版本。但是爲了兼容性的原因,舊的exec_program命令還會繼續保留。

CMD#27:export 從構建樹中導出目標供外部使用。

export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename>)

  創建一個名爲<filename>的文件,它可以被外部工程包含進去,從而外部工程可以從當前工程的構建樹中導入目標。這對於交叉編譯那些可以運行在宿主平臺的的utility可執行文件,然後將它們導入到另外一個編譯成目標平臺代碼的工程中的情形,特別有用。如果指定了NAMESPACE選項,<namespace>字符串將會被擴展到輸出文件中的所有目標的名字中。如果指定了APPEND選項,生成的代碼將會續接在文件之後,而不是覆蓋它。如果一個庫目標被包含在export中,但是連接成它的目標沒有被包含,行爲沒有指定。

  由該命令創建的文件是與指定的構建樹一致的,並且絕對不應該被安裝。要從一個安裝樹上導出目標,參見install(EXPORT)命令。

export(PACKAGE <name>)

  在CMake的用戶包註冊表中,爲<name>包(package)存儲當前的構建目錄。這將有助於依賴於它的工程從當前工程的構建樹中查找並使用包而不需要用戶的介入。注意,該命令在包註冊表中創建的條目,僅僅在與跟構建樹一起運行的包配置文件(<name>Config.cmake)一起使用時纔會起作用。

CMD#28: file 文件操作命令

複製代碼
file(WRITE filename "message to write"... )
file(APPEND filename "message to write"... )
file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
file(STRINGS filename variable [LIMIT_COUNT num]
[LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
[LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
[NEWLINE_CONSUME] [REGEX regex]
[NO_HEX_CONVERSION])
file(GLOB variable [RELATIVE path] [globbing expressions]...)
file(GLOB_RECURSE variable [RELATIVE path] 
[FOLLOW_SYMLINKS] [globbing expressions]...)
file(RENAME <oldname> <newname>)
file(REMOVE [file1 ...])
file(REMOVE_RECURSE [file1 ...])
file(MAKE_DIRECTORY [directory1 directory2 ...])
file(RELATIVE_PATH variable directory file)
file(TO_CMAKE_PATH path result)
file(TO_NATIVE_PATH path result)
file(DOWNLOAD url file [TIMEOUT timeout] [STATUS status] [LOG log]
[EXPECTED_MD5 sum] [SHOW_PROGRESS])
複製代碼

WRITE選項將會寫一條消息到名爲filename的文件中。如果文件已經存在,該命令會覆蓋已有的文件;如果文件不存在,它將創建該文件。

APPEND選項和WRITE選項一樣,將會寫一條消息到名爲filename的文件中,只是該消息會附加到文件末尾。

READ選項將會讀一個文件中的內容並將其存儲在變量裏。讀文件的位置從offset開始,最多讀numBytes個字節。如果指定了HEX參數,二進制代碼將會轉換爲十六進制表達方式,並存儲在變量裏。

STRINGS將會從一個文件中將一個ASCII字符串的list解析出來,然後存儲在variable變量中。文件中的二進制數據會被忽略。回車換行符會被忽略。它也可以用在Intel的Hex和Motorola的S-記錄文件;讀取它們時,它們會被自動轉換爲二進制格式。可以使用NO_HEX_CONVERSION選項禁止這項功能。LIMIT_COUNT選項設定了返回的字符串的最大數量。LIMIT_INPUT設置了從輸入文件中讀取的最大字節數。LIMIT_OUTPUT設置了在輸出變量中存儲的最大字節數。LENGTH_MINIMUM設置了要返回的字符串的最小長度;小於該長度的字符串會被忽略。LENGTH_MAXIMUM設置了返回字符串的最大長度;更長的字符串會被分割成不長於最大長度的字符串。NEWLINE_CONSUME選項允許新行被包含到字符串中,而不是終止它們。REGEX選項指定了一個待返回的字符串必須滿足的正則表達式。典型的使用方式是:

file(STRINGS myfile.txt myfile)

該命令在變量myfile中存儲了一個list,該list中每個項是輸入文件中的一行文本。
GLOB選項將會爲所有匹配查詢表達式的文件生成一個文件list,並將該list存儲進變量variable裏。文件名查詢表達式與正則表達式類似,只不過更加簡單。如果爲一個表達式指定了RELATIVE標誌,返回的結果將會是相對於給定路徑的相對路徑。文件名查詢表達式的例子有:

*.cxx - 匹配所有擴展名爲cxx的文件。
*.vt? - 匹配所有擴展名是vta,...,vtz的文件。
f[3-5].txt - 匹配文件f3.txt, f4.txt, f5.txt。

GLOB_RECURSE選項將會生成一個類似於通常的GLOB選項的list,只是它會尋訪所有那些匹配目錄的子路徑並同時匹配查詢表達式的文件。作爲符號鏈接的子路徑只有在給定FOLLOW_SYMLINKS選項或者cmake策略CMP0009被設置爲NEW時,纔會被尋訪到。參見cmake --help-policy CMP0009 查詢跟多有用的信息。

使用遞歸查詢的例子有:

/dir/*.py - 匹配所有在/dir及其子目錄下的python文件。

MAKE_DIRECTORY選項將會創建指定的目錄,如果它們的父目錄不存在時,同樣也會創建。(類似於mkdir命令)

RENAME選項對同一個文件系統下的一個文件或目錄重命名。(類似於mv命令)

REMOVE選項將會刪除指定的文件,包括在子路徑下的文件。(類似於rm命令)

REMOVE_RECURSE選項會刪除給定的文件以及目錄,包括非空目錄。(類似於rm -r 命令)

RELATIVE_PATH選項會確定從direcroty參數到指定文件的相對路徑。

TO_CMAKE_PATH選項會把path轉換爲一個以unix的 / 開頭的cmake風格的路徑。輸入可以是一個單一的路徑,也可以是一個系統路徑,比如"$ENV{PATH}"。注意,在調用TO_CMAKE_PATH的ENV周圍的雙引號只能有一個參數(Note the double quotes around the ENV call TO_CMAKE_PATH only takes one argument. 原文如此。quotes和後面的takes讓人後糾結,這句話翻譯可能有誤。歡迎指正)。

TO_NATIVE_PATH選項與TO_CMAKE_PATH選項很相似,但是它會把cmake風格的路徑轉換爲本地路徑風格:windows下用\,而unix下用/。

DOWNLOAD 將給定的URL下載到指定的文件中。如果指定了LOG var選項,下載日誌將會被輸出到var中。如果指定了STATUS var選項,下載操作的狀態會被輸出到var中。該狀態返回值是一個長度爲2的list。list的第一個元素是操作的數字返回值,第二個返回值是錯誤的字符串值。錯誤信息如果是數字0,操作中沒有發生錯誤。如果指定了TIMEOUT time選項,在time秒之後,操作會超時退出;time應該是整數。如果指定了EXPECTED_MD5 sum選項,下載操作會認證下載的文件的實際MD5和是否與期望值匹配。如果不匹配,操作將返回一個錯誤。如果指定了SHOW_PROGRESS選項,進度信息會以狀態信息的形式被打印出來,直到操作完成。

file命令還提供了COPY和INSTALL兩種格式:

複製代碼
file(<COPY|INSTALL> files... DESTINATION <dir>
[FILE_PERMISSIONS permissions...]
[DIRECTORY_PERMISSIONS permissions...]
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
[FILES_MATCHING]
[[PATTERN <pattern> | REGEX <regex>]
[EXCLUDE] [PERMISSIONS permissions...]] [...])
複製代碼

COPY版本把文件、目錄以及符號連接拷貝到一個目標文件夾。相對輸入路徑的評估是基於當前的源代碼目錄進行的,相對目標路徑的評估是基於當前的構建目錄進行的。複製過程將保留輸入文件的時間戳;並且如果目標路徑處存在同名同時間戳的文件,複製命令會把它優化掉。賦值過程將保留輸入文件的訪問權限,除非顯式指定權限或指定NO_SOURCE_PERMISSIONS選項(默認是USE_SOURCE_PERMISSIONS)。參見install(DIRECTORY)命令中關於權限(permissions),PATTERN,REGEX和EXCLUDE選項的文檔。

INSTALL版本與COPY版本只有十分微小的差別:它會打印狀態信息,並且默認使用NO_SOURCE_PERMISSIONS選項。install命令生成的安裝腳本使用這個版本(它會使用一些沒有在文檔中涉及的內部使用的選項。)

CMD#29:find_file 查找一個文件的完整路徑。

find_file(<VAR> name1 [path1 path2 ...])

  這是該命令的精簡格式,對於大多數場合它都足夠了。它與命令find_file(<VAR> name1 [PATHS path1 path2 ...])是等價的。

複製代碼
find_file(
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
複製代碼

  這條命令用來查找指定文件的完整路徑。一個名字是<VAR>的緩存條目(參見CMakeCache.txt的介紹)變量會被創建,用來存儲該命令的結果。如果發現了文件的一個完整路徑,該結果會被存儲到該變量裏並且搜索過程不會再重複,除非該變量被清除。如果什麼都沒發現,搜索的結果將會是<VAR>-NOTFOUND;並且在下一次以相同的變量調用find_file時,該搜索會重新嘗試。被搜索的文件的文件名由NAMES選項後的名字列表指定。附加的其他搜索位置可以在PATHS選項之後指定。如果ENV var在HINTS或PATHS段中出現,環境變量var將會被讀取然後被轉換爲一個系統級環境變量,並存儲在一個cmake風格的路徑list中。比如,使用ENV PATH將會將系統的path變量列出來。在DOC之後的變量將會用於cache中的文檔字符串(documentation string)。PATH_SUFFIXES指定了在每個搜索路徑下的需要搜索的子路徑。

  如果指定了NO_DEFAULT_PATH選項,那麼在搜索時不會附加其它路徑。如果沒有指定NO_DEFAULT_PATH選項,搜索過程如下:

1、在cmake特有的cache變量中指定的搜索路徑搜索。這些路徑用於在命令行裏用-DVAR=value被設置。如果使用了NO_CMAKE_PATH選項,該路徑會被跳過。(此句翻譯可能有誤。)搜索路徑還包括:
  對於每個在CMAKE_PREFIX_PATH中的路徑<prefix>,<prefix>/include  
  變量:CMAKE_INCLUDE_PATH
  變量:CMAKE_FRAMEWORK_PATH

2、在cmake特定的環境變量中指定的搜索路徑搜索。該路徑會在用戶的shell配置中被設置。如果指定了NO_CMAKE_ENVIRONMENT_PATH選項,該路徑會被跳過。搜索路徑還包括:

  對於每個在CMAKE_PREFIX_PATH中的路徑<prefix>,<prefix>/include  
  變量:CMAKE_INCLUDE_PATH
  變量:CMAKE_FRAMEWORK_PATH

3、由HINTS選項指定的搜索路徑。這些路徑是由系統內省(introspection)時計算出來的路徑,比如已經發現的其他項的位置所提供的痕跡。硬編碼的參考路徑應該使用PATHS選項指定。(HINTS與PATHS有何不同?比後者的優先級高?有疑問。)

4、搜索標準的系統環境變量。如果指定NO_SYSTEM_ENVIRONMENT_PATH選項,搜索路徑將跳過其後的參數。搜索路徑包括環境變量PATH個INCLUDE。

5、查找在當前系統的平臺文件中定義的cmake變量。如果指定了NO_CMAKE_SYSTEM_PATH選項,該路徑會被跳過。其他的搜索路徑還包括:

  對於每個在CMAKE_PREFIX_PATH中的路徑<prefix>,<prefix>/include  
  變量:CMAKE_SYSTEM_INCLUDE_PATH
  變量:CMAKE_SYSTEM_FRAMEWORK_PATH

6、搜索由PATHS選項指定的路徑或者在命令的簡寫版本中指定的路徑。這一般是一些硬編碼的參考路徑。在Darwin後者支持OS X框架的系統上,cmake變量CMAKE_FIND_FRAMWORK可以設置爲空或者下述值之一:

"FIRST" - 在標準庫或者頭文件之前先查找框架。對於Darwin系統,這是默認的。
"LAST" - 在標準庫或頭文件之後再查找框架。
"ONLY" - 只查找框架。
"NEVER" - 從不查找框架。

  在Darwin或者支持OS X Application Bundles的系統上,cmake變量CMAKE_FIND_APPBUNDLE可以被設置爲空,或者下列值之一:

"FIRST" - 在標準程序之前查找application bundles,這也是Darwin系統的默認選項。
"LAST" - 在標準程序之後查找application bundlesTry。
"ONLY" - 只查找application bundles。
"NEVER" - 從不查找application bundles。

CMake的變量CMAKE_FIND_ROOT_PATH指定了一個或多個在所有其它搜索路徑之前的搜索路徑。該選項很有效地將給定位置下的整個搜索路徑的最優先路徑進行了重新指定。默認情況下,它是空的。當交叉編譯一個指向目標環境下的根目錄中的目標時,CMake也會搜索那些路徑;該變量這時顯得非常有用。默認情況下,首先會搜索在CMAKE_FIND_ROOT_PATH變量中列出的路徑,然後纔是非根路徑。設置CMAKE_FIND_ROOT_PATH_MODE_INCLUDE變量可以調整該默認行爲。該行爲可以在每次調用時被手動覆蓋。通過使用CMAKE_FIND_ROOT_PATH_BOTH變量,搜索順序將會是上述的那樣。如果使用了NO_CMAKE_FIND_ROOT_PATH變量,那麼CMAKE_FIND_ROOT_PATH將不會被用到。如果使用了ONLY_CMAKE_FIND_ROOT_PATH變量,那麼只有CMAKE_FIND_ROOT_PATH中的路徑(即re-rooted目錄)會被搜索。

一般情況下,默認的搜索順序是從最具體的路徑到最不具體的路徑。只要用NO_*選項多次調用該命令,工程就可以覆蓋該順序。

find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
    find_file(<VAR> NAMES name)

  只要這些調用中的一個成功了,返回變量就會被設置並存儲在cache中;然後該命令就不會再繼續查找了。

CMD#30:find_library 查找一個庫文件

find_library(<VAR> name1 [path1 path2 ...])

  這是該命令的簡寫版本,在大多數場合下都已經夠用了。它與命令find_library(<VAR> name1 [PATHS path1 path2 ...])等價。

複製代碼
find_library(
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
複製代碼

  該命令用來查找一個庫文件。一個名爲<VAR>的cache條目會被創建來存儲該命令的結果。如果找到了該庫文件,那麼結果會存儲在該變量裏,並且搜索過程將不再重複,除非該變量被清空。如果沒有找到,結果變量將會是<VAR>-NOTFOUND,並且在下次使用相同變量調用find_library命令時,搜索過程會再次嘗試。在NAMES參數後列出的文件名是要被搜索的庫名。附加的搜索位置在PATHS參數後指定。如果再HINTS或者PATHS字段中設置了ENV變量var,環境變量var將會被讀取並從系統環境變量轉換爲一個cmake風格的路徑list。例如,指定ENV PATH是獲取系統path變量並將其轉換爲cmake的list的一種方式。在DOC之後的參數用來作爲cache中的註釋字符串。PATH_SUFFIXES選項指定了每個搜索路徑下待搜索的子路徑。

  如果指定了NO_DEFAULT_PATH選項,那麼搜索的過程中不會有其他的附加路徑。如果沒有指定該選項,搜索過程如下:

1、搜索cmake特有的cache變量指定的路徑。這些變量是在用cmake命令行時,通過-DVAR=value指定的變量。如果指定了NO_CMAKE_PATH選項,這些路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_PREFIX_PATH中的<prefix>,路徑<prefix>/lib

CMAKE_LIBRARY_PATH
CMAKE_FRAMEWORK_PATH

2、搜索cmake特有的環境變量指定的路徑。這些變量是用戶的shell配置中設置的變量。如果指定了NO_CMAKE_ENVIRONMENT_PATH選項,這些路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_PREFIX_PATH中的<prefix>,路徑<prefix>/lib

CMAKE_LIBRARY_PATH
CMAKE_FRAMEWORK_PATH

3、搜索由HINTS選項指定的路徑。這些路徑是系統內省(introspection)估算出的路徑,比如由另一個已經發現的庫文件的地址提供的參考信息。硬編碼的推薦路徑應該通過PATHS選項指定。

4、查找標準的系統環境變量。如果指定了NO_SYSTEM_ENVIRONMENT_PATH選項,這些路徑會被跳過。搜索的路徑還包括:

PATH
LIB

5、查找在爲當前系統的平臺文件中定義的cmake變量。如果指定了NO_CMAKE_SYSTEM_PATH選項,該路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_SYSTEM_PREFIX_PATH中的<prefix>,路徑<prefix>/lib

CMAKE_SYSTEM_LIBRARY_PATH
CMAKE_SYSTEM_FRAMEWORK_PATH

6、搜索PATHS選項或者精簡版命令指定的路徑。這些通常是硬編碼的推薦搜索路徑。

  在Darwin或者支持OS X 框架的系統上,cmake變量CMAKE_FIND_FRAMEWORK可以用來設置爲空,或者下述值之一:

"FIRST" - 在標準庫或頭文件之前查找框架。在Darwin系統上這是默認選項。
"LAST" - 在標準庫或頭文件之後查找框架。
"ONLY" - 僅僅查找框架。
"NEVER" - 從不查找框架。

  在Darwin或者支持OS X Application Bundles的系統,cmake變量CMAKE_FIND_APPBUNDLE可以被設置爲空或者下面這些值中的一個:

"FIRST" - 在標準庫或頭文件之前查找application bundles。在Darwin系統上這是默認選項。
"LAST" - 在標準庫或頭文件之後查找application bundles。
"ONLY" - 僅僅查找application bundles。
"NEVER" - 從不查找application bundles。

CMake變量CMAKE_FIND_ROOT_PATH指定了一個或者多個優先於其他搜索路徑的搜索路徑。該變量能夠有效地重新定位在給定位置下進行搜索的根路徑。該變量默認爲空。當使用交叉編譯時,該變量十分有用:用該變量指向目標環境的根目錄,然後CMake將會在那裏查找。默認情況下,在CMAKE_FIND_ROOT_PATH中列出的路徑會首先被搜索,然後是“非根”路徑。該默認規則可以通過設置CMAKE_FIND_ROOT_PATH_MODE_LIBRARY做出調整。在每次調用該命令之前,都可以通過設置這個變量來手動覆蓋默認行爲。如果使用了NO_CMAKE_FIND_ROOT_PATH變量,那麼只有重定位的路徑會被搜索。

  默認的搜索順序的設計邏輯是按照使用時從最具體到最不具體。通過多次調用find_library命令以及NO_*選項,可以覆蓋工程的這個默認順序:

find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_library(<VAR> NAMES name)

  只要這些調用中的一個成功返回,結果變量就會被設置並且被存儲到cache中;這樣隨後的調用都不會再行搜索。如果那找到的庫是一個框架,VAR將會被設置爲指向框架“<完整路徑>/A.framework” 的完整路徑。當一個指向框架的完整路徑被用作一個庫文件,CMake將使用-framework A,以及-F<完整路徑>這兩個選項將框架連接到目標上。

CMD#31:find_package 爲外部工程加載設置。

find_package(<package> [version] [EXACT] [QUIET]
[[REQUIRED|COMPONENTS] [components...]]
[NO_POLICY_SCOPE])

  查找並加載外來工程的設置。該命令會設置<package>_FOUND變量,用來指示要找的包是否被找到了。如果這個包被找到了,與它相關的信息可以通過包自身記載的變量中得到。QUIET選項將會禁掉包沒有被發現時的警告信息。REQUIRED選項表示如果包沒有找到的話,cmake的過程會終止,並輸出警告信息。在REQUIRED選項之後,或者如果沒有指定REQUIRED選項但是指定了COMPONENTS選項,在它們的後面可以列出一些與包相關的部件清單(components list)。[version]參數需要一個版本號,它是正在查找的包應該兼容的版本號(格式是major[.minor[.patch[.tweak]]])。EXACT選項要求該版本號必須精確匹配。如果在find-module內部對該命令的遞歸調用沒有給定[version]參數,那麼[version]和EXACT選項會自動地從外部調用前向繼承。對版本的支持目前只存在於包和包之間(詳見下文)。

  用戶代碼總體上應該使用上述的簡單調用格式查詢需要的包。本命令文檔的剩餘部分則詳述了find_package的完整命令格式以及具體的查詢過程。期望通過該命令查找並提供包的項目維護人員,我們鼓勵你能繼續讀下去。

  該命令在搜索包時有兩種模式:“模塊”模式和“配置”模式。當該命令是通過上述的精簡格式調用的時候,使用的就是模塊模式。在該模式下,CMake搜索所有名爲Find<package>.cmake的文件,這些文件的路徑變量由安裝CMake時指定的CMAKE_MODULE_PATH變量指定。如果查找到了該文件,它會被CMake讀取並被處理。該模式對查找包,檢查版本以及生成任何別的必須信息負責。許多查找模塊(find-module)僅僅提供了有限的,甚至根本就沒有對版本化的支持;具體信息查看該模塊的文檔。如果沒有找到任何模塊,該命令會進入配置模式繼續執行。

  完整的配置模式下的命令格式是:

複製代碼
find_package(<package> [version] [EXACT] [QUIET]
[[REQUIRED|COMPONENTS] [components...]] [NO_MODULE]
[NO_POLICY_SCOPE]
[NAMES name1 [name2 ...]]
[CONFIGS config1 [config2 ...]]
[HINTS path1 [path2 ... ]]
[PATHS path1 [path2 ... ]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[NO_DEFAULT_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_PACKAGE_REGISTRY]
[NO_CMAKE_BUILDS_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH])
複製代碼

NO_MODULE可以用來明確地跳過模塊模式。它也隱含指定了不使用在精簡格式中使用的那些選項。

  配置模式試圖查找一個由待查找的包提供的配置文件的位置。包含該文件的路徑會被存儲在一個名爲<package>_DIR的cache條目裏。默認情況下,該命令搜索名爲<package>的包。如果指定了NAMES選項,那麼其後的names參數會取代<package>的角色。該命令會爲每個在names中的name搜索名爲<name>Config.cmake或者<name全小寫>-config.cmake的文件。通過使用CONFIGS選項可以改變可能的配置文件的名字。以下描述搜索的過程。如果找到了配置文件,它將會被CMake讀取並處理。由於該文件是由包自身提供的,它已經知道包中內容的位置。配置文件的完整地址存儲在cmake的變量<package>_CONFIG中。

  所有CMake要處理的配置文件將會搜索該包的安裝信息,並且將該安裝匹配的適當版本號(appropriate version)存儲在cmake變量<package>_CONSIDERED_CONFIGS中,與之相關的版本號(associated version)將被存儲在<package>_CONSIDERED_VERSIONS中。

  如果沒有找到包配置文件,CMake將會生成一個錯誤描述文件,用來描述該問題——除非指定了QUIET選項。如果指定了REQUIRED選項,並且沒有找到該包,將會報致命錯誤,然後配置步驟終止執行。如果設置了<package>_DIR變量被設置了,但是它沒有包含配置文件信息,那麼CMake將會直接無視它,然後重新開始查找。

  如果給定了[version]參數,那麼配置模式僅僅會查找那些在命令中請求的版本(格式是major[.minor[.patch[.tweak]]])與包請求的版本互相兼容的那些版本的包。如果指定了EXACT選項,一個包只有在它請求的版本與[version]提供的版本精確匹配時才能被找到。CMake不會對版本數的含義做任何的轉換。包版本號由包自帶的版本文件來檢查。對於一個備選的包配置文件<config-file>.cmake,對應的版本文件的位置緊挨着它,並且名字或者是<config-file>-version.cmake或者是<config-file>Version.cmake。如果沒有這個版本文件,那麼配置文件就會認爲不兼容任何請求的版本。當找到一個版本文件之後,它會被加載然後用來檢查(find_package)請求的版本號。版本文件在一個下述變量被定義的嵌套域中被加載:

PACKAGE_FIND_NAME = <package>名字。
PACKAGE_FIND_VERSION = 請求的完整版本字符串
PACKAGE_FIND_VERSION_MAJOR = 如果被請求了,那麼它是major版本號,否則是0。
PACKAGE_FIND_VERSION_MINOR = 如果被請求了,那麼它是minor版本號,否則是0。

PACKAGE_FIND_VERSION_PATCH = 如果被請求了,那麼它是patch版本號,否則是0。
PACKAGE_FIND_VERSION_TWEAK = 如果被請求了,那麼它是tweak版本號,否則是0。
PACKAGE_FIND_VERSION_COUNT = 版本號包含幾部分,0到4。

  版本文件會檢查自身是否滿足請求的版本號,然後設置了下面這些變量:

PACKAGE_VERSION = 提供的完整的版本字符串。
PACKAGE_VERSION_EXACT = 如果版本號精確匹配,返回true。
PACKAGE_VERSION_COMPATIBLE = 如果版本號相兼容,返回true。
PACKAGE_VERSION_UNSUITABLE = 如果不適合任何版本,返回true。

  下面這些變量將會被find_package命令檢查,用以確定配置文件是否提供了可接受的版本。在find_package命令返回後,這些變量就不可用了。如果版本可接受,下述的變量會被設置:

<package>_VERSION = 提供的完整的版本字符串。
<package>_VERSION_MAJOR = 如果被請求了,那麼它是major版本號,否則是0。
<package>_VERSION_MINOR = 如果被請求了,那麼它是minor版本號,否則是0。
<package>_VERSION_PATCH = 如果被請求了,那麼它是patch版本號,否則是0。
<package>_VERSION_TWEAK = 如果被請求了,那麼它是tweak版本號,否則是0。
<package>_VERSION_COUNT = 版本號包含幾部分,0到4。

然後,對應的包配置文件纔會被加載。當多個包配置文件都可用時,並且這些包的版本文件都與請求的版本兼容,選擇哪個包將會是不確定的。不應該假設cmake會選擇最高版本或者是最低版本。(以上的若干段是對find_package中版本匹配步驟的描述,並不需要用戶干預。)

  配置模式提供了一種高級接口和搜索步驟的接口。這些被提供的接口的大部分是爲了完整性的要求,以及在模塊模式下,包被find-module加載時供內部使用。大多數用戶僅僅應該調用:

find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])

來查找包。鼓勵那些需要提供CMake包配置文件的包維護人員應該命名這些文件並安裝它們,這樣下述的整個過程將會找到它們而不需要使用附加的選項。

CMake爲包構造了一組可能的安裝前綴。在每個前綴下,若干個目錄會被搜索,用來查找配置文件。下述的表格展示了待搜索的路徑。每個條目都是專門爲Windows(W),UNIX(U)或者Apple(A)約定的安裝樹指定的。

複製代碼
<prefix>/ (W)
<prefix>/(cmake|CMake)/ (W)
<prefix>/<name>*/ (W)
<prefix>/<name>*/(cmake|CMake)/ (W)
<prefix>/(share|lib)/cmake/<name>*/ (U)
<prefix>/(share|lib)/<name>*/ (U)
<prefix>/(share|lib)/<name>*/(cmake|CMake)/ (U)
複製代碼

  在支持OS X平臺和Application Bundles的系統上,包含配置文件的框架或者bundles會在下述的路徑中被搜索:

複製代碼
<prefix>/<name>.framework/Resources/ (A)
<prefix>/<name>.framework/Resources/CMake/ (A)
<prefix>/<name>.framework/Versions/*/Resources/ (A)
<prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
<prefix>/<name>.app/Contents/Resources/ (A)
<prefix>/<name>.app/Contents/Resources/CMake/ (A)
複製代碼

  在所有上述情況下,<name>是區分大小寫的,並且對應於在<package>或者由NAMES給定的任何一個名字。

  這些路徑集用來與那些在各自的安裝樹上提供了配置文件的工程協作。上述路徑中被標記爲(W)的是專門爲Windows上的安裝設置的,其中的<prefix>部分可能是一個應用程序的頂層安裝路徑。那些被標記爲(U)的是專門爲UNIX平臺上的安裝設置的,其中的<prefix>被多個包共用。這僅僅是個約定,因此,所有(W)和(U)路徑在所有平臺上都仍然會被搜索。那些被標記爲(A)的路徑是專門爲Apple平臺上的安裝設置的。CMake變量CMAKE_FIND_FRAMEWORK和CMAKE_FIND_APPBUNDLE確定了偏好的順序,如下所示:

  安裝前綴是通過以下步驟被構建出來的。如果指定了NO_DEFAULT_PATH選項,所有NO_*選項都會被激活。

1、搜索在cmake特有的cache變量中指定的搜索路徑。這些變量是爲了在命令行中用-DVAR=value選項指定而設計的。通過指定NO_CMAKE_PATH選項可以跳過該搜索路徑。搜索路徑還包括:

CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH

2、搜索cmake特有的環境變量。這些變量是爲了在用戶的shell配置中進行配置而設計的。通過指定NO_CMAKE_ENVIRONMENT_PATH選項可以跳過該路徑。搜索的路徑包括:

<package>_DIR
CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH

3、搜索HINTS選項指定的路徑。這些路徑應該是由操作系統內省時計算產生的,比如由其它已經找到的項的位置而提供的線索。硬編碼的參考路徑應該在PATHS選項中指定。

4、搜索標準的系統環境變量。如果指定了NO_SYSTEM_ENVIRONMENT_PATH選項,這些路徑會被跳過。以"/bin"或"/sbin"結尾的路徑條目會被自動轉換爲它們的父路徑。搜索的路徑包括:

PATH

5、搜索在CMake GUI中最新配置過的工程的構建樹。可以通過設置NO_CMAKE_BUILDS_PATH選項來跳過這些路徑。這是爲了在用戶正在依次構建多個相互依賴的工程時而準備的。

6、搜索存儲在CMake用戶包註冊表中的路徑。通過設置NO_CMAKE_PACKAGE_REGISTRY選項可以跳過這些路徑。當CMake嗲用export(PACKAGE<name>)配置一個工程時,這些路徑會被存儲在註冊表中。參見export(PACKAGE)命令的文檔閱讀更多細節。

7、搜索在當前系統的平臺文件中定義的cmake變量。可以用NO_CMAKE_SYSTEM_PATH選項跳過這些路徑。

CMAKE_SYSTEM_PREFIX_PATH

CMAKE_SYSTEM_FRAMEWORK_PATH

CMAKE_SYSTEM_APPBUNDLE_PATH

8、搜索由PATHS選項指定的路徑。這些路徑一般是硬編碼的參考路徑。

在Darwin或者支持OS X 框架的系統上,cmake變量CMAKE_FIND_FRAMEWORK可以用來設置爲空,或者下述值之一:

"FIRST" - 在標準庫或頭文件之前查找框架。在Darwin系統上這是默認選項。
"LAST" - 在標準庫或頭文件之後查找框架。
"ONLY" - 僅僅查找框架。
"NEVER" - 從不查找框架。

  在Darwin或者支持OS X Application Bundles的系統,cmake變量CMAKE_FIND_APPBUNDLE可以被設置爲空或者下面這些值中的一個:

"FIRST" - 在標準庫或頭文件之前查找application bundles。在Darwin系統上這是默認選項。
"LAST" - 在標準庫或頭文件之後查找application bundles。
"ONLY" - 僅僅查找application bundles。
"NEVER" - 從不查找application bundles。

CMake變量CMAKE_FIND_ROOT_PATH指定了一個或者多個優先於其他搜索路徑的搜索路徑。該變量能夠有效地重新定位在給定位置下進行搜索的根路徑。該變量默認爲空。當使用交叉編譯時,該變量十分有用:用該變量指向目標環境的根目錄,然後CMake將會在那裏查找。默認情況下,在CMAKE_FIND_ROOT_PATH中列出的路徑會首先被搜索,然後是“非根”路徑。該默認規則可以通過設置CMAKE_FIND_ROOT_PATH_MODE_LIBRARY做出調整。在每次調用該命令之前,都可以通過設置這個變量來手動覆蓋默認行爲。如果使用了NO_CMAKE_FIND_ROOT_PATH變量,那麼只有重定位的路徑會被搜索。

  默認的搜索順序的設計邏輯是按照使用時從最具體到最不具體。通過多次調用find_library命令以及NO_*選項,可以覆蓋工程的這個默認順序:

find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_library(<VAR> NAMES name)

  只要這些調用中的一個成功返回,結果變量就會被設置並且被存儲到cache中;這樣隨後的調用都不會再行搜索。如果那找到的庫是一個框架,VAR將會被設置爲指向框架“<完整路徑>/A.framework” 的完整路徑。當一個指向框架的完整路徑被用作一個庫文件,CMake將使用-framework A,以及-F<完整路徑>這兩個選項將框架連接到目標上。

  參見cmake_policy()命令的文檔中關於NO_POLICY_SCOPE選項討論。

CMD#32 : find_path 搜索包含某個文件的路徑

find_path(<VAR> name1 [path1 path2 ...])

  在多數情況下,使用上述的精簡命令格式就足夠了。它與命令find_path(<VAR> name1 [PATHS path1 path2 ...])等價。

複製代碼
find_path(
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
複製代碼

  該命令用於給定名字文件所在的路徑。一條名爲<VAR>的cache條目會被創建,並存儲該命令的執行結果。如果在某個路徑下發現了該文件,該結果會被存儲到該變量中;除非該變量被清除,該次搜索不會繼續進行。如果沒有找到,存儲的結果將會是<VAR>-NOTFOUND,並且當下一次以相同的變量名調用find_path命令時,該命令會再一次嘗試搜索該文件。需要搜索的文件名通過在NAMES選項後面的列出來的參數來確定。附加的搜索位置可以在PATHS選項之後指定。如果在PATHS或者HINTS命令中還指定了ENV var選項,環境變量var將會被讀取並從一個系統環境變量轉換爲一個cmake風格的路徑list。比如,ENV PATH是列出系統path變量的一種方法。參數DOC將用來作爲該變量在cache中的註釋。PATH_SUFFIXES指定了在每個搜索路徑下的附加子路徑。

  如果指定了NO_DEFAULT_PATH選項,那麼沒有其它附加的路徑會被加到搜索過程中。如果並未指定NO_DEFAULT_PATH選項,搜索的過程如下:

1、搜索cmake專有的cache變量中的路徑。這種用法是爲了在命令行中用選項-DVAR=value指定搜索路徑。如果指定了NO_CMAKE_PATH選項,該路徑會被跳過。搜索路徑還包括:

對於每個在CMAKE_PREFIX_PATH中的<prefix>/,路徑<prefix>/include

CMAKE_INCLUDE_PATH
CMAKE_FRAMEWORK_PATH

2、搜索cmake專有的環境變量中指定的路徑。這種用法是爲了在用戶的shell配置中設置指定的搜索路徑。如果指定了NO_CMAKE_ENVIRONMENT_PATH選項,該路徑會被跳過。搜索路徑還包括:

對於每個在CMAKE_PREFIX_PATH中的<prefix>/,路徑<prefix>/include

CMAKE_INCLUDE_PATH
CMAKE_FRAMEWORK_PATH

3、搜索由HINTS選項指定的路徑。這些路徑應該是由系統內省時計算得出的路徑,比如由其它已經發現的項目提供的線索。硬編碼的參考路徑應該在PATHS選項中指定。

4、搜索標準的系統環境變量。通過指定選項NO_SYSTEM_ENVIRONMENT_PATH可以跳過搜索環境變量。搜索的路徑還包括:

PATH
INCLUDE

5、查找在爲當前系統的平臺文件中定義的cmake變量。如果指定了NO_CMAKE_SYSTEM_PATH選項,該路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_SYSTEM_PREFIX_PATH中的<prefix>,路徑<prefix>/include

CMAKE_SYSTEM_LIBRARY_PATH
CMAKE_SYSTEM_FRAMEWORK_PATH

6、搜索PATHS選項或者精簡版命令指定的路徑。這些通常是硬編碼的推薦搜索路徑。

  在Darwin或者支持OS X 框架的系統上,cmake變量CMAKE_FIND_FRAMEWORK可以用來設置爲空,或者下述值之一:

"FIRST" - 在標準庫或頭文件之前查找框架。在Darwin系統上這是默認選項。
"LAST" - 在標準庫或頭文件之後查找框架。
"ONLY" - 僅僅查找框架。
"NEVER" - 從不查找框架。

  在Darwin或者支持OS X Application Bundles的系統,cmake變量CMAKE_FIND_APPBUNDLE可以被設置爲空或者下面這些值中的一個:

"FIRST" - 在標準庫或頭文件之前查找application bundles。在Darwin系統上這是默認選項。
"LAST" - 在標準庫或頭文件之後查找application bundles。
"ONLY" - 僅僅查找application bundles。
"NEVER" - 從不查找application bundles。

CMake變量CMAKE_FIND_ROOT_PATH指定了一個或者多個優先於其他搜索路徑的搜索路徑。該變量能夠有效地重新定位在給定位置下進行搜索的根路徑。該變量默認爲空。當使用交叉編譯時,該變量十分有用:用該變量指向目標環境的根目錄,然後CMake將會在那裏查找。默認情況下,在CMAKE_FIND_ROOT_PATH中列出的路徑會首先被搜索,然後是“非根”路徑。該默認規則可以通過設置CMAKE_FIND_ROOT_PATH_MODE_LIBRARY做出調整。在每次調用該命令之前,都可以通過設置這個變量來手動覆蓋默認行爲。如果使用了NO_CMAKE_FIND_ROOT_PATH變量,那麼只有重定位的路徑會被搜索。

  默認的搜索順序的設計邏輯是按照使用時從最具體到最不具體的路徑。通過多次調用find_path命令以及NO_*選項,可以覆蓋工程的這個默認順序:

find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_path(<VAR> NAMES name)

  只要這些調用中的一個成功返回,結果變量就會被設置並且被存儲到cache中;這樣隨後的調用都不會再行搜索。在搜索框架時,如果以A/b.h的格式指定文件,那麼該框架搜索過程會搜索A.framework/Headers/b.h。如果找到了該路徑,它將會被設置爲框架的路徑。CMake將把它轉換爲正確的-F選項來包含該文件。

CMD#33:find_program 查找可執行程序

find_program(<VAR> name1 [path1 path2 ...])

  這是該命令的精簡格式,它在大多數場合下都夠用了。命令find_program(<VAR> name1 [PATHS path1 path2 ...])是它的等價形式。

複製代碼
find_program(
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
複製代碼

  該命令用於查找程序。一個名爲<VAR>的cache條目會被創建用來存儲該命令的結果。如果該程序被找到了,結果會存儲在該變量中,搜索過程將不會再重複,除非該變量被清除。如果沒有找到,結果將會是<VAR>-NOTFOUND,並且下次以相同的變量調用該命令時,還會做搜索的嘗試。被搜索的程序的名字由NAMES選項後列出的參數指定。附加的搜索位置可以在PATHS參數後指定。如果在HINTS或者PATHS選項後有ENV var參數,環境變量var將會被讀取並從系統環境變量轉換爲cmake風格的路徑list。比如ENV PATH是一種列出所有系統path變量的方法。DOC後的參數將會被用作cache中的註釋字符串。PATH_SUFFIXES指定了在每個搜索路徑下要檢查的附加子路徑。

  如果指定了NO_DEFAULT_PATH選項,那麼搜索的過程中不會有其他的附加路徑。如果沒有指定該選項,搜索過程如下:

1、搜索cmake特有的cache變量指定的路徑。這些變量是在用cmake命令行時,通過-DVAR=value指定的變量。如果指定了NO_CMAKE_PATH選項,這些路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_PREFIX_PATH中的<prefix>,路徑<prefix>/[s]bin

CMAKE_PROGRAM_PATH
CMAKE_APPBUNDLE_PATH

2、搜索cmake特有的環境變量指定的路徑。這些變量是用戶的shell配置中設置的變量。如果指定了NO_CMAKE_ENVIRONMENT_PATH選項,這些路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_PREFIX_PATH中的<prefix>,路徑<prefix>/[s]bin

CMAKE_PROGRAM_PATH
CMAKE_APPBUNDLE_PATH

3、搜索由HINTS選項指定的路徑。這些路徑是系統內省(introspection)估算出的路徑,比如由另一個已經發現的程序的地址提供的參考信息。硬編碼的推薦路徑應該通過PATHS選項指定。

4、查找標準的系統環境變量。如果指定了NO_SYSTEM_ENVIRONMENT_PATH選項,這些路徑會被跳過。搜索的路徑還包括:

PATH

5、查找在爲當前系統的平臺文件中定義的cmake變量。如果指定了NO_CMAKE_SYSTEM_PATH選項,該路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_SYSTEM_PREFIX_PATH中的<prefix>,路徑<prefix>/[s]bin

CMAKE_SYSTEM_PROGRAM_PATH
CMAKE_SYSTEM_APPBUNDLE_PATH

6、搜索PATHS選項或者精簡版命令指定的路徑。這些通常是硬編碼的推薦搜索路徑。

  在Darwin或者支持OS X 框架的系統上,cmake變量CMAKE_FIND_FRAMEWORK可以設置爲空,或者下述值之一:

"FIRST" - 在標準庫或頭文件之前查找框架。在Darwin系統上這是默認選項。
"LAST" - 在標準庫或頭文件之後查找框架。
"ONLY" - 僅僅查找框架。
"NEVER" - 從不查找框架。

  在Darwin或者支持OS X Application Bundles的系統,cmake變量CMAKE_FIND_APPBUNDLE可以被設置爲空或者下面這些值中的一個:

"FIRST" - 在標準程序之前查找application bundles。在Darwin系統上這是默認選項。
"LAST" - 在標準程序之後查找application bundles。
"ONLY" - 僅僅查找application bundles。
"NEVER" - 從不查找application bundles。

CMake變量CMAKE_FIND_ROOT_PATH指定了一個或者多個優先於其他搜索路徑的搜索路徑。該變量能夠有效地重新定位在給定位置下進行搜索的根路徑。該變量默認爲空。當使用交叉編譯時,該變量十分有用:用該變量指向目標環境的根目錄,然後CMake將會在那裏查找。默認情況下,在CMAKE_FIND_ROOT_PATH中列出的路徑會首先被搜索,然後是“非根”路徑。該默認規則可以通過設置CMAKE_FIND_ROOT_PATH_MODE_LIBRARY做出調整。在每次調用該命令之前,都可以通過設置這個變量來手動覆蓋默認行爲。如果使用了NO_CMAKE_FIND_ROOT_PATH變量,那麼只有重定位的路徑會被搜索。

  默認的搜索順序的設計邏輯是按照使用時從最具體到最不具體。通過多次以NO_*選項調用find_program命令,可以覆蓋工程的這個默認順序:

find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_library(<VAR> NAMES name)

  只要這些調用中的一個成功返回,結果變量就會被設置並且被存儲到cache中;這樣隨後的調用都不會再行搜索。

CMD#34:fltk_wrap_ui 創建FLTK用戶界面包裝器。

fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )

  爲所有列出的.fl和.fld文件生成.h和.cxx文件。這些生成的.h和.cxx文件將會加到變量resultingLibraryName_FLTK_UI_SRCS中,它也會加到你的庫中。

CMD#33:find_program 查找可執行程序

find_program(<VAR> name1 [path1 path2 ...])

  這是該命令的精簡格式,它在大多數場合下都夠用了。命令find_program(<VAR> name1 [PATHS path1 path2 ...])是它的等價形式。

複製代碼
find_program(
<VAR>
name | NAMES name1 [name2 ...]
[HINTS path1 [path2 ... ENV var]]
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
複製代碼

  該命令用於查找程序。一個名爲<VAR>的cache條目會被創建用來存儲該命令的結果。如果該程序被找到了,結果會存儲在該變量中,搜索過程將不會再重複,除非該變量被清除。如果沒有找到,結果將會是<VAR>-NOTFOUND,並且下次以相同的變量調用該命令時,還會做搜索的嘗試。被搜索的程序的名字由NAMES選項後列出的參數指定。附加的搜索位置可以在PATHS參數後指定。如果在HINTS或者PATHS選項後有ENV var參數,環境變量var將會被讀取並從系統環境變量轉換爲cmake風格的路徑list。比如ENV PATH是一種列出所有系統path變量的方法。DOC後的參數將會被用作cache中的註釋字符串。PATH_SUFFIXES指定了在每個搜索路徑下要檢查的附加子路徑。

  如果指定了NO_DEFAULT_PATH選項,那麼搜索的過程中不會有其他的附加路徑。如果沒有指定該選項,搜索過程如下:

1、搜索cmake特有的cache變量指定的路徑。這些變量是在用cmake命令行時,通過-DVAR=value指定的變量。如果指定了NO_CMAKE_PATH選項,這些路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_PREFIX_PATH中的<prefix>,路徑<prefix>/[s]bin

CMAKE_PROGRAM_PATH
CMAKE_APPBUNDLE_PATH

2、搜索cmake特有的環境變量指定的路徑。這些變量是用戶的shell配置中設置的變量。如果指定了NO_CMAKE_ENVIRONMENT_PATH選項,這些路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_PREFIX_PATH中的<prefix>,路徑<prefix>/[s]bin

CMAKE_PROGRAM_PATH
CMAKE_APPBUNDLE_PATH

3、搜索由HINTS選項指定的路徑。這些路徑是系統內省(introspection)估算出的路徑,比如由另一個已經發現的程序的地址提供的參考信息。硬編碼的推薦路徑應該通過PATHS選項指定。

4、查找標準的系統環境變量。如果指定了NO_SYSTEM_ENVIRONMENT_PATH選項,這些路徑會被跳過。搜索的路徑還包括:

PATH

5、查找在爲當前系統的平臺文件中定義的cmake變量。如果指定了NO_CMAKE_SYSTEM_PATH選項,該路徑會被跳過。搜索的路徑還包括:

對於每個在CMAKE_SYSTEM_PREFIX_PATH中的<prefix>,路徑<prefix>/[s]bin

CMAKE_SYSTEM_PROGRAM_PATH
CMAKE_SYSTEM_APPBUNDLE_PATH

6、搜索PATHS選項或者精簡版命令指定的路徑。這些通常是硬編碼的推薦搜索路徑。

  在Darwin或者支持OS X 框架的系統上,cmake變量CMAKE_FIND_FRAMEWORK可以設置爲空,或者下述值之一:

"FIRST" - 在標準庫或頭文件之前查找框架。在Darwin系統上這是默認選項。
"LAST" - 在標準庫或頭文件之後查找框架。
"ONLY" - 僅僅查找框架。
"NEVER" - 從不查找框架。

  在Darwin或者支持OS X Application Bundles的系統,cmake變量CMAKE_FIND_APPBUNDLE可以被設置爲空或者下面這些值中的一個:

"FIRST" - 在標準程序之前查找application bundles。在Darwin系統上這是默認選項。
"LAST" - 在標準程序之後查找application bundles。
"ONLY" - 僅僅查找application bundles。
"NEVER" - 從不查找application bundles。

CMake變量CMAKE_FIND_ROOT_PATH指定了一個或者多個優先於其他搜索路徑的搜索路徑。該變量能夠有效地重新定位在給定位置下進行搜索的根路徑。該變量默認爲空。當使用交叉編譯時,該變量十分有用:用該變量指向目標環境的根目錄,然後CMake將會在那裏查找。默認情況下,在CMAKE_FIND_ROOT_PATH中列出的路徑會首先被搜索,然後是“非根”路徑。該默認規則可以通過設置CMAKE_FIND_ROOT_PATH_MODE_LIBRARY做出調整。在每次調用該命令之前,都可以通過設置這個變量來手動覆蓋默認行爲。如果使用了NO_CMAKE_FIND_ROOT_PATH變量,那麼只有重定位的路徑會被搜索。

  默認的搜索順序的設計邏輯是按照使用時從最具體到最不具體。通過多次以NO_*選項調用find_program命令,可以覆蓋工程的這個默認順序:

find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_library(<VAR> NAMES name)

  只要這些調用中的一個成功返回,結果變量就會被設置並且被存儲到cache中;這樣隨後的調用都不會再行搜索。

CMD#34:fltk_wrap_ui 創建FLTK用戶界面包裝器。

fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )

  爲所有列出的.fl和.fld文件生成.h和.cxx文件。這些生成的.h和.cxx文件將會加到變量resultingLibraryName_FLTK_UI_SRCS中,它也會加到你的庫中。

CMD#35 : foreach 對一個list中的每一個變量執行一組命令。

foreach(loop_var arg1 arg2 ...)
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endforeach(loop_var)

  所有的foreach和與之匹配的endforeach命令之間的命令會被記錄下來而不會被調用。等到遇到endforeach命令時,先前被記錄下來的命令列表中的每條命令都會爲list中的每個變量調用一遍。在每次迭代中,循環變量${loop_var}將會被設置爲list中的當前變量值。

foreach(loop_var RANGE total)
foreach(loop_var RANGE start stop [step])

foreach命令也可以遍歷一個人爲生成的數據區間。遍歷的方式有三種:

*如果指定了一個數字,區間是[0, total]。

*如果指定了兩個數字,區間將會是第一個數字到第二個數字。

*第三個數字是從第一個數字遍歷到第二個數字時的步長。

foreach(loop_var IN [LISTS [list1 [...]]]
[ITEMS [item1 [...]]])

  該命令的含義是:精確遍歷一個項組成的list。LISTS選項後面是需要被遍歷的list變量的名字,包括空元素(一個空字符串是一個零長度list)。ITEMS選項結束了list參數的解析,然後在迭代中引入所有在其後出現的項。(猜測是用list1中的項item1,依次類推,爲循環變量賦值。)

CMD#36 : function 開始記錄一個函數,爲以後以命令的方式調用它做準備。

function(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endfunction(<name>)

  定義一個名爲<name>的函數,它以arg1 arg2 arg3 (...)爲參數。在function之後,對應的endfunction之前列出的命令,在函數被調用之前,是不會被調用的。當函數被調用時,在函數中記錄的那些命令首先會用傳進去的參數替換掉形參(${arg1});然後跟正常命令一樣去調用這些命令。除了形參,你還可以引用這些變量:ARGC爲傳遞給函數的變量個數,ARGV0 ARGV1 ARGV2 ...表示傳到函數中的實參值。這些變量爲編寫可選參數函數提供了便利。此外,ARGV保留了一個該函數所有實參的list,ARGN保留了函數形參列表以後的所有參數列表。

  參見cmake_policy()命令文檔中function內部策略行爲的相關行爲。

CMD#37 : get_cmake_property 獲取一個CMake實例的屬性。

get_cmake_property(VAR property)

  從指定的CMake實例中獲取屬性。屬性的值存儲在變量VAR中。如果屬性不存在,CMake會報錯。一些會被支持的屬性包括:VATIABLES,COMMANDS,MACROS以及COMPONENTS。

CMD#38 : get_directory_property 獲取DIRECTORY域中的某種屬性。

get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)

  在指定的變量中存儲路徑(directory)域中的某種屬性。如果該屬性沒有被定義,將會返回空字符串。DIRECTORY參數指定了要取出的屬性值的另一個路徑。指定的路徑必須已經被CMake遍歷過了。

get_directory_property(<variable> [DIRECTORY <dir>]
                         DEFINITION <var-name>)

  該命令從一個路徑中獲取一個變量的定義。這種格式在從另一個路徑中獲取變量的定義時比較有用。

CMD#39 : get_filename_component 得到一個完整文件名中的特定部分。

get_filename_component(<VAR> FileName
PATH|ABSOLUTE|NAME|EXT|NAME_WE|REALPATH
[CACHE])

  將變量<VAR>設置爲路徑(PATH),文件名(NAME),文件擴展名(EXT),去掉擴展名的文件名(NAME_WE),完整路徑(ABSOLUTE),或者所有符號鏈接被解析出的完整路徑(REALPATH)。注意,路徑會被轉換爲Unix的反斜槓(/),並且沒有結尾的反斜槓。該命令已經考慮了最長的文件擴展名。如果指定了CACHE選項,得到的變量會被加到cache中。

get_filename_component(<VAR> FileName
PROGRAM [PROGRAM_ARGS <ARG_VAR>]
[CACHE])

  在FileName中的程序將會在系統搜索路徑中被查找,或者是一個完整路徑。如果與PRPGRAM一起給定了PROGRAM_ARGS選項,那麼任何在Filename字符串中出現的命令行中選項將會從程序名中分割出來並存儲在變量<ARG_VAR>中。這可以用來從一個命令行字符串中分離程序名及其選項。

CMD#40 : get_property 獲取一個屬性值

複製代碼
get_property(<variable>
<GLOBAL |
DIRECTORY [dir] |
TARGET <target> |
SOURCE <source> |
TEST <test> |
CACHE <entry> |
VARIABLE>
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
複製代碼

  獲取在某個域中一個對象的某種屬性值。第一個參數指定了存儲屬性值的變量。第二個參數確定了獲取該屬性的域。域的選項僅限於:

GLOBAL 域是唯一的,它不接受域名字。

DIRECTORY域默認爲當前目錄,但是其他的路徑(已經被CMake處理過)可以以相對路徑或完整路徑的方式跟在該域後面。

TARGET域後面必須跟有一個已有的目標名。

SOURCE域後面必須跟有一個源文件名。

TEST域後面必須跟有一個已有的測試。

CACHE域後面必須跟有一個cache條目。

VARIABLE域是唯一的,它不接受域名字。

PROPERTY選項是必須的,它後面緊跟要獲取的屬性名。如果該屬性沒有被設置,該命令將返回空值。如果給定了SET選項,那麼返回值會被設置爲一個布爾值,用來指示該屬性是否被設置過。如果給定了DEFINED選項,那麼返回值會被設置爲一個布爾值,用來指示該屬性是否被類似於define_property的命令定義過。如果指定了BRIEF_DOCS或者FULL_DOCS選項,那麼該變量將會被設置爲被查詢屬性的文檔的字符串。如果被請求的屬性的文檔沒有被定義,將返回NOTFOUND。

CMD#41 : get_source_file_property 爲一個源文件獲取一種屬性值。

get_source_file_property(VAR file property)

  從一個源文件中獲取某種屬性值。這個屬性值存儲在變量VAR中。如果該屬性沒有被找到,VAR會被設置爲NOTFOUND。使用set_source_files_proterties命令來設置屬性值。源文件屬性通常用來控制文件如何被構建。一個必定存在的屬性是LOCATION。

CMD#42 : get_target_property 從一個目標中獲取一個屬性值。

get_target_property(VAR target property)

  從一個目標中獲取屬性值。屬性的值會被存儲在變量VAR中。如果該屬性沒有被發現,VAR會被設置爲NOTFOUND。使用set_target_properties命令來設置屬性值。屬性值一般用於控制如何去構建一個目標,但是有些屬性用來查詢目標的信息。該命令可以獲取當前已經被構建好的任意目標的屬性。該目標不一定存在於當前的CMakeLists.txt文件中。

CMD#43 : get_test_property 獲取一個測試的屬性。

get_test_property(test VAR property)

  從指定的測試中獲取某種屬性。屬性值會被存儲到變量VAR中。如果沒有找到該屬性,CMake將會報錯。你可以使用命令cmake --help-property-list來獲取標準屬性的清單。

CMD#44 : if 條件執行一組命令。

複製代碼
if(expression)
# then section.
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
elseif(expression2)
# elseif section.
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
else(expression)
# else section.
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endif(expression)
複製代碼

  評估給定的表達式。如果結果是true,在THEN段的命令就會被調用。否則,在ELSE區段的命令會被調用。ELSEIF和ELSE區段是可選的 。可以有多個ELSEIF子句。注意,在else和elseif子句中的表達式也是可選的。判斷條件可以用長表達式,並且表達式有約定的優先級順序。括號中的表達式會首先被調用;然後是一元運算符,比如EXISTS,COMMAND以及DEFINED;然後是EQUAL,LESS,GREATER,STRLESS,STRGREATER,STREQUAL,MATCHES;然後是NOT運算符,最後是AND,OR運算符。幾種可能的表達式是:

if(<常量>)

  如果<常量>是1,ON,YES,TRUE,Y或者非0數值,那麼表達式爲真;如果<常量>是0,OFF,NO,FALSE,N,IGNORE,"",或者以'-NOTFOUND'爲後綴,那麼表達式爲假。這些布爾常量值是大小寫無關的。

if(<變量>)

  如果<變量>的值不是一個false常量,表達式爲真。

if(NOT <表達式>)

  如果<表達式>的值是false的話,真個表達式爲真。

if(<表達式1> AND <表達式2>)

  如果兩個表達式都爲真,整個表達式爲真。

if(<表達式1> OR <表達式2>)

  只要有一個表達式爲真,整個表達式爲真。

if(COMMAND command-name)

  如果給出的名字是一個可以被調用的命令,宏,或者函數的話,整個表達式的值爲真。

if(POLICY policy-id)

  如果給出的名字是一個已有的策略(格式是CMP<NNNN>),表達式爲真。

if(TARGET 目標名)

  如果給出的名字是一個已有的構建目標或導入目標的話,表達式爲真。

if(EXISTS 文件名)

if(EXISTS 路徑名)

  如果給出的文件名或路徑名存在,表達式爲真。該命令只對完整路徑有效。

if(file1 IS_NEWER_THAN file2)

  如果file1比file2更新或者其中的一個文件不存在,那麼表達式爲真。該命令只對完整路徑有效。

if(IS_DIRECTORY directory-name)

  如果給定的名字是一個路徑,表達式返回真。該命令只對完整路徑有效。

if(IS_SYMLINK file-name)

  如果給定的名字十一個符號鏈接的話,表達式返回真。該命令只對完整路徑有效。

if(IS_ABSOLUTE path)

  如果給定的路徑是一個絕對路徑的話,表達式返回真。

if(variable MATCHES regex)

if(string MATCHES regex)

  如果給定的字串或變量值域給定的正則表達式匹配的話,表達式返回真。

複製代碼
if(variable LESS number)
if(string LESS number)
if(variable GREATER number)
if(string GREATER number)
if(variable EQUAL number)
if(string EQUAL number)
複製代碼

  如果給定的字串或變量值是一個有效的數字並且不等號或等號滿足的話,表達式返回真。

複製代碼
if(variable STRLESS string)
if(string STRLESS string)
if(variable STRGREATER string)
if(string STRGREATER string)
if(variable STREQUAL string)
if(string STREQUAL string)
複製代碼

  如果給定的字串或變量值依字典序小於(或者大於,或者等於)右邊給出的字串或變量值的話,表達式返回真。

if(version1 VERSION_LESS version2)
if(version1 VERSION_EQUAL version2)
if(version1 VERSION_GREATER version2)

  對版本號的各部分依次比較(版本號格式是major[.minor[.patch[.tweak]]])version1和version2的大小。

if(DEFINED variable)

  如果給定的變量被定義了的話,該表達式爲真。如果變量被設置了,它的值是真是假都無所謂。

if((expression) AND (expression OR (expression)))

  在小括號內的表達式會首先被計算,然後才按照先前介紹的運算來計算。有內嵌的括號時,最裏的括號會作爲包含它們的表達式的計算過程的一部分。IF語句在CMake的歷史上出現的相當早,它擁有一些需要特殊介紹的便捷特性。IF表達式只有在其中有一個單一的保留值的時候,纔會精簡操作(即不做變量展開);這些保留值包括:如果是大小寫無關的 ON,1, YES,TRUE,Y,它返回真;如果是OFF,0,NO,FALSE,N,NOTFOUND,*-NOTFOUND,IGNORE,它返回假。這種特性非常合理,它爲新作者提供了一種不需要精確匹配true或者false的便利性。這些值會被當做變量處理,即使它們沒有使用${}語法的時候,也會被解引用。這意味着,如果你寫下了這樣的語句:

if (boobah)

CMake將會把它當做你寫了

if (${boobah})

  來處理。類似地,如果你寫了

if (fubar AND sol)

CMake將會便捷地把它解釋爲

if ("${fubar}" AND "${sol}")

  上述兩例的後者確實是正確的書寫方式,但是前者也是可行的。if語句中只有某些操作有這種特殊的變量處理方式。這些特殊的語句包括:

對於MATCHES運算符,待匹配的左邊的參數首先被檢查,用來確認它是否是一個已經定義的變量;如果是,該變量的值會被使用,否則就會用它的原始值。

如果MATCHES運算符沒有左邊的參數,它返回false,但不產生錯誤。

LESS,GREATER,EQUAL運算符的左邊的參數和右邊的參數會被獨立測試,用來確認它們是否是被定義的變量;如果是,使用它們被定義的值,否則使用它們的原始值。

STRLESS,STRGREATER,STREQUAL運算符的左邊的參數和右邊的參數會被獨立測試,用來確認它們是否是被定義的變量;如果是,使用它們被定義的值,否則使用它們的原始值。

VERSIONLESS,VERSIONGREATER,VERSIONEQUAL運算符的左邊的參數和右邊的參數會被獨立測試,用來確認它們是否是被定義的變量;如果是,使用它們被定義的值,否則使用它們的原始值。

NOT運算符右邊的參數會被測試用來確定它是否是布爾常量,如果是,就用這個常量;否則它會被當做一個變量然後被解引用。

AND和OR運算符的左邊的參數和右邊的參數會被獨立測試,用來確認它們是否是布爾常量;如果是,就用這個常量,否則它們會被當做變量然後被解引用。

CMD#45 : include 從給定的文件中讀取CMake的列表文件。

include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
[NO_POLICY_SCOPE])

從給定的文件中讀取CMake的清單文件代碼。在清單文件中的命令會被立即處理,就像它們是寫在這條include命令展開的地方一樣。如果指定了OPTIONAL選項,那麼如果被包含文件不存在的話,不會報錯。如果指定了RESULT_VARIABLE選項,那麼var或者會被設置爲被包含文件的完整路徑,或者是NOTFOUND,表示沒有找到該文件。

  如果指定的是一個模塊(module)而不是一個文件,查找的對象會變成路徑CMAKE_MODULE_PATH下的文件<modulename>.camke。

  參考cmake_policy()命令文檔中關於NO_POLICY_SCOPE選項的討論。

CMD#46 : include_directories 爲構建樹添加包含路徑。

include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)

  將給定的路徑添加到編譯器搜索包含文件(.h文件)的路徑列表中。缺省情況下,該路徑會被附加在當前路徑列表的後面。這種缺省行爲可以通過設置CMAKE_include_directories_BEFORE變量爲ON被改變。通過將該變量改變爲BEFORE或AFTER,你可以在追加和附加在前端這兩種方式中選擇,而不用理會缺省設置。如果指定了SYSTEM選項,編譯器將會認爲該路徑是某種平臺上的系統包含路徑。

CMD#47 : include_external_msproject 在一個workspace中包含一個外部的Microsoft工程。

include_external_msproject(projectname location dep1 dep2 ...)

  在生成的workspace文件中包含一個外部的Microsoft工程。它會創建一個名爲[projectname]的目標。這個目標可以用在add_dependencies命令中讓其他工程依賴於這個外部工程。當前版本下,該命令在UNIX平臺上不會做任何事情。

CMD#48 : include_regular_expression 設置用於依賴性檢查的正則表達式。

include_regular_expression(regex_match [regex_complain])

  設置依賴性檢查的正則表達式。這有匹配正則表達式regex_match的文件會成爲依賴性跟蹤的對象。只有匹配regex_complain的文件,在找不到它們的時候纔會給出警告(標準頭文件不會被搜索)。正則表達式的默認值是:

regex_match = "^.*$" (匹配所有文件)

regex_complain = "^$" (僅匹配空字符串)

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命令那樣解釋爲相對於當前源路徑的相對路徑。)

CMD#51: list列表操作命令。

複製代碼
list(LENGTH <list> <output variable>)
list(GET <list> <element index> [<element index> ...] <output variable>)
list(APPEND <list> <element> [<element> ...])
list(FIND <list> <value> <output variable>)
list(INSERT <list> <element_index> <element> [<element> ...])
list(REMOVE_ITEM <list> <value> [<value> ...])
list(REMOVE_AT <list> <index> [<index> ...])
list(REMOVE_DUPLICATES <list>)
list(REVERSE <list>)
list(SORT <list>)
複製代碼

  使用LENGTH選項時,該命令會返回給定list的長度。

  使用GET選項時,該命令返回list中所有被index索引的元素構成的list。

  使用APPEND選項時,該命令將會在該list之後追加若干元素。

  使用FIND選項時,該命令將返回list中指定的元素的索引;若果未找到,返回-1。

  使用INSERT選項時,該命令將在list中指定的位置插入若干元素。

  使用REMOVE_AT和REMOVE_ITEM選項將會從list中刪除一些元素。它們之間的區別是:REMOVE_ITEM刪除的是指定的項,而REMOVE_AT刪除的是在指定索引處的項。

  使用REMOVE_DUPLICATES選項時,該命令將刪除list中的重複項。

  使用REVERSE選項時,該命令將把list的內容就地前後倒換。

  使用SORT選項時,該命令將按字母序對list總的內容就地排序。

  注意:在CMake中,一個list是一個由封號;分割的一組字符串。使用set命令可以創建一個list。例如,set(var a b c d e)命令將會創建一個list:a;b;c;d;e;而set(var "a b c d e")命令創建的只是一個字符串,或者說是隻有一個項的list。

  當使用指定索引的命令格式時,如果<element index>是大於等於0的數,<element index>是從list第一個項開始的序號,list的第一項的索引是0。如果<element index>小於等於-1,這個索引是從結尾開始的逆向索引,其中-1表示的是list的最後一項。當使用負數索引時,注意它們不是從0開始!-0與0等價,它指向list的第一個成員。

CMD#52:load_cache 從另一個工程的CMake cache中加載值。

load_cache(pathToCacheFile READ_WITH_PREFIX
prefix entry1...)

  該命令讀取指定的cache文件,並將以請求的前綴爲其前綴的那些cache文件中的entry(ies)保存到變量中。這個格式僅僅讀取值,但是不在本地工程的cache中創建entry(ies)。

load_cache(pathToCacheFile [EXCLUDE entry1...]
[INCLUDE_INTERNALS entry1...])

  從另一個cache文件中加載值並像內部entry(ies)那樣,將它們存儲到本地工程的cache中。這條命令對於一個依賴於另一個不同構建樹上的另一個工程的工程比較有用。EXCLUDE選項給出了那些需要排除在外的entry(ies)的一個list。INCLUDE_INTERNALS選項給出了需要包含的entry(ies)的內部entry(ies)的一個list。通常情況下,不需要引入內部entry(ies)。強烈不推薦使用該命令的這種格式,但是它可以被用來維持向後兼容性。

CMD#53:load_command 將一條命令加載到一個運行中的CMake。

load_command(COMMAND_NAME <loc1> [loc2 ...])

  該命令將在給定的路徑下查找名字爲cmCOMMAND_NAME的一個庫。如果找到了,它將會以模塊的方式被加載,然後該命令將會被添加到可用的CMake命令集中。通常,TRY_COMPILE選項被用在這個命令之前來編譯這個模塊。如果該命令被成功加載,一個名爲CMAKE_LOADED_COMMAND_<COMMAND_NAME>的變量將會被設置爲這個加載模塊的完整路徑。否則,這個變量就不會被設置。

CMD#54:macro 爲後續以命令方式調用而開始記錄一組宏。

macro(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endmacro(<name>)

  定義一個名爲<name>的宏,它以arg1 arg2 arg3 (...)爲參數。在macro命令之後,在與之配對的endmacro命令之前出現的命令,只有在宏被調用的時候纔會被調用。當被調用的時候,這些被記錄的命令首先以傳進來的實參替換掉形參(如${arg1}),然後像正常的命令那樣執行。除了形參之外,你還可以引用變量${ARGC},它表示傳遞到宏裏的參數的數量;${ARG0}, ${ARG1}, ${ARG2} ...等等則是傳進來的實參值。這些變量使得創建帶可選參數的宏變得很便捷。此外,變量${ARGV}保留了所有傳遞到宏裏的所有參數組成的一個list,變量${ARGN}保留了在最後一個形參之後的參數組成的一個list。注意:傳遞到宏內部的參數和值,比如ARGN不是CMake通常意義下的變量;它們只是字符串替換,這一點非常像C預處理器對C語言宏的處理過程。如果你想要用真正的CMake變量,你應該查看一下function命令的說明。

  關於在macro內部的策略的行爲,參見cmake_policy()命令的相關文檔。

CMD#55:mark_as_advanced 將CMake 的緩存變量標記爲高級。

mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)

  將緩存的變量標記爲高級變量。其中,高級變量指的是那些在cmake GUI中,只有當“顯示高級選項”被打開時纔會被顯示的變量。如果CLEAR是第一個選項,參數中的高級變量將變回非高級變量。如果FORCE是第一個選項,參數中的變量會被提升爲高級變量。如果兩者都未出現,新的變量會被標記爲高級變量;如果這個變量已經是高級/非高級狀態的話,它將會維持原狀。

  該命令在腳本中無效。

CMD#56:math 數學表達式。

math(EXPR <output variable> <math expression>)

EXPR計算數學表達式然後通過output變量返回計算結果。數學表達式的一個例子是"5*(10+13)"。該命令支持的運算符包括:+ - * / % ^ ~ << >> ;它們的含義與C語言中的完全一致。

CMD#57:message 爲用戶顯示一條消息。

message([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
"message to display" ...)

  可以用下述可選的關鍵字指定消息的類型:

(無) = 重要消息;
STATUS = 非重要消息;
WARNING = CMake 警告, 會繼續執行;
AUTHOR_WARNING = CMake 警告 (dev), 會繼續執行;
SEND_ERROR = CMake 錯誤, 繼續執行,但是會跳過生成的步驟;
FATAL_ERROR = CMake 錯誤, 終止所有處理過程;

CMake的命令行工具會在stdout上顯示STATUS消息,在stderr上顯示其他所有消息。CMake的GUI會在它的log區域顯示所有消息。交互式的對話框(ccmake和CMakeSetup)將會在狀態行上一次顯示一條STATUS消息,而其他格式的消息會出現在交互式的彈出式對話框中。

CMake警告和錯誤消息的文本顯示使用的是一種簡單的標記語言。文本沒有縮進,超過長度的行會回捲,段落之間以新行做爲分隔符。

CMD#58: option 爲用戶提供一個可選項。

option(<option_variable> "描述選項的幫助性文字" [initial value])

  該命令爲用戶提供了一個在ON和OFF中做出選擇的選項。如果沒有指定初始值,將會使用OFF作爲初值。如果有些選項依賴於其他選項的值,參見CMakeDependentOption模塊的幫助文件。

CMD#59: output_required_files 輸出一個list,其中包含了一個給定源文件所需要的其他源文件。

output_required_files(srcfile outputfile)

  輸出一個指定的源文件所需要的所有源文件的list。這個list會寫到outputfile變量中。該命令的功能是將srcfile的依賴性寫出到outputfile中,不過該命令將儘可能地跳過.h文件,搜索依賴中的.cxx,.c和.cpp文件。

CMD#60: project 爲整個工程設置一個工程名。

project(<projectname> [languageName1 languageName2 ... ] )

  爲本工程設置一個工程名。而且,該命令還將變量<projectName>_BINARY_DIR和<projectName>_SOURCE_DIR設置爲對應值。後面的可選項還可以讓你指定你的工程可以支持的語言。比如CXX(即C++),C,Fortran,等等。在默認條件下,支持C和CXX語言。例如,如果你沒有C++編譯器,你可以通過列出你想要支持的語言,例如C,來明確地禁止對它的檢查。使用特殊語言"NONE",針對任何語言的檢查都會被禁止。

CMD#61: qt_wrap_cpp 創建Qt包裹器。

qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)

  爲所有在SourceLists中列出的.h文件生成moc文件。這些moc文件將會被添加到那些使用DestName源文件列表的庫文件中。

Produce moc files for all the .h files listed in the SourceLists. The moc files will be added to the library using the DestName source list.

CMD#62: qt_wrap_ui 創建Qt的UI包裹器。

qt_wrap_ui(resultingLibraryName HeadersDestName SourcesDestName SourceLists ...)

  爲所有在SourceLists中列出的.ui文件生成.h和.cxx文件。這些.h文件會被添加到使用HeadersDestNamesource列表的庫中。這些.cxx文件會被添加到使用SourcesDestNamesource列表的庫中。

CMD#63: remove_definitions 取消由add_definitions命令添加的-D定義標誌。

remove_definitions(-DFOO -DBAR ...)

  在當前及以下的路徑,從編譯命令行中取消(由add_definitions命令添加的)標誌。

CMD#64: return 從一個文件,路徑或函數內返回。

return()

  從一個文件,路徑或函數中返回。若出現在一個include文件裏(經由include()或find_package()命令),該命令會導致當前文件的處理過程停止,並且將控制權轉移到試圖包含它的文件中。若出現在一個不被任何文件包含的文件中,例如,一個CMakeLists.txt中,那麼該命令將控制權轉移到父目錄下,如果存在這樣的父目錄的話。如果在一個函數中調用return函數,控制權會返回到該函數的調用函數那裏。注意,宏不是函數,它不會像函數那樣去處理return命令。

CMD#65: separate_arguments將空格分隔的參數解析爲一個分號分隔的list。

separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")

  解析一個unix或者windows風格的命令行字符串"<args>",並將結果以分號分隔的list的形式存儲到<var>中。整個命令行都必須從這個"<args>"參數中給出。

UNIX_COMMAND模式以沒有被括起來的白字符爲參數的分隔符。它可以識別單引號和雙引號的引號對。反斜槓可以對下一個字符的字面值轉義(\",就是");沒有其他特殊的轉義字符(例如\n就是n)。

WINDOWS_COMMAND模式按照與運行時庫相同的語法解析一個windows命令行,在啓動(starrtup)時構造argv。它使用沒有被雙引號括起來的白字符來分隔參數。反斜槓維持其字面含義,除非它們在雙引號之前。更多細節,參見MSDN的文章:"Parsing C Command-Line Arguments"。

separate_arguments(VARIABLE)

  將VARIABLE的值轉換爲一個分號分隔的list。所有的空格會被替換爲';'。該命令可以用來輔助生成命令行。

CMD#66: set將一個CMAKE變量設置爲給定值。

set(<variable> <value> [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])

  將變量<variable>的值設置爲<value>。在<variable>被設置之前,<value>會被展開。如果有CACHE選項,那麼<variable>就會添加到cache中;這時<type>和<docstring>是必需的。<type>被CMake GUI用來選擇一個窗口,讓用戶設置值。<type>可以是下述值中的一個:

FILEPATH = 文件選擇對話框。
PATH = 路徑選擇對話框。
STRING = 任意的字符串。
BOOL = 布爾值選擇複選框。
INTERNAL = 不需要GUI輸入端。(適用於永久保存的變量)。

  如果<type>是內部的(INTERNAL),那麼<value>總是會被寫入到cache中,並替換任何已經存在於cache中的值。如果它不是一個cache變量,那麼這個變量總是會寫入到當前的makefile中。FORCE選項將覆蓋cache值,從而去掉任何用戶帶來的改變。

  如果指定了PARENT_SCOPE選項,變量<variable>將會被設置爲當前作用域之上的作用域中。每一個新的路徑或者函數都可以創建一個新作用域。該命令將會把一個變量的值設置到父路徑或者調用函數中(或者任何類似的可用的情形中。)

  如果沒有指定<value>,那麼這個變量就會被撤銷而不是被設置。另見:unset()命令。

set(<variable> <value1> ... <valueN>)

  在這種情形下,<variable>被設置爲一個各個值之間由分號分隔的list。

<variable>可以是環境變量,比如:

set( ENV{PATH} /home/martink )

  在這種情形下,環境變量將會被設置。

CMD#67: set_directory_properties 設置某個路徑的一種屬性。

set_directory_properties(PROPERTIES prop1 value1 prop2 value2)

  爲當前的路徑及其子路徑設置一種屬性。如果該屬性不存在,CMake將會報告一個錯誤。屬性包括:INCLUDE_DIRECTORIES, LINK_DIRECTORIES, INCLUDE_REGULAR_EXPRESSION, 以及ADDITIONAL_MAKE_CLEAN_FILES共四種。ADDITIONAL_MAKE_CLEAN_FILES是一個文件名的list,其中包含有"make clean"階段會被清除掉的文件。

CMD#68: set_property 在給定的作用域內設置一個命名的屬性。

複製代碼
set_property(<GLOBAL |
DIRECTORY [dir] |
TARGET [target1 [target2 ...]] |
SOURCE [src1 [src2 ...]] |
TEST [test1 [test2 ...]] |
CACHE [entry1 [entry2 ...]]>
[APPEND]
PROPERTY <name> [value1 [value2 ...]])
複製代碼

  爲作用域裏的0個或多個對象設置一種屬性。第一個參數決定了屬性可以影響到的作用域。他必須是下述值之一:GLOBAL,全局作用域,唯一,並且不接受名字。DIRECTORY,路徑作用域,默認爲當前路徑,但是也可以用全路徑或相對路徑指定其他值。TARGET,目標作用域,可以命名0個或多個已有的目標。SOURCE,源作用域,可以命名0個或多個源文件。注意,源文件屬性只對加到相同路徑(CMakeLists.txt)中的目標是可見的。TEST 測試作用域可以命名0個或多個已有的測試。CACHE作用域必須指定0個或多個cache中已有的條目。

PROPERTY選項是必須的,並且要緊跟在待設置的屬性的後面。剩餘的參數用來組成屬性值,該屬性值是一個以分號分隔的list。如果指定了APPEND選項,該list將會附加在已有的屬性值之後。

CMD#69: set_source_files_properties 源文件有一些屬性來可以改變它們構建的方式。

set_source_files_properties([file1 [file2 [...]]]
PROPERTIES prop1 value1
[prop2 value2 [...]])

  以鍵/值對的方式設置與源文件相關的那些屬性值。那些CMake中的源文件屬性,參見關於屬性的相關文檔。不能被識別的屬性將會被忽略。源文件屬性只對同一路徑(CMakeLists.txt)中添加的目標可見。

CMD#70: set_target_properties 設置目標的一些屬性來改變它們構建的方式。

set_target_properties(target1 target2 ...
PROPERTIES prop1 value1
prop2 value2 ...)

  爲一個目標設置屬性。該命令的語法是列出所有你想要變更的文件,然後提供你想要設置的值。你能夠使用任何你想要的屬性/值對,並且在隨後的代碼中調用GET_TARGET_PROPERTY命令取出屬性的值。

  影響一個目標輸出文件的名字的屬性詳述如下。PREFIX和SUFFIX屬性覆蓋了默認的目標名前綴(比如lib)和後綴(比如.so)。IMPORT_PREFIX和IMPORT_SUFFIX是與之等價的屬性,不過針對的是DLL(共享庫目標)的導入庫。在構建目標時,OUTPUT_NAME屬性設置目標的真實名字,並且可以用來輔助創建兩個具有相同名字的目標,即使CMake需要唯一的邏輯目標名。<CONFIG>_OUTPUT_NAME可以爲不同的配置設置輸出的目標名字。當目標在指定的配置名<CONFIG>(全部大寫,例如DEBUG_POSTFIX)下被構建時,<CONFIG>_POSTFIX爲目標的真實名字設置一個後綴。該屬性的值在目標創建時被初始化爲CMAKE_<CONFIG>_POSTFIX的值(可執行目標除外,因爲較早的CMake版本不會爲可執行文件使用這個屬性。)

LINK_FLAGS屬性可以用來爲一個目標的鏈接階段添加額外的標誌。LINK_FLAGS_<CONFIG>將爲配置<CONFIG>添加鏈接標誌,例如DEBUG,RELEASE,MINSIZEREL,RELWITHDEBINFO。DEFINE_SYMBOL屬性設置了編譯一個共享庫中的源文件時纔會被定義的預處理器符號名。如果這個值沒有被設置的話,那麼它會被設置爲默認值target_EXPORTS(如果目標不是一個合法的C標示符的話可以用一些替代標誌)。這對於檢測頭文件是包含在它們的庫以內還是以外很有幫助,從而可以合理設置dllexport/dllimport修飾符(注意,只有在編譯到的時候,這個符號纔會被定義;因此猜測在代碼中,判斷預處理符號是否被定義可以知道依賴庫是導入的還是導出的)。COMPILE_FLAGS屬性可以設置附加的編譯器標誌,它們會在構建目標內的源文件時被用到。它也可以用來傳遞附加的預處理器定義。

LINKER_LANGUAGE屬性用來改變鏈接可執行文件或共享庫的工具。默認的值是設置與庫中的文件相匹配的語言。CXX和C是這個屬性的公共值。

  對於共享庫,VERSION和SOVERSION屬性分別可以用來指定構建的版本號以及API版本號。當構建或者安裝時,如果平臺支持符號鏈接並且鏈接器支持so名字,那麼恰當的符號鏈接會被創建。如果只指定兩者中的一個,缺失的另一個假定爲具有相同的版本號。對於可執行文件,VERSION可以被用來指定構建版本號。當構建或者安裝時,如果該平臺支持符號鏈接,那麼合適的符號鏈接會被創建。對於在Windows系統而言,共享庫和可執行文件的VERSION屬性被解析成爲一個"major.minor"的版本號。這些版本號被用做該二進制文件的鏡像版本。

  還有一些屬性用來指定RPATH規則。INSTALL_RPATH是一個分號分隔的list,它指定了在安裝目標時使用的rpath(針對支持rpath的平臺而言)(-rpath在gcc中用於在編譯時指定加載動態庫的路徑;優先級較系統庫路徑要高。詳情參見http://www.cmake.org/Wiki/CMake_RPATH_handling#What_is_RPATH_.3F)。INSTALL_RPATH_USE_LINK_PATH是一個布爾值屬性,如果它被設置爲真,那麼在鏈接器的搜索路徑中以及工程之外的目錄會被附加到INSTALL_RPATH之後。SKIP_BUILD_RPATH是一個布爾值屬性,它指定了是否跳過一個rpath的自動生成過程,從而可以從構建樹開始運行。BUILD_WITH_INSTALL_RPATH是一個布爾值屬性,它指定了是否將在構建樹上的目標與INSTALL_RPATH鏈接。該屬性要優先於SKIP_BUILD_RPATH,因此避免了安裝之前的重新鏈接。INSTALL_NAME_DIR是一個字符串屬性,它用於在Mac OSX系統上,指定了被安裝的目標中使用的共享庫的"install_name"域的目錄部分。如果目標已經被創建,變量CMAKE_INSTALL_RPATH, CMAKE_INSTALL_RPATH_USE_LINK_PATH, CMAKE_SKIP_BUILD_RPATH, CMAKE_BUILD_WITH_INSTALL_RPATH和CMAKE_INSTALL_NAME_DIR的值會被用來初始化這個屬性。

PROJECT_LABEL屬性可以用來在IDE環境,比如visual studio,中改變目標的名字。 VS_KEYWORD可以用來改變visual studio的關鍵字,例如如果該選項被設置爲Qt4VSv1.0的話,QT集成將會運行得更好。

VS_SCC_PROJECTNAME, VS_SCC_LOCALPATH, VS_SCC_PROVIDER可以被設置,從而增加在一個VS工程文件中對源碼控制綁定的支持。

PRE_INSTALL_SCRIPT和POST_INSTALL_SCRIPT屬性是在安裝一個目標之前及之後指定運行CMake腳本的舊格式。只有當使用舊式的INSTALL_TARGETS來安裝目標時,才能使用這兩個屬性。使用INSTALL命令代替這種用法。

EXCLUDE_FROM_DEFAULT_BUILD屬性被visual studio生成器使用。如果屬性值設置爲1,那麼當你選擇"構建解決方案"時,目標將不會成爲默認構建的一部分。

CMD#71: set_tests_properties 設置若干個測試的屬性值。

set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)

  爲若干個測試設置一組屬性。若屬性未被發現,CMake將會報告一個錯誤。這組屬性包括:WILL_FAIL, 如果設置它爲true,那將會把這個測試的“通過測試/測試失敗”標誌反轉。PASS_REGULAR_EXPRESSION,如果它被設置,這個測試的輸出將會被檢測是否違背指定的正則表達式,並且至少要有一個正則表達式要匹配;否則測試將會失敗。

例子: PASS_REGULAR_EXPRESSION "TestPassed;All ok"

FAIL_REGULAR_EXPRESSION: 如果該屬性被設置,那麼只要輸出匹配給定的正則表達式中的一個,那麼測試失敗。

例子: PASS_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"

PASS_REGULAR_EXPRESSION和FAIL_REGULAR_EXPRESSION屬性都期望一個正則表達式列表(list)作爲其參數。

TIMEOUT: 設置該屬性將會限制測試的運行時長不超過指定的秒數。

CMD#72: site_name 將給定的變量設定爲計算機名。

site_name(variable)

CMD#73: source_group 爲Makefile中的源文件定義一個分組。

source_group(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])

  爲工程中的源文件中定義一個分組。這主要用來在Visual Studio中建立文件組按鈕(file tabs)。所有列出來的文件或者匹配正則表達式的文件都會被放到這個文件組中。如果一個文件匹配多個組,那麼最後明確地列出這個文件的組將會包含這個文件,如果有這樣的組的話。如果沒有任何組明確地列出這個文件,那麼最後那個其正則表達式與該文件名匹配的組,將會成爲最終候選者。

  組名中可以包含反斜槓,以指定子文件組:source_group(outer\\inner ...)

  爲了保持後向兼容性,這個命令也支持這種格式:source_group(name regex)

CMD#74: string 字符串操作函數。

複製代碼
string(REGEX MATCH <regular_expression> <output variable> <input> [<input>...])
string(REGEX MATCHALL <regular_expression> <output variable> <input> [<input>...])
string(REGEX REPLACE <regular_expression> <replace_expression> <output variable> <input> [<input>...])
string(REPLACE <match_string> <replace_string> <output variable> <input> [<input>...])
string(COMPARE EQUAL <string1> <string2> <output variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
string(COMPARE LESS <string1> <string2> <output variable>)
string(COMPARE GREATER <string1> <string2> <output variable>)
string(ASCII <number> [<number> ...] <output variable>)
string(CONFIGURE <string1> <output variable> [@ONLY] [ESCAPE_QUOTES])
string(TOUPPER <string1> <output variable>)
string(TOLOWER <string1> <output variable>)
string(LENGTH <string> <output variable>)
string(SUBSTRING <string> <begin> <length> <output variable>)
string(STRIP <string> <output variable>)
string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] [RANDOM_SEED <seed>] <output variable>)
複製代碼

REGEX MATCH : 匹配正則表達式一次,然後將匹配的值存儲到輸出變量中。

REGEX MATCHALL : 儘可能多次地匹配正則表達式,然後將匹配的值以list的形勢存儲到輸出變量中。

REGEX REPLACE : 儘可能多次地匹配正則表達式,並且將匹配的值用replacement expression 替換掉,然後存儲到輸出變量中。這個replace expression 可以引用包含匹配字符串的子表達式,這些匹配的字符串用圓括號隔開的\1,\2,...,\9等加以引用。注意:在CMake代碼裏,如果要使用一個反斜槓,必須要用兩個反斜槓(\\1)轉義,才能通過參數解析。

REPLACE : 將輸入字符串內所有出現match_string的地方都用replace_string代替,然後將結果存儲到輸出變量中。

COMPARE EQUAL/NOTEQUAL/LESS/GREATER : 將會比較兩個字符串,然後將比較的結果(true/false)存儲到輸出變量中。

ASCII : 將會把所有數字轉換爲對應的ASCII字符。

CONFIGURE : 將一個字符串進行變換,這種變換與將一個FILE變換爲CONFIGURE_FILE相似。

TOUPPER/TOLOWER : 將字符串轉換爲大寫/小寫字符。

LENGTH : 返回給定字符串的長度。

SUBSTRING : 返回給定字符串的子串。

STRIP : 返回一個給定字符串的子串,它會去掉原先字符串開始和結尾的空格。

RANDOM : 將會返回一個給定長度的隨機字符串,它由給定的字母表中的字母組成。默認的長度是5個字符,默認的字母表是全部的大小寫字母以及數字。如果指定了一個整數RANDOM_SEED,它的值將會被用做隨機數發生器的種子。

  在正則表達式中,下述字符有特殊含義:

^ 在行首匹配。
$ 在行尾匹配。
. 匹配任意單個字符。
[ ] 匹配在中括號中的任意字符。
[^ ] 匹配不在中括號中的任意字符。
- 匹配任意在短橫線兩端字符閉區間中間的任意一個字符。
* 匹配先前模式零次或多次。
+ 匹配先前模式一次或多次。
? 匹配先前模式零次或一次。
| 匹配|兩側的任意一種模式。
() 保存一個匹配的子表達式,這個子表達式後續可以在REGEX REPLACE操作中以\n的方式引用。 它也會被所有正則表達式相關的命令所保存;包括,比如,如果用到if( MATCHES )命令的話,這些匹配的值被保存在變量CMAKE_MATCH_(0..9)中。

CMD#75: target_link_libraries 將給定的庫鏈接到一個目標上。

target_link_libraries(<target> [item1 [item2 [...]]] [[debug|optimized|general] <item>] ...)

  爲給定的目標設置連接時使用的庫或者標誌(flags)。如果一個庫名字與工程中的另外一個目標相匹配,一個依賴關係會自動添加到構建系統中來,這樣就可以在鏈接目標之前,保證正在被鏈接的庫是最新的。以“-”開始,但不是“-l”或“-framework”的那些項,將會被當作鏈接器標誌來處理。

  關鍵字“debug”,“optimized”或者“general” 表示緊隨關鍵字之後的庫僅僅會被用到相應的構建配置上。“debug”關鍵字對應於調試配置(或者,如果全局屬性DEBUG_CONFIGURATIONS被設置的話,就是DEBUG_CONFIGURATIONS中的名字所指定的配置)。“optimized”關鍵字對應於所有其他的配置類型。“general”關鍵字對應於所有的配置,並且純粹是可選的(它是默認配置,可以省略)。通過創建並鏈接到導入庫目標,可以對每種配置規則進行更細緻的粒度控制。更多內容參見add_library命令的IMPORTED模式。

  默認時,庫之間的依賴性是可傳遞的。當這個目標被鏈接到其他目標上時,那麼鏈接到這個目標上的庫也會出現在其他目標的鏈接依賴上。參見LINK_INTERFACE_LIBRARIES屬性的相關文檔,其中有關於如何覆蓋一個目標的鏈接依賴性傳遞設置的介紹。

target_link_libraries(<target> LINK_INTERFACE_LIBRARIES [[debug|optimized|general] <lib>] ...)

  對於LINK_INTERFACE_LIBRARIES模式,它將會把庫附加在LINK_INTERFACE_LIBRARIES以及LINK_INTERFACE_LIBRARIES在不同配置下的等價目標屬性,而不是用這些庫去鏈接。指定爲“debug”的庫將會被附加到LINK_INTERFACE_LIBRARIES_DEBUG屬性(或者是在DEBUG_CONFIGURATIONS全局屬性中列出的配置,如果DEBUG_CONFIGURATIONS被設置的話)。指定爲“optimized”庫將會被附加到LINK_INTERFACE_LIBRARIES屬性上。指定爲“general”的庫(或者沒有任何關鍵字的庫),將會被當做即被指定爲“debug”又被指定爲“optimized”對待。

  庫之間的依賴圖通常是非循環圖(DAG),但是如果出現互相依賴的靜態庫,CMake會允許依賴圖中包含循環依賴(強連通分支)。當其它目標鏈接到這些庫中的一個時,CMake會重複整個連通分支。例如,代碼:

複製代碼
add_library(A STATIC a.c)

add_library(B STATIC b.c)

target_link_libraries(A B)

target_link_libraries(B A)

add_executable(main main.c)

target_link_libraries(main A)
複製代碼

將“main”鏈接到了“A B A B”。(雖然通常一次重複就足夠了,但是病態對象文件以及符號排布可能需要多次重複。你可以通過在上一次target_link_libraries調用中手動重複該分支來處理這種情況。不過,如果兩個歸檔文件確實是如此緊密的相互關聯,它們可能會被合併爲一個單一的歸檔文件。)

CMD#76: try_compile 嘗試編譯一些代碼。

try_compile(RESULT_VAR bindir srcdir
projectName <targetname> [CMAKE_FLAGS <Flags>]
[OUTPUT_VARIABLE var])

  嘗試編譯一個程序。在這種格式時,srcdir路徑下應該包含一個完整的CMake工程,包括CMakeLists.txt文件以及所有的源文件。在該命令運行完之後,路徑bindir和srcdir不會被刪除。如果指定了<target name>,那麼CMake將只構建那個目標;否則,目標all或ALL_BUILD將會被構建。

try_compile(RESULT_VAR bindir srcfile
[CMAKE_FLAGS <Flags>]
[COMPILE_DEFINITIONS <flags> ...]
[OUTPUT_VARIABLE var]
[COPY_FILE <filename> )

  嘗試編譯一個srcfile。在這種情況下,用戶僅僅需要提供源文件。CMake會創建合適的CMakeLists.txt文件來構建源文件。如果使用了COPY_FILE選項,編譯出的文件將會被拷貝到給定的文件那裏。

  在這個版本里,所有在bindir/CMakeFiles/CMakeTmp文件夾下的文件,將會被自動清除;通過向CMake傳遞調試選項--debug-trycompile可以避免這個清除步驟。另外一些可以包含的額外標誌有:INCLUDE_DIRECTORIES, LINK_DIRECTORIES, 和LINK_LIBRARIES。COMPILE_DEFINITIONS是通過-Ddefinations選項設置的預定義符號,這會傳遞到編譯器命令行。try_compile命令在構建過程中伴隨創建出的CMakeLists.txt看起來像這樣:

add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
include_directories(${INCLUDE_DIRECTORIES})
link_directories(${LINK_DIRECTORIES})
add_executable(cmTryCompileExec sources)
target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})

  在該命令的這兩種版本里,如果指定了OUTPUT_VARIABLE,那麼構建過程的輸出會存儲到給定的變量裏。編譯成功或失敗的結果,會通過RESULT_VAR返回。CMAKE_FLAGS可以用來向正在構建的CMake傳遞-DVAR:TYPE = VALUE 符號。

CMD#77: try_run 嘗試編譯並運行某些代碼。

複製代碼
try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
bindir srcfile [CMAKE_FLAGS <Flags>]
[COMPILE_DEFINITIONS <flags>]
[COMPILE_OUTPUT_VARIABLE comp]
[RUN_OUTPUT_VARIABLE run]
[OUTPUT_VARIABLE var]
[ARGS <arg1> <arg2>...])
複製代碼

  嘗試編譯一個源文件srcfile。通過變量COMPILE_RESULT_VAR返回TRUE或者FALSE來反應編譯是否失敗。如果構建出了可執行文件,但是不能運行,那麼RUN_RESULT_VAR會被設置爲FAILED_TO_RUN。COMPILE_OUTPUT_VARIABLE變量指定了一個變量,這個變量存儲了構建步驟輸出的信息。RUN_OUTPUT_VARIABLE指定了一個變量,這個變量存儲了運行可執行文件時的輸出。出於兼容性的考慮,OUTPUT_VARIABLE還會被支持,它包含了包含編譯和運行階段的輸出信息。

交叉編譯相關問題

  當運行交叉編譯時,第一步中編譯出的可執行文件通常不能在編譯宿主機上直接運行。try_run()函數會檢查CMAKE_CROSSCOMPILING變量來檢測CMake是否是交叉編譯模式。如果是的話,CMake還是會嘗試編譯可執行文件,但是它不會嘗試運行可執行文件。相反,他會創建一些cache變量,這些變量必須由用戶填充,或者在某個CMake腳本中預先設置爲那些在真實目標機平臺上執行的結果。這些變量有:RUN_RESULT_VAR (解釋參見上文),以及如果使用了RUN_OUTPUT_VARIABLE (或者OUTPUT_VARIABLE) ,還有一個附加的cache變量RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT。該變量是爲了保存執行過程中stdout和stderr的輸出。

  爲了讓交叉編譯更加容易些,必要時再使用try_run命令。如果你使用了try_run命令,那麼只有必要時才使用RUN_OUTPUT_VARIABLE(或者OUTPUT_VARIABLE)變量。在交叉編譯時,使用這些變量需要cache變量必須被手動設置爲可執行文件的輸出。你也可以用if(CMAKE_CROSSCOMPILING)將try_run的調用“保護”起來,同時還要爲這種情形給定一個易於預先設置的備選方案。

CMD#78 unset 撤銷對一個變量,cache變量或者環境變量的設置。

unset(<variable> [CACHE])

  刪除一個指定的變量,讓它變成未定義的。如果指定了CACHE選項,那麼這個變量將會從cache中刪除而不是當前作用域。<variable>可以是一個環境變量,比如:

unset(ENV{LD_LIBRARY_PATH})

在這個例子中,這個變量將會從當前的環境中被刪除。

CMD#79 : variable_watch 監視CMake變量的改變。

variable_watch(<variable name> [<command to execute>])

  如果給定的變量發生了變化,關於正在被改寫的變臉的消息會被打印出來。如果指定了command選項,這條命令會被執行。這條命令會接受這樣的參數:COMMAND(<variable> <access> <value> <current list file> <stack>)

CMD#80: while 當條件爲真時,評估(執行)一組命令。

while(condition)
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endwhile(condition)

  所有在while和與之配對的endwhile之間的命令將會被記錄,但並不會執行。只有當endwhile被評估,並且條件爲真時,這個命令列表的記錄纔會被調用。條件值的評估與if命令使用相同的邏輯。


發佈了13 篇原創文章 · 獲贊 23 · 訪問量 7萬+
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章