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 [/.../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_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_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.