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 подмодули, которые должны быть обновлены, все, если пусто

HG_REPOSITORY <url>

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

HG_TAG <tag>

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

URL /.../src.tgz

Полный путь или URL источника

URL_HASH ALGO=value

Хэш файла по URL

URL_MD5 md5

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

TLS_VERIFY <bool>

Нужно ли проверять сертификат для https

TLS_CAINFO <file>

Путь к файлу сертификационного центра

TIMEOUT <seconds>

Время, отводимое на операции скачивания файла

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

UPDATE_COMMAND <cmd>...

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

UPDATE_DISCONNECTED 1

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

PATCH_COMMAND <cmd>...

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

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

SOURCE_DIR <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_COMMAND <cmd>...

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

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

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_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>, <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.