ExternalProject

• Определение внешнего проекта
• Получение свойств проекта
• Явное управление этапами
• Примеры

Определение внешнего проекта

ExternalProject_Add

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

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

Отдельные этапы процесса могут управляться независимо при необходимости (например, для отправки в CDash), и могут быть определены дополнительные пользовательские этапы, а также возможность управления зависимостями этапов. Структура каталогов для управления внешним проектом также может быть настраиваемой. Функция поддерживает большое количество параметров, которые можно использовать для настройки поведения внешнего проекта.

Параметры каталогов:

В большинстве случаев, стандартная структура каталогов достаточна. В основном это реализация, которую обычно не нужно изменять в главном проекте. Однако в некоторых случаях контроль над структурой каталогов может быть полезен или необходим. Параметры каталогов могут быть полезнее с точки зрения того, что основной проект может использовать команду ExternalProject_Get_Property() для получения их значений, что позволяет главному проекту ссылаться на артефакты сборки внешнего проекта.

PREFIX <dir>

Корневой каталог внешнего проекта. Если не указано иное ниже, все другие каталоги, связанные с внешним проектом, будут созданы внутри него.

TMP_DIR <dir>

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

STAMP_DIR <dir>

Каталог для хранения отметки времени каждого этапа. Лог-файлы отдельных этапов также создаются здесь, если не переопределены LOG_DIR (см. Параметры ведения журнала ниже).

LOG_DIR <dir>

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

DOWNLOAD_DIR <dir>

Каталог для хранения загруженных файлов перед распаковкой. Этот каталог используется только методом загрузки URL; все другие методы загрузки используют SOURCE_DIR напрямую.

SOURCE_DIR <dir>

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

Примечание

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

BINARY_DIR <dir>

Укажите расположение каталога сборки. Этот параметр игнорируется, если включен BUILD_IN_SOURCE.

INSTALL_DIR <dir>

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

Если какой-либо из вышеперечисленных ..._DIR параметров не указан, их значения вычисляются следующим образом. Если указан параметр PREFIX или установлено свойство каталога 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>
LOG_DIR      = <STAMP_DIR>

В противном случае, если установлено свойство каталога 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>
LOG_DIR      = <STAMP_DIR>

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

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

Метод загрузки можно опустить, если использовать опцию SOURCE_DIR для указания существующей непустой директории. В противном случае, должен быть указан один из методов загрузки ниже (несколько методов загрузки не допускаются) или предоставлена настраиваемая опция DOWNLOAD_COMMAND.

DOWNLOAD_COMMAND <cmd>...

Переопределяет команду, используемую для шага загрузки (generator expressions поддерживаются). Если эта опция указана, все другие опции загрузки будут проигнорированы. Указание пустой строки для <cmd> эффективно отключает шаг загрузки.

Загрузка по URL

URL <url1> [<url2>...]

Список путей и/или URL(ов) исходного кода внешнего проекта. Если указано более одного URL, они будут пробоваться по очереди до тех пор, пока один не увенчается успехом. URL может быть обычным путем в локальной файловой системе (в этом случае должен быть указан только один URL) или любым загружаемым URL, поддерживаемым командой file(DOWNLOAD). Локальный путь к файловой системе может ссылаться на существующую директорию или на архивный файл, тогда как URL должен указывать на файл, который можно рассматривать как архив. При использовании архива он будет распакован автоматически, если опция DOWNLOAD_NO_EXTRACT не отключит эту функцию. Тип архива определяется путем проверки фактического содержимого, а не с помощью логики, основанной на расширении файла.

URL_HASH <algo>=<hashValue>

Хэш архивного файла для загрузки. Аргумент должен иметь вид <algo>=<hashValue>, где algo может быть любым из алгоритмов хеширования, поддерживаемых командой file(). Сильно рекомендуется указывать эту опцию для загрузки по URL, так как она гарантирует целостность загруженного содержимого. Она также используется для проверки ранее загруженного файла, позволяя избежать подключения к удаленному расположению, если локальная директория уже содержит файл из предыдущей загрузки, соответствующий указанному хэшу.

