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 ... 0, что может привести к неопределенному поведению.

#  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 */

Затем можно использовать команду include_directories() для указания директории вывода как директории включения:

include_directories(${CMAKE_CURRENT_BINARY_DIR})

чтобы исходные файлы могли включать заголовок как #include <foo.h>.