file

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

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

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

Примечание

Подкоманды RELATIVE_PATH, TO_CMAKE_PATH и TO_NATIVE_PATH были заменены соответственно подкомандами RELATIVE_PATH, CONVERT ... TO_CMAKE_PATH_LIST и CONVERT ... TO_NATIVE_PATH_LIST команды 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 <directories>...)
  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).

Изменено в версии 3.29: Группы захвата из последней совпавшей строки в файле хранятся в CMAKE_MATCH_<n>, аналогично string(REGEX MATCHALL). См. политику CMP0159.
ENCODING <encoding-type>: Новое в версии 3.1.

Рассматривать строки заданной кодировки. В настоящее время поддерживаются кодировки: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. Если опция ENCODING не указана, а файл имеет метку порядка байтов, опция ENCODING будет установлена по умолчанию, учитывая метку порядка байтов.

Новое в версии 3.2: Добавлены кодировки UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.

Например, код

file(STRINGS myfile.txt myfile)

сохраняет список в переменной myfile, где каждый элемент — строка из входного файла.

file(<HASH> <filename> <variable>): Вычислить криптографический хэш содержимого <filename> и сохранить его в <variable>. Поддерживаемые алгоритмы хэширования - те, которые перечислены командой string(<HASH>).

file(TIMESTAMP <filename> <variable> [<format>] [UTC])

Вычислить строковое представление времени модификации <filename> и сохранить его в <variable>. Если команда не сможет получить временную метку, переменная будет установлена в пустую строку ("").

См. команду string(TIMESTAMP) для получения документации по опциям <format> и UTC.

