ExternalProject

• Команды

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

Команды

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

ExternalProject_Add

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

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

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

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

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

PREFIX <dir>

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

TMP_DIR <dir>

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

STAMP_DIR <dir>

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

LOG_DIR <dir>

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

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

DOWNLOAD_DIR <dir>

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

SOURCE_DIR <dir>

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

Примечание

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

BINARY_DIR <dir>

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

INSTALL_DIR <dir>

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

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

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

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

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

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

Опции этапа загрузки:

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

DOWNLOAD_COMMAND <cmd>...

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

Загрузка по URL

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

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

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

URL_HASH <algo>=<hashValue>

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

URL_MD5 <md5>

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

DOWNLOAD_NAME <fname>

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

DOWNLOAD_EXTRACT_TIMESTAMP <bool>

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

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

DOWNLOAD_NO_EXTRACT <bool>

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

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

DOWNLOAD_NO_PROGRESS <bool>

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

TIMEOUT <seconds>

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

INACTIVITY_TIMEOUT <seconds>

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

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

HTTP_USERNAME <username>

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

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

HTTP_PASSWORD <password>

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

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

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

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

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

TLS_VERIFY <bool>

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

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

TLS_CAINFO <file>

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

NETRC <level>

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

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

IGNORED

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

OPTIONAL

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

REQUIRED

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

NETRC_FILE <file>

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

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

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

Git

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

GIT_REPOSITORY <url>

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

GIT_TAG <tag>

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

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

GIT_SHALLOW <bool>

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

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

GIT_PROGRESS <bool>

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

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

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

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

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

GIT_REMOTE_UPDATE_STRATEGY <strategy>

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

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

CHECKOUT

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

REBASE

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

REBASE_CHECKOUT

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

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

Subversion

SVN_REPOSITORY <url>

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

SVN_REVISION -r<rev>

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

SVN_USERNAME <username>

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

SVN_PASSWORD <password>

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

SVN_TRUST_CERT <bool>

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

Mercurial

HG_REPOSITORY <url>

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

HG_TAG <tag>

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

CVS

CVS_REPOSITORY <cvsroot>

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

CVS_MODULE <mod>

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

CVS_TAG <tag>

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

Параметры этапа обновления:

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

UPDATE_COMMAND <cmd>...

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

UPDATE_DISCONNECTED <bool>

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

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

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

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

Параметры этапа применения исправлений:

PATCH_COMMAND <cmd>...

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

Параметры этапа конфигурации:

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

CONFIGURE_COMMAND <cmd>...

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

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

CMAKE_COMMAND /.../cmake

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

CMAKE_GENERATOR <gen>

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

CMAKE_GENERATOR_PLATFORM <platform>

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

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

CMAKE_GENERATOR_TOOLSET <toolset>

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

CMAKE_GENERATOR_INSTANCE <instance>

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

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

CMAKE_ARGS <arg>...

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

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

CMAKE_CACHE_ARGS <arg>...

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

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

CMAKE_CACHE_DEFAULT_ARGS <arg>...

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

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

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

SOURCE_SUBDIR <dir>

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

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

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

CONFIGURE_HANDLED_BY_BUILD <bool>

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

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

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

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

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

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

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

INSTALL_COMMAND <cmd>...

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

Примечание

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

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

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

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

Шаг тестирования определен только если указан хотя бы один из следующих TEST_... параметров.

TEST_COMMAND <cmd>...

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

TEST_BEFORE_INSTALL <bool>

При включении этого параметра, шаг тестирования будет выполнен до шага установки. По умолчанию шаг тестирования выполняется после шага установки.

TEST_AFTER_INSTALL <bool>

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

TEST_EXCLUDE_FROM_MAIN <bool>

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

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

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

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

LOG_DOWNLOAD <bool>

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

LOG_UPDATE <bool>

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

LOG_PATCH <bool>

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

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

LOG_CONFIGURE <bool>

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

LOG_BUILD <bool>

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

LOG_INSTALL <bool>

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

LOG_TEST <bool>

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

LOG_MERGED_STDOUTERR <bool>

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

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

LOG_OUTPUT_ON_FAILURE <bool>

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

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

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

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

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

USES_TERMINAL_DOWNLOAD <bool>

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

USES_TERMINAL_UPDATE <bool>

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

USES_TERMINAL_PATCH <bool>

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

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

USES_TERMINAL_CONFIGURE <bool>

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

USES_TERMINAL_BUILD <bool>

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

USES_TERMINAL_INSTALL <bool>

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

USES_TERMINAL_TEST <bool>

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

Параметры целевого объекта:

DEPENDS <targets>...

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

EXCLUDE_FROM_ALL <bool>

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

STEP_TARGETS <step-target>...

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

INDEPENDENT_STEP_TARGETS <step-target>...

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

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

Различные параметры:

LIST_SEPARATOR <sep>

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

COMMAND <cmd>...

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

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

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

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

ExternalProject_Get_Property

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

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

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

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

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

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

ExternalProject_Add_Step

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

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

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

COMMAND <cmd>...

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

COMMENT "<text>..."

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

DEPENDEES <step>...

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

DEPENDERS <step>...

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

DEPENDS <file>...

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

INDEPENDENT <bool>

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

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

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

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

BYPRODUCTS <file>...

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

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

ALWAYS <bool>

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

EXCLUDE_FROM_MAIN <bool>

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

WORKING_DIRECTORY <dir>

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

LOG <bool>

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

USES_TERMINAL <bool>

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

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

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

Новое в версии 3.11: Токен подстановки <DOWNLOAD_DIR>.

ExternalProject_Add_StepTargets

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

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

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

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

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

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

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

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

ExternalProject_Add_StepDependencies

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

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

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

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

Примеры

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

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

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

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

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

ExternalProject_Add_StepDependencies(secretsauce build foobar)

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

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

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

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

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

set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)

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

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

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

cmake --build . --target secretsauce-docs