file

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

Сводка

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

Writing
  file({WRITE | APPEND} <filename> <content>...)
  file({TOUCH | TOUCH_NOCREATE} [<file>...])
  file(GENERATE OUTPUT <output-file> [...])
  file(CONFIGURE OUTPUT <output-file> CONTENT <content> [...])

Filesystem
  file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
  file(RENAME <oldname> <newname>)
  file({REMOVE | REMOVE_RECURSE } [<files>...])
  file(MAKE_DIRECTORY [<dir>...])
  file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
  file(SIZE <filename> <out-var>)
  file(READ_SYMLINK <linkname> <out-var>)
  file(CREATE_LINK <original> <linkname> [...])

Path Conversion
  file(RELATIVE_PATH <out-var> <directory> <file>)
  file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)

Transfer
  file(DOWNLOAD <url> <file> [...])
  file(UPLOAD <file> <url> [...])

Locking
  file(LOCK <path> [...])

Archiving
  file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [...])
  file(ARCHIVE_EXTRACT INPUT <archive> [...])

Чтение

file(READ <filename> <variable>
     [OFFSET <offset>] [LIMIT <max-in>] [HEX])

Прочитать содержимое файла под названием <filename> и сохранить его в <variable>. Допустимо начать чтение с указанного <offset> и прочитать не более <max-in> байт. Опция HEX преобразует данные в шестнадцатеричное представление (полезно для двоичных данных). Если указана опция HEX, буквы в выводе (a по f) будут в нижнем регистре.

file(STRINGS <filename> <variable> [<options>...])

Разобрать список ASCII-строк из <filename> и сохранить их в <variable>. Двоичные данные в файле игнорируются. Символы возврата каретки (\r, CR) игнорируются. Доступны следующие опции:

LENGTH_MAXIMUM <max-len>

Учитывать только строки длиной не более заданной.

LENGTH_MINIMUM <min-len>

Учитывать только строки длиной не менее заданной.

LIMIT_COUNT <max-num>

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

LIMIT_INPUT <max-in>

Ограничить количество считываемых байтов из файла.

LIMIT_OUTPUT <max-out>

Ограничить общее количество байтов для хранения в <variable>.

NEWLINE_CONSUME

Обрабатывать символы новой строки (\n, LF) как часть содержимого строки, а не как разделители.

NO_HEX_CONVERSION

Файлы Intel Hex и Motorola S-record автоматически преобразуются в двоичный формат при чтении, если эта опция не указана.

REGEX <regex>

Учитывать только строки, которые соответствуют заданному регулярному выражению.

ENCODING <encoding-type>

Учитывать строки с заданной кодировкой. В настоящее время поддерживаются кодировки: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. Если опция ENCODING не задана, а в файле присутствует метка порядка байтов, опция ENCODING будет установлена по умолчанию в соответствии с меткой порядка байтов.

Например, код

file(STRINGS myfile.txt myfile)

хранит список в переменной myfile, где каждый элемент — строка из входного файла.

file(<HASH> <filename> <variable>)

Вычислить криптографический хеш содержимого <filename> и сохранить его в <variable>. Поддерживаемые имена алгоритмов <HASH> — те, которые перечислены командой string(<HASH>).

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

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

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

file(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>...]]
  )

Рекурсивно получить список библиотек, от которых зависят указанные файлы.

Обратите внимание, что эту подкоманду не следует использовать в режиме проекта. Вместо этого используйте её в блоке 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, который обозначает «главный» исполняемый файл пакета.

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

PRE_INCLUDE_REGEXES <regexes>

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

PRE_EXCLUDE_REGEXES <regexes>

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

POST_INCLUDE_REGEXES <regexes>

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

POST_EXCLUDE_REGEXES <regexes>

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

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

