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)