ExternalProject

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

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

ExternalProject_Add

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

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

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

Опции каталогов:

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

PREFIX <dir>

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

TMP_DIR <dir>

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

STAMP_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>

В противном случае, если свойство каталога 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. Относительные пути интерпретируются относительно 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_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. Это означает, что значения действуют только как начальные значения по умолчанию и не переопределяют никакие переменные, уже заданные в предыдущий запуск. Используйте этот параметр с осторожностью, так как он может привести к разному поведению в зависимости от того, начинается ли сборка с пустого каталога сборки или используется содержимое предыдущей сборки.

SOURCE_SUBDIR <dir>

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

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

Если шаг конфигурации предположил, что внешний проект использует CMake в качестве своей системы сборки, то шаг сборки также будет использовать CMake. В противном случае шаг сборки предположит Makefile-based сборку и просто запустит 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().

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

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

INSTALL_COMMAND <cmd>...

Этап установки внешнего проекта вызывается как часть основного этапа построения проекта. Он выполняется после этапа построения внешнего проекта и может выполняться до или после этапа тестирования внешнего проекта (см. параметр 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>

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

TEST_EXCLUDE_FROM_MAIN <bool>

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

Параметры ведения журналов вывода:

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

LOG_DOWNLOAD <bool>

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

LOG_UPDATE <bool>

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

LOG_CONFIGURE <bool>

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

LOG_BUILD <bool>

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

LOG_INSTALL <bool>

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

LOG_TEST <bool>

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

Параметры доступа к терминалу:

В некоторых случаях шагам может быть предоставлен прямой доступ к терминалу. Предоставление шагу доступа к терминалу может позволить ему получать ввод с терминала, если это необходимо, например, для данных аутентификации, не предоставленных другими параметрами. С генератором 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>

При установке этой опции вывод пользовательского шага будет записан во файлы в 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