1. Если еще не разрешенная зависимость соответствует какому-либо из PRE_INCLUDE_REGEXES, шаги 2 и 3 пропускаются, и процесс разрешения зависимостей переходит к шагу 4.
2. Если еще не разрешенная зависимость соответствует какому-либо из PRE_EXCLUDE_REGEXES, разрешение зависимостей останавливается для этой зависимости.
3. В противном случае разрешение зависимостей продолжается.
4. file(GET_RUNTIME_DEPENDENCIES) ищет зависимость в соответствии с правилами линковки платформы (см. ниже).
5. Если зависимость найдена, и её полный путь соответствует одному из POST_INCLUDE_REGEXES, полный путь добавляется к разрешенным зависимостям, и file(GET_RUNTIME_DEPENDENCIES) рекурсивно разрешает зависимости этой библиотеки. В противном случае разрешение продолжается со шага 6.
6. Если зависимость найдена, но её полный путь соответствует одному из POST_EXCLUDE_REGEXES, она не добавляется к разрешенным зависимостям, и разрешение зависимостей останавливается для этой зависимости.
7. Если зависимость найдена, и её полный путь не соответствует ни POST_INCLUDE_REGEXES, ни POST_EXCLUDE_REGEXES, полный путь добавляется к разрешенным зависимостям, и file(GET_RUNTIME_DEPENDENCIES) рекурсивно разрешает зависимости этой библиотеки.

Разные платформы имеют разные правила разрешения зависимостей. Эти особенности описаны здесь.

На платформах Linux разрешение библиотек происходит следующим образом:

1. Если у зависимого файла нет записей RUNPATH, и библиотека существует в одной из записей RPATH зависимого файла или его родительских, в указанном порядке, зависимость разрешается к этому файлу.
2. В противном случае, если у зависимого файла есть записи RUNPATH, и библиотека существует в одной из этих записей, зависимость разрешается к этому файлу.
3. В противном случае, если библиотека существует в одном из каталогов, перечисленных в ldconfig, зависимость разрешается к этому файлу.
4. В противном случае, если библиотека существует в одной из записей DIRECTORIES, зависимость разрешается к этому файлу. В этом случае выдается предупреждение, потому что нахождение файла в одной из записей DIRECTORIES означает, что зависимый файл неполный (он не перечисляет все каталоги, из которых он получает зависимости).
5. В противном случае зависимость не разрешается.

На платформах Windows разрешение библиотек происходит следующим образом:

1. Имя зависимой 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.)

   Обратите внимание, что часть пути к разрешенным DLL сохраняет свой регистр и не преобразуется в нижний регистр. Только имя файла преобразуется.

2. (Ещё не реализовано) Если зависимый файл — приложение Windows Store, и зависимость указана как зависимость в манифесте пакета приложения, зависимость разрешается к этому файлу.
3. В противном случае, если библиотека существует в той же директории, что и зависимый файл, зависимость разрешается к этому файлу.
4. В противном случае, если библиотека существует в каталоге system32 или каталоге Windows операционной системы, в указанном порядке, зависимость разрешается к этому файлу.
5. В противном случае, если библиотека существует в одном из каталогов, указанных в DIRECTORIES, в порядке их перечисления, зависимость разрешается к этому файлу. В этом случае не выдается предупреждение, поскольку поиск в других каталогах является нормальной частью разрешения зависимостей библиотек Windows.
6. В противном случае, зависимость не разрешается.

На платформах Apple разрешение библиотек работает следующим образом:

1. Если зависимость начинается с @executable_path/, и аргумент EXECUTABLES находится в процессе разрешения, и замена @executable_path/ на каталог исполняемого файла приводит к существующему файлу, зависимость разрешается к этому файлу.
2. В противном случае, если зависимость начинается с @executable_path/, и есть аргумент BUNDLE_EXECUTABLE, и замена @executable_path/ на каталог исполняемого файла пакета приводит к существующему файлу, зависимость разрешается к этому файлу.
3. В противном случае, если зависимость начинается с @loader_path/, и замена @loader_path/ на каталог зависимого файла приводит к существующему файлу, зависимость разрешается к этому файлу.
4. В противном случае, если зависимость начинается с @rpath/, и замена @rpath/ на один из элементов RPATH зависимого файла приводит к существующему файлу, зависимость разрешается к этому файлу. Обратите внимание, что элементы RPATH, начинающиеся с @executable_path/ или @loader_path/, также имеют эти элементы, заменённые соответствующим путём.
5. В противном случае, если зависимость является абсолютным путём к существующему файлу, зависимость разрешается к этому файлу.
6. В противном случае, зависимость не разрешается.

