ExternalProject

• Команды

  • Определение внешнего проекта
  • Получение свойств проекта
  • Явное управление этапами
• Примеры

Команды

Определение внешнего проекта

ExternalProject_Add

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

ExternalProject_Add(<name> [<option>...])

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

Опции каталогов:

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

PREFIX <dir>

Корневой каталог внешнего проекта. Если не указано иное, все остальные каталоги, связанные с внешним проектом, будут созданы внутри него.

TMP_DIR <dir>

Каталог для хранения временных файлов.

STAMP_DIR <dir>

Каталог для хранения отметки времени каждого этапа. Лог-файлы отдельных этапов также создаются здесь, если не переопределено опцией LOG_DIR (см. Опции ведения журнала ниже).

LOG_DIR <dir>

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

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

DOWNLOAD_DIR <dir>

Каталог для хранения загруженных файлов перед их распаковкой. Этот каталог используется только методом загрузки URL, все другие методы загрузки используют SOURCE_DIR напрямую вместо него.

SOURCE_DIR <dir>

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

Примечание

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

BINARY_DIR <dir>

Указывает расположение каталога сборки. Эта опция игнорируется, если включена BUILD_IN_SOURCE.

INSTALL_DIR <dir>

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

Если любая из вышеперечисленных ..._DIR опций не указана, их значения вычисляются следующим образом. Если указана опция PREFIX или свойство каталога EP_PREFIX задано, тогда внешний проект собирается и устанавливается в указанный префикс:

TMP_DIR      = <prefix>/tmp
STAMP_DIR    = <prefix>/src/<name>-stamp
DOWNLOAD_DIR = <prefix>/src
SOURCE_DIR   = <prefix>/src/<name>
BINARY_DIR   = <prefix>/src/<name>-build
INSTALL_DIR  = <prefix>
LOG_DIR      = <STAMP_DIR>

В противном случае, если свойство каталога EP_BASE задано, компоненты внешнего проекта хранятся в указанном базовом каталоге:

TMP_DIR      = <base>/tmp/<name>
STAMP_DIR    = <base>/Stamp/<name>
DOWNLOAD_DIR = <base>/Download/<name>
SOURCE_DIR   = <base>/Source/<name>
BINARY_DIR   = <base>/Build/<name>
INSTALL_DIR  = <base>/Install/<name>
LOG_DIR      = <STAMP_DIR>

Если не указаны PREFIX, EP_PREFIX, или EP_BASE, то значение PREFIX по умолчанию устанавливается в <name>-prefix. Относительные пути интерпретируются относительно CMAKE_CURRENT_BINARY_DIR в момент вызова ExternalProject_Add().

Опции шага загрузки:

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

DOWNLOAD_COMMAND <cmd>...

Переопределяет команду, используемую для шага загрузки (generator expressions поддерживаются). Если эта опция задана, все другие опции загрузки будут игнорироваться. Указание пустой строки для <cmd> эффективно отключает шаг загрузки.

Загрузка по URL

URL <url1> [<url2>...]

Список путей и/или URL(ов) исходного кода внешнего проекта. Если задано более одного URL, они будут пробоваться по очереди до тех пор, пока один не будет успешным. URL может быть обычным путем в локальной файловой системе (в этом случае должен быть указан только один URL) или любым поддерживаемым URL для загрузки командой file(DOWNLOAD). Путь в локальной файловой системе может ссылаться на существующую директорию или на архивный файл, в то время как URL должен указывать на файл, который может обрабатываться как архив. При использовании архива он будет автоматически распакован, если опция DOWNLOAD_NO_EXTRACT не отключит это. Тип архива определяется путем проверки фактического содержимого, а не по расширению файла.

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

URL_HASH <algo>=<hashValue>

Хэш архиваемого файла для загрузки. Аргумент должен иметь вид <algo>=<hashValue> , где algo может быть любым из алгоритмов хэширования, поддерживаемых командой file(). Указание этой опции настоятельно рекомендуется для загрузки по URL, так как она гарантирует целостность загружаемого содержимого. Она также используется для проверки ранее загруженного файла, что позволяет избежать подключения к удаленному расположению, если в локальной директории уже есть файл из предыдущей загрузки, соответствующий указанному хэшу.

URL_MD5 <md5>

Эквивалентно URL_HASH MD5=<md5>.

DOWNLOAD_NAME <fname>

Имя файла для использования при загрузке. Если не указано, имя файла определяется из конца URL. Эта опция редко используется, имя по умолчанию обычно подходит и обычно не используется за пределами кода, внутреннего для модуля ExternalProject.

DOWNLOAD_EXTRACT_TIMESTAMP <bool>

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

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

DOWNLOAD_NO_EXTRACT <bool>

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

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

DOWNLOAD_NO_PROGRESS <bool>

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

TIMEOUT <seconds>

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

INACTIVITY_TIMEOUT <seconds>

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

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

HTTP_USERNAME <username>

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

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

HTTP_PASSWORD <password>

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

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

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

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

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

TLS_VERIFY <bool>

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

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

TLS_CAINFO <file>

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

