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(<HASH> <filename> <variable>)

Вычислить криптографический хэш содержимого <filename> и сохранить его в <variable>. Поддерживаемые алгоритмы хэширования <HASH> соответствуют тем, что перечислены командой string(<HASH>).

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>

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

USERPWD <username>:<password>

Установить имя пользователя и пароль для операции.

HTTPHEADER <HTTP-header>

HTTP заголовок для операции. Подопция может быть повторена несколько раз.

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

EXPECTED_HASH ALGO=<value>

EXPECTED_MD5 <value>

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

TLS_VERIFY <ON|OFF>

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

TLS_CAINFO <file>

Указать файл пользовательского центра сертификации для 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(GENERATE) не создаёт выходной файл до стадии генерации. Выходной файл ещё не будет записан, когда команда file(GENERATE) возвращает результат, он записывается только после обработки всех файлов CMakeLists.txt проекта.

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.