URL_MD5 <md5>

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

DOWNLOAD_NAME <fname>

Имя файла, которое будет использоваться для загруженного файла. Если не указано, имя файла определяется из конца URL. Эта опция редко необходима; имя по умолчанию, как правило, подходит и обычно не используется вне кода, внутреннего для модуля ExternalProject.

DOWNLOAD_NO_EXTRACT <bool>

Позволяет отключить распаковку загруженного файла, передав для этой опции значение true. Если эта опция не указана, загруженное содержимое будет распаковано автоматически, если это необходимо. Если распаковка отключена, полный путь к загруженному файлу доступен как <DOWNLOADED_FILE> в последующих шагах или как свойство DOWNLOADED_FILE с помощью команды ExternalProject_Get_Property().

DOWNLOAD_NO_PROGRESS <bool>

Может быть использована для отключения регистрации прогресса загрузки. Если эта опция не указана, сообщения о прогрессе загрузки будут регистрироваться.

TIMEOUT <seconds>

Максимальное время, разрешенное для операций загрузки файлов.

HTTP_USERNAME <username>

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

HTTP_PASSWORD <password>

Пароль для операции загрузки, если требуется аутентификация.

HTTP_HEADER <header1> [<header2>...]

Предоставляет произвольный список HTTP-заголовков для операции загрузки. Это может быть полезно для доступа к содержимому в системах, таких как AWS и т.д.

TLS_VERIFY <bool>

Указывает, должна ли выполняться проверка сертификата для HTTPS-URL. Если эта опция не предоставлена, поведение по умолчанию определяется переменной CMAKE_TLS_VERIFY (см. file(DOWNLOAD)). Если она также не задана, проверка сертификата не будет выполнена. В ситуациях, когда URL_HASH не может быть предоставлена, эта опция может быть альтернативной мерой проверки.

TLS_CAINFO <file>

Указывает настраиваемый файл авторитета сертификата для использования, если TLS_VERIFY включен. Если эта опция не указана, будет использовано значение переменной CMAKE_TLS_CAINFO (см. file(DOWNLOAD))

NETRC <level>

Указывает, должен ли использоваться файл .netrc для операции. Если эта опция не указана, будет использовано значение переменной CMAKE_NETRC (см. file(DOWNLOAD)). Допустимые уровни:

IGNORED

Файл .netrc игнорируется. Это значение по умолчанию.

OPTIONAL

Файл .netrc необязателен, и информация из URL имеет приоритет. Файл будет проверен для поиска любой информации, которая не указана в URL.

REQUIRED

Файл .netrc обязателен, и информация из URL игнорируется.

NETRC_FILE <file>

Указывает альтернативный файл .netrc вместо файла в вашем домашнем каталоге, если уровень NETRC равен OPTIONAL или REQUIRED. Если эта опция не указана, будет использовано значение переменной CMAKE_NETRC_FILE (см. file(DOWNLOAD))

Git

ПРИМЕЧАНИЕ: Для использования этого метода загрузки требуется версия Git 1.6.5 или выше.

GIT_REPOSITORY <url>

URL репозитория Git. Можно использовать любой URL, понимаемый командой git.

GIT_TAG <tag>

Имя ветки, тега или хэш коммита Git. Обратите внимание, что имена веток и тегов обычно следует указывать как имена удалённых репозиториев (например, origin/myBranch, а не просто myBranch). Это гарантирует, что если удалённый репозиторий изменит тег или ветку или перепишет историю, локальная копия всё равно будет обновлена правильно. Однако, в общем случае, для многих причин предпочтительнее указать хэш коммита:

• Если локальная копия уже содержит коммит, соответствующий хэшу, не требуется выполнение git fetch для проверки изменений каждый раз при повторном запуске CMake. Это может значительно ускорить работу, если используется много внешних проектов.
• Использование конкретного хэша Git гарантирует полную прослеживаемость истории основного проекта до конкретной точки в эволюции внешнего проекта. Если используется имя ветки или тега, то выход к конкретному коммиту основного проекта не обязательно привязывает весь сборку к определённой точке в жизни внешнего проекта. Отсутствие такого детерминированного поведения делает основной проект менее прослеживаемым и воспроизводимым.

