Écrire des plugins Gradle personnalisés

1. introduction

Gradle est un outil de construction très populaire, qui est souvent apprécié pour le processus de construction hautement personnalisable.

Aujourd'hui, nous allons montrer comment créer des plugins Gradle personnalisés, qui nous permettront de modifier le processus de construction au-delà de ce que nous pouvons réaliser avec la configuration standard.

2. Emplacement de la source du plug-in

Nous pouvons placer notre code dans quelques endroits différents. Tous ont des avantages et des inconvénients.

2.1. Build Script

Nous pouvons simplement mettre le code source de notre plugin dans le script de construction lui-même. Cela nous donnera la compilation automatique et l'inclusion du plugin.

It’s very simple, however, our plugin won’t be visible outside of the build script. Pour cette raison, nous ne pouvons pas le réutiliser dans d'autres scripts de construction.

2.2. DossierBuildSrc

Une autre possibilité que nous pouvons utiliser est de placer le code source de notre plugin dans le dossierbuildSrc/src/main/java.

Lorsque vous exécutez Gradle, il vérifie l’existence du dossierbuildSrc. Si cela existe, Gradle construira et inclura automatiquement notre plugin.

Cela nous donnera la possibilité de partager notre plugin entre différents scripts de construction, mais nous ne pourrons toujours pas l'utiliser dans d'autres projets.

2.3. Projet autonome

Enfin, nous pouvons créer notre plug-in en tant que projet séparé, ce qui le rend entièrement réutilisable dans différents projets.

Cependant, pour l'utiliser dans un projet externe, nous devons le regrouper dans un fichier JAR et l'ajouter à un projet.

3. Notre premier plugin

Commençons par les bases -every Gradle Plugin must implement the com.gradle.api.Plugin interface.

L'interface est générique, nous pouvons donc la paramétrer avec différents types de paramètres. Habituellement, le type de paramètre estorg.gradle.api.Project.

Cependant, nous pouvons utiliser différents paramètres de type pour que le plug-in soit appliqué à différentes phases de la vie:

l'utilisation deorg.gradle.api.Settings entraînera l'application du plugin à un script de paramètres
l'utilisation deorg.gradle.api.Gradle entraînera l'application du plugin à un script d'initialisation

Le plugin le plus simple que nous puissions créer est une applicationhello world:

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

Nous pouvons maintenant l'appliquer en ajoutant une ligne dans notre script de construction:

apply plugin: GreetingPlugin

Maintenant, après avoir appelégradle hello,, nous verrons le message de“Hello Gradle” dans les journaux.

4. Configuration du plugin

La plupart des plugins auront besoin d'un accès à une configuration externe à partir du script de construction.

Nous pouvons le faire en utilisantextension objects:

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

Ajoutons maintenant les nouveauxextension object à notre classe de plugins:

@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());
      });
}

Maintenant, lorsque nous appelonsgradle hello,, nous verrons le message par défaut défini dans nosGreetingPluginExtension.

Mais depuis que nous avons créé l'extension, nous pouvons utiliser une fermeture pour le faire dans le script de construction:

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

5. Projet de plug-in autonome

Pour créer des plugins Gradle autonomes, nous devons faire un peu plus de travail.

5.1. Installer

Tout d’abord, nous devons importer la dépendance de l’API Gradle - ce qui est assez simple:

dependencies {
    compile gradleApi()
}

Notez que faire de même dans Maven nécessite la dépendancegradle-tooling-api - du référentiel 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. Câblage du plugin

Pour permettre à Gradle de trouver l'implémentation de notre plugin autonome, nous devons créer le fichier de propriétés dans lesrc/main/resources/META-INF/gradle_-plugins_.

Le fichier de ressources doit avoir un nom correspondant à l'id du plugin. 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.

Ensuite, nous pouvons définir la classe d'implémentation du plugin:

    implementation-class=org.gradle.GreetingPlugin

Lesimplementation-class doivent être égaux au nom complet du package de notre classe de plugin.

5.3. Création de l'ID de plug-in

Il existe certaines règles et conventions que le plugin ID doit suivre dans Gradle. La plupart d'entre eux sont similaires aux règles de nom de paquet en Java:

Ils ne peuvent contenir que des caractères alphanumériques, “.” Et “-“
L'identifiant doit avoir au moins un “.” Séparant le nom de domaine du nom du plugin
Les espaces de nomsorg.gradle etcom.gradleware sont restreints
Un identifiant ne peut pas commencer ou se terminer par “.”
Aucun ou plusieurs caractères «.» Consécutifs ne sont autorisés

Enfin, il existe une convention selon laquelle l'identifiant du plug-in doit être un nom en minuscules respectant la convention de nom de domaine inversé.

La principale différence entre les noms de package Java et les noms de plug-in Gradle est que le nom du package est généralement plus détaillé que l'ID du plug-in.

5.4. Plugin de publication

Lorsque nous voulons publier notre plug-in pour pouvoir le réutiliser dans des projets externes, nous avons deux moyens pour y parvenir.

Premièrement,we can publish our plugin JAR to an external repository like Maven or Ivy.

Alternativement, nous pouvons utiliser le portail Gradle Plugin. Cela permettra à notre plugin d'être accessible par la large communauté Gradle. Pour en savoir plus sur la publication de projets dans le référentiel Gradle, consultezGradle Plugin Portal Documentation.

5.5. Plugin de développement Java Gradle

Lorsque nous écrivons nos plugins en Java, nous pouvons bénéficier desJava Gradle Development Plugin.

Cela compilera et ajoutera automatiquement les dépendances degradleApi(). Il effectuera également la validation des métadonnées du plugin dans le cadre de la tâchegradle jar.

Nous pouvons ajouter un plugin en ajoutant le bloc suivant à notre script de construction:

plugins {
    id 'java-gradle-plugin'
}

6. Test des plugins

Pour tester que notre plugin fonctionne correctement et qu'il est correctement appliqué auxProject,, nous pouvons utiliserorg.gradle.testfixtures.ProjectBuilder pour créer une instance desProject.

Nous pouvons alors vérifier si le plugin a été appliqué et si les tâches appropriées sont présentes dans notre instanceProject. Nous pouvons utiliser les tests standardJUnit pour faire cela:

@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. Sommaire

Dans cet article, nous avons présenté les bases de l'écriture de plug-ins personnalisés dans Gradle. Pour approfondir la création de plugins, jetez un œil auxGradle Documentation.

Et, comme toujours, tous les échantillons de code peuvent être trouvésover on Github.

TOC

Écrire des plugins Gradle personnalisés