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>指定輸出檔案的換行樣式。對於
\n換行符號，指定UNIX或LF，或對於\r\n換行符號，指定DOS、WIN32或CRLF。此選項不能與COPYONLY一起使用。
轉換¶
在輸入檔案內容中以 @VAR@、${VAR}、$CACHE{VAR} 參考的變數，以及以 $ENV{VAR} 參考的 環境變數，都將被替換為變數的目前值，如果變數未定義，則為空字串。此外，以下形式的輸入行
#cmakedefine VAR ...
將會被替換為
#define VAR ...
或
/* #undef VAR */
取決於 VAR 是否在 CMake 中設定為任何不被 if() 命令視為 false 常數的值。如果有的話，變數名稱後面的行上的「...」內容將如上所述進行處理。
與 #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>。