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

#  cmakedefine VAR
#  cmakedefine01 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>.

См. также

• file(GENERATE)