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>

Новое в версии 3.14.

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

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 не отключена. Тип архива определяется путём проверки фактического содержимого, а не на основе расширения файла.

Изменено в версии 3.7: Разрешено несколько URL.

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>

Новая в версии 3.6.

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

DOWNLOAD_NO_PROGRESS <bool>

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

TIMEOUT <seconds>

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

INACTIVITY_TIMEOUT <seconds>

Новая в версии 3.19.

Прервать операцию после периода бездействия.

HTTP_USERNAME <username>

Новая в версии 3.7.

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

HTTP_PASSWORD <password>

Новая в версии 3.7.

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

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

Новая в версии 3.7.

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

TLS_VERIFY <bool>

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

Изменено в версии 3.6: Эта опция также применима к вызовам git clone.

TLS_CAINFO <file>

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

NETRC <level>

Новая в версии 3.11.

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

IGNORED

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

OPTIONAL

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

REQUIRED

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

NETRC_FILE <file>

Новая в версии 3.11.

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

Новая в версии 3.1: Добавлена поддержка расширений tbz2, .tar.xz, .txz, и .7z.

Git

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

GIT_REPOSITORY <url>

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

GIT_TAG <tag>

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

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

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

GIT_REMOTE_NAME <name>

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

GIT_SUBMODULES <module>...

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

Изменено в версии 3.16: Когда CMP0097 установлено в NEW, если это значение установлено на пустую строку, подмодули не инициализируются и не обновляются.

GIT_SUBMODULES_RECURSE <bool>

Добавлено в версии 3.17.

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

GIT_SHALLOW <bool>

Добавлено в версии 3.6.

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

GIT_PROGRESS <bool>

Добавлено в версии 3.8.

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

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

Добавлено в версии 3.8.

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

GIT_REMOTE_UPDATE_STRATEGY <strategy>

Добавлено в версии 3.18.

Когда 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 относится к валидному ref, если только нет несохранённых изменений, которые не могут быть успешно восстановлены.

Переменная 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>

Добавлено в версии 3.2.

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

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

Это может привести к автоматическому созданию целевого шага для шага download. См. политику CMP0114.

Параметры шага исправления:

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>

Новая функция в версии 3.1.

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

CMAKE_GENERATOR_TOOLSET <toolset>

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

CMAKE_GENERATOR_INSTANCE <instance>

Новая функция в версии 3.11.

Передайте команду CMake для выбора экземпляра генератора (см. CMAKE_GENERATOR_INSTANCE). Ошибка возникает при использовании данного параметра без параметра CMAKE_GENERATOR.

CMAKE_ARGS <arg>...

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

Новая функция в версии 3.3: Аргументы могут использовать generator expressions.

CMAKE_CACHE_ARGS <arg>...

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

Новая функция в версии 3.3: Аргументы могут использовать generator expressions.

CMAKE_CACHE_DEFAULT_ARGS <arg>...

Новая функция в версии 3.2.

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

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

SOURCE_SUBDIR <dir>

Новая функция в версии 3.7.

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

Новая функция в версии 3.14: Когда включён параметр BUILD_IN_SOURCE, то BUILD_COMMAND используется для указания альтернативной директории в дереве исходных кодов.

CONFIGURE_HANDLED_BY_BUILD <bool>

Новая функция в версии 3.20.

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

Параметры этапа сборки:

Если этап конфигурации предположил, что внешний проект использует 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>...

Новая функция в версии 3.2.

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

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

TEST_EXCLUDE_FROM_MAIN <bool>

Новая версия с 3.2.

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

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

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

LOG_DOWNLOAD <bool>

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

LOG_UPDATE <bool>

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

LOG_PATCH <bool>

Новая версия с 3.14.

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

LOG_CONFIGURE <bool>

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

LOG_BUILD <bool>

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

LOG_INSTALL <bool>

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

LOG_TEST <bool>

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

LOG_MERGED_STDOUTERR <bool>

Новая версия с 3.14.

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

LOG_OUTPUT_ON_FAILURE <bool>

Новая версия с 3.14.

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

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

Новая версия с 3.4.

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

USES_TERMINAL_DOWNLOAD <bool>

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

USES_TERMINAL_UPDATE <bool>

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

USES_TERMINAL_PATCH <bool>

Новая версия с 3.20.

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

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_StepTargets() ниже.

INDEPENDENT_STEP_TARGETS <step-target>...

Устарело начиная с версии 3.19: Это разрешено только если политика CMP0114 не установлена в NEW.

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

Прочие параметры:

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

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

INDEPENDENT <bool>

Добавлен в версии 3.19.

Указывает, независим ли этот шаг от внешних зависимостей, указанных параметром DEPENDS вызова ExternalProject_Add(). По умолчанию FALSE. Шаги, помеченные как независимые, могут зависеть только от других шагов, помеченных как независимые. См. политику CMP0114.

Обратите внимание, что в данном случае термин «независимый» относится только к независимости от внешних целей, указанных параметром DEPENDS, и ортогонален зависимостям шага от других шагов.

Если для независимого шага создаётся целевой объект с помощью параметра STEP_TARGETS функции ExternalProject_Add() или функции ExternalProject_Add_StepTargets(), он не будет зависеть от внешних целей, но может зависеть от целей других шагов.

BYPRODUCTS <file>...

Добавлен в версии 3.2.

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

ALWAYS <bool>

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

EXCLUDE_FROM_MAIN <bool>

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

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().

Новое в версии 3.3: Замена токенов расширена до побочных продуктов.

Новое в версии 3.11: Токен подстановки <DOWNLOAD_DIR>.

ExternalProject_Add_StepTargets

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

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

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

Внутренне, ExternalProject_Add() вызывает ExternalProject_Add_Step() для создания каждого шага. Если были указаны какие-либо STEP_TARGETS, то ExternalProject_Add_StepTargets() также будет вызван после ExternalProject_Add_Step(). Даже если шаг не упоминается в опции STEP_TARGETS, ExternalProject_Add_StepTargets() может быть вызван позже для ручного определения цели для шага.

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

Введено в версии 3.19: Если CMP0114 установлено в NEW, цели шагов полностью отвечают за хранение пользовательских команд, реализующих их шаги. Основная цель, созданная ExternalProject_Add, зависит от целей шагов, а цели шагов зависят друг от друга. Зависимости на уровне целей соответствуют зависимостям на уровне файлов, используемым пользовательскими командами для каждого шага. Цели шагов, созданные с помощью опции INDEPENDENT ExternalProject_Add_Step(), не зависят от внешних целей, указанных в опции DEPENDS ExternalProject_Add(). Предварительно определённые шаги mkdir, download, update и patch независимы.

Если CMP0114 не NEW, доступно следующее устаревшее поведение:

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

ExternalProject_Add_StepDependencies

Введено в версии 3.2.

Функция 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