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