Эта функция принимает несколько переменных, определяющих, какой инструмент используется для разрешения зависимостей:

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	dumpbin
windows+pe	objdump
macos+macho	otool

Если эта переменная не указана, она определяется автоматически путём интроспекции системы.

CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

Определяет путь к инструменту для разрешения зависимостей. Это фактический путь к objdump, dumpbin или otool.

Если эта переменная не указана, она определяется по значению CMAKE_OBJDUMP, если оно задано, в противном случае — путём интроспекции системы.

Запись

file(WRITE <filename> <content>...)
file(APPEND <filename> <content>...)

Запишите <content> в файл с именем <filename>. Если файл не существует, он будет создан. Если файл уже существует, режим WRITE перепишет его, а режим APPEND добавит в конец. Любые директории в пути, указанном в <filename>, которые не существуют, будут созданы.

Если файл является входным файлом сборки, используйте команду configure_file(), чтобы обновить файл только при изменении его содержимого.

file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])

Создайте файл без содержимого, если он ещё не существует. Если файл уже существует, его доступ и/или время изменения будут обновлены до времени выполнения вызова функции.

Используйте TOUCH_NOCREATE для изменения метки времени файла, если он существует, но не создавать его. Если файл не существует, он будет проигнорирован.

С TOUCH и TOUCH_NOCREATE содержимое существующего файла не будет изменено.

file(GENERATE OUTPUT output-file
     <INPUT input-file|CONTENT content>
     [CONDITION expression])

Создайте выходной файл для каждой поддерживаемой конфигурации сборки текущим генератором CMake Generator. Вычислите generator expressions из входного содержимого для создания выходного содержимого. Опции:

CONDITION <condition>

Сгенерировать выходной файл для конкретной конфигурации только если условие истинно. Условие должно быть либо 0, либо 1 после вычисления выражений генератора.

CONTENT <content>

Использовать явно заданное входное содержимое.

INPUT <input-file>

Использовать содержимое из указанного файла в качестве входных данных. Относительный путь рассматривается относительно значения CMAKE_CURRENT_SOURCE_DIR. См. политику CMP0070.

OUTPUT <output-file>

Указать имя выходного файла для генерации. Используйте выражения генератора, такие как $<CONFIG>, чтобы указать имя выходного файла, специфичное для конфигурации. Несколько конфигураций могут генерировать один и тот же выходной файл только если сгенерированное содержимое идентично. В противном случае <output-file> должно вычисляться в уникальное имя для каждой конфигурации. Отнoсительный путь (после вычисления выражений генератора) обрабатывается относительно значения CMAKE_CURRENT_BINARY_DIR. См. политику CMP0070.

Должна быть указана ровно одна 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] ])

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

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

Если задан флаг CONFIGURE_DEPENDS, CMake добавит логику в целевой объект проверки основной системы сборки, чтобы повторно выполнить помеченные GLOB команды во время сборки. Если какие-либо из выходных данных изменятся, CMake перегенерирует систему сборки.

По умолчанию GLOB перечисляет директории — директории опускаются в результате, если LIST_DIRECTORIES установлено в false.

Примеры выражений глоббинга включают:

*.cxx      - match all files with extension cxx
*.vt?      - match all files with extension vta,...,vtz
f[3-5].txt - match files f3.txt, f4.txt, f5.txt

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

По умолчанию GLOB_RECURSE опускает директории из списка результатов — установка LIST_DIRECTORIES в true добавляет директории в список результатов. Если задан FOLLOW_SYMLINKS или политика CMP0009 не установлена в NEW, то LIST_DIRECTORIES обрабатывает символические ссылки как директории.

Примеры рекурсивного глоббинга включают:

