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 и более ранних версиях требовалось указать хотя бы один файл.

END_OF_DOCUMENT_MARKER ```

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 и подкаталогах

END_OF_DOCUMENT_MARKER ```

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)

Это установит все символические ссылки и 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 для каталогов.

END_OF_DOCUMENT_MARKER

file(CHMOD_RECURSE <files>... <directories>... [PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...]): Added in version 3.19.

То же, что и CHMOD, но изменяет разрешения файлов и каталогов, присутствующих в <directories>... рекурсивно.

Преобразование путей

file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])

Added in version 3.19.

Вычислить абсолютный путь к существующему файлу или каталогу с разрешёнными символическими ссылками. Доступные параметры:

BASE_DIRECTORY <dir>: Если предоставленный <path> — относительный путь, он вычисляется относительно заданного базового каталога <dir>. Если базовый каталог не задан, по умолчанию используется базовый каталог CMAKE_CURRENT_SOURCE_DIR.
EXPAND_TILDE: Added in version 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 архивам, поскольку их маловероятно удастся извлечь, используя относительный путь.

Обработка библиотек 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. Для каждого имени файла список путей, которые были найдены для этого имени файла, хранятся в <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 преобразуются в нижний регистр для сопоставления с фильтрами. Имена 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.31/command/file.html