ExternalProject

Создание пользовательских целей для сборки проектов во внешних деревьях

ExternalProject_Add

Функция ExternalProject_Add создаёт пользовательскую цель для управления этапами загрузки, обновления/патчинга, конфигурации, сборки, установки и тестирования внешнего проекта:

ExternalProject_Add(<name> [<option>...])

Общие параметры:

DEPENDS <projects>...

Цели, от которых зависит проект

PREFIX <dir>

Корневой каталог для всего проекта

LIST_SEPARATOR <sep>

Разделитель, заменяемый на «;» в командных строках

TMP_DIR <dir>

Каталог для хранения временных файлов

STAMP_DIR <dir>

Каталог для хранения отметки времени этапов

EXCLUDE_FROM_ALL 1

Цель «all» от неё не зависит

Параметры этапа загрузки:

DOWNLOAD_NAME <fname>

Имя файла для сохранения (если это не конец URL)

DOWNLOAD_DIR <dir>

Каталог для хранения загруженных файлов

DOWNLOAD_COMMAND <cmd>...

Команда для загрузки дерева исходного кода

DOWNLOAD_NO_PROGRESS 1

Отключить сообщения о прогрессе загрузки

CVS_REPOSITORY <cvsroot>

CVSROOT репозитория CVS

CVS_MODULE <mod>

Модуль для проверки из репозитория CVS

CVS_TAG <tag>

Тег для проверки из репозитория CVS

SVN_REPOSITORY <url>

URL репозитория Subversion

SVN_REVISION -r<rev>

Ревизия для проверки из репозитория Subversion

SVN_USERNAME <username>

Имя пользователя для проверки и обновления Subversion

SVN_PASSWORD <password>

Пароль для проверки и обновления Subversion

SVN_TRUST_CERT 1

Доверять сертификату сайта сервера Subversion

GIT_REPOSITORY <url>

URL репозитория git

GIT_TAG <tag>

Имя ветки git, идентификатор коммита или тег

GIT_REMOTE_NAME <name>

Необязательное имя удалённого хранилища, по умолчанию origin

GIT_SUBMODULES <module>...

Git подмодули, которые нужно обновить, все, если пусто

GIT_SHALLOW 1

Указать Git клонировать с --depth 1. Используйте, когда GIT_TAG не указан или когда он задаёт ветку, чтобы загрузить только вершину ветки без остальной её истории.

GIT_PROGRESS 1

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

GIT_CONFIG <option>...

Заставить Git клонировать с --config <option>. Используйте дополнительные параметры конфигурации при клонировании проекта (key=value как ожидается %%%CODE_BLOCK_34%%).

HG_REPOSITORY <url>

URL репозитория mercurial

HG_TAG <tag>

Имя ветки mercurial, идентификатор коммита или тег

URL /.../src.tgz [/.../src.tgz]...

Полный путь или URL(ы) исходного кода. Несколько URL разрешены как зеркала.

URL_HASH ALGO=value

Хеш файла по URL

URL_MD5 md5

Эквивалентно URL_HASH MD5=md5

HTTP_USERNAME <username>

Имя пользователя для загрузки

HTTP_PASSWORD <username>

Пароль для загрузки

HTTP_HEADER <header>

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

TLS_VERIFY <bool>

Проверять сертификат для https

TLS_CAINFO <file>

Путь к файлу сертификата доверенной стороны

TIMEOUT <seconds>

Время, разрешённое на загрузку файла

DOWNLOAD_NO_EXTRACT 1

Только загрузить файл и не разархивировать; полный путь к загруженному файлу доступен как <DOWNLOADED_FILE>.

Параметры этапа обновления/патчинга:

UPDATE_COMMAND <cmd>...

Команда для обновления рабочей области исходного кода

UPDATE_DISCONNECTED 1

Никогда не обновлять автоматически из удалённого репозитория

PATCH_COMMAND <cmd>...

Команда для применения патча загруженного исходного кода

Параметры этапа конфигурации:

SOURCE_DIR <dir>

Исходный каталог, который будет использован для сборки

