Mukautetun Gradle-lisäosan kirjoittaminen, testaaminen ja julkaiseminen

Käytännön opas omien Gradle-pluginien kirjoittamiseen, testaamiseen ja julkaisemiseen – mukana demorepositorio, jonka avulla pääset nopeasti alkuun!

Johdanto

Pluginit ovat erinomainen tapa jakaa Gradlen toiminnallisuuksia, olipa kyseessä julkinen plugini, joka tarjoaa työkalintegraatioita, kuten Artifactory-plugin, tai organisaation sisäinen plugini, jolla jaetaan yhteisiä tehtäviä – kuten ne, joiden kehittämisessä autamme asiakkaitamme.

Valitettavasti huomasin, että oman Gradle-pluginin kirjoittamista käsittelevä dokumentaatio ja esimerkit ovat melko hajallaan. Päätin kirjoittaa hyvin yksinkertaisen Gradle-pluginin pohjaksi, jotta sekä minä että nyt sinä pääsette nopeasti alkuun omaa Gradle-pluginia kehittäessä. Se sisältää Hello, world! -tehtäviä, testejä ja julkaisemiseen tarvittavat keinot. Kirjoitin samalla myös tämän blogin dokumentaatioksi. Toivottavasti pidät siitä!

Plugin-repositorio

Löydät Gradle-pluginin aloituspohjan GitHubista: Praqma/gradle-plugin-bootstrap. Se on täysin toimiva Gradle-plugin. Voit käyttää sitä vapaasti lähtökohtana: kloonaa se ja muokkaa tarpeidesi mukaan.

Osat

Käyn lyhyesti läpi Gradle-pluginin muodostavat osat. Löydät kaiken mainitun repositoriosta, mutta käsittelen niitä täällä yksityiskohtaisemmin kuin kommenteissa olisi mahdollista.

Aloituspiste

Esimerkki löytyy täältä:src/main/groovy/com/praqma/demo/DemoPlugin.groovy

Tämä on pluginin ydin. Täältä löydät apply-metodin, sillä se toteuttaa rajapinnan org.gradle.api.Plugin. Gradle kutsuu tätä metodia, kun se ottaa pluginisi käyttöön projektissa. Täällä voit lisätä tehtäviä, laajennuksia ja muuta vastaavaa.

Esimerkkipluginissa tällaiset asiat on siirretty erilliseen moduuliin. Tällä pyritään vain estämään pääpluginiluokan kasvaminen liian suureksi. Pidä tätä suosituksena silloin, kun odotat lisääväsi pluginiisi useita erilaisia tehtäviä.

Aloituspisteen rekisteröinti

Esimerkki löytyy täältä:build.gradle

Ennen kuin Gradle voi ottaa pluginisi käyttöön, sille on kerrottava, mistä se löytyy. Tee tämä ottamalla käyttöön ja määrittämällä java-gradle-plugin-Gradle-plugin build.gradle-tiedostossa. Ota plugini käyttöön build.gradle-tiedoston alussa olevan plugins-lohkon avulla:

plugins {    id 'java-gradle-plugin' }

Määritä pluginisi gradlePlugin-lohkossa, jonka java-gradle-plugin tarjoaa. plugins-lohkossa voit lisätä merkinnän jokaiselle projektin pluginille. Pidämme asian yksinkertaisena ja käytämme vain yhtä pluginia, joten lisäämme sen alle vapaasti nimetyn lohkon, jossa määritämme pluginimme ja asetamme kaksi ominaisuutta:

• id on pluginisi tunniste, jota käytetään pluginin käyttöönottoon:plugins { id: 'com.praqma.demo' }

• implementationClass osoittaa aloituspisteen luokkaan, jotta Gradle löytää sen. Tässä tapauksessa se on com.praqma.demo.DemoPlugin.

id on pluginisi tunniste, jota käytetään pluginin käyttöönottoon:

