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> [...])
  file(SIZE <filename> <out-var>)
  file(READ_SYMLINK <linkname> <out-var>)
  file(CREATE_LINK <original> <linkname> [...])

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(SIZE <filename> <variable>)

Определите размер файла <filename> и поместите результат в переменную <variable>. Требуется, чтобы <filename> был действительным путем к файлу и был доступен для чтения.

file(READ_SYMLINK <linkname> <variable>)

Эта подкоманда запрашивает символическую ссылку <linkname> и сохраняет путь, на который она указывает, в результате <variable>. Если <linkname> не существует или не является символической ссылкой, CMake выдаёт ошибку fatal.

Обратите внимание, что эта команда возвращает исходный путь символической ссылки и не разрешает относительный путь. Следующий пример демонстрирует, как получить абсолютный путь:

set(linkname "/path/to/foo.sym")
file(READ_SYMLINK "${linkname}" result)
if(NOT IS_ABSOLUTE "${result}")
  get_filename_component(dir "${linkname}" DIRECTORY)
  set(result "${dir}/${result}")
endif()

file(CREATE_LINK <original> <linkname>
     [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])

Создайте ссылку <linkname>, указывающую на <original>. По умолчанию это будет жёсткая ссылка, но использование опции SYMBOLIC создаст символическую ссылку вместо этого. Для жёстких ссылок требуется, чтобы original существовал и был файлом, а не каталогом. Если <linkname> уже существует, он будет перезаписан.

Переменная <result>, если указана, получает статус операции. Она устанавливается в 0 при успехе или в сообщение об ошибке в противном случае. Если RESULT не указана и операция завершается ошибкой, генерируется ошибка fatal.

Указание COPY_ON_ERROR позволяет копировать файл в качестве резервного варианта, если создание ссылки завершается неудачно. Это может быть полезно для ситуаций, когда <original> и <linkname> находятся на разных дисках или точках монтирования, что делает невозможным создание жёсткой ссылки.

Преобразование путей

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>

Проверьте, что хэш загруженного содержимого соответствует ожидаемому значению, где ALGO — один из алгоритмов, поддерживаемых file(<HASH>). Если они не совпадают, операция завершится с ошибкой.

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 будет ждать, пока блокировка не будет успешной или не произойдёт ошибка fatal. Если TIMEOUT установлено в 0, блокировка будет попытана один раз, и результат будет сообщён немедленно. Если TIMEOUT не равно 0, CMake будет пытаться заблокировать файл на период, указанный в значении <seconds>. Любые ошибки будут интерпретироваться как fatal, если нет опции RESULT_VARIABLE. В противном случае результат будет сохранён в <variable> и будет 0 в случае успеха или сообщение об ошибке при неудаче.

Обратите внимание, что блокировка является рекомендательной — нет гарантии, что другие процессы будут соблюдать эту блокировку, т.е. блокировка синхронизирует два или более экземпляров CMake, использующих общие изменяемые ресурсы. Аналогичная логика применяется к опции DIRECTORY — блокировка родительского каталога не препятствует другим командам LOCK блокировать любые дочерние каталоги или файлы.

Попытка заблокировать файл дважды запрещена. Все промежуточные каталоги и сам файл будут созданы, если они не существуют. Опции GUARD и TIMEOUT игнорируются при операции RELEASE.