ExternalProject

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

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

ExternalProject_Add

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

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

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

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

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

PREFIX <dir>

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

TMP_DIR <dir>

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

STAMP_DIR <dir>

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

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>

В противном случае, если установлено свойство каталога 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>

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

URL_HASH <algo>=<hashValue>

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

URL_MD5 <md5>

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

DOWNLOAD_NAME <fname>

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

DOWNLOAD_NO_EXTRACT <bool>

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

DOWNLOAD_NO_PROGRESS <bool>

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

TIMEOUT <seconds>

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

HTTP_USERNAME <username>

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

HTTP_PASSWORD <password>

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

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

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

TLS_VERIFY <bool>

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

TLS_CAINFO <file>

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

NETRC <level>

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

IGNORED

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

OPTIONAL

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

REQUIRED

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

NETRC_FILE <file>

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

Git

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

GIT_REPOSITORY <url>

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

GIT_TAG <tag>

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

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

GIT_REMOTE_NAME <name>

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

GIT_SUBMODULES <module>...

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

GIT_SHALLOW <bool>

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

GIT_PROGRESS <bool>

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

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

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

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>

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

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

PATCH_COMMAND <cmd>...

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

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

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

CONFIGURE_COMMAND <cmd>...

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

CMAKE_COMMAND /.../cmake

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

CMAKE_GENERATOR <gen>

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

CMAKE_GENERATOR_PLATFORM <platform>

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

CMAKE_GENERATOR_TOOLSET <toolset>

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

CMAKE_GENERATOR_INSTANCE <instance>

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

CMAKE_ARGS <arg>...

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

CMAKE_CACHE_ARGS <arg>...

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

CMAKE_CACHE_DEFAULT_ARGS <arg>...

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

SOURCE_SUBDIR <dir>

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

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

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

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

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

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

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

INSTALL_COMMAND <cmd>...

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

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

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

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

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

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

LOG_DOWNLOAD <bool>

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

LOG_UPDATE <bool>

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

LOG_CONFIGURE <bool>

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

LOG_BUILD <bool>

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

LOG_INSTALL <bool>

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

LOG_TEST <bool>

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

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

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

USES_TERMINAL_DOWNLOAD <bool>

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

USES_TERMINAL_UPDATE <bool>

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

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_Step() ниже для более подробного обсуждения влияния этого параметра.

INDEPENDENT_STEP_TARGETS <step-target>...

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

Прочие параметры:

LIST_SEPARATOR <sep>

Для любого из различных ..._COMMAND параметров замените ; на <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, skip-update, patch, configure, build, install или test). Поддерживаемые параметры:

COMMAND <cmd>...

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

COMMENT "<text>..."

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

DEPENDEES <step>...

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

DEPENDERS <step>...

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

DEPENDS <file>...

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

BYPRODUCTS <file>...

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

ALWAYS <bool>

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

EXCLUDE_FROM_MAIN <bool>

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

WORKING_DIRECTORY <dir>

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

LOG <bool>

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

USES_TERMINAL <bool>

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

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

ExternalProject_Add_StepTargets

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

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

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

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

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

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

ExternalProject_Add_StepDependencies

Функция 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