Spec-Zone.ru › CMake

Внешний проект

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

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

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

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

Этот модуль предоставляет команды для загрузки и сборки внешних проектов в рамках процесса сборки CMake.

Загрузите этот модуль в проект CMake с помощью:

include(ExternalProject)

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

ExternalProject_Add

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

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

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

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

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

PREFIX <dir>

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

TMP_DIR <dir>

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

STAMP_DIR <dir>

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

LOG_DIR <dir>

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

Каталог для файлов журналов каждого этапа.

DOWNLOAD_DIR <dir>

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

SOURCE_DIR <dir>

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

Примечание

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

BINARY_DIR <dir>

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

INSTALL_DIR <dir>

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

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

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

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

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

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

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

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

DOWNLOAD_COMMAND <cmd>...

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

URL

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

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

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

URL_HASH <algo>=<hashValue>

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

URL_MD5 <md5>

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

DOWNLOAD_NAME <fname>

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

DOWNLOAD_EXTRACT_TIMESTAMP <bool>

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

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

DOWNLOAD_NO_EXTRACT <bool>

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

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

DOWNLOAD_NO_PROGRESS <bool>

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

TIMEOUT <seconds>

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

INACTIVITY_TIMEOUT <seconds>

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

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

HTTP_USERNAME <username>

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

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

HTTP_PASSWORD <password>

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

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

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

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

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

TLS_VERSION <min>

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

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

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

TLS_VERIFY <bool>

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

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

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

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

TLS_CAINFO <file>

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

NETRC <level>

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

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

IGNORED

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

OPTIONAL

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

REQUIRED

Файл .netrc обязателен, сведения в URL-адресе игнорируются.

NETRC_FILE <file>

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

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

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

Добавлено в версии 4.1: Поддерживаются все типы архивов, которые может распаковать cmake -E tar, независимо от расширения файла.

Git

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

GIT_REPOSITORY <url>

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

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

GIT_TAG <tag>

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

  • Если локальный клон уже содержит коммит, соответствующий хешу, при каждом повторном запуске CMake не требуется выполнять git fetch для проверки изменений. Это может значительно ускорить сборку при использовании множества внешних проектов.
  • Использование конкретного хеша 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. Если параметр не указан, по умолчанию используется значение on.

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

Для управления поведением повторных попыток операций git clone можно задать следующие переменные:

CMAKE_EP_GIT_CLONE_RETRY_COUNT

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

Указывает количество повторных попыток операции git clone в случае сбоя. По умолчанию выполняется 2 повторных попыток. Первая попытка не считается повторной, поэтому общее количество попыток равно заданному числу повторов плюс один. Проекту не следует задавать эту переменную — она предназначена для пользователя. Она особенно полезна при периодических проблемах с сетью или ограничении частоты запросов хостинг-сервисами Git.

CMAKE_EP_GIT_CLONE_RETRY_DELAY

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

Указывает задержку в секундах между повторными попытками клонирования Git. По умолчанию задержка составляет 0 секунд (между попытками задержки нет). Проекту не следует задавать эту переменную — она предназначена для пользователя. Задержка может быть полезна при ограничении частоты запросов хостинг-сервисами Git, которые могут отклонять и немедленные повторные попытки.

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>...

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

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

CMAKE_COMMAND /.../cmake

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

CMAKE_GENERATOR <gen>

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

CMAKE_GENERATOR_PLATFORM <platform>

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

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

CMAKE_GENERATOR_TOOLSET <toolset>

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

CMAKE_GENERATOR_INSTANCE <instance>

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

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

CMAKE_ARGS <arg>...

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

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

CMAKE_CACHE_ARGS <arg>...

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

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

CMAKE_CACHE_DEFAULT_ARGS <arg>...

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

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

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

SOURCE_SUBDIR <dir>

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

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

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

CONFIGURE_HANDLED_BY_BUILD <bool>

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

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

CONFIGURE_ENVIRONMENT_MODIFICATION <modification>...

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

Задаёт переменные среды, которые следует изменить для шага конфигурирования.