SOURCE_SUBDIR <dir>

Путь к CMakeLists.txt относительно SOURCE_DIR

CONFIGURE_COMMAND <cmd>...

Команда для конфигурации дерева сборки

CMAKE_COMMAND /.../cmake

Указать альтернативную программу cmake

CMAKE_GENERATOR <gen>

Указать генератор для локальной сборки

CMAKE_GENERATOR_PLATFORM <platform>

Имя платформы, специфичное для генератора

CMAKE_GENERATOR_TOOLSET <toolset>

Имя набора инструментов, специфичное для генератора

CMAKE_ARGS <arg>...

Аргументы командной строки CMake. Эти аргументы передаются в командную строку CMake и могут содержать аргументы, отличные от значений кеша; см. также CMake Options. Аргументы в формате -Dvar:string=on всегда передаются в командную строку и поэтому не могут быть изменены пользователем. Аргументы могут использовать generator expressions.

CMAKE_CACHE_ARGS <arg>...

Начальные аргументы кеша в формате -Dvar:string=on. Эти аргументы записываются в скрипт предварительной загрузки, который заполняет кеш CMake; см. также cmake -C. Это позволяет обойти ограничения длины командной строки. Эти аргументы set() с помощью аргумента FORCE, и поэтому не могут быть изменены пользователем. Аргументы могут использовать generator expressions.

CMAKE_CACHE_DEFAULT_ARGS <arg>...

Начальные значения аргументов кеша по умолчанию в формате -Dvar:string=on. Эти аргументы записываются в скрипт предварительной загрузки, который заполняет кеш CMake; см. также cmake -C. Это позволяет обойти ограничения длины командной строки. Эти аргументы могут быть использованы в качестве значения по умолчанию, которое будет установлено, если предварительное значение не найдено в кеше, и пользователь может его изменить позже. Аргументы могут использовать generator expressions.

Параметры этапа сборки:

BINARY_DIR <dir>

Указать расположение каталога сборки

BUILD_COMMAND <cmd>...

Команда для запуска локальной сборки

BUILD_IN_SOURCE 1

Использовать каталог исходного кода для каталога сборки

BUILD_ALWAYS 1

Файл отметки времени не используется, этап сборки всегда выполняется

BUILD_BYPRODUCTS <file>...

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

Параметры этапа установки:

INSTALL_DIR <dir>

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

INSTALL_COMMAND <cmd>...

Команда для запуска установки внешнего проекта после его сборки. Это происходит только во время сборки вызывающего проекта. Чтобы установить файлы из внешнего проекта вместе с локально собранными файлами, необходимо добавить отдельный локальный вызов install() для извлечения файлов из одного из деревьев внешнего проекта.

Параметры этапа тестирования:

TEST_BEFORE_INSTALL 1

Добавить этап тестирования, выполняемый до этапа установки

TEST_AFTER_INSTALL 1

Добавить этап тестирования, выполняемый после этапа установки

TEST_EXCLUDE_FROM_MAIN 1

Основная цель не зависит от этапа тестирования

TEST_COMMAND <cmd>...

Команда для запуска тестирования

Параметры для ведения логов вывода:

LOG_DOWNLOAD 1

Оборачивает загрузку в скрипт для ведения логов вывода

LOG_UPDATE 1

Оборачивает обновление в скрипт для ведения логов вывода

LOG_CONFIGURE 1

Оборачивает конфигурацию в скрипт для ведения логов вывода

LOG_BUILD 1

Оборачивает сборку в скрипт для ведения логов вывода

LOG_TEST 1

Оборачивает тестирование в скрипт для ведения логов вывода

LOG_INSTALL 1

Оборачивает установку в скрипт для ведения логов вывода

Этапы могут получить прямой доступ к терминалу, если это возможно. С генератором Ninja это помещает этапы в console pool. Параметры:

USES_TERMINAL_DOWNLOAD 1

Предоставить терминальный доступ для загрузки.

USES_TERMINAL_UPDATE 1

Предоставить терминальный доступ для обновления.

