TOC

Escrevendo plugins Gradle personalizados

Escrevendo plugins Gradle personalizados

1. Introdução

O Gradle é uma ferramenta de compilação muito popular, geralmente apreciada pelo processo de compilação altamente personalizável.

Hoje vamos mostrar como criar plug-ins personalizados do Gradle, que nos permitirão modificar o processo de construção além do que podemos alcançar com a configuração padrão.

2. Localização da fonte do plug-in

Podemos colocar nosso código em alguns locais diferentes. Todos eles têm algumas vantagens e desvantagens.

2.1. Script de Compilação

Podemos simplesmente colocar o código fonte do nosso plugin dentro do próprio script de construção. Isso nos dará compilação e inclusão automáticas do plugin.

It’s very simple, however, our plugin won’t be visible outside of the build script. Por causa disso, não podemos reutilizá-lo em outros scripts de construção.

2.2. PastaBuildSrc

Outra possibilidade que podemos usar é colocar o código-fonte do nosso plugin na pastabuildSrc/src/main/java.

Quando você executa o Gradle, ele verifica a existência da pastabuildSrc. Se isso existir, o Gradle criará e incluirá automaticamente nosso plugin.

Isso nos dará a possibilidade de compartilhar nosso plugin entre vários scripts de construção, mas ainda não seremos capazes de usá-lo em outros projetos.

2.3. Projeto autônomo

Por fim, podemos criar nosso plugin como um projeto separado, o que torna o plug-in totalmente reutilizável em vários projetos.

No entanto, para usá-lo em um projeto externo, precisaremos agrupá-lo em um arquivo jar e adicioná-lo a um projeto.

3. Nosso primeiro plug-in

Vamos começar com o básico -every Gradle Plugin must implement the com.gradle.api.Plugin interface.

A interface é genérica, portanto, podemos parametrizá-la com vários tipos de parâmetros. Normalmente, o tipo de parâmetro éorg.gradle.api.Project.

No entanto, podemos usar parâmetros de tipo diferentes para que o plug-in seja aplicado em diferentes fases da vida útil:

  • usarorg.gradle.api.Settings resultará na aplicação do plugin a um script de configurações

  • usarorg.gradle.api.Gradle resultará na aplicação do plugin a um script de inicialização

O plugin mais simples que podemos criar é um aplicativohello world: 

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

Agora podemos aplicá-lo adicionando uma linha dentro do nosso script de construção: 

apply plugin: GreetingPlugin

Agora, depois de chamargradle hello,, veremos a mensagem“Hello Gradle” nos logs.

4. Configuração de plugins

A maioria dos plug-ins precisará acessar uma configuração externa a partir do script de construção.

Podemos fazer isso usandoextension objects: 

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

Vamos agora adicionar o novoextension object à nossa classe de plugin: 

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

Agora, quando chamarmosgradle hello,, veremos a mensagem padrão definida em nossoGreetingPluginExtension.

Mas desde que criamos a extensão, podemos usar um fechamento para fazer isso dentro do script de construção: 

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

5. Projeto de plug-in autônomo

Para criar plugins Gradle independentes, precisamos fazer um pouco mais de trabalho.

5.1. Configuração

Primeiro, precisamos importar a dependência da API Gradle - o que é bastante direto: 

dependencies {
    compile gradleApi()
}

Observe que fazer o mesmo no Maven requer dependênciagradle-tooling-api - do repositório 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. Conectando o Plugin

Para permitir que o Gradle encontre a implementação de nosso plug-in autônomo, precisamos criar o arquivo de propriedades emsrc/main/resources/META-INF/gradle_-plugins_.

O arquivo de recurso precisa ter um nome que corresponda à identificação do plug-in. 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.

Em seguida, podemos definir a classe de implementação do plug-in: 

    implementation-class=org.gradle.GreetingPlugin

Oimplementation-class deve ser igual ao nome completo do pacote de nossa classe de plugin.

5.3. Criando o ID do Plugin

Existem algumas regras e convenções que o ID do plugin deve seguir em Gradle. A maioria deles é semelhante às regras de nome de pacote em Java:

  • Eles podem conter apenas caracteres alfanuméricos, "." e "-"

  • O ID precisa ter pelo menos um "." separando o nome do domínio do nome do plug-in

  • Os namespacesorg.gradle ecom.gradleware são restritos

  • Um ID não pode começar ou terminar com "."

  • Não há dois ou mais "." Consecutivos caracteres são permitidos

Finalmente, há uma convenção de que o Id do plugin deve ser um nome em minúsculas que segue a convenção reversa de nome de domínio.

A principal diferença entre os nomes de pacotes Java e os nomes de plug-in Gradle é que o nome do pacote geralmente é mais detalhado que o ID do plug-in.

5.4. Publishing Plugin

Quando queremos publicar nosso plug-in para poder reutilizá-lo em projetos externos, temos duas maneiras de conseguir isso.

Em primeiro lugar,we can publish our plugin JAR to an external repository like Maven or Ivy.

Como alternativa, podemos usar o Portal Gradle Plugin. Isso permitirá que nosso plugin seja acessível por uma ampla comunidade Gradle. Mais sobre como publicar projetos no repositório Gradle pode ser encontrado emGradle Plugin Portal Documentation.

5.5. Plug-in de desenvolvimento Java Gradle

Quando estamos escrevendo nossos plug-ins em Java, podemos nos beneficiar doJava Gradle Development Plugin.

Isso irá compilar e adicionar dependênciasgradleApi() automaticamente. Ele também executará a validação de metadados do plugin como parte da tarefagradle jar.

Podemos adicionar o plugin adicionando o seguinte bloco ao nosso script de construção: 

plugins {
    id 'java-gradle-plugin'
}

6. Testando Plugins

Para testar se nosso plug-in funciona corretamente e se está aplicado corretamente aProject,, podemos usarorg.gradle.testfixtures.ProjectBuilder para criar uma instância deProject.

Podemos então verificar se o plugin foi aplicado e se as tarefas adequadas estão presentes em nossa instânciaProject. Podemos usar testesJUnit padrão para fazer isso: 

@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. Sumário

Neste artigo, mostramos o básico para escrever plug-ins personalizados no Gradle. Para se aprofundar na criação de plugins, dê uma olhada emGradle Documentation.

E, como sempre, todas as amostras de código podem ser encontradasover on Github.

Related