file

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

Эта команда предназначена для работы с файлами и путями, требующими доступа к файловой системе.

Для других операций с путями, обрабатывающих только синтаксические аспекты, обратитесь к команде cmake_path().

Описание

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>

Новая в версии 3.1.

Учитывать строки заданного кодирования. В настоящее время поддерживаются кодировки: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. Если опция ENCODING не задана, и файл имеет метку порядка байтов, опция ENCODING будет установлена по умолчанию для соответствия метке порядка байтов.

Новая в версии 3.2: Добавлены кодировки UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.

Например, код

file(STRINGS myfile.txt myfile)

сохраняет список в переменной myfile, где каждый элемент — строка из входного файла.

file(<HASH> <filename> <variable>)

Вычисляет криптографический хеш содержимого файла <filename> и сохраняет его в <variable>.

file(TIMESTAMP <filename> <variable> [<format>] [UTC])

Вычисляет строковое представление времени модификации файла <filename> и сохраняет его в <variable>.

Документацию по опциям <format> и UTC см. в команде string(TIMESTAMP).

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>

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

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

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

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

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

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

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

1. Имя зависимой DLL преобразуется в нижний регистр. Имена Windows DLL не чувствительны к регистру, а некоторые линковщики изменяют регистр имён зависимостей 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 сохраняет свой регистр и не преобразуется в нижний регистр. Только часть имени файла преобразуется.

2. (Ещё не реализовано) Если зависимый файл — приложение из Магазина Windows, и зависимость перечислена в манифесте пакета приложения, зависимость разрешается на этот файл.
3. В противном случае, если библиотека существует в том же каталоге, что и зависимый файл, зависимость разрешается на этот файл.
4. В противном случае, если библиотека существует в каталоге операционной системы system32 или Windows в указанном порядке, зависимость разрешается на этот файл.
5. В противном случае, если библиотека существует в одном из каталогов, указанных в DIRECTORIES, в порядке их перечисления, зависимость разрешается на этот файл. В этом случае предупреждение не выдаётся, так как поиск в других каталогах — нормальная часть разрешения библиотек Windows.
6. В противном случае зависимость не разрешается.

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

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

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

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, если оно задано, иначе — путём интроспекции системы.

Новое в версии 3.18: Используйте 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]
     [FILE_PERMISSIONS <permissions>...]
     [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
     [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

Создайте выходной файл для каждой конфигурации сборки, поддерживаемой текущим CMake Generator. Оцените generator expressions из входного содержимого для получения выходного содержимого. Опции:

CONDITION <condition>

Создайте выходной файл для определённой конфигурации только если условие истинно. Условие должно быть либо 0 или 1 после оценки выражений генератора.

CONTENT <content>

Используйте явно заданное содержимое как вход.

INPUT <input-file>

Используйте содержимое из заданного файла как вход.

Изменено в версии 3.10: Относительный путь обрабатывается относительно значения CMAKE_CURRENT_SOURCE_DIR. См. политику CMP0070.

OUTPUT <output-file>

Укажите имя выходного файла для создания. Используйте выражения генератора, такие как $<CONFIG> для указания имени выходного файла, специфичного для конфигурации. Несколько конфигураций могут генерировать один и тот же выходной файл только если сгенерированное содержимое идентично. В противном случае, <output-file> должно оцениваться в уникальное имя для каждой конфигурации.

Изменено в версии 3.10: Относительный путь (после оценки выражений генератора) обрабатывается относительно значения CMAKE_CURRENT_BINARY_DIR. См. политику CMP0070.

TARGET <target>

Новое в версии 3.19.

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

FILE_PERMISSIONS <permissions>...

Используйте предоставленные пользователем права доступа для сгенерированного файла.

NO_SOURCE_PERMISSIONS

Права доступа к сгенерированному файлу по умолчанию — стандартное значение 644 (-rw-r--r--).

USE_SOURCE_PERMISSIONS

Перенести права доступа к оригинальному файлу в сгенерированный файл. Эта опция ожидает опцию INPUT.

NEWLINE_STYLE <style>

Новое в версии 3.20.

Укажите стиль перевода строки для сгенерированного файла. Укажите UNIX или LF для \n перевода строк, или укажите DOS, WIN32, или CRLF для \r\n перевода строк.

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

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

*.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.

Примеры рекурсивной подстановки шаблонов:

/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).

• /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, SETUID, SETGID.

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

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>. Режим UPLOAD загружает локальный <file> в указанный <url>.

Опции для DOWNLOAD и UPLOAD:

INACTIVITY_TIMEOUT <seconds>

Прекратить операцию после периода бездействия.

LOG <variable>

Сохранить удобочитаемый журнал операции в переменной.

SHOW_PROGRESS

Печатать информацию о прогрессе в виде сообщений состояния до завершения операции.

STATUS <variable>

Сохранить результирующий статус операции в переменной. Статус — список, разделенный ;, длиной 2. Первый элемент — числовое возвращаемое значение операции, второй — строковое значение для ошибки. Значение 0 обозначает отсутствие ошибки в операции.

TIMEOUT <seconds>

Прекратить операцию по истечении заданного времени.

USERPWD <username>:<password>

Новое в версии 3.7.

Установить имя пользователя и пароль для операции.

HTTPHEADER <HTTP-header>

Новое в версии 3.7.

HTTP-заголовок для операции. Подопция может повторяться несколько раз.

NETRC <level>

Новое в версии 3.11.

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

IGNORED

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

OPTIONAL

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

REQUIRED

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

NETRC_FILE <file>

Новое в версии 3.11.

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

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

TLS_VERIFY <ON|OFF>

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

Новое в версии 3.18: Добавлена поддержка file(UPLOAD).

TLS_CAINFO <file>

Указать пользовательский файл авторитетных сертификатов для https:// URL.

Новое в версии 3.18: Добавлена поддержка file(UPLOAD).

Для 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>.

Обратите внимание, что блокировка — консультативная; нет гарантии, что другие процессы будут учитывать эту блокировку. То есть, блокировка синхронизирует два или более экземпляра 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.

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

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

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

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

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

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

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

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