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]
     [FOLLOW_SYMLINK_CHAIN]
     [FILES_MATCHING]
     [[PATTERN <pattern> | REGEX <regex>]
      [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

Подпись COPY копирует файлы, каталоги и символические ссылки в целевую папку. Относительные пути к вводу оцениваются относительно текущего каталога исходных файлов, а относительный путь к цели оценивается относительно текущего каталога сборки. Копирование сохраняет временные метки входных файлов и исключает файл, если он существует в цели с той же временной меткой. Копирование сохраняет входные разрешения, если не указаны явные разрешения или NO_SOURCE_PERMISSIONS (по умолчанию USE_SOURCE_PERMISSIONS).

Если указан FOLLOW_SYMLINK_CHAIN, COPY рекурсивно разрешит символические ссылки в заданных путях, пока не найдёт реальный файл, и установит соответствующую символическую ссылку в целевой папке для каждой встреченной символической ссылки. Для каждой установленной символической ссылки разрешение очищается от каталога, оставляя только имя файла, что означает, что новая символическая ссылка указывает на файл в той же папке, что и символическая ссылка. Эта функция полезна на некоторых системах Unix, где библиотеки устанавливаются как цепочка символических ссылок с номерами версий, где менее конкретные версии указывают на более конкретные версии. FOLLOW_SYMLINK_CHAIN установит все эти символические ссылки и саму библиотеку в целевой каталог. Например, если у вас есть следующая структура каталогов:

• /opt/foo/lib/libfoo.so.1.2.3
• /opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3
• /opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2
• /opt/foo/lib/libfoo.so -> libfoo.so.1

и вы делаете:

file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)

Это установит все символические ссылки и libfoo.so.1.2.3 в lib.

См. команду 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 выдаёт ошибку.

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

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 не указана и операция завершается ошибкой, генерируется фатальная ошибка.

Указание 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>

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

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

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