ExternalProject

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

  • Параметры каталогов

  • Параметры шага загрузки

    • URL
    • Git
    • Subversion
    • Mercurial
    • CVS
  • Параметры шага обновления
  • Параметры шага применения патчей
  • Параметры шага конфигурации
  • Параметры шага сборки
  • Параметры шага установки
  • Параметры шага тестирования
  • Параметры ведения журнала вывода
  • Параметры доступа к терминалу
  • Параметры целевых систем
  • Разные параметры
• Получение свойств проекта
• Явное управление шагами
• Примеры

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

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_VERSION <min>

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

Укажите минимальную версию TLS для https:// URL. Если эта опция не указана, будет использовано значение переменной CMAKE_TLS_VERSION или переменной окружения CMAKE_TLS_VERSION (см. file(DOWNLOAD)).

Эта опция также применяется к вызовам git clone, хотя поведение по умолчанию отличается. Если ни одна из опций TLS_VERSION, переменная CMAKE_TLS_VERSION, или переменная окружения CMAKE_TLS_VERSION не указана, поведение будет определяться значением по умолчанию git или опцией http.sslVersion git config, которую пользователь может установить на глобальном уровне.

TLS_VERIFY <bool>

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

Эта опция также применяется к вызовам git clone, хотя поведение по умолчанию отличается. Если ни одна из опций TLS_VERIFY, переменная CMAKE_TLS_VERIFY или переменная окружения CMAKE_TLS_VERIFY не указана, поведение будет определяться значением по умолчанию git (true) или опцией http.sslVerify git config, которую пользователь может установить на глобальном уровне.

Изменено в версии 3.6: Ранее эта опция не применялась к вызовам git clone.

Изменено в версии 3.30: Ранее переменная окружения CMAKE_TLS_VERIFY не проверялась.

TLS_CAINFO <file>

Укажите файл пользовательского сертификата CA для использования, если 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))

Git

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

GIT_REPOSITORY <url>

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

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

GIT_TAG <tag>

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

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

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

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

GIT_REMOTE_NAME <name>

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

GIT_SUBMODULES <module>...

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

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

GIT_SUBMODULES_RECURSE <bool>

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

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

GIT_SHALLOW <bool>

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

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

GIT_PROGRESS <bool>

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

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

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

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

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

GIT_REMOTE_UPDATE_STRATEGY <strategy>

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

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

CHECKOUT

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

REBASE

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

REBASE_CHECKOUT

Аналогично REBASE, но если перебазирование завершится ошибкой, будет создан аннотированный тег в исходном положении HEAD до перебазирования, а затем выполнится переключение на GIT_TAG аналогично стратегии CHECKOUT. Сообщение, хранящееся в аннотированном теге, содержит информацию о попытке и имя тега будет содержать отметку времени, чтобы каждый неудачный запуск добавлял новый тег. Эта стратегия гарантирует, что изменения не будут потеряны, но обновления должны всегда выполняться успешно, если GIT_TAG ссылается на действительный ref, если только нет несохранённых изменений, которые не могут быть успешно восстановлены.

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

Subversion

SVN_REPOSITORY <url>

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

SVN_REVISION -r<rev>

Ревизия для проверки из репозитория Subversion.

SVN_USERNAME <username>

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

SVN_PASSWORD <password>

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

SVN_TRUST_CERT <bool>

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

Mercurial

HG_REPOSITORY <url>

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

HG_TAG <tag>

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

CVS

CVS_REPOSITORY <cvsroot>

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

CVS_MODULE <mod>

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

CVS_TAG <tag>

Тег для проверки из репозитория CVS.

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

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

UPDATE_COMMAND <cmd>...

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

UPDATE_DISCONNECTED <bool>

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

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

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

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

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

Параметры шага применения

PATCH_COMMAND <cmd>...

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

Параметры шага настройки

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

CONFIGURE_COMMAND <cmd>...

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

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

CMAKE_COMMAND /.../cmake

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

CMAKE_GENERATOR <gen>

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

CMAKE_GENERATOR_PLATFORM <platform>

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

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

CMAKE_GENERATOR_TOOLSET <toolset>

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

CMAKE_GENERATOR_INSTANCE <instance>

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

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

CMAKE_ARGS <arg>...

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

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

CMAKE_CACHE_ARGS <arg>...

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

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

CMAKE_CACHE_DEFAULT_ARGS <arg>...

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

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

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

SOURCE_SUBDIR <dir>

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

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

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

CONFIGURE_HANDLED_BY_BUILD <bool>

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

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

Параметры шага сборки

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

BUILD_JOB_SERVER_AWARE <bool>

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

Указывает, что шаг сборки знает о сервере заданий GNU Make. Смотрите документацию к add_custom_command() документации параметра JOB_SERVER_AWARE для получения подробной информации. Этот параметр актуален только при явном указании BUILD_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(), который имеет дополнительную документацию.

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

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

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

В некоторых случаях шаги могут получить прямой доступ к терминалу. Предоставление шагу доступа к терминалу может позволить ему получить ввод с терминала, если это требуется, например, для данных аутентификации, которые не предоставляются другими опциями. С генератором 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, ExternalProject заменит <sep> на ; в указанных командных строках. Это можно использовать для того, чтобы убедиться, что команда содержит литерную ; в ней, где прямое использование в противном случае интерпретировалось бы как разделители аргументов API CMake вместо этого. Обратите внимание, что разделитель следует выбирать таким образом, чтобы его не путали с использованием последовательности в качестве разделителя не списков. Например, использование LIST_SEPARATOR позволяет передавать значения списка в переменные кэша CMake в командной строке:

ExternalProject_Add(example
  ... # Download options, etc.
  LIST_SEPARATOR ","
  CMAKE_ARGS "-DCMAKE_PREFIX_PATH:STRING=${first_prefix},${second_prefix}"
)

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>

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

JOB_SERVER_AWARE <bool>

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

Указывает, что пользовательский шаг осведомлён о сервере задач GNU Make. Подробности см. в документации add_custom_command() для её варианта JOB_SERVER_AWARE.

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