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_GENERATOR может быть задан для переопределения этого. Проект отвечает за добавление любых деталей инструментальной цепочки, флагов или других настроек, которые он хочет повторно использовать из основного проекта или иначе указать (см. CMAKE_ARGS, CMAKE_CACHE_ARGS и CMAKE_CACHE_DEFAULT_ARGS ниже).

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

Если как основной, так и внешний проект используют make в качестве инструмента сборки, этап сборки внешнего проекта вызывается как рекурсивный make с использованием $(MAKE). Это позволит передать некоторые настройки инструмента сборки от основного проекта к внешнему проекту. Если основной или внешний проект не использует make, никакие настройки инструмента сборки не будут переданы внешнему проекту, кроме тех, которые установлены на этапе конфигурации (т. е. выполнение ninja -v в основном проекте не передаст -v на этапе сборки внешнего проекта, даже если он также использует ninja в качестве инструмента сборки).

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

INSTALL_COMMAND <cmd>...

Этап установки внешнего проекта вызывается в рамках этапа сборки основного проекта. Он выполняется после этапа сборки внешнего проекта и может выполняться до или после этапа тестирования внешнего проекта (см. параметр TEST_BEFORE_INSTALL ниже). Правила установки внешнего проекта не входят в правила установки основного проекта, поэтому, если что-либо из внешнего проекта должно быть установлено в рамках основной сборки, это необходимо указать в основной сборке как дополнительные команды install(). По умолчанию этап установки собирает целевой объект install внешнего проекта, но это можно переопределить с помощью пользовательской команды с помощью этого параметра (generator expressions поддерживаются). Передача пустой строки в качестве параметра <cmd> заставляет этап установки ничего не делать.

Примечание

Если переменная окружения CMAKE_INSTALL_MODE установлена во время сборки основного проекта, она будет иметь эффект только при соблюдении следующих условий:

• Этап настройки основного проекта предполагал, что внешний проект использует CMake в качестве системы сборки.
• Команда установки внешнего проекта действительно выполняется. Обратите внимание, что из-за того, как ExternalProject может использовать отметки времени внутри, если ничего, на что зависит этап установки, не нужно перевыполнять, команде установки также может не потребоваться выполнение.

Также обратите внимание, что ExternalProject не проверяет, изменилась ли переменная окружения CMAKE_INSTALL_MODE с одной итерации на другую.

Параметры этапа тестирования:

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

В версии 3.2.

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

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

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 вариантов и CMAKE_ARGS, замените ; на <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