Задайте разделённый точками с запятой список переменных среды и значений в формате MYVAR=OP:VALUE, где MYVAR — имя переменной среды с учётом регистра, которую нужно изменить. Записи обрабатываются в порядке, заданном в значении свойства. OP может принимать одно из следующих значений:

  • reset: Сбросить до неизменённого значения, игнорируя все изменения MYVAR, внесённые до этой записи. Обратите внимание, что переменная будет сброшена до значения, заданного свойством ENVIRONMENT, если оно задано, или до состояния, установленного остальной частью выполнения CTest.
  • set: Заменить текущее значение MYVAR на VALUE.
  • unset: Удалить текущее значение MYVAR.
  • string_append: Добавить единичное значение VALUE в конец текущего значения MYVAR.
  • string_prepend: Добавить единичное значение VALUE в начало текущего значения MYVAR.
  • path_list_append: Добавить единичное значение VALUE в конец текущего значения MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • path_list_prepend: Добавить единичное значение VALUE в начало текущего значения MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • cmake_list_append: Добавить единичное значение VALUE в конец текущего значения MYVAR, используя ; в качестве разделителя.
  • cmake_list_prepend: Добавить единичное значение VALUE в начало текущего значения MYVAR, используя ; в качестве разделителя.
ExternalProject_Add(example
  ... # Download options, etc...
  CONFIGURE_ENVIRONMENT_MODIFICATION
    SDKROOT=set:macosx
    PKG_CONFIG_PATH=set:$ENV{PKG_CONFIG_PATH}
)

Этот фрагмент задаёт две переменные среды при конфигурировании примера проекта. Переменной среды SDKROOT присваивается значение macosx, а значение PKG_CONFIG_PATH передаётся внешнему проекту.

Изменения среды взаимодействуют с LIST_SEPARATOR, чтобы заменить разделитель на ; в переменной среды.

ExternalProject_Add(example
  ... # Download options, etc...
  LIST_SEPARATOR ,
  CONFIGURE_ENVIRONMENT_MODIFICATION
    LIST_VAR=set:a,b,c
)

Этот фрагмент и переменная среды LIST_VAR передаются вызову команды конфигурирования со значением a;b;c.

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

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

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

BUILD_COMMAND <cmd>...

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

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.

BUILD_ENVIRONMENT_MODIFICATION <modification>...

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

Задаёт переменные среды, которые следует изменить для шага сборки.

Задайте разделённый точками с запятой список переменных среды и значений в формате MYVAR=OP:VALUE, где MYVAR — имя переменной среды с учётом регистра, которую нужно изменить. Записи обрабатываются в порядке, заданном в значении свойства. OP может принимать одно из следующих значений:

  • reset: Сбросить до неизменённого значения, игнорируя все изменения MYVAR, внесённые до этой записи. Обратите внимание, что переменная будет сброшена до значения, заданного свойством ENVIRONMENT, если оно задано, или до состояния, установленного остальной частью выполнения CTest.
  • set: Заменить текущее значение MYVAR на VALUE.
  • unset: Удалить текущее значение MYVAR.
  • string_append: Добавить единичное значение VALUE в конец текущего значения MYVAR.
  • string_prepend: Добавить единичное значение VALUE в начало текущего значения MYVAR.
  • path_list_append: Добавить единичное значение VALUE в конец текущего значения MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • path_list_prepend: Добавить единичное значение VALUE в начало текущего значения MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • cmake_list_append: Добавить единичное значение VALUE в конец текущего значения MYVAR, используя ; в качестве разделителя.
  • cmake_list_prepend: Добавить единичное значение VALUE в начало текущего значения MYVAR, используя ; в качестве разделителя.

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

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

INSTALL_JOB_SERVER_AWARE <bool>

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

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

Примечание

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

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

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

INSTALL_ENVIRONMENT_MODIFICATION <modification>...

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

Задаёт переменные среды, которые следует изменить для шага установки.

Задайте разделённый точками с запятой список переменных среды и значений в формате MYVAR=OP:VALUE, где MYVAR — имя переменной среды с учётом регистра, которую нужно изменить. Записи обрабатываются в порядке, заданном в значении свойства. OP может принимать одно из следующих значений:

  • reset: Сбросить до неизменённого значения, игнорируя все изменения MYVAR, внесённые до этой записи. Обратите внимание, что переменная будет сброшена до значения, заданного свойством ENVIRONMENT, если оно задано, или до состояния, установленного остальной частью выполнения CTest.
  • set: Заменить текущее значение MYVAR на VALUE.
  • unset: Удалить текущее значение MYVAR.
  • string_append: Добавить единичное значение VALUE в конец текущего значения MYVAR.
  • string_prepend: Добавить единичное значение VALUE в начало текущего значения MYVAR.
  • path_list_append: Добавить единичное значение VALUE в конец текущего значения MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • path_list_prepend: Добавить единичное значение VALUE в начало текущего значения MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • cmake_list_append: Добавить единичное значение VALUE в конец текущего значения MYVAR, используя ; в качестве разделителя.
  • cmake_list_prepend: Добавить единичное значение VALUE в начало текущего значения MYVAR, используя ; в качестве разделителя.

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

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

