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中；然后該命令就不會再繼續查找了。