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

Новое в версии 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> является ошибкой.

RANGE_START <value>

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

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

RANGE_END <value>

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

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

Блокировка

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]
  [TOUCH])

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

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

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

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

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