file

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

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

Записать <content> в файл под названием <filename>. Если файл не существует, он будет создан. Если файл уже существует, режим WRITE перезапишет его, а режим APPEND добавит содержимое в конец. (Если файл является входными данными для сборки, используйте команду configure_file(), чтобы обновить файл только при изменении его содержимого.)

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(GLOB <variable>
     [LIST_DIRECTORIES true|false] [RELATIVE <path>]
     [<globbing-expressions>...])
file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
     [LIST_DIRECTORIES true|false] [RELATIVE <path>]
     [<globbing-expressions>...])

Сгенерировать список файлов, соответствующих <globbing-expressions>, и сохранить его в <variable>. Выражения подстановки похожи на регулярные выражения, но намного проще. Если указан флаг RELATIVE, результаты будут возвращены как относительные пути к заданному пути. Специфического порядка результатов не определено, кроме того, что он детерминированный. Если порядок важен, отсортируйте список явно (например, с помощью команды list(SORT)).

По умолчанию 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(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-заголовок для операции. Подопция может повторяться несколько раз.

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

EXPECTED_HASH ALGO=<value>

EXPECTED_MD5 <value>

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

TLS_VERIFY <ON|OFF>

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

TLS_CAINFO <file>

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

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

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

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

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

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>

Использовать содержимое из заданного файла как вход.

OUTPUT <output-file>

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

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

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

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

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

См. команду install(DIRECTORY) для документации по правам доступа, FILES_MATCHING, PATTERN, REGEX, и EXCLUDE параметрам. Копирование каталогов сохраняет структуру их содержимого даже при использовании параметров для выбора подмножества файлов.

Подпись INSTALL отличается от COPY: она выводит сообщения об статусе (в зависимости от переменной CMAKE_INSTALL_MESSAGE), и NO_SOURCE_PERMISSIONS является значением по умолчанию. Скрипты установки, сгенерированные командой install(), используют эту подпись (с некоторыми неудокументированными параметрами для внутреннего использования).

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 и RELEASE игнорируются при операции TIMEOUT.