configure_file¶
複製檔案到另一個位置並修改其內容。
configure_file(<input> <output>
[NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
FILE_PERMISSIONS <permissions>...]
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF]])
複製 <input> 檔案到 <output> 檔案，同時對輸入檔案內容執行轉換。
如果輸入檔案被修改，建置系統將重新執行 CMake 以重新設定檔案並再次產生建置系統。只有在其內容變更時，產生的檔案才會在後續的 cmake 執行中被修改並更新其時間戳記。
選項¶
選項如下：
<input>輸入檔案的路徑。相對路徑會被視為相對於
CMAKE_CURRENT_SOURCE_DIR的值。輸入路徑必須是檔案，而非目錄。<output>輸出檔案或目錄的路徑。相對路徑會被視為相對於
CMAKE_CURRENT_BINARY_DIR的值。如果路徑名稱是現有的目錄，則輸出檔案會放置在該目錄中，並與輸入檔案具有相同的文件名。如果路徑包含不存在的目錄，則會建立這些目錄。NO_SOURCE_PERMISSIONS在版本 3.19 中新增。
不要將輸入檔案的權限轉移到輸出檔案。複製的檔案權限預設為標準的 644 值 (-rw-r--r--)。
USE_SOURCE_PERMISSIONS在版本 3.20 中新增。
將輸入檔案的權限轉移到輸出檔案。如果未提供三個權限相關的關鍵字（
NO_SOURCE_PERMISSIONS、USE_SOURCE_PERMISSIONS或FILE_PERMISSIONS），這已經是預設行為。USE_SOURCE_PERMISSIONS關鍵字主要用於使呼叫位置的預期行為更清晰。FILE_PERMISSIONS <permissions>...在版本 3.20 中新增。
忽略輸入檔案的權限，並改為對輸出檔案使用指定的
<permissions>。COPYONLY複製檔案，而不替換任何變數參考或其他內容。此選項不能與
NEWLINE_STYLE一起使用。ESCAPE_QUOTES使用反斜線（C 樣式）跳脫任何替換的引號。
@ONLY將變數替換限制為
@VAR@形式的參考。這對於設定使用${VAR}語法的腳本很有用。NEWLINE_STYLE <style>指定輸出檔案的換行符號樣式。指定
UNIX或LF代表\n換行符號，或指定DOS、WIN32或CRLF代表\r\n換行符號。此選項不能與COPYONLY一起使用。
轉換¶
在輸入檔案內容中以 @VAR@、${VAR}、$CACHE{VAR} 形式參考的變數，以及以 $ENV{VAR} 形式參考的 環境變數，都會被替換為變數的當前值，如果變數未定義，則替換為空字串。此外，以下形式的輸入行
#cmakedefine VAR ...
將被替換為
#define VAR ...
或
/* #undef VAR */
取決於 VAR 是否在 CMake 中設定為任何非 if() 命令視為假常數的值。變數名稱後面的 "..." 內容（如果有的話）會如上處理。
與 #cmakedefine VAR ... 形式的行不同，在 #cmakedefine01 VAR 形式的行中，VAR 本身將展開為 VAR 0 或 VAR 1，而不是被賦予值 ...。因此，以下形式的輸入行
#cmakedefine01 VAR
將被替換為
#define VAR 0
或
#define VAR 1
形式為 #cmakedefine01 VAR ... 的輸入行將展開為 #cmakedefine01 VAR ... 0 或 #cmakedefine01 VAR ... 1，這可能會導致未定義的行為。
在版本 3.10 中新增：結果行（除了 #undef 註解之外）可以在 # 字元和 cmakedefine 或 cmakedefine01 單字之間使用空格和/或 Tab 字元縮排。此空格縮排將保留在輸出行中
# cmakedefine VAR
# cmakedefine01 VAR
如果定義了 VAR，將被替換為
# define VAR
# define VAR 1
範例¶
考慮一個包含 foo.h.in 檔案的原始碼樹
#cmakedefine FOO_ENABLE
#cmakedefine FOO_STRING "@FOO_STRING@"
相鄰的 CMakeLists.txt 可以使用 configure_file 來設定標頭檔
option(FOO_ENABLE "Enable Foo" ON)
if(FOO_ENABLE)
set(FOO_STRING "foo")
endif()
configure_file(foo.h.in foo.h @ONLY)
這會在對應於此原始碼目錄的建置目錄中建立 foo.h。如果 FOO_ENABLE 選項開啟，則設定的檔案將包含
#define FOO_ENABLE
#define FOO_STRING "foo"
否則它將包含
/* #undef FOO_ENABLE */
/* #undef FOO_STRING */
然後可以使用 target_include_directories() 命令將輸出目錄指定為包含目錄
target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")
以便原始碼可以包含標頭檔，如 #include <foo.h>。