file

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

Резюме

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

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

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> [...])
  file(CHMOD <files>... <directories>... PERMISSIONS <permissions>... [...])
  file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... [...])

Path Conversion
  file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>])
  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> [...])

Archiving
  file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [...])
  file(ARCHIVE_EXTRACT INPUT <archive> [...])

Чтение

file(READ <filename> <variable>
     [OFFSET <offset>] [LIMIT <max-in>] [HEX])

Прочитайте содержимое файла под названием <filename> и сохраните его в <variable>. Допускается начать чтение с указанного <offset> и прочитать не более <max-in> байт. Опция HEX преобразует данные в шестнадцатеричное представление (полезно для бинарных данных). Если указана опция HEX, буквы в выводе (a до f) будут в нижнем регистре.

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(GET_RUNTIME_DEPENDENCIES
  [RESOLVED_DEPENDENCIES_VAR <deps_var>]
  [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
  [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
  [EXECUTABLES [<executable_files>...]]
  [LIBRARIES [<library_files>...]]
  [MODULES [<module_files>...]]
  [DIRECTORIES [<directories>...]]
  [BUNDLE_EXECUTABLE <bundle_executable_file>]
  [PRE_INCLUDE_REGEXES [<regexes>...]]
  [PRE_EXCLUDE_REGEXES [<regexes>...]]
  [POST_INCLUDE_REGEXES [<regexes>...]]
  [POST_EXCLUDE_REGEXES [<regexes>...]]
  )

Рекурсивно получить список библиотек, от которых зависят указанные файлы.

Обратите внимание, что эта подкоманда не предназначена для использования в режиме проекта. Вместо этого используйте её в блоке install(CODE) или install(SCRIPT). Например:

install(CODE [[
  file(GET_RUNTIME_DEPENDENCIES
    # ...
    )
  ]])

Аргументы представлены следующим образом:

RESOLVED_DEPENDENCIES_VAR <deps_var>: Имя переменной, в которую будет сохранён список разрешённых зависимостей.
UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>: Имя переменной, в которую будет сохранён список неразрешённых зависимостей. Если эта переменная не указана, а неразрешённые зависимости существуют, выводится ошибка.
CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>: Префикс переменной, в которую будет сохранена информация о конфликтующих зависимостях. Зависимости конфликтуют, если два файла с одинаковым именем найдены в двух разных директориях. Список имён файлов, которые конфликтуют, хранится в <conflicting_deps_prefix>_FILENAMES. Для каждого имени файла список путей, которые были найдены для этого имени файла, хранится в <conflicting_deps_prefix>_<filename>.
EXECUTABLES <executable_files>: Список исполняемых файлов для чтения зависимостей. Это исполняемые файлы, которые обычно создаются с помощью add_executable(), но они не обязательно должны создаваться CMake. На платформах Apple пути к этим файлам определяют значение @executable_path при рекурсивном разрешении библиотек. Указание любого типа библиотек (STATIC, MODULE, или SHARED) приведёт к неопределённому поведению.
LIBRARIES <library_files>: Список файлов библиотек для чтения зависимостей. Это библиотеки, которые обычно создаются с помощью add_library(SHARED), но они не обязательно должны создаваться CMake. Указание библиотек STATIC, библиотек MODULE или исполняемых файлов приведёт к неопределённому поведению.
MODULES <module_files>: Список файлов модулей для загрузки для чтения зависимостей. Это модули, которые обычно создаются с помощью add_library(MODULE), но они не обязательно должны создаваться CMake. Обычно они используются для вызова dlopen() во время выполнения, а не для линковки во время линковки с ld -l. Указание библиотек STATIC, библиотек SHARED или исполняемых файлов приведёт к неопределённому поведению.
DIRECTORIES <directories>: Список дополнительных директорий для поиска зависимостей. На платформах Linux эти директории ищутся, если зависимость не найдена в каком-либо из других стандартных путей. Если она найдена в такой директории, выводится предупреждение, потому что это означает, что файл неполный (он не перечисляет все директории, содержащие его зависимости). На платформах Windows эти директории ищутся, если зависимость не найдена в каком-либо из других путей поиска, но предупреждение не выводится, так как поиск в других путях является нормальной частью разрешения зависимостей Windows. На платформах Apple этот аргумент не имеет эффекта.
BUNDLE_EXECUTABLE <bundle_executable_file>: Исполняемый файл, который будет обрабатываться как «исполняемый файл пакета» при разрешении библиотек. На платформах Apple этот аргумент определяет значение @executable_path при рекурсивном разрешении библиотек для файлов LIBRARIES и MODULES. Он не оказывает влияния на файлы EXECUTABLES. На других платформах он не оказывает влияния. Обычно (но не всегда) это один из исполняемых файлов в аргументе EXECUTABLES , который определяет «основной» исполняемый файл пакета.

Следующие аргументы задают фильтры для включения или исключения библиотек, подлежащих разрешению. Подробное описание их работы приведено ниже.

PRE_INCLUDE_REGEXES <regexes>: Список регулярных выражений для предварительного включения для фильтрации имён ещё не разрешённых зависимостей.
PRE_EXCLUDE_REGEXES <regexes>: Список регулярных выражений для предварительного исключения для фильтрации имён ещё не разрешённых зависимостей.
POST_INCLUDE_REGEXES <regexes>: Список регулярных выражений для последующего включения для фильтрации имён разрешённых зависимостей.
POST_EXCLUDE_REGEXES <regexes>: Список регулярных выражений для последующего исключения для фильтрации имён разрешённых зависимостей.

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

Если неразрешённая зависимость соответствует любому из PRE_INCLUDE_REGEXES, шаги 2 и 3 пропускаются, и разрешение зависимостей переходит к шагу 4.
Если неразрешённая зависимость соответствует любому из PRE_EXCLUDE_REGEXES, разрешение зависимостей останавливается для этой зависимости.
В противном случае разрешение зависимостей продолжается.
file(GET_RUNTIME_DEPENDENCIES) ищет зависимость в соответствии с правилами линковки платформы (см. ниже).
Если зависимость найдена, а её полный путь соответствует одному из POST_INCLUDE_REGEXES, полный путь добавляется к разрешённым зависимостям, и file(GET_RUNTIME_DEPENDENCIES) рекурсивно разрешает зависимости этой библиотеки. В противном случае разрешение продолжается на шаге 6.
Если зависимость найдена, но её полный путь соответствует одному из POST_EXCLUDE_REGEXES, она не добавляется к разрешённым зависимостям, и разрешение зависимостей останавливается для этой зависимости.
Если зависимость найдена, а её полный путь не соответствует ни POST_INCLUDE_REGEXES, ни POST_EXCLUDE_REGEXES, полный путь добавляется к разрешённым зависимостям, и file(GET_RUNTIME_DEPENDENCIES) рекурсивно разрешает зависимости этой библиотеки.

Разные платформы имеют разные правила разрешения зависимостей. Эти особенности описаны здесь.

На платформах Linux разрешение библиотек работает следующим образом:

Если у зависящего файла нет записей RUNPATH, и библиотека существует в одной из записей RPATH зависящего файла или его предков, в таком порядке, зависимость разрешается к этому файлу.
В противном случае, если у зависящего файла есть записи RUNPATH, и библиотека существует в одной из этих записей, зависимость разрешается к этому файлу.
В противном случае, если библиотека существует в одной из директорий, перечисленных в ldconfig, зависимость разрешается к этому файлу.
В противном случае, если библиотека существует в одной из записей DIRECTORIES, зависимость разрешается к этому файлу. В этом случае выводится предупреждение, потому что обнаружение файла в одной из DIRECTORIES означает, что зависящий файл неполный (он не перечисляет все директории, откуда он получает зависимости).
В противном случае зависимость не разрешается.

На платформах Windows разрешение библиотек работает следующим образом:

Имя зависимой DLL преобразуется в нижний регистр. Имена DLL в Windows регистронезависимы, и некоторые линковщики изменяют регистр имён зависимостей DLL. Однако это затрудняет PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, и POST_EXCLUDE_REGEXES правильную фильтрацию имён DLL — каждый регулярное выражение должно было бы проверять как прописные, так и строчные буквы. Например:
```
file(GET_RUNTIME_DEPENDENCIES
  # ...
  PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
  )
```
Преобразование имени DLL в нижний регистр позволяет регулярным выражениям соответствовать только именам в нижнем регистре, упрощая регулярное выражение. Например:
```
file(GET_RUNTIME_DEPENDENCIES
  # ...
  PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
  )
```
Это регулярное выражение будет соответствовать mylibrary.dll независимо от регистра, как на диске, так и в зависимом файле. (Например, оно будет соответствовать mylibrary.dll, MyLibrary.dll, и MYLIBRARY.DLL.)

Обратите внимание, что часть пути к любой разрешённой DLL сохраняет свой регистр и не преобразуется в нижний регистр. Преобразуется только часть имени файла.
(Не реализовано) Если зависимый файл — приложение Windows Store, и зависимость указана в манифесте пакета приложения, зависимость разрешается к этому файлу.
В противном случае, если библиотека существует в той же директории, что и зависимый файл, зависимость разрешается к этому файлу.
В противном случае, если библиотека существует в директории операционной системы system32 или директории Windows, в указанном порядке, зависимость разрешается к этому файлу.
В противном случае, если библиотека существует в одном из директорий, указанных в DIRECTORIES, в порядке их перечисления, зависимость разрешается к этому файлу. В этом случае предупреждение не выводится, так как поиск в других директориях является нормальной частью разрешения зависимостей библиотек в Windows.
В противном случае, зависимость не разрешена.

На платформах Apple разрешение библиотек работает следующим образом:

Если зависимость начинается с @executable_path/, и в процессе разрешения аргумента EXECUTABLES, и замена @executable_path/ на директорию исполняемого файла даёт существующий файл, зависимость разрешается к этому файлу.
В противном случае, если зависимость начинается с @executable_path/, и существует аргумент BUNDLE_EXECUTABLE, и замена @executable_path/ на директорию исполняемого файла пакета даёт существующий файл, зависимость разрешается к этому файлу.
В противном случае, если зависимость начинается с @loader_path/, и замена @loader_path/ на директорию зависимого файла даёт существующий файл, зависимость разрешается к этому файлу.
В противном случае, если зависимость начинается с @rpath/, и замена @rpath/ на один из элементов RPATH зависимого файла даёт существующий файл, зависимость разрешается к этому файлу. Обратите внимание, что элементы RPATH которые начинаются с @executable_path/ или @loader_path/ также заменяют эти элементы соответствующим путём.
В противном случае, если зависимость является абсолютным путём к существующему файлу, зависимость разрешается к этому файлу.
В противном случае, зависимость не разрешена.

Эта функция принимает несколько переменных, определяющих инструмент, используемый для разрешения зависимостей:

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM

Определяет операционную систему и формат исполняемых файлов, для которых построены файлы. Это может быть одно из нескольких значений:

linux+elf
windows+pe
macos+macho

Если эта переменная не указана, она определяется автоматически с помощью интроспекции системы.

CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

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

`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`	`CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`
`linux+elf`	`objdump`
`windows+pe`	`dumpbin`
`windows+pe`	`objdump`
`macos+macho`	`otool`

Если эта переменная не указана, она определяется автоматически с помощью интроспекции системы.

CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

Определяет путь к инструменту, используемому для разрешения зависимостей. Это фактический путь к objdump, dumpbin, или otool.

Если эта переменная не указана, она определяется по значению CMAKE_OBJDUMP, если оно установлено, иначе — с помощью интроспекции системы.

Запись

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] [TARGET target])

