file

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

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

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

Синтаксис

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

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

Filesystem
  file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
  file(RENAME <oldname> <newname> [...])
  file(COPY_FILE <oldname> <newname> [...])
  file({REMOVE | REMOVE_RECURSE } [<files>...])
  file(MAKE_DIRECTORY [<dir>...])
  file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
  file(SIZE <filename> <out-var>)
  file(READ_SYMLINK <linkname> <out-var>)
  file(CREATE_LINK <original> <linkname> [...])
  file(CHMOD <files>... <directories>... PERMISSIONS <permissions>... [...])
  file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... [...])

Path Conversion
  file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [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(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>. В противном случае генерируется сообщение об ошибке.

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

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

file(MAKE_DIRECTORY [<directories>...])

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

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

file(SIZE <filename> <variable>)

Определите размер файла <filename> и поместите результат в переменную <variable>. Требуется, чтобы <filename> был допустимым путём к файлу и был доступен для чтения.

file(READ_SYMLINK <linkname> <variable>)

Эта подкоманда запрашивает символическую ссылку <linkname> и сохраняет путь, на который она указывает, в результате <variable>. Если <linkname> не существует или не является символической ссылкой, CMake выводит ошибку.

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

set(linkname "/path/to/foo.sym")
file(READ_SYMLINK "${linkname}" result)
if(NOT IS_ABSOLUTE "${result}")
  get_filename_component(dir "${linkname}" DIRECTORY)
  set(result "${dir}/${result}")
endif()

file(CREATE_LINK <original> <linkname>
     [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])

Создайте ссылку <linkname>, указывающую на <original>. По умолчанию это жёсткая ссылка, но использование опции SYMBOLIC приводит к созданию символической ссылки вместо этого. Для жёстких ссылок необходимо, чтобы original существовал и был файлом, а не каталогом. Если <linkname> уже существует, он будет перезаписан.

Переменная <result>, если указана, получает статус операции. Она устанавливается в значение 0 при успехе или сообщении об ошибке в противном случае. Если RESULT не указана и операция завершается ошибкой, генерируется критическая ошибка.

Указание COPY_ON_ERROR позволяет скопировать файл как резервный вариант, если создание ссылки завершается ошибкой. Это может быть полезно для обработки ситуаций, когда <original> и <linkname> находятся на разных дисках или точках монтирования, что не позволит создать жёсткую ссылку.

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

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

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

PERMISSIONS

Все элементы изменяются.

FILE_PERMISSIONS

Изменяются только файлы.

DIRECTORY_PERMISSIONS

Изменяются только каталоги.

PERMISSIONS and FILE_PERMISSIONS

FILE_PERMISSIONS переопределяет PERMISSIONS для файлов.

PERMISSIONS and DIRECTORY_PERMISSIONS

DIRECTORY_PERMISSIONS переопределяет PERMISSIONS для каталогов.

FILE_PERMISSIONS and DIRECTORY_PERMISSIONS

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

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

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

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

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

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

TLS_VERIFY <ON|OFF>

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

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

TLS_CAINFO <file>

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

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

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

Дополнительные параметры для DOWNLOAD:

EXPECTED_HASH ALGO=<value>

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

EXPECTED_MD5 <value>

Исторический сокращённый синтаксис для EXPECTED_HASH MD5=<value>. Задание этого параметра при отсутствии DOWNLOAD с <file> является ошибкой.

Блокировка

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

Заблокировать файл, указанный в <path>, если параметр DIRECTORY не задан, и файл <path>/cmake.lock в противном случае. Файл будет заблокирован на период, определённый параметром GUARD (значение по умолчанию — PROCESS). Параметр 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, команда выведет подробный вывод.