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

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

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

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

Предоставить доступ к терминалу шагу конфигурации.

USES_TERMINAL_BUILD <bool>

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

USES_TERMINAL_INSTALL <bool>

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

USES_TERMINAL_TEST <bool>

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

Параметры целевых объектов:

DEPENDS <targets>...

Укажите другие целевые объекты, от которых зависит внешний проект. Другие целевые объекты будут обновлены перед выполнением любого шага внешнего проекта. Поскольку внешний проект использует дополнительные пользовательские целевые объекты для каждого шага внутри, параметр DEPENDS является наиболее удобным способом обеспечения зависимости всех этих шагов от других целевых объектов. Простое выполнение add_dependencies(<name> <targets>) не сделает ни один из шагов зависимым от <targets>.

EXCLUDE_FROM_ALL <bool>

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

STEP_TARGETS <step-target>...

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

INDEPENDENT_STEP_TARGETS <step-target>...

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

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

Разные параметры:

LIST_SEPARATOR <sep>

Для любого из различных параметров ..._COMMAND, замените ; на <sep> в указанных командных строках. Это может быть полезно, когда переменные списков используются в командах, где они должны оказаться в качестве аргументов, разделённых пробелами (<sep> в этом случае будет строкой с единственным пробелом).

COMMAND <cmd>...

Любой из других параметров ..._COMMAND может иметь дополнительные команды, добавленные к ним, следуя за ними, так же как и многими параметрами COMMAND ... (generator expressions поддерживаются). Например:

ExternalProject_Add(example
  ... # Download options, etc.
  BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
  COMMAND       ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
  COMMAND       ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
)

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

Получение свойств проекта

ExternalProject_Get_Property

Функция ExternalProject_Get_Property() извлекает свойства целевых объектов внешнего проекта:

ExternalProject_Get_Property(<name> <prop1> [<prop2>...])

Функция сохраняет значения свойств в переменные с таким же именем. Имена свойств соответствуют именам аргументов ключевых слов в ExternalProject_Add(). Например, каталог исходных файлов можно получить следующим образом:

ExternalProject_Get_property(myExtProj SOURCE_DIR)
message("Source dir of myExtProj = ${SOURCE_DIR}")

Управление явными шагами

Функция ExternalProject_Add() часто достаточна для включения внешнего проекта в основной сборке. В некоторых сценариях требуется дополнительная работа для реализации желаемого поведения, например, добавления пользовательского шага или предоставления шагов как запускаемых вручную целевых объектов. Функции ExternalProject_Add_Step(), ExternalProject_Add_StepTargets() и ExternalProject_Add_StepDependencies обеспечивают необходимый низкоуровневый контроль для реализации таких возможностей на уровне шагов.

ExternalProject_Add_Step

Функция ExternalProject_Add_Step() задаёт дополнительный пользовательский шаг для внешнего проекта, определённого ранее вызовом ExternalProject_Add():

ExternalProject_Add_Step(<name> <step> [<option>...])

<name> — это то же имя, что и переданное при первоначальном вызове ExternalProject_Add(). Указанный <step> не должен совпадать с одним из предопределённых шагов (mkdir, download, update, patch, configure, build, install или test). Поддерживаемые параметры:

COMMAND <cmd>...

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

COMMENT "<text>..."

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

DEPENDEES <step>...

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

DEPENDERS <step>...

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

DEPENDS <file>...

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

INDEPENDENT <bool>

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

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

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

Если для независимого шага создаётся целевой объект функцией ExternalProject_Add() с параметром STEP_TARGETS или функцией 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. Оно действует как значение по умолчанию для опций целевой задачи шага и может сэкономить время, когда требуется неоднократно указывать тот же набор целевых задач шагов при определении нескольких внешних проектов.

New in version 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

New in version 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