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

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

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

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

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

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

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

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

LIST_ONLY будет отображать файлы в архиве, а не извлекать их.

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