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

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

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.

Изменено в версии 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>

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

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

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.28/command/file.html