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

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