USES_TERMINAL_CONFIGURE 1

Предоставить терминальный доступ для конфигурации.

USES_TERMINAL_BUILD 1

Предоставить терминальный доступ для сборки.

USES_TERMINAL_TEST 1

Предоставить терминальный доступ для тестирования.

USES_TERMINAL_INSTALL 1

Предоставить терминальный доступ для установки.

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

STEP_TARGETS <step-target>...

Генерировать пользовательские цели для этих этапов

INDEPENDENT_STEP_TARGETS <step-target>...

Генерировать пользовательские цели для этих этапов, которые не зависят от других внешних проектов, даже если зависимость установлена

Параметры *_DIR определяют каталоги для проекта, с вычислением по умолчанию следующим образом. Если параметр PREFIX задан для ExternalProject_Add() или свойство каталога EP_PREFIX установлено, тогда внешний проект собирается и устанавливается в указанном префиксе:

TMP_DIR      = <prefix>/tmp
STAMP_DIR    = <prefix>/src/<name>-stamp
DOWNLOAD_DIR = <prefix>/src
SOURCE_DIR   = <prefix>/src/<name>
BINARY_DIR   = <prefix>/src/<name>-build
INSTALL_DIR  = <prefix>

В противном случае, если свойство каталога EP_BASE установлено, компоненты внешнего проекта хранятся в указанном базовом каталоге:

TMP_DIR      = <base>/tmp/<name>
STAMP_DIR    = <base>/Stamp/<name>
DOWNLOAD_DIR = <base>/Download/<name>
SOURCE_DIR   = <base>/Source/<name>
BINARY_DIR   = <base>/Build/<name>
INSTALL_DIR  = <base>/Install/<name>

Если PREFIX, EP_PREFIX, или EP_BASE не указаны, по умолчанию PREFIX устанавливается в <name>-prefix. Относительные пути интерпретируются относительно каталога сборки, соответствующего каталогу исходного кода, в котором вызывается ExternalProject_Add.

Если SOURCE_SUBDIR установлено, и CONFIGURE_COMMAND не указано, команда конфигурации запустит CMake с CMakeLists.txt, расположенным в относительном пути, указанном в SOURCE_SUBDIR, относительно SOURCE_DIR. Если SOURCE_SUBDIR не задано, используется SOURCE_DIR

Если SOURCE_DIR явно задан как существующая директория, проект будет скомпилирован из неё. В противном случае необходимо указать шаг загрузки, используя один из параметров DOWNLOAD_COMMAND, CVS_*, SVN_*, или URL. Параметр URL может ссылаться на локальную директорию или архив исходных кодов, или на удалённый архив (например, http://.../src.tgz).

Если UPDATE_DISCONNECTED установлен, шаг обновления не выполняется автоматически при сборке основного целевого объекта. Шаг обновления всё ещё может быть добавлен как целевой шаг и вызван вручную. Это полезно, если вы хотите позволить сборку проекта при отсутствии подключения к сети (возможно, вам всё ещё потребуется сеть для шага загрузки). По умолчанию эта опция отключена. Свойство директории EP_UPDATE_DISCONNECTED может быть использовано для изменения значения по умолчанию для всех внешних проектов в текущей директории и её поддиректориях.

ExternalProject_Add_Step

Функция ExternalProject_Add_Step добавляет пользовательский шаг к внешнему проекту:

ExternalProject_Add_Step(<name> <step> [<option>...])

Параметры:

COMMAND <cmd>...

Командная строка, вызываемая этим шагом

COMMENT "<text>..."

Текст, отображаемый при выполнении шага

DEPENDEES <step>...

Шаги, от которых зависит этот шаг

DEPENDERS <step>...

Шаги, которые зависят от этого шага

DEPENDS <file>...

Файлы, от которых зависит этот шаг

BYPRODUCTS <file>...

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

ALWAYS 1

Файл метки отсутствует, шаг всегда выполняется

EXCLUDE_FROM_MAIN 1

Основной целевой объект не зависит от этого шага

WORKING_DIRECTORY <dir>

Рабочая директория для команды

LOG 1

Обернуть шаг в скрипт для логирования вывода

USES_TERMINAL 1

Предоставить шагу прямой доступ к терминалу, если это возможно.

Командная строка, комментарий, рабочая директория и побочные продукты каждого стандартного и пользовательского шага обрабатываются для замены маркеров <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>, <INSTALL_DIR>, и <TMP_DIR> соответствующими значениями свойств.

Любой встроенный шаг, который указывает <step>_COMMAND cmd..., или пользовательский шаг, который указывает COMMAND cmd..., может указать дополнительные командные строки в формате COMMAND cmd.... Во время сборки команды будут выполняться в порядке их указания, и сборка прервётся, если одна из команд завершится с ошибкой. Например:

... BUILD_COMMAND make COMMAND echo done ...

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

Аргументы к параметрам <step>_COMMAND или COMMAND могут использовать generator expressions.

ExternalProject_Get_Property

Функция ExternalProject_Get_Property извлекает свойства целевых объектов внешнего проекта:

ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])

