file

Команда для работы с файлами.

file(WRITE <filename> <content>...)
file(APPEND <filename> <content>...)

Записать <content> в файл под названием <filename>. Если файл не существует, он будет создан. Если файл уже существует, режим WRITE перезапишет его, а режим APPEND добавит данные в конец. (Если файл является входным файлом сборки, используйте команду configure_file() для обновления файла только при изменении его содержимого.)

file(READ <filename> <variable>
     [OFFSET <offset>] [LIMIT <max-in>] [HEX])

Прочитать содержимое файла под названием <filename> и сохранить его в <variable>. Дополнительно можно начать чтение с заданного <offset> и прочитать не более <max-in> байтов. Опция HEX преобразует данные в шестнадцатеричное представление (полезно для двоичных данных).

file(STRINGS <filename> <variable> [<options>...])

Разбор списка ASCII-строк из <filename> и сохранение их в <variable>. Двоичные данные в файле игнорируются. Символы возврата каретки (\r, CR) игнорируются. Доступны следующие опции:

LENGTH_MAXIMUM <max-len>

Учитывать только строки длиной не более заданной.

LENGTH_MINIMUM <min-len>

Учитывать только строки длиной не менее заданной.

LIMIT_COUNT <max-num>

Ограничить количество уникальных строк, которые будут извлечены.

LIMIT_INPUT <max-in>

Ограничить количество байтов входного файла, подлежащих чтению.

LIMIT_OUTPUT <max-out>

Ограничить общее количество байтов для хранения в <variable>.

NEWLINE_CONSUME

Обрабатывать символы новой строки (\n, LF) как часть содержимого строки, а не как символы завершения строки.

NO_HEX_CONVERSION

Файлы Intel Hex и Motorola S-record автоматически преобразуются в двоичный формат при чтении, если эта опция не указана.

REGEX <regex>

Учитывать только строки, соответствующие заданному регулярному выражению.

ENCODING <encoding-type>

Учитывать строки заданной кодировки. В настоящее время поддерживаются кодировки: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. Если опция ENCODING не указана, а в файле есть маркер порядка байтов, опция ENCODING будет установлена по умолчанию, чтобы учитывать маркер порядка байтов.

Например, код

file(STRINGS myfile.txt myfile)

хранит список в переменной myfile , где каждый элемент — строка из входного файла.

file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> <filename> <variable>)

Вычислить криптографический хеш содержимого <filename> и сохранить его в <variable>.

file(GLOB <variable>
     [LIST_DIRECTORIES true|false] [RELATIVE <path>]
     [<globbing-expressions>...])
file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
     [LIST_DIRECTORIES true|false] [RELATIVE <path>]
     [<globbing-expressions>...])

Сгенерировать список файлов, соответствующих <globbing-expressions>, и сохранить его в <variable>. Выражения подстановки подобны регулярным выражениям, но значительно проще. Если указан флаг RELATIVE, результаты будут возвращены как относительные пути к данному пути. Определённый порядок результатов не задан. Если порядок важен, отсортируйте список явно (например, используя команду list(SORT)).

По умолчанию GLOB перечисляет каталоги — каталоги опускаются из результата, если LIST_DIRECTORIES установлено в false.

Примеры выражений подстановки включают:

*.cxx      - match all files with extension cxx
*.vt?      - match all files with extension vta,...,vtz
f[3-5].txt - match files f3.txt, f4.txt, f5.txt

Режим GLOB_RECURSE будет переходить по всем подкаталогам совпадающего каталога и подбирать файлы. Подкаталоги, являющиеся символами, будут перебираться только если задан FOLLOW_SYMLINKS или политика CMP0009 не установлена в NEW.

По умолчанию GLOB_RECURSE исключает каталоги из списка результатов — установка LIST_DIRECTORIES в true добавляет каталоги в список результатов. Если FOLLOW_SYMLINKS задан или политика CMP0009 не установлена в OLD, то LIST_DIRECTORIES обрабатывает символы как каталоги.