Сгенерировать выходной файл для каждой поддерживаемой текущим 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.
TARGET <target>: Указать целевой объект для использования при оценке выражений генератора, требующих целевой объект для оценки (например, $<COMPILE_FEATURES:...>, $<TARGET_PROPERTY:prop>).

Должна быть указана ровно одна опция CONTENT или INPUT. Конкретный файл OUTPUT может быть назван не более чем одним вызовом file(GENERATE). Сгенерированные файлы изменяются и их временные метки обновляются при последующих запусках cmake только если их содержимое изменено.

Также обратите внимание, что file(GENERATE) не создаёт выходной файл до фазы генерации. Выходной файл ещё не будет записан, когда возвращается команда file(GENERATE), он записывается только после обработки всех файлов CMakeLists.txt проекта.

file(CONFIGURE OUTPUT output-file
     CONTENT content
     [ESCAPE_QUOTES] [@ONLY]
     [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

Сгенерировать выходной файл, используя входные данные из CONTENT и подставляя значения переменных, указанные как @VAR@ или ${VAR} в нём. Правила подстановки идентичны поведению команды configure_file(). Для соответствия поведению команды configure_file(), выражения генератора не поддерживаются как для OUTPUT, так и для CONTENT.

Аргументы:

OUTPUT <output-file>: Укажите имя выходного файла для генерации. Относительный путь рассматривается относительно значения CMAKE_CURRENT_BINARY_DIR. <output-file> не поддерживает выражения генератора.
CONTENT <content>: Используйте явно заданное содержимое в качестве входных данных. <content> не поддерживает выражения генератора.
ESCAPE_QUOTES: Экранируйте любые подставленные кавычки обратными слешами (стиль C).
@ONLY: Ограничьте замену переменных ссылками вида @VAR@. Это полезно для настройки скриптов, использующих синтаксис ${VAR}.
NEWLINE_STYLE <style>: Укажите стиль новой строки для выходного файла. Укажите UNIX или LF для \n новых строк или укажите DOS, WIN32, или CRLF для \r\n новых строк.

Файловая система

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

В Windows и macOS подстановка игнорирует регистр, даже если основная файловая система чувствительна к регистру (и имена файлов, и выражения подстановки приводятся к нижнему регистру перед сопоставлением). На других платформах подстановка чувствительна к регистру.

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

По умолчанию GLOB перечисляет каталоги — каталоги опускаются в результате, если LIST_DIRECTORIES установлено в false.

Примечание

Не рекомендуется использовать GLOB для сбора списка исходных файлов из вашей исходной директории. Если при добавлении или удалении исходного файла не изменяется файл CMakeLists.txt, сгенерированная система сборки не может знать, когда запросить у CMake перегенерацию. Флаг CONFIGURE_DEPENDS может работать ненадёжно на всех генераторах или при добавлении нового генератора, который не может его поддержать, проекты, его использующие, застрянут. Даже если CONFIGURE_DEPENDS работает надёжно, всё равно есть затраты на выполнение проверки при каждой пересборке.

Примеры выражений подстановки включают:

*.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 не установлена в NEW, тогда 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(CHMOD <files>... <directories>...
    [PERMISSIONS <permissions>...]
    [FILE_PERMISSIONS <permissions>...]
    [DIRECTORY_PERMISSIONS <permissions>...])

Установить права доступа для <files>... и <directories>... указанных. Допустимые права доступа: OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE.

Допустимые комбинации ключевых слов:

PERMISSIONS: Все элементы изменяются.
FILE_PERMISSIONS: Изменяются только файлы.
DIRECTORY_PERMISSIONS: Изменяются только каталоги.
PERMISSIONS and FILE_PERMISSIONS: FILE_PERMISSIONS переопределяет PERMISSIONS для файлов.
PERMISSIONS and DIRECTORY_PERMISSIONS: DIRECTORY_PERMISSIONS переопределяет PERMISSIONS для каталогов.
FILE_PERMISSIONS and DIRECTORY_PERMISSIONS: Используйте FILE_PERMISSIONS для файлов и DIRECTORY_PERMISSIONS для каталогов.

file(CHMOD_RECURSE <files>... <directories>...
     [PERMISSIONS <permissions>...]
     [FILE_PERMISSIONS <permissions>...]
     [DIRECTORY_PERMISSIONS <permissions>...])

То же, что и CHMOD, но изменить права доступа к файлам и каталогам, присутствующим в <directories>... рекурсивно.

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

file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>])

