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 как ожидается от git config).

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> placeholder. Это не на самом деле настраивает внешний проект на установку по заданному префиксу. Это нужно сделать, передав соответствующие аргументы на шаг конфигурации внешнего проекта, например, используя <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 не указано, команда configure выполнит 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.