Глава 14. Встраивание Gradle с использованием инструментального API.

14.1. Введение в инструментальное API.

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

  • Gradle TestKit использует инструментальное API для функционального тестирования ваших плагинов к Gradle.
  • Eclipse Buildship использует инструментальное API для импорта вашего проекта Gradle и для запуска задач.
  • IntelliJ IDEA использует инструментальное API для импорта вашего проекта Gradle и запуска задач.

14.2. Возможности инструментального API.

Фундаментальная характеристика инструментального API состоит в том, что оно работает независимо от версии. Это означает, что вы можете использовать одно и то же API для работы со сборками, использующими различные версии Gradle, включая версии, которые новее или старее версии инструментального API, которое вы используете. Инструментальное API знает о Gradle Wrapper'е и, по умолчанию, использует ту же версию Gradle, которая используется сборкой работающая с Wrapper'ом.

Некоторые из функций, предоставляемые инструментальным API:

  • Запрос деталей сборки, включая иерархию проекта и его зависимости, внешние зависимости (включая исходные коды и Javadoc jar-файлы), папки с исходным кодом и задачи каждого из проектов.
  • Выполнение сборки и прослушивание стандартного вывода и стандартного вывода ошибок на наличие информационных и сообщений о прогрессе (например, сообщения, отображаемые в 'строке состояния', когда вы запускаете из командной строки).
  • Выполнение специфичного тестового класса или тестового метода.
  • Получение интересных событый во время выполнения сборки, таких как конфигурация проекта, выполнение задачи или выполнение теста.
  • Отмена выполняющейся сборки.
  • Объединение множества отдельных сборок Gradle в одну составную.
  • Также как и wrapper, инструментальное API может скачать и установить подходящую версию Gradle.
  • "Легкая" реализация, с небольших количеством зависимостей. Также это "послушная" библиотека, которая не делают предположений о вашей структуре загрузчика классов или конфиграции логгирования. Все это позволяет легко встраивать API в ваше приложение.

14.3. Инструментальное API и демон сборки Gradle.

Инструментальное API всегда использует демона Gradle. Это означает, что последующие обращения к Инструментальному API, будут ли это запросы сборки модели или запросы на выполнение задачи, будут выполняться в одном и том же долгоживущем процессе. Глава 6 Демон Gradle содержит больше информации о демоне, в особенности о ситуациях, при которых запускаются новые процессы демона.

14.4. Быстрый старт.

Так как Инструментальное API интерфейс для программистов, то Javadoc - основная документация для него. Мы предоставляем несколько примеров, которые размещаются в samples/toolingApi в вашем дистрибутиве Gradle. Эти примеры определяют все необходимые зависимости для Инструментального API с примерами запроса информации из сборок Gradle и выполнения задач из Инструментального API.

Для использования Инструментального API, добавьте следующее хранилище и объявления зависимостей в вашем сборочном скрипте:

Пример 14.1. Использование Инструментального API

build.gradle

repositories {
    maven { url 'https://repo.gradle.org/gradle/libs-releases' }
}

dependencies {
    compile "org.gradle:gradle-tooling-api:${toolingApiVersion}"
    // The tooling API need an SLF4J implementation available at runtime, replace this with any other implementation
    runtime 'org.slf4j:slf4j-simple:1.7.10'
}
	  

Основная точка входа в инструментальное API - GradleConnector. Оттуда мы можете двинуться на поиск примером и исследовать доступные модели Инструментального API. Вы можете использовать GradleConnector.connect() для создания ProjectConnection. ProjectConnection подкючается к одиночному проекту Gradle. Используя подкючение, вы можете выполнять задачу, тесты и извлекать модели связанные с этим проектом.

14.5. Совместимость версий Gradle и Java.

Текущая версия Инструментального API поддерживает запуск сборок, использующих Gradle версии 1.2 и выше.

Вы должны обратить внимание на то, что не все функции Инструментального API доступны для всех версий Gradle. Например, отмена сборки доступна только тогда, когда для нее используется Gradle 2.1 и выше. Больше информации ищите в документации к классам и методам.

Текущая версия Gradle может быть использована из Инструментального API версии 2.0 и выше.

Для Инструментального API требуется Java 7 и выше. Версия Gradle, используемая сборками, может иметь дополнительные требования к версии Java.