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

Примечание

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

BINARY_DIR <dir>

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

INSTALL_DIR <dir>

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

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

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

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

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

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

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

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

DOWNLOAD_COMMAND <cmd>...

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

URL

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

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

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

URL_HASH <algo>=<hashValue>

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

URL_MD5 <md5>

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

DOWNLOAD_NAME <fname>

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

DOWNLOAD_EXTRACT_TIMESTAMP <bool>

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

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

DOWNLOAD_NO_EXTRACT <bool>

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

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

DOWNLOAD_NO_PROGRESS <bool>

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

TIMEOUT <seconds>

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

INACTIVITY_TIMEOUT <seconds>

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

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

HTTP_USERNAME <username>

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

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

HTTP_PASSWORD <password>

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

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

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

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

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

TLS_VERIFY <bool>

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

Изменено в версии 3.6: Эта опция также применяется к вызовам git clone, хотя поведение по умолчанию отличается. Если TLS_VERIFY не указан и CMAKE_TLS_VERIFY не установлен, поведение будет определяться настройками git по умолчанию. Как правило, настройка git sslVerify по умолчанию равна 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, отличается от отслеживаемой ветки вверх по потоку, перебазирование не безопасно. В этой ситуации REBASE будет молчаливо обработано как CHECKOUT.

REBASE_CHECKOUT

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

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

Subversion

SVN_REPOSITORY <url>

URL хранилища Subversion.

SVN_REVISION -r<rev>

Ревизия для взятия из хранилища Subversion.

SVN_USERNAME <username>

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

SVN_PASSWORD <password>

Пароль для взятия и обновления Subversion.

SVN_TRUST_CERT <bool>

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

Mercurial

HG_REPOSITORY <url>

URL хранилища Mercurial.

HG_TAG <tag>

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

CVS

CVS_REPOSITORY <cvsroot>

CVSROOT хранилища CVS.

CVS_MODULE <mod>

Модуль для взятия из хранилища CVS.

CVS_TAG <tag>

Тег для взятия из хранилища CVS.

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

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

UPDATE_COMMAND <cmd>...

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

UPDATE_DISCONNECTED <bool>

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

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

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

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

CONFIGURE_HANDLED_BY_BUILD <bool>

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

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

COMMAND <cmd>...

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

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

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

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

ExternalProject_Get_Property

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

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

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

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

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

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

ExternalProject_Add_Step

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

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

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

COMMAND <cmd>...

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

COMMENT "<text>..."

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

DEPENDEES <step>...

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

DEPENDERS <step>...

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

DEPENDS <file>...

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

INDEPENDENT <bool>

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

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

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

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

BYPRODUCTS <file>...

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

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