Если GIT_SHALLOW включено, то GIT_TAG работает только с именами веток и тегов. Хэш коммита не допускается.

GIT_REMOTE_NAME <name>

Необязательное имя удалённого репозитория. Если эта опция не указана, используется значение по умолчанию origin.

GIT_SUBMODULES <module>...

Конкретные подмодули Git, которые также должны быть обновлены. Если эта опция не предоставлена, все подмодули Git будут обновлены.

GIT_SHALLOW <bool>

При включении этой опции операции git clone будет передана опция --depth 1. Это выполняет поверхностное клонирование, что позволяет избежать загрузки всей истории, а вместо этого извлекает только коммит, обозначенный опцией GIT_TAG.

GIT_PROGRESS <bool>

При включении эта опция инструктирует операцию git clone сообщать о прогрессе, передавая ей опцию --progress. Без этой опции шаг клонирования для больших проектов может показаться зависанием сборки, так как ничего не будет регистрироваться до завершения операции клонирования. Хотя эта опция может использоваться для отображения прогресса, чтобы избежать визуального зависания сборки, она также может сделать сборку избыточно шумной, если используются много внешних проектов.

GIT_CONFIG <option1> [<option2>...]

Укажите список конфигурационных опций для передачи в git clone. Каждый перечисленный вариант преобразуется в отдельную опцию --config <option> в командной строке команды git clone, и каждый вариант должен иметь вид key=value.

Subversion

SVN_REPOSITORY <url>

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

SVN_REVISION -r<rev>

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

SVN_USERNAME <username>

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

SVN_PASSWORD <password>

Пароль для взятия и обновления Subversion.

SVN_TRUST_CERT <bool>

Указывает, следует ли доверять сертификату сайта сервера Subversion. При включении опция --trust-server-cert передаётся командам взятия и обновления svn.

Mercurial

HG_REPOSITORY <url>

URL репозитория Mercurial.

HG_TAG <tag>

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

CVS

CVS_REPOSITORY <cvsroot>

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

CVS_MODULE <mod>

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

CVS_TAG <tag>

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

Опции шага обновления/патчинга:

Всякий раз, когда CMake перевыполняется, по умолчанию исходные файлы внешнего проекта будут обновляться, если метод загрузки поддерживает обновления (например, репозиторий git будет проверен, если GIT_TAG не ссылается на конкретный коммит).

UPDATE_COMMAND <cmd>...

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

UPDATE_DISCONNECTED <bool>

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

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

PATCH_COMMAND <cmd>...

Указывает пользовательскую команду для применения патчей к исходным файлам после обновления. По умолчанию команда патчей не определена. Обратите внимание, что определение подходящей команды патчей, которая работает надёжно, особенно для методов загрузки, таких как git, где изменение GIT_TAG не отбросит изменения предыдущего патча, но команда патчей будет вызвана снова после обновления до новой метки, может быть довольно сложной.

Параметры шага настройки:

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

CONFIGURE_COMMAND <cmd>...

Команда настройки по умолчанию выполняет CMake с параметрами, основанными на основном проекте. Для внешних проектов, не являющихся проектами CMake, необходимо использовать параметр CONFIGURE_COMMAND для переопределения этого поведения (generator expressions поддерживаются). Для проектов, для которых не требуется шаг настройки, укажите этот параметр со пустой строкой в качестве команды для выполнения.

CMAKE_COMMAND /.../cmake

Укажите альтернативный исполняемый файл cmake для шага настройки (используйте абсолютный путь). Это, как правило, не рекомендуется, так как обычно желательно использовать одну и ту же версию CMake во всём процессе сборки. Этот параметр игнорируется, если пользовательская команда настройки была указана с помощью CONFIGURE_COMMAND.

CMAKE_GENERATOR <gen>

Переопределите генератор CMake, используемый для шага настройки. Без этого параметра будет использован тот же генератор, что и для основной сборки. Этот параметр игнорируется, если пользовательская команда настройки была указана с параметром CONFIGURE_COMMAND.

