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>

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

INACTIVITY_TIMEOUT <seconds>

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

HTTP_USERNAME <username>

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

HTTP_PASSWORD <password>

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

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

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

TLS_VERIFY <bool>

Указывает, должна ли выполняться проверка сертификатов для URL https. Если этот параметр не указан, поведение по умолчанию определяется переменной 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.

GIT_REMOTE_UPDATE_STRATEGY <strategy>

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

CHECKOUT

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

REBASE

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

REBASE_CHECKOUT

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

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

Subversion

SVN_REPOSITORY <url>

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

SVN_REVISION -r<rev>

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

SVN_USERNAME <username>

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

SVN_PASSWORD <password>

Пароль для проверки и обновления Subversion.

SVN_TRUST_CERT <bool>

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

Mercurial

HG_REPOSITORY <url>

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

HG_TAG <tag>

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

CVS

CVS_REPOSITORY <cvsroot>

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

CVS_MODULE <mod>

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

CVS_TAG <tag>

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

Параметры шага обновления/патчинга:

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

UPDATE_COMMAND <cmd>...

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

UPDATE_DISCONNECTED <bool>

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

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

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

PATCH_COMMAND <cmd>...

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

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

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

CONFIGURE_COMMAND <cmd>...

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

SOURCE_SUBDIR <dir>

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

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

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

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

TEST_EXCLUDE_FROM_MAIN <bool>

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

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

Каждый из следующих 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_StepTargets() ниже для получения дополнительной информации об эффектах этого параметра.

INDEPENDENT_STEP_TARGETS <step-target>...

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

Разные параметры:

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, update, patch, configure, build, install или test).

Доступные опции:

COMMAND <cmd>...

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

COMMENT "<text>..."

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

DEPENDEES <step>...

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

DEPENDERS <step>...

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

DEPENDS <file>...

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

INDEPENDENT <bool>

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

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

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

BYPRODUCTS <file>...

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

ALWAYS <bool>

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

EXCLUDE_FROM_MAIN <bool>

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

WORKING_DIRECTORY <dir>

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

LOG <bool>

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

USES_TERMINAL <bool>

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

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

ExternalProject_Add_StepTargets

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

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

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

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

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

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

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

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

ExternalProject_Add_StepDependencies

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