END_OF_DOCUMENT_MARKER ```

file(GET_RUNTIME_DEPENDENCIES [...])

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

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

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.

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

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

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

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

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

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

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

Имена зависимостей 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.)

Изменено в версии 3.27: Преобразование в нижний регистр применяется только при сопоставлении с фильтрами. Результаты, отчёт о которых составлен после фильтрации, сохраняют каждый имя DLL в том виде, в котором оно найдено на диске, если оно разрешено, и в противном случае, как оно упоминается в зависимом двоичном файле.

До CMake 3.27 результаты отчёта составлялись с именами файлов DLL в нижнем регистре, но часть пути сохраняла свой регистр.
(Ещё не реализовано) Если зависимый файл является приложением Windows Store, и зависимость перечислена в манифесте пакета приложения, зависимость разрешается к этому файлу.
В противном случае, если библиотека существует в той же директории, что и зависимый файл, зависимость разрешается к этому файлу.
В противном случае, если библиотека существует либо в каталоге операционной системы system32, либо в каталоге Windows, в указанном порядке, зависимость разрешается к этому файлу.
В противном случае, если библиотека существует в одном из каталогов, указанных в DIRECTORIES, в порядке их перечисления, зависимость разрешается к этому файлу. В этом случае предупреждение не выдаётся, потому что поиск в других каталогах является нормальной частью разрешения библиотек в Windows.
В противном случае зависимость не разрешается.

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

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

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

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`	`objdump` или `dumpbin`
`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>...)

Добавлено в версии 3.12.

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

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

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

file(GENERATE [...])

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

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

Опции:

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

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

Генерирует выходной файл, используя входные данные, предоставленные 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, результаты будут возвращены как относительные пути к заданному пути.

Изменено в версии 3.6: Результаты будут упорядочены лексикографически.

В Windows и macOS подстановка игнорирует регистр, даже если файловая система чувствительна к регистру (имена файлов и выражения подстановки приводятся к нижнему регистру перед сопоставлением). На других платформах подстановка чувствительна к регистру.

Новое в версии 3.3: По умолчанию GLOB перечисляет каталоги. Каталоги опускаются из результата, если LIST_DIRECTORIES установлен в значение false.

Новое в версии 3.12: Если задан флаг CONFIGURE_DEPENDS, CMake добавит логику в цель проверки основной системы сборки, чтобы повторно выполнить помеченные GLOB команды во время сборки. Если любой из выходов изменится, CMake пересоздаст систему сборки.

Примечание

Не рекомендуется использовать GLOB для сбора списка исходных файлов из вашей исходной структуры. Если файл CMakeLists.txt не изменяется при добавлении или удалении исходного файла, сгенерированная система сборки не сможет знать, когда нужно попросить CMake перегенерировать её. Флаг CONFIGURE_DEPENDS может работать ненадёжно на всех генераторах или, если в будущем будет добавлен новый генератор, который не поддерживает его, проекты, использующие его, застрянут. Даже если CONFIGURE_DEPENDS работает надёжно, существует затраты на выполнение проверки при каждой пересборке.

Примеры выражений подстановки:

`*.cxx`	сопоставить все файлы с расширением `cxx`
`*.vt?`	сопоставить все файлы с расширением `vta`, ..., `vtz`
`f[3-5].txt`	сопоставить файлы `f3.txt`, `f4.txt`, `f5.txt`

Рекурсивный режим GLOB_RECURSE будет обходить все подкаталоги сопоставленного каталога и сопоставлять файлы. Подкаталоги, которые являются символическими ссылками, будут обходиться только если FOLLOW_SYMLINKS задан или политика CMP0009 не установлена в NEW.

Новое в версии 3.3: По умолчанию GLOB_RECURSE опускает каталоги из списка результатов. Установка LIST_DIRECTORIES в значение true добавляет каталоги в список результатов. Если задан FOLLOW_SYMLINKS или политика CMP0009 не установлена в NEW, то LIST_DIRECTORIES рассматривает символические ссылки как каталоги.

Примеры рекурсивной подстановки:

/dir/*.py

сопоставить все файлы python в /dir и подкаталогах

file(MAKE_DIRECTORY <directories>...): Создаёт заданные каталоги и их родительские каталоги по мере необходимости.

file(REMOVE <files>...)
file(REMOVE_RECURSE <files>...): Удаляет указанные файлы. Режим REMOVE_RECURSE удалит указанные файлы и каталоги, включая непустые каталоги. Если указанный файл не существует, ошибка не выдаётся. Относительные пути ввода обрабатываются относительно текущего каталога исходных файлов.

Изменено в версии 3.15: Пустые пути ввода игнорируются с предупреждением. Предыдущие версии CMake интерпретировали пустые строки как относительный путь относительно текущего каталога и удаляли его содержимое.

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

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

Копирует файл из <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 [...])

file(INSTALL [...])

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

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

Примечание

Для простой операции копирования файла можно использовать подкоманду file(COPY_FILE) чуть выше.

Новое в версии 3.15: Если указан FOLLOW_SYMLINK_CHAIN, COPY будет рекурсивно разрешать символьные ссылки по указанным путям до нахождения реального файла и устанавливать соответствующую символьную ссылку в пункт назначения для каждой встреченной символьной ссылки. Для каждой установленной символьной ссылки разрешение обрезается до имени файла, оставляя только имя файла, что означает, что новая символьная ссылка указывает на файл в той же директории, что и символьная ссылка. Эта функция полезна на некоторых системах Unix, где библиотеки устанавливаются как цепочка символьных ссылок с номерами версий, где менее специфичные версии указывают на более специфичные версии. FOLLOW_SYMLINK_CHAIN будет устанавливать все эти символьные ссылки и саму библиотеку в папку назначения. Например, если у вас есть следующая структура каталогов:

/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(), используют эту подпись (с некоторыми неудокументированными опциями для внутреннего использования).

Изменено в версии 3.22: Переменная окружения CMAKE_INSTALL_MODE может переопределить поведение копирования по умолчанию для file(INSTALL).

file(SIZE <filename> <variable>): Новое в версии 3.14.

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

file(READ_SYMLINK <linkname> <variable>)

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

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

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

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

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

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

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

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

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

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

Установить разрешения для <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>...]): Новое в версии 3.19.

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

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

file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])

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

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

BASE_DIRECTORY <dir>: Если предоставленный <path> является относительным путём, он обрабатывается относительно заданной базовой директории <dir>. Если базовая директория не указана, по умолчанию используется CMAKE_CURRENT_SOURCE_DIR.
EXPAND_TILDE: Новое в версии 3.21.

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

Изменено в версии 3.28: Все символьные ссылки разрешаются до сжатия ../ компонентов. См. политику CMP0152.

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>.

Добавлено в версии 3.19: Если <file> не указано для file(DOWNLOAD), файл не сохраняется. Это может быть полезно, если вы хотите узнать, можно ли загрузить файл (например, чтобы проверить, существует ли он), не сохраняя его нигде.

Опции для 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-заголовок для операций DOWNLOAD и UPLOAD. HTTPHEADER может повторяться для нескольких вариантов:

file(DOWNLOAD <url>
     HTTPHEADER "Authorization: Bearer <auth-token>"
     HTTPHEADER "UserAgent: Mozilla/5.0")

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 <algorithm>=<value>: Проверить, соответствует ли контрольная сумма загруженного содержимого ожидаемому значению, где <algorithm> — один из алгоритмов, поддерживаемых <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>])

Добавлено в версии 3.2.

Заблокировать файл, указанный <path>, если опция DIRECTORY отсутствует, и файл <path>/cmake.lock в противном случае. Файл будет заблокирован на период, определяемый опцией GUARD (значение по умолчанию — PROCESS). Опция RELEASE может быть использована для явного разблокирования файла. Если опция TIMEOUT не указана, CMake будет ожидать, пока блокировка не выполнится, или произойдёт фатальная ошибка. Если TIMEOUT установлено в 0, блокировка будет выполнена один раз, и результат будет сообщён сразу. Если TIMEOUT не 0, CMake будет пытаться заблокировать файл на период, указанный значением TIMEOUT <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])

Добавлено в версии 3.18.

Создаёт указанный <archive> файл с файлами и каталогами, перечисленными в <paths>. Обратите внимание, что <paths> должен содержать фактические файлы или каталоги; подстановочные знаки не поддерживаются.

Используйте опцию FORMAT для указания формата архива. Поддерживаемые значения для <format>: 7zip, gnutar, pax, paxr, raw и zip. Если FORMAT не указано, по умолчанию используется формат paxr.

Некоторые форматы архивов позволяют указывать тип сжатия. Форматы архивов 7zip и zip уже подразумевают конкретный тип сжатия. Другие форматы по умолчанию не используют сжатие, но могут быть настроены на его использование с помощью опции COMPRESSION. Допустимые значения для <compression>: None, BZip2, GZip, XZ, и Zstd.

Добавлено в версии 3.19: Уровень сжатия можно указать с помощью опции COMPRESSION_LEVEL. Значение <compression-level> должно быть в диапазоне от 0 до 9, по умолчанию 0. Опция COMPRESSION должна присутствовать при указании COMPRESSION_LEVEL.

Добавлено в версии 3.26: Можно настроить <compression-level> алгоритма Zstd в диапазоне от 0 до 19.

Примечание

При FORMAT в raw, только один файл будет сжат с типом сжатия, указанным COMPRESSION.

Опция VERBOSE включает подробный вывод для операции архивирования.

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

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

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

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

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

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

LIST_ONLY отобразит файлы в архиве вместо их извлечения.

Примечание

Рабочая директория для этой подкоманды — директория DESTINATION (предоставленная или вычисленная), за исключением случаев, когда указана опция LIST_ONLY. Поэтому вне режима скриптов, возможно, лучше указывать абсолютные пути к INPUT архивам, так как их извлечение по относительному пути может быть непредсказуемым.

Новое в версии 3.24: Опция TOUCH задает текущую локальную метку времени для извлеченных файлов вместо извлечения меток времени из архива.

Использование VERBOSE, команда выведет подробный вывод.

© 2000–2024 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.29/command/file.html