Вычислить абсолютный путь к существующему файлу или каталогу с разрешением символических ссылок.

Если предоставленный <path> является относительным путём, он оценивается относительно заданной базовой директории <dir>. Если базовая директория не указана, по умолчанию будет CMAKE_CURRENT_SOURCE_DIR.

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

TLS_VERIFY <ON|OFF>: Указать, нужно ли проверять сертификат сервера для https:// URL. По умолчанию проверка не выполняется.
TLS_CAINFO <file>: Указать файл пользовательских сертификатов CA для https:// URL.

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

Дополнительные опции для DOWNLOAD:

EXPECTED_HASH ALGO=<value>

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

EXPECTED_MD5 <value>: Исторический синоним для EXPECTED_HASH MD5=<value>. Нельзя указать эту опцию, если DOWNLOAD не указана с <file>.

Блокировка

file(LOCK <path> [DIRECTORY] [RELEASE]
     [GUARD <FUNCTION|FILE|PROCESS>]
     [RESULT_VARIABLE <variable>]
     [TIMEOUT <seconds>])

Заблокировать файл, указанный <path>, если опция DIRECTORY отсутствует, и файл <path>/cmake.lock в противном случае. Файл будет заблокирован в рамках области, определённой опцией GUARD (значение по умолчанию — PROCESS). Опцию TIMEOUT можно использовать для явного разблокирования файла. Если опция TIMEOUT не указана, CMake будет ожидать, пока блокировка не будет успешной или произойдёт фатальная ошибка. Если TIMEOUT установлено в 0, попытка блокировки будет произведена один раз, и результат будет немедленно сообщён. Если TIMEOUT не равно 0, CMake будет пытаться заблокировать файл на период, указанный значением <seconds> . Любые ошибки будут расценены как фатальные, если опция RESULT_VARIABLE отсутствует. В противном случае результат будет сохранён в <variable> и будет 0 при успехе или сообщение об ошибке при неудаче.

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

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

