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

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>. Если команда не может получить метку времени, переменная будет установлена в пустую строку ("").

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

Запись

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

Изменено в версии 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), которая предоставляет дополнительные возможности копирования файлов.

END_OF_DOCUMENT_MARKER

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>

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

TLS_VERIFY <ON|OFF>

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

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

TLS_CAINFO <file>

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

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

Для https:// URL CMake должен быть скомпилирован с поддержкой OpenSSL. Сертификаты TLS/SSL по умолчанию не проверяются. Установите TLS_VERIFY в ON, чтобы проверить сертификаты.

Дополнительные опции к DOWNLOAD:

EXPECTED_HASH <algorithm>=<value>: Проверить, соответствует ли хэш загруженного содержимого ожидаемому значению, где <algorithm> — один из алгоритмов, поддерживаемых <HASH>. Если файл уже существует и соответствует хэшу, загрузка пропускается. Если файл уже существует, но хэши не совпадают, файл загружается снова. Если после загрузки файл не соответствует хэшу, операция завершается с ошибкой. Указание этой опции является ошибкой, если DOWNLOAD не получает <file>.
EXPECTED_MD5 <value>: Исторический сокращённый вариант EXPECTED_HASH MD5=<value>. Указание этой опции является ошибкой, если DOWNLOAD не получает <file>.
RANGE_START <value>: Новая в версии 3.24.

Смещение начала диапазона в файле в байтах. Может быть опущено для загрузки до указанного RANGE_END.
RANGE_END <value>: Новая в версии 3.24.

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

Блокировка

file(LOCK <path> [DIRECTORY] [RELEASE] [GUARD <FUNCTION|FILE|PROCESS>] [RESULT_VARIABLE <variable>] [TIMEOUT <seconds>])

Новая в версии 3.2.

Блокировать файл, указанный в <path>, если опция DIRECTORY отсутствует, и файл <path>/cmake.lock в противном случае. Файл будет заблокирован на срок, определённый опцией GUARD (значение по умолчанию — PROCESS). Опция RELEASE может быть использована для явного разблокирования файла. Если опция TIMEOUT не указана, CMake будет ожидать, пока блокировка не будет успешной или пока не произойдёт ошибка. Если TIMEOUT установлено в 0, блокировка будет попытана один раз, а результат будет сообщён немедленно. Если TIMEOUT не равно 0, CMake будет пытаться заблокировать файл на срок, указанный в значении TIMEOUT <seconds>. Любые ошибки будут интерпретироваться как критические, если нет опции RESULT_VARIABLE В противном случае результат будет сохранён в <variable> и будет 0 при успехе или сообщение об ошибке при неудаче.

Обратите внимание, что блокировка является рекомендательной; нет гарантии, что другие процессы будут соблюдать эту блокировку, т.е. блокировка не синхронизирует два или более экземпляров CMake, которые совместно используют некоторые изменяемые ресурсы. Аналогичная логика применима к опции DIRECTORY; блокировка родительского каталога не предотвращает другие команды LOCK от блокирования любого дочернего каталога или файла.

Попытка дважды заблокировать один и тот же файл запрещена. Все промежуточные каталоги и сам файл будут созданы, если они не существуют. Опции GUARD и TIMEOUT игнорируются в операции RELEASE.

Архивирование

file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [FORMAT <format>] [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] [MTIME <mtime>] [VERBOSE])

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

Обработка бинарных файлов runtime

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

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