TEST_ENVIRONMENT_MODIFICATION <modification>...

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

Указывает переменные среды, которые следует изменить для этапа тестирования.

Задайте список, разделённый точками с запятой, состоящий из переменных среды и значений в форме MYVAR=OP:VALUE, где MYVAR — имя переменной среды, которое следует изменить; регистр символов учитывается. Записи обрабатываются в порядке, указанном в значении свойства. OP может принимать одно из следующих значений:

  • reset: сбрасывает переменную к исходному значению, игнорируя все изменения MYVAR, сделанные до этой записи. Обратите внимание: переменная будет сброшена к значению, заданному свойством ENVIRONMENT, если оно задано, а в противном случае — к значению, действовавшему в остальной части выполнения CTest.
  • set: заменяет текущее значение MYVAR на VALUE.
  • unset: удаляет текущее значение MYVAR.
  • string_append: добавляет единичное значение VALUE к текущему значению MYVAR.
  • string_prepend: добавляет единичное значение VALUE перед текущим значением MYVAR.
  • path_list_append: добавляет единичное значение VALUE к текущему значению MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • path_list_prepend: добавляет единичное значение VALUE перед текущим значением MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • cmake_list_append: добавляет единичное значение VALUE к текущему значению MYVAR, используя ; в качестве разделителя.
  • cmake_list_prepend: добавляет единичное значение VALUE перед текущим значением MYVAR, используя ; в качестве разделителя.

Параметры ведения журнала вывода

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

LOG_DOWNLOAD <bool>

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

LOG_UPDATE <bool>

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

LOG_PATCH <bool>

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

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

LOG_CONFIGURE <bool>

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

LOG_BUILD <bool>

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

LOG_INSTALL <bool>

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

LOG_TEST <bool>

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

LOG_MERGED_STDOUTERR <bool>

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

Если параметр включён, stdout и stderr объединяются для всех этапов, вывод которых записывается в файлы.

LOG_OUTPUT_ON_FAILURE <bool>

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

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

Параметры доступа к терминалу

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

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

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

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

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

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

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

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

ExternalProject_Get_Property

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

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

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

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

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

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

ExternalProject_Add_Step

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

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

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

COMMAND <cmd>...

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

COMMENT "<text>..."

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

DEPENDEES <step>...

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

DEPENDERS <step>...

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

DEPENDS <file>...

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

ENVIRONMENT_MODIFICATION <modification>...

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

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

Задайте список, разделённый точками с запятой, состоящий из переменных среды и значений в форме MYVAR=OP:VALUE, где MYVAR — имя переменной среды, которое следует изменить; регистр символов учитывается. Записи обрабатываются в порядке, указанном в значении свойства. OP может принимать одно из следующих значений:

  • reset: сбрасывает переменную к исходному значению, игнорируя все изменения MYVAR, сделанные до этой записи. Обратите внимание: переменная будет сброшена к значению, заданному свойством ENVIRONMENT, если оно задано, а в противном случае — к значению, действовавшему в остальной части выполнения CTest.
  • set: заменяет текущее значение MYVAR на VALUE.
  • unset: удаляет текущее значение MYVAR.
  • string_append: добавляет единичное значение VALUE к текущему значению MYVAR.
  • string_prepend: добавляет единичное значение VALUE перед текущим значением MYVAR.
  • path_list_append: добавляет единичное значение VALUE к текущему значению MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • path_list_prepend: добавляет единичное значение VALUE перед текущим значением MYVAR, используя разделитель списков путей платформы хоста (; в Windows и : в других системах).
  • cmake_list_append: добавляет единичное значение VALUE к текущему значению MYVAR, используя ; в качестве разделителя.
  • cmake_list_prepend: добавляет единичное значение VALUE перед текущим значением MYVAR, используя ; в качестве разделителя.
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. Подробные сведения см. в описании параметра JOB_SERVER_AWARE команды add_custom_command().

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_Step() будет также вызвана функция ExternalProject_Add_StepTargets(). Даже если этап не указан в параметре 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, доступно следующее устаревшее поведение:

  • Сразу после <name> и перед первым этапом можно указать устаревший параметр NO_DEPENDS. Если задан параметр 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>...])

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

Примеры

В следующем примере показано, как загрузить и собрать гипотетический проект 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

© 2000–2026 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/latest/module/ExternalProject.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API