NETRC <level>

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

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

IGNORED

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

OPTIONAL

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

REQUIRED

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

NETRC_FILE <file>

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

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

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

Git

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

GIT_REPOSITORY <url>

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

GIT_TAG <tag>

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

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

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

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

GIT_REMOTE_NAME <name>

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

GIT_SUBMODULES <module>...

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

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

GIT_SUBMODULES_RECURSE <bool>

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

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

GIT_SHALLOW <bool>

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

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

GIT_PROGRESS <bool>

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

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

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

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

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

GIT_REMOTE_UPDATE_STRATEGY <strategy>

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

Когда GIT_TAG ссылается на удалённую ветку, этот параметр используется для указания поведения операции обновления. Значение <strategy> должно быть одним из следующих:

CHECKOUT

Игнорировать локальную ветку и всегда переключаться на ветку, указанную параметром GIT_TAG.

REBASE

Попробовать ребазить текущую ветку на ту, которая указана параметром GIT_TAG . Если есть несохранённые локальные изменения, они будут отложены, а затем снова восстановлены после ребезинга. Если ребезинг или восстановление отложенных изменений завершатся неудачей, прервите ребезинг и остановитесь с ошибкой. Если GIT_REMOTE_UPDATE_STRATEGY отсутствует, это стратегия по умолчанию, если стратегия по умолчанию не переопределена CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY (см. ниже). Обратите внимание, что если ветка, указанная в GIT_TAG отличается от ветки, отслеживаемой в настоящее время, выполнять ребаз небезопасно. В этой ситуации REBASE будет молча трактоваться как CHECKOUT.

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 не указан, этап конфигурации предполагает, что во внешнем проекте в корне дерева исходных кодов (т. е. в SOURCE_DIR ) имеется файл CMakeLists.txt. Параметр SOURCE_SUBDIR можно использовать для указания альтернативной директории в дереве исходных кодов, которая будет использоваться как корень дерева исходных кодов CMake. Путь должен быть относительным и будет интерпретироваться как относительный к SOURCE_DIR.

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

CONFIGURE_HANDLED_BY_BUILD <bool>

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

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

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

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

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

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

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

INSTALL_COMMAND <cmd>...

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

INSTALL_BYPRODUCTS <file>...

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

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

Примечание

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

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

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

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

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

TEST_COMMAND <cmd>...

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

TEST_BEFORE_INSTALL <bool>

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

TEST_AFTER_INSTALL <bool>

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

TEST_EXCLUDE_FROM_MAIN <bool>

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

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

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

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

LOG_DOWNLOAD <bool>

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

LOG_UPDATE <bool>

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

LOG_PATCH <bool>

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

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

LOG_CONFIGURE <bool>

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

LOG_BUILD <bool>

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

LOG_INSTALL <bool>

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

LOG_TEST <bool>

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

LOG_MERGED_STDOUTERR <bool>

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

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

LOG_OUTPUT_ON_FAILURE <bool>

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

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

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

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

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

USES_TERMINAL_DOWNLOAD <bool>

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

USES_TERMINAL_UPDATE <bool>

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

USES_TERMINAL_PATCH <bool>

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

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

USES_TERMINAL_CONFIGURE <bool>

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

USES_TERMINAL_BUILD <bool>

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

USES_TERMINAL_INSTALL <bool>

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

USES_TERMINAL_TEST <bool>

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

Опции целевого объекта:

DEPENDS <targets>...

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

EXCLUDE_FROM_ALL <bool>

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

STEP_TARGETS <step-target>...

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

INDEPENDENT_STEP_TARGETS <step-target>...

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

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

Дополнительные опции:

LIST_SEPARATOR <sep>

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

COMMAND <cmd>...

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

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

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

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

ExternalProject_Get_Property

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

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

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

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

Явное управление шагами

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

ExternalProject_Add_Step

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

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

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

COMMAND <cmd>...

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

COMMENT "<text>..."

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

DEPENDEES <step>...

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

DEPENDERS <step>...

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

DEPENDS <file>...

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

INDEPENDENT <bool>

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

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

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

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

BYPRODUCTS <file>...

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

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

ALWAYS <bool>

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

EXCLUDE_FROM_MAIN <bool>

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

WORKING_DIRECTORY <dir>

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

LOG <bool>

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

USES_TERMINAL <bool>

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

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

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

Введено в версии 3.11: Маркер замены <DOWNLOAD_DIR>.

ExternalProject_Add_StepTargets

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

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

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

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

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

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

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

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

ExternalProject_Add_StepDependencies

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

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

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

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

Примеры

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

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

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

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

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

ExternalProject_Add_StepDependencies(secretsauce build foobar)

Другой вариант — создать пользовательскую целевую задачу для шага сборки foobar и сделать secretsauce зависимой от неё, а не от всего проекта foobar. Это означало бы, что необходимо собрать только foobar, а не нужно выполнять его шаги установки или тестирования до сборки secretsauce. Зависимость также может быть определена вместе с проектом secretsauce:

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

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

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

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

set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)

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

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

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

cmake --build . --target secretsauce-docs