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 преобразуется в нижний регистр. Имена 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.

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

Запись

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 не установлена в OLD, то 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>

Сохранить полученный статус операции в переменной. Статус — список из 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 соответственно.

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

EXPECTED_HASH ALGO=<value>

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

EXPECTED_MD5 <value>

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

TLS_VERIFY <ON|OFF>

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

TLS_CAINFO <file>

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