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 в локальный путь с платформ-зависимыми слешами (\ в 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>

Указать файл авторитетного центра сертификации для 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.