CMAKE_GENERATOR_PLATFORM <platform>

Передайте имя платформы, специфичное для генератора, команде CMake (см. CMAKE_GENERATOR_PLATFORM). Указание этого параметра без параметра CMAKE_GENERATOR является ошибкой.

CMAKE_GENERATOR_TOOLSET <toolset>

Передайте имя набора инструментов, специфичное для генератора, команде CMake (см. CMAKE_GENERATOR_TOOLSET). Указание этого параметра без параметра CMAKE_GENERATOR является ошибкой.

CMAKE_GENERATOR_INSTANCE <instance>

Передайте выбор экземпляра, специфичный для генератора, команде CMake (см. CMAKE_GENERATOR_INSTANCE). Указание этого параметра без параметра CMAKE_GENERATOR является ошибкой.

CMAKE_ARGS <arg>...

Указанные аргументы передаются в командную строку cmake. Они могут быть любыми аргументами, которые понимает команда cmake, а не только значениями кэша, определёнными -D... аргументами (см. также CMake Options). Кроме того, аргументы могут использовать generator expressions.

CMAKE_CACHE_ARGS <arg>...

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

CMAKE_CACHE_DEFAULT_ARGS <arg>...

Это то же самое, что и параметр CMAKE_CACHE_ARGS, за исключением того, что команды set() не включают ключевое слово FORCE. Это означает, что значения действуют только как начальные значения по умолчанию и не будут переопределять какие-либо переменные, уже установленные с предыдущего запуска. Используйте этот параметр с осторожностью, так как он может привести к различным результатам в зависимости от того, начинается ли сборка с нового каталога сборки или повторно использует содержимое предыдущей сборки.

Если генератор CMake — Green Hills MULTI, а не переопределен, то исходные настройки проекта для набора инструментов GHS и кастомных переменных кэша для настроек целевой системы распространяются на внешний проект.

SOURCE_SUBDIR <dir>

Если параметр CONFIGURE_COMMAND не указан, шаг настройки предполагает, что внешний проект имеет файл CMakeLists.txt в верхней части своей структуры исходных кодов (т.е. в SOURCE_DIR). Параметр SOURCE_SUBDIR можно использовать для указания альтернативного каталога в структуре исходных кодов для использования в качестве верхней части структуры исходных кодов CMake. Это должен быть относительный путь, и он будет интерпретироваться как относительный к SOURCE_DIR. Если указан BUILD_IN_SOURCE 1, то BUILD_COMMAND используется для указания альтернативного каталога внутри структуры исходных кодов.

Параметры шага сборки:

Если шаг настройки предполагал, что внешний проект использует CMake в качестве системы сборки, шаг сборки также будет использовать его. В противном случае шаг сборки будет предполагать сборку на основе Makefile и просто выполнит make без аргументов в качестве шага сборки по умолчанию. Это можно переопределить пользовательскими командами сборки, если это необходимо.

BUILD_COMMAND <cmd>...

Переопределяет команду сборки по умолчанию (generator expressions поддерживаются). Если этот параметр не указан, команда сборки по умолчанию будет выбрана для интеграции со основной сборкой наиболее подходящим образом (например, используя рекурсивную make для генераторов Makefile или cmake --build , если проект использует сборку CMake). Этот параметр можно указать с пустой строкой в качестве команды, чтобы шаг сборки не выполнял ничего.

BUILD_IN_SOURCE <bool>

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

BUILD_ALWAYS <bool>

Включение этого параметра заставляет шаг сборки всегда выполняться. Это может быть самым простым способом надёжно убедиться, что зависимости сборки внешнего проекта оцениваются, а не полагаться на метод, основанный на времени успешного выполнения по умолчанию. Этот параметр обычно не нужен, если не ожидается, что разработчики будут изменять что-либо, от чего зависит сборка внешнего проекта, способом, не обнаруживаемым через зависимости целевых шагов (например, SOURCE_DIR используется без метода загрузки, и разработчики могут изменить исходные файлы в SOURCE_DIR).

BUILD_BYPRODUCTS <file>...

