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

в зависимости от того, задана ли в CMake переменная VAR значением, которое команда 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)