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.

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

DOWNLOAD_NO_PROGRESS <bool>

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

TIMEOUT <seconds>

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

INACTIVITY_TIMEOUT <seconds>

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

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

HTTP_USERNAME <username>

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

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

HTTP_PASSWORD <password>

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

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

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

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

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

TLS_VERIFY <bool>

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

Изменено в версии 3.6: Эта опция также применяется к вызовам git clone, хотя поведение по умолчанию отличается. Если TLS_VERIFY не указано и CMAKE_TLS_VERIFY не установлено, поведение будет определяться по умолчанию git. Обычно значение sslVerify git конфигурации равно true, но пользователь может изменить его на глобальном уровне.

TLS_CAINFO <file>

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

NETRC <level>

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

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

IGNORED

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

OPTIONAL

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

REQUIRED

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

NETRC_FILE <file>

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

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

Git

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

GIT_REPOSITORY <url>

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

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

GIT_TAG <tag>

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

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

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

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

GIT_REMOTE_NAME <name>

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

GIT_SUBMODULES <module>...

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

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

GIT_SUBMODULES_RECURSE <bool>

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

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

GIT_SHALLOW <bool>

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

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

GIT_PROGRESS <bool>

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

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

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

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

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

GIT_REMOTE_UPDATE_STRATEGY <strategy>

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

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

CHECKOUT

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

REBASE

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

REBASE_CHECKOUT

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

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

Subversion

SVN_REPOSITORY <url>

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

SVN_REVISION -r<rev>

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

SVN_USERNAME <username>

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

SVN_PASSWORD <password>

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

SVN_TRUST_CERT <bool>

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

Mercurial

HG_REPOSITORY <url>

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

HG_TAG <tag>

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

CVS

CVS_REPOSITORY <cvsroot>

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

CVS_MODULE <mod>

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

CVS_TAG <tag>

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

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

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

UPDATE_COMMAND <cmd>...

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

UPDATE_DISCONNECTED <bool>

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

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

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

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

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

Параметры шага применения исправлений

PATCH_COMMAND <cmd>...

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

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

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

CONFIGURE_COMMAND <cmd>...

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

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

CMAKE_COMMAND /.../cmake

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

CMAKE_GENERATOR <gen>

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

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

CONFIGURE_HANDLED_BY_BUILD <bool>

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

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

Параметры Шага Сборки

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

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

Параметры Шага Установки

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