Указывает файлы, которые будут сгенерированы командой сборки, но у которых время модификации может или не может быть обновлено последующими сборками. В конечном счете они передаются как BYPRODUCTS в собственный вызов шага сборки к add_custom_command().

Параметры шага установки:

Если шаг configure предполагал, что внешний проект использует CMake в качестве системы сборки, шаг install также будет. В противном случае шаг install будет предполагать сборку на основе Makefile и просто выполнит make install в качестве шага сборки по умолчанию. Это можно переопределить с помощью пользовательских команд install, если необходимо.

INSTALL_COMMAND <cmd>...

Шаг install внешнего проекта вызывается как часть шага build основного проекта. Он выполняется после шага сборки внешнего проекта и может быть выполнен до или после шага тестирования внешнего проекта (см. опцию TEST_BEFORE_INSTALL ниже). Правила установки внешнего проекта не являются частью правил установки основного проекта, поэтому если что-либо из внешнего проекта должно быть установлено как часть основной сборки, это нужно указать в основной сборке как дополнительные команды install(). Шагом установки по умолчанию является построение целевой install внешнего проекта, но это можно переопределить с помощью пользовательской команды, используя эту опцию (generator expressions поддерживаются). Передача пустой строки в качестве <cmd> заставляет шаг установки ничего не делать.

Опции шага тестирования:

Шаг тестирования определён только если предоставлены хотя бы одна из следующих TEST_... опций.

TEST_COMMAND <cmd>...

Переопределяет команду тестирования по умолчанию (generator expressions поддерживаются). Если эта опция не указана, по умолчанию шаг тестирования строит целевой test внешний проект. Эта опция может быть указана с <cmd> как пустой строкой, что позволяет определить шаг тестирования, но он ничего не сделает. Не указывайте ни одной из других TEST_... опций, если вы предоставляете пустую строку в качестве команды тестирования, но предпочтительнее вообще опустить все TEST_... опции, если целевой объект шага тестирования не нужен.

TEST_BEFORE_INSTALL <bool>

При включении этой опции шаг тестирования будет выполняться до шага установки. По умолчанию шаг тестирования выполняется после шага установки.

TEST_AFTER_INSTALL <bool>

Эта опция в основном полезна как способ указать, что шаг тестирования необходим, но все по умолчанию достаточны. Указание этой опции с булевым значением true гарантирует, что шаг тестирования определён и что он выполняется после шага установки. Если оба TEST_BEFORE_INSTALL и TEST_AFTER_INSTALL включены, последнее значение игнорируется.

TEST_EXCLUDE_FROM_MAIN <bool>

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

Опции ведения логов вывода:

Каждая из следующих LOG_... опций может быть использована для обертывания соответствующего шага в скрипт, чтобы захватить его вывод в файлы. Лог-файлы будут созданы в LOG_DIR если задано, в противном случае в каталоге STAMP_DIR с именами файлов, специфичными для шага.

LOG_DOWNLOAD <bool>

При включении вывод шага скачивания записывается в файлы.

LOG_UPDATE <bool>

При включении вывод шага обновления записывается в файлы.

LOG_PATCH <bool>

При включении вывод шага патчинга записывается в файлы.

LOG_CONFIGURE <bool>

При включении вывод шага конфигурации записывается в файлы.

LOG_BUILD <bool>

При включении вывод шага сборки записывается в файлы.

LOG_INSTALL <bool>

При включении вывод шага установки записывается в файлы.

LOG_TEST <bool>

При включении вывод шага тестирования записывается в файлы.

LOG_MERGED_STDOUTERR <bool>

При включении stdout и stderr будут объединены для любого шага, вывод которого записывается в файлы.

LOG_OUTPUT_ON_FAILURE <bool>

Эта опция действует только в том случае, если хотя бы одна из других LOG_<step> опций включена. Если произошла ошибка для шага, для которого включено ведение журнала в файл, вывод этого шага будет выведен в консоль, если LOG_OUTPUT_ON_FAILURE установлено в true. В случаях, когда записывается большой объём вывода, в консоль может быть выведен только конец этого вывода.