plugins {     id: 'com.praqma.demo' }

implementationClass osoittaa aloituspisteen luokkaan, jotta Gradle löytää sen. Tässä tapauksessa se on com.praqma.demo.DemoPlugin.

Koko määritys näyttää suunnilleen tältä:

gradlePlugin {    plugins {        demoPlugin {            id = 'com.praqma.demo'            implementationClass = 'com.praqma.demo.DemoPlugin'        }    }}

Tehtävien lisääminen

Esimerkki löytyy täältä:src/main/groovy/com/praqma/demo/greeting/GreetingModule.groovy

Lisäsin tähän kaksi tehtävää: toinen havainnollistaa projektin laajennusten ominaisuuksien käyttöä ja toinen projektin ominaisuuksien käyttöä. Tehtävien lisääminen pluginin eroaa vain vähän niiden lisäämisestä tavalliseen Gradle-projektiin: kutsu vain projektin task-metodia.

Tehtävien jakaminen moduuleihin ei ole missään nimessä pakollista. Se on vain tapani estää pluginiluokkaa muuttumasta kahdentuhannen rivin hirvitykseksi.

Tehtävätyyppien lisääminen

Esimerkki löytyy tiedostoista:src/main/groovy/com/praqma/demo/greeting/GreetingTask.groovysrc/main/groovy/com/praqma/demo/greeting/GreetingModule.groovy

Mukautetun tehtävätyypin luominen antaa lisäosan käyttäjille mahdollisuuden perustaa omat mukautetut tehtävänsä sinun tehtäviisi, aivan kuten me perustamme omamme Zip- ja Copy-tehtäviin. Jaa ne lisäämällä nämä tehtäväluokat osaksi lisäosaasi. Pelkkä niiden mukanaolo antaa käyttäjille mahdollisuuden määrittää tämän tyyppisiä tehtäviä käyttämällä niiden täysin määritettyä nimeä. Esimerkiksi:

import com.praqma.demo.greeting.GreetingTasktask myGreetingTask(type:GreetingTask) {    message = "Howdy"}

Jotta käyttäjien ei tarvitse tuoda tehtävää erikseen, lisää tehtäväluokka projektin ExtraPropertiesExtension-laajennukseen, kun lisäosaa otetaan käyttöön. Tämän kätevän keinon avulla käyttäjät voivat käyttää tehtävääsi tässä määrittämälläsi nimellä ilman erillistä tuontia.

project.ext.GreetingTask = com.praqma.demo.greeting.GreetingTask

Laajennusten lisääminen

Esimerkki löytyy tiedostoista:src/main/groovy/com/praqma/demo/greeting/GreetingExtension.groovysrc/main/groovy/com/praqma/demo/greeting/GreetingModule.groovy

Laajennukset tuovat esiin ominaisuuksia, joita lisäosan käyttäjät voivat määrittää. Niiden avulla käyttäjät voivat määrittää tehtävissä tarvitsemiasi arvoja. Demolisäosassa käyttäjät voivat määrittää helloWorld-tehtävässä käytettävän tervehdyksen asettamalla greeting.message-ominaisuuden build.gradle-tiedostossaan.

Voit lisätä lisäosaasi omia laajennuksia luomalla yksinkertaisen luokan, joka sisältää ominaisuuksia, ja lisäämällä sen projektin laajennukseksi lisäosasi apply-metodissa:

project.extensions.create('greeting', GreetingExtension)

Näitä ominaisuuksia voi käyttää projektin laajennusten kautta, esimerkiksi:

project.extensions.<extensionName>.<propertyName>

Lisäosan testaaminen

En käsittele Gradle-lisäosan yksikkötestausta, sillä se ei eroa tavallisen Groovy-projektin yksikkötestauksesta ja aiheesta on saatavilla paljon hyviä materiaaleja (katso alla oleva resurssiosio). Käsittelen kuitenkin toiminnallisia testejä sekä sitä, miten lisäosaa testataan paikallisen julkaisun avulla.

