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=<value>

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

URL_MD5 <md5>

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

DOWNLOAD_NAME <fname>

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

DOWNLOAD_NO_EXTRACT <bool>

Позволяет отключить этап извлечения при загрузке, передав для этого параметра значение boolean 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))

Git

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

GIT_REPOSITORY <url>

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

GIT_TAG <tag>

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

• Если локальная копия уже имеет коммит, соответствующий хэшу, проверка изменений каждый раз при повторном запуске 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_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 и просто запустить 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>

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