Опции доступа к терминалу:

В некоторых случаях шаги могут получить прямой доступ к терминалу. Предоставление шагу доступа к терминалу может позволить ему получить ввод с терминала, если это необходимо, например, для данных аутентификации, не предоставляемых другими опциями. С генератором Ninja эти опции помещают шаги в console job pool. Каждый шаг может получить доступ к терминалу индивидуально с помощью следующих опций:

USES_TERMINAL_DOWNLOAD <bool>

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

USES_TERMINAL_UPDATE <bool>

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

USES_TERMINAL_CONFIGURE <bool>

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

USES_TERMINAL_BUILD <bool>

Предоставить шагу сборки доступ к терминалу.

USES_TERMINAL_INSTALL <bool>

Предоставить шагу установки доступ к терминалу.

USES_TERMINAL_TEST <bool>

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

Опции целевых объектов:

DEPENDS <targets>...

Укажите другие целевые объекты, от которых зависит внешний проект. Другие целевые объекты будут обновлены перед выполнением любых шагов внешнего проекта. Поскольку внешний проект использует дополнительные пользовательские целевые объекты для каждого шага внутри, опция DEPENDS является наиболее удобным способом гарантировать, что все эти шаги зависят от других целевых объектов. Простое выполнение add_dependencies(<name> <targets>) не сделает ни один из шагов зависимым от <targets>.

EXCLUDE_FROM_ALL <bool>

При включении этой опции внешний проект исключается из целевого объекта ALL основной сборки.

STEP_TARGETS <step-target>...

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

INDEPENDENT_STEP_TARGETS <step-target>...

Генерировать пользовательские целевые объекты для указанных шагов и предотвратить применение к этим целевым объектам обычных зависимостей. Если эта опция не указана, значение по умолчанию взято из свойства каталога EP_INDEPENDENT_STEP_TARGETS. Эта опция в основном полезна для запуска отдельных шагов независимо, например, для настройки CDash, где каждый шаг должен запускаться и отчитываться индивидуально, а не как один целый процесс сборки. См. ExternalProject_Add_Step() ниже для дальнейшего обсуждения влияния этой опции.

Разные опции:

LIST_SEPARATOR <sep>

Для любой из различных ..._COMMAND опций замените ; на <sep> в указанных командных строках. Это может быть полезно в случаях, когда списковые переменные могут быть указаны в командах, где они должны оказаться в качестве разделенных пробелами аргументов (<sep> будет в данном случае строкой с одиночным пробелом).

COMMAND <cmd>...

Любая из других ..._COMMAND опций может иметь дополнительные команды, добавленные к ним, добавив столько COMMAND ... опций, сколько нужно (generator expressions поддерживаются). Например:

ExternalProject_Add(example
  ... # Download options, etc.
  BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
  COMMAND       ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
  COMMAND       ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
)

Также следует отметить, что каждый шаг сборки создается с помощью вызова ExternalProject_Add_Step(). См. документацию этой команды для автоматических подстановок, которые поддерживаются для некоторых опций.

Получение свойств проекта

ExternalProject_Get_Property

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

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

Функция сохраняет значения свойств в переменных с одинаковыми именами. Имена свойств соответствуют именам ключевых аргументов ExternalProject_Add(). Например, директорию исходных файлов можно получить следующим образом:

ExternalProject_Get_property(myExtProj SOURCE_DIR)
message("Source dir of myExtProj = ${SOURCE_DIR}")

Явное управление шагами

Функция ExternalProject_Add() сама по себе часто достаточна для включения внешнего проекта в основную сборку. В некоторых сценариях требуются дополнительные действия для реализации желаемого поведения, например, добавления пользовательского шага или предоставления шагов в качестве запускаемых вручную целевых объектов. Функции ExternalProject_Add_Step(), ExternalProject_Add_StepTargets() и ExternalProject_Add_StepDependencies предоставляют необходимый низкоуровневый контроль для реализации таких возможностей на уровне шагов.

ExternalProject_Add_Step

Функция ExternalProject_Add_Step() определяет дополнительный пользовательский шаг для внешнего проекта, определённого в предыдущем вызове ExternalProject_Add():

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

