file

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

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

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

Если файл является входным файлом для сборки, используйте команду 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, результаты будут возвращены как относительные пути к заданному пути. Результаты будут отсортированы лексикографически.

По умолчанию 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>

Использовать содержимое из заданного файла в качестве входных данных. Относительный путь обрабатывается относительно значения CMAKE_CURRENT_SOURCE_DIR. См. политику CMP0070.

OUTPUT <output-file>

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

Должен быть задан ровно один параметр 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.