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 не указан или когда он называет ветку, чтобы загрузить только последнюю версию ветки без остальной её истории.

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>

Время, разрешённое для операций загрузки файлов

DOWNLOAD_NO_EXTRACT 1

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

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

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.