<name> совпадает с именем, переданным в исходном вызове ExternalProject_Add(). Указанный <step> не должен совпадать с одним из предопределённых шагов (mkdir, download, update, skip-update, patch, configure, build, install или test). Поддерживаемые опции:

COMMAND <cmd>...

Командная строка, которая будет выполнена этим пользовательским шагом (generator expressions поддерживаются). Эту опцию можно повторять несколько раз для указания нескольких команд, которые будут выполнены по порядку.

COMMENT "<text>..."

Текст, который будет напечатан при выполнении пользовательского шага.

DEPENDEES <step>...

Другие шаги (пользовательские или предопределённые), от которых зависит этот шаг.

DEPENDERS <step>...

Другие шаги (пользовательские или предопределённые), которые зависят от этого нового пользовательского шага.

DEPENDS <file>...

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

BYPRODUCTS <file>...

Файлы, которые будут сгенерированы этим пользовательским шагом, но у которых время модификации может или может не быть обновлено последующими сборками. Этот список файлов в конечном итоге будет передан в качестве опции BYPRODUCTS в add_custom_command(), используемой для реализации пользовательского шага внутри.

ALWAYS <bool>

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

EXCLUDE_FROM_MAIN <bool>

При включении эта опция указывает, что основной целевой объект внешнего проекта не зависит от пользовательского шага.

WORKING_DIRECTORY <dir>

Устанавливает рабочую директорию перед запуском команды пользовательского шага. Если эта опция не указана, директория будет равна значению CMAKE_CURRENT_BINARY_DIR в момент вызова ExternalProject_Add_Step().

LOG <bool>

Если установлено, это заставляет вывод пользовательского шага быть записанным в файлы во внешнем проекте LOG_DIR или STAMP_DIR (если указано).

USES_TERMINAL <bool>

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

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

ExternalProject_Add_StepTargets

Функция ExternalProject_Add_StepTargets() генерирует целевые объекты для перечисленных шагов. Имя каждого созданного целевого объекта будет иметь вид <name>-<step>:

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

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

Если указана опция NO_DEPENDS, целевой объект шага не будет зависеть от зависимостей внешнего проекта (т.е. от любых зависимостей от <name> пользовательского целевого объекта, созданного ExternalProject_Add()). Это обычно безопасно для шагов download, update и patch, так как им обычно не требуется обновление и построение зависимостей. Однако использование NO_DEPENDS для любых других предопределённых шагов может нарушить параллельную сборку. Используйте NO_DEPENDS только в тех случаях, когда точно известно, что указанные шаги не имеют зависимостей. Для пользовательских шагов подумайте о том, требуют ли пользовательские команды конфигурирования, построения и установки зависимостей.

Внутри ExternalProject_Add() вызывает ExternalProject_Add_Step() для создания каждого шага. Если были указаны STEP_TARGETS или INDEPENDENT_STEP_TARGETS, тогда ExternalProject_Add_StepTargets() также будет вызван после ExternalProject_Add_Step(). INDEPENDENT_STEP_TARGETS имеют установленную опцию NO_DEPENDS, в то время как STEP_TARGETS не имеют. Помимо этого, две опции приводят к вызову ExternalProject_Add_StepTargets() аналогичным образом. Даже если шаг не указан ни в одной из этих двух опций, ExternalProject_Add_StepTargets() всё равно можно вызвать позже для ручного определения целевого объекта для шага.

Опции STEP_TARGETS и INDEPENDENT_STEP_TARGETS для ExternalProject_Add() обычно являются наиболее простым способом обеспечения создания целевых объектов для конкретных шагов, представляющих интерес. Для пользовательских шагов ExternalProject_Add_StepTargets() необходимо вызывать явно, если целевой объект также должен быть создан для этого пользовательского шага. Альтернативой этим двум опциям является заполнение свойств каталога EP_STEP_TARGETS и EP_INDEPENDENT_STEP_TARGETS. Они действуют как значения по умолчанию для опций целевых объектов шага и могут сэкономить время, не нужно повторять один и тот же набор целевых объектов шагов при определении нескольких внешних проектов.

