file

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

Синопсис

Reading
  file(READ <filename> <out-var> [...])
  file(STRINGS <filename> <out-var> [...])
  file(<HASH> <filename> <out-var>)
  file(TIMESTAMP <filename> <out-var> [...])

Writing
  file({WRITE | APPEND} <filename> <content>...)
  file({TOUCH | TOUCH_NOCREATE} [<file>...])
  file(GENERATE OUTPUT <output-file> [...])

Filesystem
  file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
  file(RENAME <oldname> <newname>)
  file({REMOVE | REMOVE_RECURSE } [<files>...])
  file(MAKE_DIRECTORY [<dir>...])
  file({COPY | INSTALL} <file>... DESTINATION <dir> [...])

Path Conversion
  file(RELATIVE_PATH <out-var> <directory> <file>)
  file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)

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

Locking
  file(LOCK <path> [...])

Чтение

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(TIMESTAMP <filename> <variable> [<format>] [UTC])

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

См. команду string(TIMESTAMP) для получения информации об опциях <format> и UTC.

Запись

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

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

Если файл является входным файлом для сборки, используйте команду configure_file() для обновления файла только при изменении его содержимого.

file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])

Создать файл без содержимого, если он еще не существует. Если файл уже существует, его атрибуты доступа и/или изменения будут обновлены до времени выполнения функции.

Используйте TOUCH_NOCREATE для обновления файла, если он существует, но не для его создания. Если файл не существует, он будет проигнорирован.

При использовании TOUCH и TOUCH_NOCREATE содержимое существующего файла не будет изменено.

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

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

Если указан флаг CONFIGURE_DEPENDS, CMake добавит в целевой объект проверки основной системы сборки логику повторного выполнения отмеченных GLOB команд во время сборки. Если какие-либо из выходных данных изменятся, CMake пересгенерирует систему сборки.

По умолчанию 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(<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(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-заголовок для операции. Подопцию можно повторять несколько раз.

NETRC <level>

Указать, использовать ли файл .netrc для операции. Если этот параметр не указан, используется значение переменной CMAKE_NETRC. Допустимые уровни:

IGNORED

Файл .netrc игнорируется. Это значение по умолчанию.

OPTIONAL

Файл .netrc необязателен, и информация в URL имеет приоритет. Файл будет просканирован для поиска любой информации, которая не указана в URL.

REQUIRED

Файл .netrc обязателен, и информация в URL игнорируется.

NETRC_FILE <file>

Указать альтернативный файл .netrc по отношению к файлу в вашем домашнем каталоге, если уровень NETRC равен OPTIONAL или REQUIRED. Если этот параметр не указан, используется значение переменной CMAKE_NETRC_FILE.

Если ни один из параметров NETRC не задан, CMake проверит переменные CMAKE_NETRC и CMAKE_NETRC_FILE соответственно.

Дополнительные параметры для DOWNLOAD:

EXPECTED_HASH ALGO=<value>

EXPECTED_MD5 <value>

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

TLS_VERIFY <ON|OFF>

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

TLS_CAINFO <file>

Указать файл авторитетного центра сертификации для URL-адресов https://.

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

Блокировка

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.