Toiminnalliset testit

Esimerkki löytyy tiedostosta:src/test/groovy/com/praqma/demo/greeting/GreetingModuleTest.groovy

Gradle-lisäosan toiminnallisten testien kirjoittaminen on lastenleikkiä GradleRunnerin ansiosta. JUnitin @Rule- ja @Before-annotaatioiden avulla voit helposti luoda jokaista testiä varten väliaikaisen hakemiston, joka sisältää lisäosaasi käyttävän build.gradle-tiedoston. GradleRunner lisää lisäosasi väliaikaisen projektin classpathiin, jotta se voi todella ottaa testattavan lisäosasi käyttöön. Kun suoritat tehtäväsi GradleRunnerin kautta, saat käyttöösi buildin tuloksen ja tekstimuotoisen tulosteen. Yhdessä väliaikaisen hakemiston käytön kanssa tämä mahdollistaa sen tarkistamisen ja varmistamisen, että kaikki suoritettiin odotetusti.

Julkaiseminen ja testaaminen paikallisella koneella

Lisäosa on mahdollista julkaista koneesi paikalliseen Maven-repositorioon. Näin voit ottaa paikallisen testijulkaisusi käyttöön koneellasi olevassa Gradle-projektissa ja testata muutoksiasi julkaisematta niitä jaettuun repositorioon. Se vaatii hieman määrityksiä, mutta on melko suoraviivaista.

Julkaiseminen paikalliseen Maven-repositorioon

Ota käyttöön maven-publish-lisäosa, joka sisältää publishToMavenLocal-tehtävän. Tämä tehtävä julkaisee kaikki määrittämäsi julkaisut paikalliseen repositorioosi, joten määritetään lisäosallemme julkaisu:

publishing {    publications {        pluginPublication (MavenPublication) {            from    components.java            groupId    project.group            artifactId    "demo"            version    project.version        }    }}

Julkaise lisäosa nykyisessä tilassaan paikalliseen repositorioosi suorittamalla gradle publishToMavenLocal.

Paikallisesti julkaistun lisäosan käyttöönotto

Jotta voit ottaa paikallisesti julkaistun lisäosan käyttöön projektissasi, sinun on lisättävä paikallinen Maven-repositoriosi luotetuksi repositorioksi Gradle-projektiisi. Onneksi Gradle mahdollistaa tämän kutsumalla mavenLocal()-metodia build.gradle-tiedostosi repository-sulussa. Esimerkiksi:

buildscript {    repositories {        mavenLocal()    }    dependencies {        classpath "com.praqma:demo:1.0.0"    }}apply plugin: 'com.praqma.demo.DemoPlugin'

Voit nyt suorittaa Gradle-buildisi, ja projektisi käyttää lisäosan paikallista jakelua.

Lisäosan jakelu

Käsittelen julkaisemista sekä julkiseen Gradle-lisäosarepositorioon että valinnaiselle Artifactory-palvelimelle. Projekti sisältää tarvittavat määritykset molempiin. Poista vain se, jota et aio käyttää, ja mukauta käyttöön jäävää.

Gradle-lisäosarepositorion kautta

Määritys

Esimerkki löytyy tiedostosta: build.gradle

Ota com.gradle.plugin-publish-lisäosa käyttöön lisäosaprojektissasi. Määritä se pluginBundle-sulun avulla. Siinä annat lisäosastasi hyödyllisiä tietoja, kuten repositorion sijainnin, kuvauksen ja asiaankuuluvat tagit.

pluginBundle {    website = 'https://github.com/Praqma/gradle-plugin-bootstrap'    vcsUrl = 'scm:git@github.com:Praqma/gradle-plugin-bootstrap.git'    tags = ['demo', 'example', 'quickstart']    plugins {        demoPlugin {            id = 'com.praqma.demo.DemoPlugin'            displayName = 'Gradle Multi Git plugin'            description = 'Demo plugin to use as a starting point for custom plugin development'        }    }}

