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>

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

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

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

• Если локальный клон уже имеет коммит, соответствующий хэшу, проверка изменений при каждом повторном запуске 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. Когда указан BUILD_IN_SOURCE 1, BUILD_COMMAND используется для указания альтернативного каталога в дереве исходных файлов.

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

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

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

TEST_EXCLUDE_FROM_MAIN <bool>

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

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

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

LOG_DOWNLOAD <bool>

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

LOG_UPDATE <bool>

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

LOG_PATCH <bool>

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

LOG_CONFIGURE <bool>

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

LOG_BUILD <bool>

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

LOG_INSTALL <bool>

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

LOG_TEST <bool>

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

LOG_MERGED_STDOUTERR <bool>

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

LOG_OUTPUT_ON_FAILURE <bool>

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

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

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

При установке этот параметр заставляет вывод от пользовательского шага быть записанным в файлы во внешнем проекте LOG_DIR, если указано, или 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