file

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

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

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

Примечание

Подкоманды file(RELATIVE_PATH), file(TO_CMAKE_PATH) и file(TO_NATIVE_PATH) были заменены соответственно подкомандами cmake_path(RELATIVE_PATH), cmake_path(CONVERT ... TO_CMAKE_PATH_LIST) и cmake_path(CONVERT ... TO_NATIVE_PATH_LIST).

Сводка

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

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

Handling Runtime Binaries
  file(GET_RUNTIME_DEPENDENCIES [...])

Чтение

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>. Поддерживаемые имена алгоритмов <HASH> перечислены в описании команды string(<HASH>).

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

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

Описание параметров <format> и UTC см. в команде string(TIMESTAMP).

Запись

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 содержимое существующего файла не изменяется.

Изменено в версии 3.30: <files> может быть пустым списком. В CMake 3.29 и более ранних версиях требовалось указать хотя бы один файл.

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>. Шаблоны glob похожи на регулярные выражения, но значительно проще. Если указан флаг RELATIVE, результаты будут представлены в виде относительных путей относительно заданного пути.

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

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

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

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

Примечание

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

Примеры шаблонов glob:

`*.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 рассматривает символические ссылки как каталоги.

Пример рекурсивного поиска по шаблону glob:

/dir/*.py

соответствует всем файлам Python в /dir и его подкаталогах

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

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

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

RESULT <result>: Добавлено в версии 3.31.

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

Изменено в версии 3.30: <directories> может быть пустым списком. В CMake 3.29 и более ранних версиях требовалось указать хотя бы один каталог.

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)

в целевой каталог lib будут установлены все символические ссылки и сама libfoo.so.1.2.3.

Описание прав доступа и параметров FILES_MATCHING, PATTERN, REGEX и EXCLUDE см. в команде install(DIRECTORY). При копировании каталогов структура их содержимого сохраняется, даже если параметры используются для выбора подмножества файлов.

Форма 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> [RESULT <result>])

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

Запросить символическую ссылку <linkname> и сохранить путь, на который она указывает, в результирующей переменной <variable>.

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

RESULT <result>: Добавлено в версии 4.4.

Сохранить результат операции в переменной <result>. В случае успеха переменной присваивается значение 0, иначе — сообщение об ошибке. Если этот параметр не указан и операция завершается с ошибкой, возникает критическая ошибка.

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

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> на разных дисках или точках монтирования, из-за чего невозможно создать жёсткую ссылку.

Изменено в версии 4.3: Если источник является каталогом, версии CMake до 4.3 создают каталог назначения, если он не существует, но не копируют в него файлы. В CMake 4.3 и более поздних версиях содержимое исходного каталога рекурсивно копируется в каталог назначения. См. политику CMP0205.

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, а если USERPROFILE не определена — переменная HOME. На всех остальных платформах используется только 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}. Путь поиска преобразуется в список, разделённый точками с запятой.

Режим TO_NATIVE_PATH преобразует <path> в формате CMake в собственный для платформы путь с соответствующими косыми чертами (\ в Windows и / в других системах).

Всегда заключайте <path> в двойные кавычки, чтобы эта команда обрабатывала его как один аргумент.

Передача данных

file(DOWNLOAD <url> [<file>] <options>...)

file(UPLOAD <file> <url> <options>...)

Подкоманда DOWNLOAD загружает указанный <url> в локальный <file>. Режим UPLOAD отправляет локальный <file> по указанному <url>.

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

Параметры для 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_VERSION <min>

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

Задаёт минимальную версию TLS для URL https://. Если этот параметр не указан, вместо него используется значение переменной CMAKE_TLS_VERSION или переменной среды CMAKE_TLS_VERSION. Допустимые значения см. в CMAKE_TLS_VERSION.

Изменено в версии 3.31: По умолчанию используется TLS 1.2. Ранее минимальная версия по умолчанию не ограничивалась.

TLS_VERIFY <ON|OFF>

Указывает, следует ли проверять сертификат сервера для URL https://. Если этот параметр не указан, вместо него используется значение переменной CMAKE_TLS_VERIFY или переменной среды CMAKE_TLS_VERIFY. Если ни одна из них не задана, по умолчанию используется значение on.

Изменено в версии 3.31: По умолчанию используется значение on. Ранее по умолчанию использовалось значение off. Чтобы восстановить прежнее значение по умолчанию, можно задать переменной среды CMAKE_TLS_VERIFY значение 0.

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

TLS_CAINFO <file>

Указывает пользовательский файл центра сертификации для URL https://. Если этот параметр не указан, вместо него используется значение переменной CMAKE_TLS_CAINFO.

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

Для URL https:// CMake должен быть собран с поддержкой SSL/TLS.

Дополнительные параметры для 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>]] [ENCODING <encoding>] [MTIME <mtime>] [THREADS <number>] [WORKING_DIRECTORY <dir>] [VERBOSE])

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

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

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

FORMAT <format>

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

Метод сжатия по умолчанию зависит от формата:

7zip использует сжатие LZMA
zip использует сжатие Deflate
для остальных форматов по умолчанию сжатие не используется

COMPRESSION <compression>

В некоторых форматах архивов можно указать тип сжатия. Форматы архивов 7zip и zip уже подразумевают определённый тип сжатия. В остальных форматах по умолчанию сжатие не используется, но его можно включить с помощью параметра COMPRESSION. Допустимые значения для <compression>:

None
BZip2
Deflate

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

Это псевдоним для GZip.
GZip
LZMA

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

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

Это псевдоним для XZ.
PPMd

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

Этот метод сжатия поддерживается только форматом архива 7zip.
XZ
Zstd

Примечание

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

Добавлено в версии 4.3: Форматы 7zip и zip поддерживают изменение метода сжатия по умолчанию.

COMPRESSION_LEVEL <compression-level>

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

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

Значение 0 задаёт уровень сжатия по умолчанию. Он выбирается автоматически серверной частью библиотеки архивации и напрямую CMake не задаётся. Уровень сжатия по умолчанию может различаться в зависимости от формата архива, платформы и других условий.

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

Добавлено в версии 4.3: Параметр <compression-level> можно также указывать для форматов 7zip и zip. Уровень сжатия алгоритма Zstd можно задавать в диапазоне от 0 до 19, за исключением формата zip.

ENCODING <encoding>

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

Задаёт кодировку символов в путях, используемую в архиве.

Значение <encoding> может быть одним из следующих:

UTF-8

Пути в архиве кодируются в UTF-8.

В CMake 4.4 и более ранних версиях это значение используется по умолчанию. Сведения о совместимости с CMake 4.3 и более ранними версиями см. в политике CMP0213.

OEM

На платформах Windows пути кодируются с использованием OEM-кодовой страницы. На платформах, отличных от Windows, кодировка путей соответствует текущей локали.

В CMake 4.3 и более ранних версиях всегда использовалась кодировка OEM (текущая локаль).

UTF-16LE, UTF-16BE

Пути в архиве кодируются в UTF-16 с порядком байтов от младшего к старшему или от старшего к младшему.

...

Любое имя кодировки, поддерживаемое iconv на текущей платформе. В Windows можно указывать имена кодовых страниц.

Примечание

В архивах 7zip пути всегда кодируются как UTF-16LE, поэтому этот параметр для данного формата молча игнорируется.

MTIME <mtime>

Задаёт время изменения, записываемое в записи tar-архива.

THREADS <number>

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

Использует для работы с архивом потоки <number>.

Если задано значение 0, используется количество доступных ядер компьютера. Обратите внимание, что не все режимы сжатия поддерживают многопоточность во всех средах.

WORKING_DIRECTORY <dir>

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

Задаёт каталог, в котором будет выполняться операция создания архива. Пути в аргументе <paths> могут быть относительными относительно этого каталога. Если этот параметр не указан, по умолчанию используется текущий рабочий каталог.

VERBOSE

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

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

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

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

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

DESTINATION <dir>

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

ENCODING <encoding>

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

Задаёт кодировку символов в путях, используемую в архиве.

Значение <encoding> может быть одним из следующих:

UTF-8

Пути в архиве кодируются в UTF-8.

В CMake 4.3 и более ранних версиях это значение используется по умолчанию, если для CMP0213 задано значение NEW.

OEM

В CMake 4.3 и более ранних версиях всегда использовалась кодировка OEM (текущая локаль).

В CMake 4.4 и более поздних версиях кодировка OEM (текущая локаль) используется, только если для CMP0213 задано значение, отличное от NEW.

UTF-16LE, UTF-16BE

Пути в архиве кодируются в UTF-16 с порядком байтов от младшего к старшему или от старшего к младшему.

...

Любое имя кодировки, поддерживаемое iconv на текущей платформе. В Windows можно указывать имена кодовых страниц.

Примечание

PATTERNS <pattern>...

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

LIST_ONLY

Выводит список файлов в архиве вместо их извлечения.

TOUCH

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

Присваивает извлечённым файлам текущую локальную временную метку вместо извлечения временных меток файлов из архива.

VERBOSE

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

Изменено в версии 4.3: Записи архива, содержащие последовательности перехода по путям (..) или абсолютные пути, отклоняются в целях безопасности.

Примечание

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

Работа с двоичными файлами времени выполнения

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, обозначающий «главный» исполняемый файл пакета.

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

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 означает, что файл-зависимый компонент неполон (в нем перечислены не все каталоги, из которых он загружает зависимости).
В противном случае зависимость остается неразрешенной.

Изменено в версии 3.31: При обработке заданного корневого ELF-файла (исполняемого файла или разделяемого объекта) имя каждого найденного файла библиотеки разрешается не более одного раза. Если имя файла библиотеки встречается в дереве зависимостей повторно, предполагается, что оно разрешается так же, как и при первом поиске. Это поведение точнее соответствует работе динамического загрузчика в Linux.

На платформах 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, если она задана.

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