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

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>: Список пре-включений (regex), которые фильтруют имена еще не разрешенных зависимостей.
PRE_EXCLUDE_REGEXES <regexes>: Список пре-исключений (regex), которые фильтруют имена еще не разрешенных зависимостей.
POST_INCLUDE_REGEXES <regexes>: Список пост-включений (regex), которые фильтруют имена разрешенных зависимостей.
POST_EXCLUDE_REGEXES <regexes>: Список пост-исключений (regex), которые фильтруют имена разрешенных зависимостей.
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 - каждый regex должен проверять как прописные, так и строчные буквы. Например:
```
file(GET_RUNTIME_DEPENDENCIES
  # ...
  PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
  )
```
Преобразование имени DLL в нижний регистр позволяет regex сопоставлять только имена в нижнем регистре, что упрощает regex. Например:
```
file(GET_RUNTIME_DEPENDENCIES
  # ...
  PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
  )
```
Этот regex будет сопоставляться с 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 выдаёт ошибку.

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

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 не указана и операция завершается неудачей, выдаётся ошибка.

Указание 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.

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>

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

END_OF_DOCUMENT_MARKER

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

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

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

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

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

LIST_ONLY будет перечислять файлы в архиве, а не извлекать их.

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

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

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