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>

Указать, нужно ли проверять сертификат сервера для 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(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.