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 Store, и зависимость указана в манифесте пакета приложения, зависимость разрешается на этот файл.
3. В противном случае, если библиотека существует в той же директории, что и зависящий файл, зависимость разрешается на этот файл.
4. В противном случае, если библиотека существует в каталоге операционной системы system32 или каталоге Windows, в указанном порядке, зависимость разрешается на этот файл.
5. В противном случае, если библиотека существует в одном из каталогов, указанных в DIRECTORIES, в порядке их перечисления, зависимость разрешается на этот файл. В этом случае предупреждение не выводится, потому что поиск в других каталогах является нормальной частью разрешения библиотек Windows.
6. В противном случае зависимость не разрешена.

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

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

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

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM

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

• linux+elf
• windows+pe
• macos+macho

Если эта переменная не указана, она определяется автоматически с помощью интроспекции системы.

CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

Определяет инструмент, используемый для разрешения зависимостей. Он может принимать несколько значений, в зависимости от значения CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM:

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM	CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
linux+elf	objdump
windows+pe	dumpbin
windows+pe	objdump
macos+macho	otool

Если эта переменная не указана, она определяется автоматически с помощью интроспекции системы.

CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

Определяет путь к инструменту, используемому для разрешения зависимостей. Это фактический путь к objdump, dumpbin, или otool.

Если эта переменная не указана, она определяется по значению CMAKE_OBJDUMP, если оно задано, иначе по интроспекции системы.

New in version 3.18: Используйте CMAKE_OBJDUMP если оно задано.

Запись

file(WRITE <filename> <content>...)
file(APPEND <filename> <content>...)

Запишите <content> в файл с именем <filename>. Если файл не существует, он будет создан. Если файл уже существует, режим WRITE перепишет его, а режим APPEND добавит в конец. Любые каталоги в пути, указанном в <filename>, которые не существуют, будут созданы.

Если файл является входным для сборки, используйте команду configure_file(), чтобы обновить файл только при изменении его содержимого.

file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])

Создайте файл без содержимого, если он еще не существует. Если файл уже существует, его доступ и/или изменение будут обновлены до времени выполнения вызова функции.

Используйте TOUCH_NOCREATE для изменения времени файла, если он существует, но не создавайте его. Если файл не существует, он будет проигнорирован.

С помощью TOUCH и TOUCH_NOCREATE содержимое существующего файла не будет изменено.

file(GENERATE OUTPUT output-file
     <INPUT input-file|CONTENT content>
     [CONDITION expression] [TARGET target]
     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
      FILE_PERMISSIONS <permissions>...]
     [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

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

CONDITION <condition>

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

CONTENT <content>

Использовать явно заданный ввод.

INPUT <input-file>

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

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

OUTPUT <output-file>

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

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

TARGET <target>

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

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

NO_SOURCE_PERMISSIONS

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

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

USE_SOURCE_PERMISSIONS

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

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

FILE_PERMISSIONS <permissions>...

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

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

NEWLINE_STYLE <style>

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

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

Должен быть задан ровно один CONTENT или INPUT параметр. Конкретный файл OUTPUT может быть назван не более чем одним вызовом file(GENERATE). Сгенерированные файлы изменяются, и их метка времени обновляется при последующих запусках 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]
     [INPUT_MAY_BE_RECENT])

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

Доступны следующие параметры:

RESULT <result>

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

ONLY_IF_DIFFERENT

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

INPUT_MAY_BE_RECENT

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

Указать CMake, что входной файл мог быть недавно создан. Это имеет значение только в Windows, где файлы могут быть недоступны в течение короткого времени после их создания. С помощью этого параметра, если доступ к файлу запрещён, CMake будет несколько раз повторно пытаться его считать.

Этот подкоманда имеет некоторые сходства с 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>

Сохранить результирующий статус операции в переменной. Статус — это список из двух элементов, разделённых ;. Первый элемент — числовое возвращаемое значение операции, а второй — строковое значение ошибки. Числовое значение ошибки 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, команда выведет подробный вывод.