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

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

Чтение

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

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

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. На других платформах он не имеет эффекта. Обычно (но не всегда) это один из исполняемых файлов в аргументе 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 преобразуется в нижний регистр. Имена 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.)

   Обратите внимание, что часть пути к любой разрешённой 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.

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

Написание

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> должно вычисляться в уникальное имя для каждой конфигурации. Относительный путь (после вычисления выражений генератора) рассматривается относительно значения CMAKE_CURRENT_BINARY_DIR. См. политику CMP0070.

Должен быть указан ровно один параметр CONTENT или INPUT. Конкретный файл OUTPUT может быть назван не более чем одним вызовом file(GENERATE). Сгенерированные файлы изменены и их отметка времени обновлена при последующих запусках cmake только если их содержимое изменено.

Также обратите внимание, что file(GENERATE) не создаёт выходной файл до фазы генерации. Выходной файл ещё не будет записан, когда команда file(GENERATE) вернётся, он будет записан только после обработки всех файлов CMakeLists.txt проекта.

Файловая система

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 выдаёт ошибку.

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

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 не указана, а операция завершается неудачей, генерируется ошибка.

Указание 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>

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

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

EXPECTED_HASH ALGO=<value>

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

EXPECTED_MD5 <value>

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

TLS_VERIFY <ON|OFF>

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

TLS_CAINFO <file>

Указать пользовательский файл Certificate Authority для https:// URL.

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

Блокировка

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.