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> и заменяет значения переменных, указанных как @VAR@ или ${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, что может привести к неопределенному поведению.

#  cmakedefine VAR
#  cmakedefine01 VAR

#  define VAR
#  define VAR 1

Если входной файл изменён, система сборки повторно запустит 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.

Пример

Рассмотрим дерево исходных файлов, содержащее файл 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>.

См. также

• file(GENERATE)