Примеры рекурсивных выражений подстановки включают:

/dir/*.py  - match all python files in /dir and subdirectories

file(RENAME <oldname> <newname>)

Переместить файл или каталог в файловой системе из <oldname> в <newname>, атомарно заменяя место назначения.

file(REMOVE [<files>...])
file(REMOVE_RECURSE [<files>...])

Удалить указанные файлы. Режим REMOVE_RECURSE удалит указанные файлы и каталоги, а также непустые каталоги.

file(MAKE_DIRECTORY [<directories>...])

Создать указанные каталоги и их родительские каталоги по мере необходимости.

file(RELATIVE_PATH <variable> <directory> <file>)

Вычислить относительный путь от <directory> к <file> и сохранить его в <variable>.

file(TO_CMAKE_PATH "<path>" <variable>)
file(TO_NATIVE_PATH "<path>" <variable>)

Режим TO_CMAKE_PATH преобразует системный путь <path> в путь в стиле CMake с прямыми слешами (/). Вход может быть одиночным путём или системным путём поиска, например, $ENV{PATH}. Путь поиска будет преобразован в список в стиле CMake, разделённый символами ;.

Режим TO_NATIVE_PATH преобразует путь в стиле CMake <path> в системный путь с платформно-зависимыми слешами (\ на Windows и / в других случаях).

Всегда используйте двойные кавычки вокруг <path> , чтобы убедиться, что это рассматривается как один аргумент этой команды.

file(DOWNLOAD <url> <file> [<options>...])
file(UPLOAD   <file> <url> [<options>...])

Режим DOWNLOAD загружает указанный <url> в локальный <file>. Режим UPLOAD загружает локальный <file> в указанный <url>.

Опции для DOWNLOAD и UPLOAD:

INACTIVITY_TIMEOUT <seconds>

Прекратить операцию после периода бездействия.

LOG <variable>

Сохранить удобочитаемый журнал операции в переменной.

SHOW_PROGRESS

Выводить информацию о ходе работы в качестве сообщений о состоянии до завершения операции.

STATUS <variable>

Сохранить полученный статус операции в переменной. Статус — это список, разделённый ;, длиной 2. Первый элемент — числовое возвращаемое значение операции, а второй — строковое значение ошибки. Числовое значение ошибки 0 означает отсутствие ошибки в ходе операции.

TIMEOUT <seconds>

Прекратить операцию по истечении заданного времени.

Дополнительные опции для DOWNLOAD:

EXPECTED_HASH ALGO=<value>

EXPECTED_MD5 <value>

Исторически сокращённое обозначение для EXPECTED_HASH MD5=<value>.

TLS_VERIFY <ON|OFF>

Указать, нужно ли проверять сертификат сервера для https:// URL. По умолчанию проверка не производится.

TLS_CAINFO <file>

Указать файл уполномоченной организации сертификации (Certificate Authority) для https:// URL.

Для https:// URL CMake должен быть скомпилирован с поддержкой OpenSSL. Сертификаты TLS/SSL не проверяются по умолчанию. Установите TLS_VERIFY в ON для проверки сертификатов и/или используйте EXPECTED_HASH для проверки загруженного содержимого. Если ни одна из опций TLS не указана, CMake будет проверять переменные CMAKE_TLS_VERIFY и CMAKE_TLS_CAINFO, соответственно.

file(TIMESTAMP <filename> <variable> [<format>] [UTC])

Вывести строковое представление времени изменения <filename> и сохранить его в <variable>. Если команда не сможет получить метку времени, переменная будет установлена в пустую строку (" ").

См. команду string(TIMESTAMP) для документации по опциям <format> и UTC.

file(GENERATE OUTPUT output-file
     <INPUT input-file|CONTENT content>
     [CONDITION expression])

Генерировать выходной файл для каждой поддерживаемой текущей CMake Generator конфигурации сборки. Оценить generator expressions из входного содержимого для создания выходного содержимого. Доступны следующие опции:

CONDITION <condition>

Генерировать выходной файл для определённой конфигурации только если условие истинно. Условие должно быть либо 0 , либо 1 после оценки выражений генератора.

CONTENT <content>

Использовать явно заданное входное содержимое.

INPUT <input-file>

Использовать содержимое из заданного файла в качестве входных данных.

OUTPUT <output-file>

Указать имя выходного файла для генерации. Используйте выражения генератора, такие как $<CONFIG>, для указания имени выходного файла, специфичного для конфигурации. Несколько конфигураций могут генерировать один и тот же выходной файл только если сгенерированное содержимое идентично. В противном случае, <output-file> должно возвращать уникальное имя для каждой конфигурации.

Должна быть указана точно одна опция CONTENT или INPUT. Указание конкретного файла OUTPUT может быть выполнено не более чем одной вызов команды file(GENERATE). Сгенерированные файлы модифицируются при последующих запусках cmake только если их содержимое изменилось.

file(<COPY|INSTALL> <files>... DESTINATION <dir>
     [FILE_PERMISSIONS <permissions>...]
     [DIRECTORY_PERMISSIONS <permissions>...]
     [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
     [FILES_MATCHING]
     [[PATTERN <pattern> | REGEX <regex>]
      [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

Подпись COPY копирует файлы, каталоги и символьные ссылки в папку назначения. Относительные пути к входным данным вычисляются относительно текущей директории исходного кода, а относительный путь назначения — относительно текущей директории сборки. Копирование сохраняет отметки времени входных файлов и исключает файл, если он существует в пункте назначения с таким же временным отметкой. Копирование сохраняет разрешения входных файлов, за исключением явных разрешений или NO_SOURCE_PERMISSIONS (значение по умолчанию USE_SOURCE_PERMISSIONS).

См. команду install(DIRECTORY) для документации по разрешениям, FILES_MATCHING, PATTERN, REGEX, и EXCLUDE опциям. Копирование каталогов сохраняет структуру их содержимого, даже если опции используются для выбора подмножества файлов.

Подпись INSTALL немного отличается от COPY: она выводит сообщения о статусе (в зависимости от переменной CMAKE_INSTALL_MESSAGE), и NO_SOURCE_PERMISSIONS является значением по умолчанию. Скрипты установки, сгенерированные командой install(), используют эту подпись (с некоторыми неудокументированными опциями для внутреннего использования).

file(LOCK <path> [DIRECTORY] [RELEASE]
     [GUARD <FUNCTION|FILE|PROCESS>]
     [RESULT_VARIABLE <variable>]
     [TIMEOUT <seconds>])

Заблокировать файл, указанный в <path>, если опция DIRECTORY отсутствует, и файл <path>/cmake.lock в противном случае. Файл будет заблокирован для области, определенной опцией GUARD (значение по умолчанию — PROCESS). Опция RELEASE может использоваться для явного разблокирования файла. Если опция TIMEOUT не указана, CMake будет ожидать успеха блокировки или возникновения критической ошибки. Если TIMEOUT установлено в значение 0, блокировка будет выполнена один раз, и результат будет сообщен немедленно. Если TIMEOUT не равно 0, CMake будет пытаться заблокировать файл на период, указанный значением <seconds>. Любые ошибки будут интерпретироваться как критические, если нет опции RESULT_VARIABLE. В противном случае результат будет сохранен в <variable> и будет 0 при успехе или сообщение об ошибке при неудаче.

Обратите внимание, что блокировка является рекомендательной — нет гарантии, что другие процессы будут соблюдать эту блокировку, т.е. блокировка синхронизирует два или более экземпляра CMake, совместно использующих некоторые изменяемые ресурсы. Аналогичная логика применяется к опции DIRECTORY — блокировка родительского каталога не препятствует другим командам LOCK блокировать любые дочерние каталоги или файлы.

Попытка заблокировать файл дважды не допускается. Все промежуточные каталоги и сам файл будут созданы, если они не существуют. Опции GUARD и TIMEOUT игнорируются при операции RELEASE.