Архивирование

file(ARCHIVE_CREATE OUTPUT <archive>
  PATHS <paths>...
  [FORMAT <format>]
  [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
  [MTIME <mtime>]
  [VERBOSE])

Создаёт указанный <archive> файл с файлами и каталогами, перечисленными в <paths>. Обратите внимание, что <paths> должен содержать фактические файлы или каталоги; подстановки не поддерживаются.

Используйте опцию FORMAT для указания формата архива. Поддерживаемые значения для <format> — 7zip, gnutar, pax, paxr, raw и zip . Если FORMAT не указана, формат по умолчанию — paxr.

Некоторые форматы архивов позволяют указать тип сжатия. Форматы архивов 7zip и zip уже подразумевают определённый тип сжатия. Другие форматы по умолчанию не используют сжатие, но могут быть на это настроены с помощью опции COMPRESSION . Допустимые значения для <compression> — None, BZip2, GZip, XZ и Zstd.

Уровень сжатия можно указать с помощью опции COMPRESSION_LEVEL . Значение <compression-level> должно быть в диапазоне от 0 до 9, значение по умолчанию — 0. Опция COMPRESSION должна быть указана, когда указана опция COMPRESSION_LEVEL.

Примечание

При установке FORMAT в raw будет сжат только один файл с типом сжатия, указанным в COMPRESSION.

Опция VERBOSE включает подробный вывод для операции архивирования.

Для указания времени изменения, записываемого в записи архива tar, используйте опцию MTIME.

file(ARCHIVE_EXTRACT INPUT <archive>
  [DESTINATION <dir>]
  [PATTERNS <patterns>...]
  [LIST_ONLY]
  [VERBOSE])

Извлекает или выводит содержимое указанного <archive>.

Каталог, в который будет извлечено содержимое архива, можно указать с помощью опции DESTINATION . Если каталог не существует, он будет создан. Если DESTINATION не указан, будет использован текущий каталог бинарных файлов.

При необходимости можно выбрать, какие файлы и каталоги извлечь или вывести из архива, используя указанные <patterns>. Поддерживаются подстановки. Если опция PATTERNS не указана, будет извлечён или выведен весь архив.

LIST_ONLY выведет список файлов в архиве, а не извлечёт их.

С опцией VERBOSE, команда будет генерировать подробный вывод.

© 2000–2020 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.19/command/file.html