TOC

Написание пользовательских плагинов Gradle

Написание пользовательских плагинов Gradle

1. Вступление

Gradle - очень популярный инструмент для сборки, который часто ценится за настраиваемый процесс сборки.

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

2. Расположение источника плагина

Мы можем разместить наш код в нескольких разных местах. Все они имеют свои преимущества и недостатки.

2.1. Сценарий сборки

Мы можем просто поместить исходный код нашего плагина в сам скрипт сборки. Это даст нам автоматическую компиляцию и включение плагина.

It’s very simple, however, our plugin won’t be visible outside of the build script. Из-за этого мы не можем повторно использовать его в других скриптах сборки.

2.2. ПапкаBuildSrc

Другая возможность, которую мы можем использовать, - это поместить исходный код нашего плагина в папкуbuildSrc/src/main/java.

Когда вы запустите Gradle, он проверит наличие папкиbuildSrc. Если он существует, Gradle автоматически создаст и включит наш плагин.

Это даст нам возможность использовать наш плагин в различных скриптах сборки, но мы по-прежнему не сможем использовать его в других проектах.

2.3. Автономный проект

Наконец, мы можем создать наш плагин как отдельный проект, который делает плагин полностью пригодным для повторного использования в различных проектах.

Однако, чтобы использовать его во внешнем проекте, нам нужно объединить его в файл jar и добавить в проект.

3. Наш первый плагин

Начнем с основ -every Gradle Plugin must implement the com.gradle.api.Plugin interface.

Интерфейс универсален, поэтому мы можем параметризовать его с различными типами параметров. Обычно тип параметраorg.gradle.api.Project.

Однако мы можем использовать разные параметры типа, чтобы плагин применялся на разных фазах жизни:

  • использованиеorg.gradle.api.Settings приведет к применению плагина к скрипту настроек

  • использованиеorg.gradle.api.Gradle приведет к применению плагина к сценарию инициализации

Самый простой плагин, который мы можем создать, - это приложениеhello world: 

public class GreetingPlugin implements Plugin {
    @Override
    public void apply(Project project) {
        project.task("hello")
          .doLast(task -> System.out.println("Hello Gradle!"));
    }
}

Теперь мы можем применить его, добавив строку в наш скрипт сборки: 

apply plugin: GreetingPlugin

Теперь, после вызоваgradle hello,, мы увидим сообщение“Hello Gradle” в журналах.

4. Конфигурация плагина

Большинству плагинов потребуется доступ к внешней конфигурации из скрипта сборки.

Мы можем сделать это с помощьюextension objects: 

public class GreetingPluginExtension {
    private String greeter = "example";
    private String message = "Message from the plugin!"
    // standard getters and setters
}

Теперь давайте добавим новыйextension object в наш класс плагина: 

@Override
public void apply(Project project) {
    GreetingPluginExtension extension = project.getExtensions()
      .create("greeting", GreetingPluginExtension.class);

    project.task("hello")
      .doLast(task -> {
          System.out.println(
            "Hello, " + extension.getGreeter());
          System.out.println(
            "I have a message for You: " + extension.getMessage());
      });
}

Теперь, когда мы вызываемgradle hello,, мы видим сообщение по умолчанию, определенное в нашемGreetingPluginExtension.

Но так как мы создали расширение, мы можем использовать замыкание для этого внутри скрипта сборки: 

greeting {
    greeter = "Stranger"
    message = "Message from the build script"
}

5. Автономный проект плагина

Для создания автономных плагинов Gradle нам нужно проделать немного больше работы.

5.1. Настроить

Во-первых, нам нужно импортировать зависимость Gradle API - что довольно просто: 

dependencies {
    compile gradleApi()
}

Обратите внимание, что для того же в Maven требуется зависимостьgradle-tooling-api - из репозитория Gradle: 


    
        org.gradle
        gradle-tooling-api
        3.0
    
    
        org.gradle
        gradle-core
        3.0
        provided
    


    
        repo.gradle.org
        https://repo.gradle.org/gradle/libs-releases-local/

5.2. Подключение плагина

Чтобы позволить Gradle найти реализацию нашего автономного плагина, нам нужно создать файл свойств вsrc/main/resources/META-INF/gradle_-plugins_.

Файл ресурса должен иметь имя, соответствующее идентификатору плагина. So if our plugin has an id of org.example.greeting, the exact path of the file would be META-INF/gradle-plugins/org.example.greeting.properties.с

Далее мы можем определить класс реализации плагина: 

    implementation-class=org.gradle.GreetingPlugin

implementation-class должно быть равно полному имени пакета нашего класса плагина.

5.3. Создание идентификатора плагина

Есть некоторые правила и соглашения, которым ID плагина должен следовать в Gradle. Большинство из них похожи на правила имен пакетов в Java:

  • Они могут содержать только буквенно-цифровые символы «.» И «-»

  • У идентификатора должна быть хотя бы одна «.», Отделяющая доменное имя от имени плагина.

  • Пространства именorg.gradle иcom.gradleware ограничены

  • Идентификатор не может начинаться или заканчиваться на «.»

  • Не допускается использование двух или более последовательных символов «.»

Наконец, существует соглашение, согласно которому идентификатор плагина должен быть именем в нижнем регистре, которое следует соглашению об обратном доменном имени.

Основное различие между именами пакетов Java и именами плагинов Gradle заключается в том, что имя пакета обычно более детально, чем идентификатор плагина.

5.4. Плагин публикации

Когда мы хотим опубликовать наш плагин, чтобы иметь возможность использовать его во внешних проектах, у нас есть два способа добиться этого.

Во-первых,we can publish our plugin JAR to an external repository like Maven or Ivy.

В качестве альтернативы, мы можем использовать портал Gradle Plugin. Это позволит нашему плагину быть доступным широкому сообществу Gradle. Подробнее о публикации проектов в репозитории Gradle можно найти вGradle Plugin Portal Documentation..

5.5. Плагин разработки Java Gradle

Когда мы пишем наши плагины на Java, мы можем извлечь выгоду изJava Gradle Development Plugin.

Это автоматически скомпилирует и добавит зависимостиgradleApi(). Он также будет выполнять проверку метаданных плагина как часть задачиgradle jar.

Мы можем добавить плагин, добавив следующий блок в наш скрипт сборки: 

plugins {
    id 'java-gradle-plugin'
}

6. Плагины для тестирования

Чтобы проверить, что наш плагин работает правильно и правильно применен кProject,, мы можем использоватьorg.gradle.testfixtures.ProjectBuilder для создания экземпляраProject.

Затем мы можем проверить, был ли применен плагин и есть ли в нашем экземпляреProject правильные задачи. Для этого мы можем использовать стандартные тестыJUnit: 

@Test
public void greetingTest(){
    Project project = ProjectBuilder.builder().build();
    project.getPluginManager().apply("com.example.greeting");

    assertTrue(project.getPluginManager()
      .hasPlugin("com.example.greeting"));

    assertNotNull(project.getTasks().getByName("hello"));
}

7. Резюме

В этой статье мы показали основы написания собственных плагинов в Gradle. Чтобы подробнее разобраться в создании плагина, взгляните на файлGradle Documentation.

И, как всегда, можно найти все образцы кодаover on Github.

Related