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

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

Subversion

SVN_REPOSITORY <url>

URL репозитория Subversion.

SVN_REVISION -r<rev>

Ревизия для выхода в Subversion репозитории.

SVN_USERNAME <username>

Имя пользователя для проверки и обновления Subversion.

SVN_PASSWORD <password>

Пароль для проверки и обновления Subversion.

SVN_TRUST_CERT <bool>

Указывает, следует ли доверять сертификату сайта сервера Subversion. Если включено, параметр --trust-server-cert передаётся командам проверки и обновления svn.

Mercurial

HG_REPOSITORY <url>

URL репозитория mercurial.

HG_TAG <tag>

Имя ветки, тега или идентификатор коммита mercurial.

CVS

CVS_REPOSITORY <cvsroot>

CVSROOT репозитория CVS.

CVS_MODULE <mod>

Модуль для выхода из репозитория CVS.

CVS_TAG <tag>

Тег для выхода из репозитория CVS.

Параметры шага обновления/патча:

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

UPDATE_COMMAND <cmd>...

Переопределяет шаг обновления метода загрузки пользовательской командой. Команда может использовать generator expressions.

UPDATE_DISCONNECTED <bool>

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

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

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

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

PATCH_COMMAND <cmd>...

Указывает пользовательскую команду для применения исправлений к исходным кодам после обновления. По умолчанию команда исправлений не определена. Обратите внимание, что может быть сложно определить подходящую команду исправлений, которая работает надёжно, особенно для методов загрузки, таких как git, где изменение GIT_TAG не отбросит изменения от предыдущего исправления, но команда исправлений будет вызвана снова после обновления до нового тега.

Параметры шага конфигурации:

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

CONFIGURE_COMMAND <cmd>...

Команда конфигурации по умолчанию выполняет CMake с несколькими параметрами, основанными на основном проекте. Добавляемые параметры, как правило, только те, которые необходимы для использования того же генератора, что и в основном проекте, но параметр CMAKE_GENERATOR может быть использован для переопределения этого. Проект отвечает за добавление всех деталей цепочки инструментов, флагов или других настроек, которые он хочет повторно использовать из основного проекта или иным образом указать (см. CMAKE_ARGS, CMAKE_CACHE_ARGS и CMAKE_CACHE_DEFAULT_ARGS ниже).

Для внешних проектов, не являющихся проектами CMake, необходимо использовать параметр CONFIGURE_COMMAND для переопределения команды конфигурации по умолчанию (generator expressions поддерживаются). Для проектов, которые не требуют этапа конфигурации, укажите этот параметр с пустой строкой в качестве команды для выполнения.

CMAKE_COMMAND /.../cmake

Укажите альтернативный исполняемый файл cmake для этапа конфигурации (используйте абсолютный путь). Это, как правило, не рекомендуется, так как обычно желательно использовать одну и ту же версию CMake на протяжении всего процесса сборки. Этот параметр игнорируется, если была указана пользовательская команда конфигурации с помощью CONFIGURE_COMMAND.

CMAKE_GENERATOR <gen>

Переопределите генератор CMake, используемый для этапа конфигурации. Без этого параметра будет использоваться тот же генератор, что и в основной сборке. Этот параметр игнорируется, если была указана пользовательская команда конфигурации с помощью CONFIGURE_COMMAND.

CMAKE_GENERATOR_PLATFORM <platform>

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

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

CMAKE_GENERATOR_TOOLSET <toolset>

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

CMAKE_GENERATOR_INSTANCE <instance>

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

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

CMAKE_ARGS <arg>...

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

Добавлено в версии 3.3: Аргументы могут использовать generator expressions.

CMAKE_CACHE_ARGS <arg>...

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

Добавлено в версии 3.3: Аргументы могут использовать generator expressions.

CMAKE_CACHE_DEFAULT_ARGS <arg>...

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

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

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

SOURCE_SUBDIR <dir>

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

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

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

CONFIGURE_HANDLED_BY_BUILD <bool>

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

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

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

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

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

BUILD_COMMAND <cmd>...

Переопределяет команду сборки по умолчанию (generator expressions поддерживаются). Если этот параметр не задан, команда сборки по умолчанию будет выбрана для наилучшей интеграции со основной сборкой (например, использование рекурсивного make для генераторов Makefile или cmake --build если проект использует сборку CMake). Этот параметр может быть задан пустой строкой для того, чтобы этап сборки ничего не делал.

BUILD_IN_SOURCE <bool>

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

BUILD_ALWAYS <bool>

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

BUILD_BYPRODUCTS <file>...

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

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

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

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

INSTALL_COMMAND <cmd>...

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

Примечание

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

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

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

Опции шага тестирования:

Этап тестирования определен только если указаны как минимум одна из следующих TEST_... опций.

TEST_COMMAND <cmd>...

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

TEST_BEFORE_INSTALL <bool>

При включении этой опции, этап тестирования будет выполнен до этапа установки. По умолчанию этап тестирования выполняется после этапа установки.

TEST_AFTER_INSTALL <bool>

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

TEST_EXCLUDE_FROM_MAIN <bool>

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

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

Опции ведения журнала вывода:

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

LOG_DOWNLOAD <bool>

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

LOG_UPDATE <bool>

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

LOG_PATCH <bool>

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

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

LOG_CONFIGURE <bool>

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

LOG_BUILD <bool>

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

LOG_INSTALL <bool>

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

LOG_TEST <bool>

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

LOG_MERGED_STDOUTERR <bool>

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

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

LOG_OUTPUT_ON_FAILURE <bool>

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

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

Опции доступа к терминалу:

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

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

USES_TERMINAL_DOWNLOAD <bool>

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

USES_TERMINAL_UPDATE <bool>

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

USES_TERMINAL_CONFIGURE <bool>

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

USES_TERMINAL_BUILD <bool>

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

USES_TERMINAL_INSTALL <bool>

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

USES_TERMINAL_TEST <bool>

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

Опции целевых объектов:

DEPENDS <targets>...

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

EXCLUDE_FROM_ALL <bool>

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

STEP_TARGETS <step-target>...

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

INDEPENDENT_STEP_TARGETS <step-target>...

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

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

Разные опции:

LIST_SEPARATOR <sep>

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

COMMAND <cmd>...

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

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

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

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

ExternalProject_Get_Property

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

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

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

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

Явное управление этапами

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

ExternalProject_Add_Step

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

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

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

COMMAND <cmd>...

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

COMMENT "<text>..."

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

DEPENDEES <step>...

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

DEPENDERS <step>...

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

DEPENDS <file>...

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

INDEPENDENT <bool>

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

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

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

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

BYPRODUCTS <file>...

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

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

ALWAYS <bool>

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

EXCLUDE_FROM_MAIN <bool>

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

WORKING_DIRECTORY <dir>

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

LOG <bool>

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

USES_TERMINAL <bool>

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

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

Добавлена в версии 3.3: Подстановка маркеров расширена на результаты.

Добавлена в версии 3.11: Маркер подстановки <DOWNLOAD_DIR>.

ExternalProject_Add_StepTargets

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

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

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

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

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

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

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

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

ExternalProject_Add_StepDependencies

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

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

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

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

Примеры

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

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

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

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

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

ExternalProject_Add_StepDependencies(secretsauce build foobar)

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

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

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

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

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

set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)

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

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

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

cmake --build . --target secretsauce-docs