file

Команда для манипулирования файлами.

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

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

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

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

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>

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

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