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

Примечание

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

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

Если GIT_SHALLOW включено, то GIT_TAG работает только с именами веток и тегами. Хэш коммита недопустим.

GIT_REMOTE_NAME <name>

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

GIT_SUBMODULES <module>...

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

GIT_SUBMODULES_RECURSE <bool>

Укажите, должны ли подмодули Git (если есть) обновляться рекурсивно, передав флаг --recursive команде git submodule update . Если не указано, значение по умолчанию — включено.

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

Если генератор CMake — Green Hills MULTI, а не переопределен, настройки GHS toolset и настройки проекта для кастомных переменных кэша распространяются на внешний проект.

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

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

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

INSTALL_COMMAND <cmd>...

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

Параметры шага Test:

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

TEST_COMMAND <cmd>...

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

TEST_BEFORE_INSTALL <bool>

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

TEST_AFTER_INSTALL <bool>

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

TEST_EXCLUDE_FROM_MAIN <bool>

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

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

Каждая из следующих 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