Julkaiseminen

com.gradle.plugin-publish-lisäosa tarjoaa tarvittavat tehtävät lisäosasi julkaisemiseen lisäosaportaalissa.

Suorita lisäosasi repositoriossa gradle login ja valtuuta kone julkaisemaan lisäosasi ohjeiden mukaisesti.

Julkaise lisäosasi portaalissa suorittamalla gradle publishPlugins.

Käyttöönotto

Kun lisäosa on julkaistu, sen voi ottaa käyttöön muissa Gradle-projekteissa plugins-sulun avulla lisäosan tunnusta ja versiota käyttäen. Esimerkiksi:

plugins {    id 'com.praqma.demo.DemoPlugin', version '1.0.0'}

Artifactoryn kautta

Määritys

Esimerkki löytyy tiedostosta: build.gradle

Ota com.jfrog.artifactory-lisäosa käyttöön ja määritä se. artifactory-sulussa määrität kaiken, mitä lisäosa tarvitsee lisäosan julkaisemiseen Artifactory-palvelimellesi. Esimerkiksi:

artifactory {    contextUrl = "http://devops.acmeindustries.com/artifactory"    publish {        repository {            repoKey     = 'plugins-release'            username    = 'joe'            password    = 's3cr3t-p4ss'            maven       = true        }        defaults{            publications("pluginPublication")    // Publication defined below        }    }}

Meidän on vielä määritettävä, mitä julkaisemme. Ota siis käyttöön maven-publish-lisäosa, jonka avulla voit määrittää lisäosamme sisältävän MavenPublication-julkaisun. Esimerkiksi:

publishing {    publications {        pluginPublication (MavenPublication) {            from    components.java            groupId    project.group            artifactId    "demo"            version    project.version        }    }}

Julkaiseminen

Julkaise lisäosasi suorittamalla gradle artifactoryPublish.

Käyttöönotto

Jotta voit ottaa lisäosan käyttöön, se on ensin haettava. Rekisteröi Artifactory-palvelimesi repositorioksi ja lisää lisäosasi riippuvuudeksi. Ota se sitten käyttöön kuten mikä tahansa muu lisäosa. Tässä on esimerkkimääritys projektista, jossa lisäosamme otetaan käyttöön:

buildscript {    repositories {        maven {            url = "http://devops.acmeindustries.com/artifactory/plugins-release"            credentials {                username = "joe"                password = "s3cr3t-p4ss"            }        }    }    dependencies {        classpath "com.praqma:demo:1.0.0"    }}apply plugin: "com.praqma.demo.DemoPlugin" // Apply with the plugin id

Loppusanat

Tämän pitäisi kattaa oman Gradle-lisäosan käyttöönoton perusteet. Toivottavasti tästä on apua omien hienojen Gradle-lisäosien kirjoittamiseen ja jakeluun. Ajatukset, kysymykset ja ehdotukset ovat erittäin tervetulleita – jätä ne alla olevaan kommenttiosioon!

Lähteet

• gradle.org – Omien lisäosien kirjoittaminen

• gradle.org – Gradle TestKit

• gradle.org – Omien tehtävien kirjoittaminen

• gradle.org – ExtraPropertiesExtension

• gradle.org – Miten lisään pluginini plugin-portaaliin?

• gradle.org – java-gradle-plugin-käyttöopas

• mrhaki.blogspot.se – Gradle Goodness: Määritä mukautetuille plugineille lyhyt plugin-tunnus

• jfrog.com – Gradle Artifactory Plugin

• tutorialspoint.com . Groovy-yksikkötestaus

• groovy-lang.org – Core Testing Guide

• Lähdedokumentaatiossa on linkkejä myös useisiin muihin viitteisiin