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

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>

Сохранить результирующий статус операции в переменную. Статус — список длиной 2, разделённый ;. Первый элемент — числовое возвращаемое значение операции, второй — строковое значение ошибки. Числовое значение ошибки 0 означает отсутствие ошибки в операции.

TIMEOUT <seconds>

Прекратить операцию после истечения заданного общего времени.

USERPWD <username>:<password>

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

Установить имя пользователя и пароль для операции.

HTTPHEADER <HTTP-header>

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

HTTP-заголовок для операций DOWNLOAD и UPLOAD. HTTPHEADER может быть повторено для нескольких параметров:

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

NETRC <level>

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

Указать, должен ли использоваться файл .netrc для операции. Если этот параметр не указан, будет использоваться значение переменной CMAKE_NETRC.

Допустимые значения:

IGNORED: Файл .netrc игнорируется. Это значение по умолчанию.
OPTIONAL: Файл .netrc необязателен, и информация из URL имеет приоритет. Файл будет прочитан для поиска информации, которая не указана в URL.
REQUIRED: Файл .netrc необходим, и информация из URL игнорируется.

NETRC_FILE <file>

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

Указать альтернативный файл .netrc по отношению к файлу в вашем домашнем каталоге, если уровень NETRC равен OPTIONAL или REQUIRED. Если этот параметр не указан, будет использоваться значение переменной CMAKE_NETRC_FILE.

TLS_VERSION <min>

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

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

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

TLS_VERIFY <ON|OFF>

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

Изменено в версии 3.31: Значение по умолчанию — включено. Раньше значение по умолчанию было выключено. Пользователи могут установить переменную среды CMAKE_TLS_VERIFY в 0 для восстановления старого значения по умолчанию.

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

TLS_CAINFO <file>

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

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

Для https:// URL 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>]] [MTIME <mtime>] [WORKING_DIRECTORY <dir>] [VERBOSE])

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

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

Доступны следующие опции:

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

Примечание

При установке FORMAT в значение raw только один файл будет сжат с использованием типа сжатия, указанного в COMPRESSION.
COMPRESSION_LEVEL <compression-level>: Добавлен в версии 3.19.

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

Добавлен в версии 3.26: Значение <compression-level> алгоритма Zstd может быть установлено в диапазоне от 0 до 19.
MTIME <mtime>: Указывает время изменения, записываемое в записи tarball.
WORKING_DIRECTORY <dir>: Добавлен в версии 3.31.

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

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

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

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

Доступные опции:

DESTINATION <dir>: Указывает каталог, в который будет извлечено содержимое архива. Если каталог не существует, он будет создан. Если DESTINATION не указан, используется текущий каталог бинарных файлов.
PATTERNS <pattern>...: Извлекать/отображать только файлы и каталоги, соответствующие одному из заданных шаблонов. Поддерживаются подстановки. Если опция PATTERNS не указана, будет отображён или извлечён весь архив.
LIST_ONLY: Отобразить содержимое архива, а не извлечь его.
TOUCH: Добавлен в версии 3.24.

Присвоить извлечённым файлам текущее локальное время вместо извлечения времени создания файлов из архива.
VERBOSE: Включить подробный вывод при операции извлечения.

Примечание

Рабочий каталог для этой подкоманды — каталог 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, который обозначает "главный" исполняемый файл пакета.

Следующие аргументы задают фильтры для включения или исключения библиотек, которые нужно разрешить. Более подробное описание того, как они работают, приведено ниже.

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 преобразуются в нижний регистр для соответствия фильтрам. Имена Windows DLL нечувствительны к регистру, а некоторые линковщики изменяют регистр имён зависимостей 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/latest/command/file.html