Она сохраняет значения свойств в переменных с тем же именем. Имена свойств соответствуют именам ключевых аргументов функции ExternalProject_Add.

ExternalProject_Add_StepTargets

Функция ExternalProject_Add_StepTargets генерирует пользовательские целевые объекты для перечисленных шагов:

ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] [step1 [step2 [...]]])

Если NO_DEPENDS установлено, целевой объект не будет зависеть от зависимостей всего проекта. Это обычно безопасно использовать для шагов загрузки, обновления и исправления, которые не требуют обновления и компиляции всех зависимостей. Использование NO_DEPENDS для других стандартных шагов может нарушить параллельные сборки, поэтому следует этого избегать. Для пользовательских шагов следует рассмотреть, требуется ли выполнение пользовательских команд, что зависимости были настроены, скомпилированы и установлены.

Если STEP_TARGETS или INDEPENDENT_STEP_TARGETS установлено, то ExternalProject_Add_StepTargets автоматически вызывается в конце соответствующих вызовов ExternalProject_Add_Step. Передайте STEP_TARGETS или INDEPENDENT_STEP_TARGETS явно отдельным вызовам ExternalProject_Add, или неявно всем вызовам ExternalProject_Add путём установки свойств директорий EP_STEP_TARGETS и EP_INDEPENDENT_STEP_TARGETS. Версия аргумента INDEPENDENT и свойства вызовет ExternalProject_Add_StepTargets с аргументом NO_DEPENDS.

Если STEP_TARGETS и INDEPENDENT_STEP_TARGETS не установлены, клиенты всё ещё могут вручную вызвать ExternalProject_Add_StepTargets после вызова ExternalProject_Add или ExternalProject_Add_Step.

Эта функциональность предназначена для удобного независимого управления шагами, указывая целевые объекты в командной строке сборки. Например, вы можете отправлять данные в панель мониторинга подпроекта, где хотите запустить часть конфигурации сборки, затем отправить данные в панель мониторинга, затем часть сборки, затем тесты. Если вы вызываете пользовательский целевой объект, который зависит от шага в середине цепочки зависимостей шагов, все предыдущие шаги также будут выполнены, чтобы убедиться, что всё обновлено.

Например, чтобы управлять шагами конфигурации, сборки и тестирования независимо для каждого вызова ExternalProject_Add в вашем проекте, напишите следующую строку перед любыми вызовами ExternalProject_Add в вашем файле CMakeLists.txt.

set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)

ExternalProject_Add_StepDependencies

Функция ExternalProject_Add_StepDependencies добавляет зависимости для шагов внешнего проекта:

ExternalProject_Add_StepDependencies(<name> <step> [target1 [target2 [...]]])

Эта функция заботится о настройке зависимостей на уровне целевых объектов и файлов и гарантирует, что параллельные сборки не будут нарушены. Её следует использовать вместо add_dependencies() при добавлении зависимостей для некоторых целевых объектов шагов, сгенерированных функцией ExternalProject.