ExternalProject_Add_StepDependencies

Функция ExternalProject_Add_StepDependencies() может быть использована для добавления зависимостей к шагу. Добавляемые зависимости должны быть целевыми объектами, о которых CMake уже знает (это могут быть обычные исполняемые файлы или библиотеки, пользовательские целевые объекты или даже целевые объекты шага другого внешнего проекта):

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

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

Примеры

Следующий пример демонстрирует, как загрузить и собрать гипотетический проект с именем FooBar с github:

include(ExternalProject)
ExternalProject_Add(foobar
  GIT_REPOSITORY    git@github.com:FooCo/FooBar.git
  GIT_TAG           origin/release/1.2.3
)

Для примера также определите второй гипотетический внешний проект с именем SecretSauce, который загружается с веб-сервера. Указаны два URL-адреса, чтобы использовать более быструю внутреннюю сеть, если она доступна, со спадным резервным вариантом более медленного внешнего сервера. Проект — типичный проект Makefile без этапа настройки, поэтому некоторые из команд по умолчанию переопределяются. Требуется только сборка целевого объекта sauce:

find_program(MAKE_EXE NAMES gmake nmake make)
ExternalProject_Add(secretsauce
  URL               http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
                    https://www.somecompany.com/downloads/sauce-2.7.zip
  URL_HASH          MD5=d41d8cd98f00b204e9800998ecf8427e
  CONFIGURE_COMMAND ""
  BUILD_COMMAND     ${MAKE_EXE} sauce
)

Предположим, что этап сборки secretsauce требует, чтобы foobar уже был собран. Это можно принудительно обеспечить следующим образом:

ExternalProject_Add_StepDependencies(secretsauce build foobar)

Другой вариант — создать пользовательский целевой объект для этапа сборки foobar и заставить secretsauce зависеть от него, а не от всего проекта foobar. Это означало бы, что нужно собрать только foobar, а не нужно запускать его этапы установки или тестирования, прежде чем можно будет собрать secretsauce. Зависимость также может быть определена вместе с проектом secretsauce:

ExternalProject_Add_StepTargets(foobar build)
ExternalProject_Add(secretsauce
  URL               http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
                    https://www.somecompany.com/downloads/sauce-2.7.zip
  URL_HASH          MD5=d41d8cd98f00b204e9800998ecf8427e
  CONFIGURE_COMMAND ""
  BUILD_COMMAND     ${MAKE_EXE} sauce
  DEPENDS           foobar-build
)

Вместо вызова ExternalProject_Add_StepTargets() целевой объект можно определить вместе с самим проектом foobar:

ExternalProject_Add(foobar
  GIT_REPOSITORY git@github.com:FooCo/FooBar.git
  GIT_TAG        origin/release/1.2.3
  STEP_TARGETS   build
)

Если у многих внешних проектов должен быть один и тот же набор целевых объектов шагов, установка свойства каталога может быть более удобной. Целевой объект build этапа может быть создан автоматически путём установки свойства каталога EP_STEP_TARGETS перед созданием внешних проектов с помощью ExternalProject_Add():

set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)

Наконец, предположим, что secretsauce предоставляет скрипт с именем makedoc, который может быть использован для генерации собственной документации. Предположим также, что скрипт ожидает, что директория вывода будет предоставлена в качестве единственного параметра, и что он должен быть запущен из каталога исходных кодов secretsauce. Пользовательский шаг и пользовательский целевой объект для запуска скрипта можно определить следующим образом:

ExternalProject_Add_Step(secretsauce docs
  COMMAND           <SOURCE_DIR>/makedoc <BINARY_DIR>
  WORKING_DIRECTORY <SOURCE_DIR>
  COMMENT           "Building secretsauce docs"
  ALWAYS            TRUE
  EXCLUDE_FROM_MAIN TRUE
)
ExternalProject_Add_StepTargets(secretsauce docs)

Затем пользовательский шаг можно запустить из основной сборки следующим образом:

cmake --build . --target secretsauce-docs