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_SUBMODULES_RECURSE <bool>

Укажите, нужно ли обновлять подмодули git (если они есть) рекурсивно, передав флаг --recursive команде git submodule update. Если не указано, значение по умолчанию — включено.

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.

GIT_REMOTE_UPDATE_STRATEGY <strategy>

Когда GIT_TAG относится к удалённой ветке, этот параметр можно использовать для указания поведения шага обновления. <strategy> должен быть одним из следующих:

CHECKOUT

Игнорировать локальную ветку и всегда создавать ветку, указанную в GIT_TAG.

REBASE

Попытаться выполнить слияние текущей ветки с веткой, указанной в GIT_TAG. Если есть несохранённые локальные изменения, они будут сохранены временно, а затем восстановлены после слияния. Если слияние или восстановление сохранённых изменений завершатся неудачей, слияние будет прервано, и сборка завершится с ошибкой. Если GIT_REMOTE_UPDATE_STRATEGY отсутствует, эта стратегия является стратегией по умолчанию, если стратегия по умолчанию не была переопределена с помощью CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY (см. ниже).

REBASE_CHECKOUT

То же, что и REBASE , за исключением того, что если слияние завершится неудачей, будет создан аннотированный тег в исходном положении HEAD до слияния, а затем будет выбрана ветка GIT_TAG так же, как и стратегия CHECKOUT . Сообщение, хранящееся в аннотированном теге, будет содержать информацию о том, что было предпринято, а имя тега будет включать отметку времени, поэтому каждый неудачный запуск будет добавлять новый тег. Эта стратегия гарантирует, что никакие изменения не будут потеряны, но обновления всегда должны быть успешными, если GIT_TAG относится к валидному этапу, если нет несохранённых изменений, которые не могут быть восстановлены успешно.

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

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 и просто выполнит 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_... параметров может использоваться для обертывания соответствующего этапа в сценарий, чтобы записать его вывод в файлы. Файлы журнала будут созданы в 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, patch, configure, build, install или test). Поддерживаемые параметры:

COMMAND <cmd>...

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

COMMENT "<text>..."

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

DEPENDEES <step>...

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

DEPENDERS <step>...

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

DEPENDS <file>...

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

BYPRODUCTS <file>...

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

ALWAYS <bool>

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

EXCLUDE_FROM_MAIN <bool>

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

WORKING_DIRECTORY <dir>

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

LOG <bool>

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

USES_TERMINAL <bool>

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

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

ExternalProject_Add_StepTargets

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

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

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

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

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

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

ExternalProject_Add_StepDependencies

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

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

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

Примеры

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

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

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

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

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

ExternalProject_Add_StepDependencies(secretsauce build foobar)

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

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

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

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

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

set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)

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

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

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

cmake --build . --target secretsauce-docs