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(MAKE_DIRECTORY [<dir>...])
  file({REMOVE | REMOVE_RECURSE } [<files>...])
  file(RENAME <oldname> <newname> [...])
  file(COPY_FILE <oldname> <newname> [...])
  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>] [EXPAND_TILDE])
  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>

Учитываются только строки, соответствующие заданному регулярному выражению, как описано в string(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>. Поддерживаемые алгоритмы хэширования <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>...]]
  [POST_INCLUDE_FILES [<files>...]]
  [POST_EXCLUDE_FILES [<files>...]]
  )

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

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

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

PRE_INCLUDE_REGEXES <regexes>

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

PRE_EXCLUDE_REGEXES <regexes>

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

POST_INCLUDE_REGEXES <regexes>

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

POST_EXCLUDE_REGEXES <regexes>

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

POST_INCLUDE_FILES <files>

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

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

POST_EXCLUDE_FILES <files>

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

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

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

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

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

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

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

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

1. Имя DLL-зависимости преобразуется в нижний регистр. Имена DLL в Windows регистронезависимы, и некоторые компоновщики меняют регистр имен DLL-зависимостей. Однако это затрудняет PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, и POST_EXCLUDE_REGEXES правильное фильтрации имён DLL — каждый regex должен проверять и заглавные, и строчные буквы. Например:

   file(GET_RUNTIME_DEPENDENCIES
     # ...
     PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
     )
   

   Преобразование имени DLL в нижний регистр позволяет regex находить только имена в нижнем регистре, что упрощает regex. Например:

   file(GET_RUNTIME_DEPENDENCIES
     # ...
     PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
     )
   

   Этот regex будет находить mylibrary.dll независимо от регистра, как на диске, так и в файле-зависимости. (Например, он будет находить mylibrary.dll, MyLibrary.dll, и MYLIBRARY.DLL.)

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

2. (Не реализовано) Если файл-зависимость — приложение Windows Store, и зависимость указана в манифесте пакета приложения, зависимость разрешается к этому файлу.
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 при установке, иначе по интроспекции системы.

New in version 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]
     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
      FILE_PERMISSIONS <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>).

NO_SOURCE_PERMISSIONS

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

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

USE_SOURCE_PERMISSIONS

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

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

FILE_PERMISSIONS <permissions>...

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

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

NEWLINE_STYLE <style>

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

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

Должен быть указан ровно один параметр CONTENT или INPUT. Конкретный файл OUTPUT может быть назван не более чем одним вызовом file(GENERATE).

Обратите внимание, что 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(MAKE_DIRECTORY [<directories>...])

Создать заданные каталоги и их родительские каталоги по мере необходимости.

file(REMOVE [<files>...])
file(REMOVE_RECURSE [<files>...])

Удалить указанные файлы. Режим REMOVE_RECURSE удаляет указанные файлы и каталоги, также и непустые каталоги. Ошибка не генерируется, если указанный файл не существует. Относительные пути ввода обрабатываются относительно текущей исходной директории.

file(RENAME <oldname> <newname>
     [RESULT <result>]
     [NO_REPLACE])

Переместить файл или каталог в файловой системе из <oldname> в <newname>, атомно заменив место назначения.

Параметры:

RESULT <result>

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

Установить переменную <result> в значение 0 при успешном выполнении или сообщение об ошибке в противном случае. Если RESULT не указан, и операция завершается ошибкой, выдаётся сообщение об ошибке.

NO_REPLACE

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

Если путь <newname> уже существует, не заменять его. Если используется RESULT <result>, переменная результата будет установлена в значение NO_REPLACE. В противном случае выдаётся сообщение об ошибке.

file(COPY_FILE <oldname> <newname>
     [RESULT <result>]
     [ONLY_IF_DIFFERENT])

Скопировать файл из <oldname> в <newname>. Каталоги не поддерживаются. Символические ссылки игнорируются, и содержимое <oldfile> читается и записывается в <newname> как новый файл.

Параметры:

RESULT <result>

Установить переменную <result> в значение 0 при успешном выполнении или сообщение об ошибке в противном случае. Если RESULT не указан, и операция завершается ошибкой, выдаётся сообщение об ошибке.

ONLY_IF_DIFFERENT

Если путь <newname> уже существует, не заменять его, если содержимое файла уже совпадает с содержимым <oldname> (это позволяет избежать обновления метки времени <newname>).

Эта подкоманда имеет некоторое сходство с configure_file() с опцией COPYONLY. Важное отличие заключается в том, что configure_file() создаёт зависимость от исходного файла, поэтому CMake будет повторно выполнен, если он изменится. Подкоманда file(COPY_FILE) такой зависимости не создаёт.

См. также подкоманду file(COPY) ниже, которая предоставляет дополнительные возможности копирования файлов.

file(<COPY|INSTALL> <files>... DESTINATION <dir>
     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
     [FILE_PERMISSIONS <permissions>...]
     [DIRECTORY_PERMISSIONS <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: она выводит сообщения об этапах выполнения, и 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>] [EXPAND_TILDE])

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

BASE_DIRECTORY <dir>

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

EXPAND_TILDE

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

Если <path> — это ~ или начинается с ~/, ~ заменяется домашней директорией пользователя. Путь к домашней директории извлекается из переменных среды. В Windows используется переменная среды USERPROFILE, а если USERPROFILE не определена, используется переменная среды HOME. На всех остальных платформах используется только HOME.

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.

TLS_VERIFY <ON|OFF>

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

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

TLS_CAINFO <file>

Указать пользовательский файл авторитета сертификата для https:// URL-адресов. Если этот параметр не указан, будет использовано значение переменной CMAKE_TLS_CAINFO.

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

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

Дополнительные параметры к 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). Параметр RELEASE можно использовать для явного разблокирования файла. Если параметр 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.

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

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

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

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

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

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

LIST_ONLY отобразит файлы в архиве, а не извлечёт их.

При использовании VERBOSE, команда будет выдавать подробную информацию.