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>

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

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).

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.