/dir/*.py  - match all python files in /dir and subdirectories

file(RENAME <oldname> <newname>)

Переместить файл или директорию внутри файловой системы из <oldname> в <newname>, атомарно заменив место назначения.

file(REMOVE [<files>...])
file(REMOVE_RECURSE [<files>...])

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

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

Создать заданные директории и их родительские директории по мере необходимости.

file(<COPY|INSTALL> <files>... DESTINATION <dir>
     [FILE_PERMISSIONS <permissions>...]
     [DIRECTORY_PERMISSIONS <permissions>...]
     [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
     [FOLLOW_SYMLINK_CHAIN]
     [FILES_MATCHING]
     [[PATTERN <pattern> | REGEX <regex>]
      [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

Подпись COPY копирует файлы, директории и символические ссылки в папку назначения. Относительные пути ввода оцениваются относительно текущей исходной директории, а относительный путь назначения — относительно текущей директории сборки. Копирование сохраняет временные метки входных файлов и оптимизирует файл, если он существует в пункте назначения с той же временной меткой. Копирование сохраняет входные разрешения, если не указаны явные разрешения или NO_SOURCE_PERMISSIONS (по умолчанию USE_SOURCE_PERMISSIONS).

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

file(SIZE <filename> <variable>)

Определите размер файла <filename> и поместите результат в переменную <variable>. Требуется, чтобы <filename> был допустимым путём к файлу и был доступен для чтения.

file(READ_SYMLINK <linkname> <variable>)

Эта подкоманда запрашивает символическую ссылку <linkname> и сохраняет путь, на который она указывает, в результате <variable>. Если <linkname> не существует или не является символической ссылкой, CMake выдаёт ошибку fatal.

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

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

Создать ссылку <linkname>, которая указывает на <original>. По умолчанию это будет жёсткая ссылка, но с опцией SYMBOLIC вместо этого будет создана символическая ссылка. Для жёстких ссылок требуется, чтобы original существовал и был файлом, а не директорией. Если <linkname> уже существует, он будет перезаписан.

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

Указание COPY_ON_ERROR позволяет копировать файл как резервный вариант, если создание ссылки завершается ошибкой. Это может быть полезно для обработки ситуаций, таких как <original> и <linkname> находятся на разных дисках или точках монтирования, что сделает их несовместимыми с жёсткой ссылкой.

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

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>.

Опции для обоих DOWNLOAD и UPLOAD:

INACTIVITY_TIMEOUT <seconds>

Завершить операцию после периода бездействия.

LOG <variable>

Сохранить удобочитаемый журнал операции в переменной.

SHOW_PROGRESS

Выводить информацию о прогрессе в виде сообщений об ошибках до завершения операции.

STATUS <variable>

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

TIMEOUT <seconds>

Завершить операцию по истечении заданного общего времени.

USERPWD <username>:<password>

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

HTTPHEADER <HTTP-header>

HTTP-заголовок для операции. Подопция может быть повторена несколько раз.

NETRC <level>

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

IGNORED

Файл .netrc игнорируется. Это значение по умолчанию.

OPTIONAL

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

REQUIRED

Файл .netrc обязателен, и информация в URL игнорируется.

NETRC_FILE <file>

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

Если ни одна из опций NETRC не указана, CMake проверит переменные CMAKE_NETRC и CMAKE_NETRC_FILE соответственно.

TLS_VERIFY <ON|OFF>

Указать, нужно ли проверять сертификат сервера для https:// URL-адресов. По умолчанию проверка не выполняется.

TLS_CAINFO <file>

Указать файл авторитетного центра сертификации для https:// URL-адресов.

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

Дополнительные параметры для DOWNLOAD:

EXPECTED_HASH ALGO=<value>

Проверьте, что хэш загруженного содержимого соответствует ожидаемому значению, где ALGO — один из алгоритмов, поддерживаемых file(<HASH>). Если они не совпадают, операция завершается ошибкой.

EXPECTED_MD5 <value>

Исторический сокращённый вариант для EXPECTED_HASH MD5=<value>.

Блокировка

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

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

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

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

Архивация

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

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

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

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

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

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

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

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

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

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

LIST_ONLY отобразит файлы в архиве, а не извлечёт их.

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