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

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

При указании со значением true, метки времени извлечённых файлов будут соответствовать меткам времени в архиве. В противном случае, метки времени извлечённых файлов будут отражать время, в которое была выполнена операция извлечения. Если URL загрузки изменится, метки времени, основанные на метках времени в архиве, могут привести к тому, что зависимые цели не будут перестроены, когда это потенциально необходимо. Поэтому, если метки времени файлов не имеют значения для проекта каким-либо образом, используйте значение false для этой опции. Если DOWNLOAD_EXTRACT_TIMESTAMP не указано, значение по умолчанию — false. См. политику CMP0135.

DOWNLOAD_NO_EXTRACT <bool>

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

Позволяет отключить часть извлечения в шаге загрузки, передав значение boolean 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_VERIFY не указана, а CMAKE_TLS_VERIFY не установлена, поведение будет определяться значениями по умолчанию git. Обычно, значение sslVerify настройки git по умолчанию равно true, но пользователь может изменить это на глобальном уровне.

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.

Изменено в версии 3.27: Относительный URL будет разрешен на основе удаленного родительского проекта, с учетом CMP0150. Обратитесь к документации по политике для получения информации о том, как выбирается удаленный сервер, включая ситуации, когда выбор удаленного сервера может завершиться неудачей. Удаленные серверы на локальной файловой системе должны всегда использовать абсолютные пути.

GIT_TAG <tag>

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

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

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

Обратите внимание, что если не указано, GIT_TAG по умолчанию устанавливается в значение master, а не в имя по умолчанию Git-ветки.

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 (см. ниже). Обратите внимание, что если ветка, указанная в GIT_TAG, отличается от ветки upstream, которая в настоящее время отслеживается, перебазирование небезопасно. В этой ситуации REBASE будет молча обрабатываться как CHECKOUT вместо этого.

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

Изменено в версии 3.27: Если UPDATE_DISCONNECTED истинно, шаг обновления будет выполнен, если любые детали шага обновления или загрузки изменены. Кроме того, при использовании метода загрузки/обновления git, логика обновления будет изменена для пропуска попыток связи с удалённым сервером. Если GIT_TAG упоминает ref, который не известен локально, шаг обновления завершится фатальной ошибкой.

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

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

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

Если этап конфигурации предполагал, что внешний проект использует CMake в качестве системы сборки, то этап установки также будет. В противном случае этап установки будет предполагать Makefile-based сборку и просто выполнит make install в качестве этапа установки по умолчанию. Это можно переопределить с помощью пользовательских команд установки, если это необходимо.

INSTALL_COMMAND <cmd>...

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

INSTALL_BYPRODUCTS <file>...

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

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

Примечание

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

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

BYPRODUCTS <file>...

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

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