Mukautetun Gradle-lisäosan kirjoittaminen, testaaminen ja julkaiseminen

Käytännön opas omien Gradle-lisäosien kirjoittamiseen, testaamiseen ja julkaisemiseen – mukana demorepositorio, jolla pääset nopeasti alkuun!

Johdanto

Lisäosat ovat erinomainen tapa jakaa Gradlen toiminnallisuuksia, olipa kyseessä sitten julkinen lisäosa, joka tarjoaa työkalintegraatioita, kuten Artifactory-lisäosa, tai organisaation sisäinen lisäosa, joka jakaa yhteisiä tehtäviä – kuten ne, joiden kehittämisessä autamme asiakkaitamme.

Valitettavasti huomasin, että oman Gradle-lisäosan kirjoittamiseen liittyvä dokumentaatio ja esimerkit olivat melko hajallaan. Päätin kirjoittaa hyvin yksinkertaisen Gradle-lisäosan pohjaksi, jotta minä – ja nyt myös sinä – pääsemme nopeasti alkuun oman Gradle-lisäosan kehittämisessä. Se sisältää Hello, world! -tehtäviä, testit ja keinot julkaisemiseen. Kirjoitin tämän blogin samalla dokumentaatioksi. Toivottavasti siitä on iloa!

Lisäosan repositorio

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

Osat ja kokonaisuus

Käyn lyhyesti läpi Gradle-lisäosan yksittäiset osat. Löydät kaikki mainitut asiat repositoriosta, mutta käsittelen niitä tässä tarkemmin kuin kommenteissa olisi mahdollista.

Aloituspiste

Esimerkki löytyy tiedostosta:src/main/groovy/com/praqma/demo/DemoPlugin.groovy

Tämä on lisäosan ydin. Täältä löydät apply-metodin, koska se toteuttaa rajapinnan org.gradle.api.Plugin. Gradle kutsuu tätä metodia, kun se ottaa lisäosasi käyttöön projektissa. Tässä voit lisätä tehtäviä, laajennuksia ja niin edelleen.

Esimerkkilisäosassa siirsin tällaiset asiat erilliseen moduuliin. Tarkoitus on vain estää pääasiallista lisäosaluokkaa kasvamasta valtavaksi. Suosittelen tätä, jos odotat lisääväsi lisäosaasi useita erilaisia tehtäviä.

Aloituspisteen rekisteröinti

Esimerkki löytyy tiedostosta:build.gradle

Ennen kuin Gradle voi ottaa lisäosasi käyttöön, sinun on kerrottava sille, mistä se löytyy. Tee tämä ottamalla java-gradle-plugin-Gradle-lisäosa käyttöön ja määrittämällä se build.gradle-tiedostossa. Ota lisäosa käyttöön build.gradle-tiedoston alussa olevalla plugins-lohkolla:

plugins {    id 'java-gradle-plugin' }

Määritä lisäosasi gradlePlugin-lohkossa, jonka java-gradle-plugin tarjoaa. plugins-lohkossa voit lisätä merkinnän jokaiselle projektin lisäosalle. Pidämme asian yksinkertaisena ja käytössämme on vain yksi lisäosa, joten lisäämme sen alle vapaasti nimetyn lohkon lisäosan määrittämiseksi ja asetamme kaksi ominaisuutta:

• id on lisäosasi tunniste, jota käytetään lisäosan 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 lisäosasi tunniste, jota käytetään lisäosan 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.

Kokonaismää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 tiedostosta:src/main/groovy/com/praqma/demo/greeting/GreetingModule.groovy

Lisäsin tähän kaksi tehtävää: toinen havainnollistaa projektin laajennusten ominaisuuksien käyttöä, toinen projektin ominaisuuksien käyttöä. Tehtävien lisääminen lisäosaan poikkeaa hyvin vähän tehtävien lisäämisestä tavalliseen Gradle-projektiin – kutsu vain projektin task-metodia.

Tehtävien jakaminen moduuleihin ei tälläkään kertaa ole välttämätöntä. Se on vain tapani estää lisäosaluokkaa muuttumasta kaksituhatriviseksi hirviöksi.

Tehtävätyyppien lisääminen

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

Mukautetun tehtävätyypin luominen antaa pluginin käyttäjille mahdollisuuden perustaa omat mukautetut tehtävänsä sinun tehtäviisi, aivan kuten me perustamme tehtävämme Zip- ja Copy-tehtäviin. Jaa ne sisällyttämällä nämä tehtäväluokat pluginiisi. Pelkkä niiden mukanaolo antaa käyttäjille mahdollisuuden määrittää tämän tyyppisiä tehtäviä käyttämällä niiden täysin määriteltyä nimeä. Esimerkiksi:

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

Jotta käyttäjien ei tarvitse importata tehtävää, lisää tehtäväluokka projektin ExtraPropertiesExtension-laajennukseen pluginia soveltaessasi. 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, että heidän tarvitsee importata sitä.

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

Laajennusten lisääminen

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

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

Lisää omia laajennuksia pluginiisi luomalla yksinkertainen luokka, joka sisältää joitakin ominaisuuksia, ja lisäämällä sen projektin laajennukseksi pluginisi apply-metodissa:

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

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

project.extensions.<extensionName>.<propertyName>

Pluginin testaaminen

En käsittele Gradle-pluginin yksikkötestausta tarkemmin, sillä se ei eroa tavallisen Groovy-projektin yksikkötestauksesta, ja aiheesta on saatavilla paljon hyviä materiaaleja (katso alla oleva resurssiosio). Sen sijaan käsittelen funktionaalisia testejä ja sitä, miten pluginia testataan paikallisen julkaisun avulla.

Funktionaaliset testit

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

Gradle-pluginin funktionaalisten testien kirjoittaminen on lastenleikkiä GradleRunnerin ansiosta. JUnitin @Rule- ja @Before-annotaatioiden avulla on helppoa luoda jokaista testiä varten väliaikainen hakemisto, joka sisältää pluginisi käyttöön ottavan build.gradle-tiedoston. GradleRunner lisää pluginisi väliaikaisen projektin classpathiin, joten se voi todella ottaa testattavan pluginisi käyttöön. Kun suoritat tehtäviäsi GradleRunnerin kautta, pääset käsiksi buildin tulokseen ja tekstimuotoiseen tulosteeseen. Yhdessä väliaikaisen hakemiston käytön kanssa tämä mahdollistaa sen, että voit tarkistaa ja varmistaa kaiken toimineen odotetusti.

Julkaiseminen ja testaaminen paikallisella koneella

Pluginisi voi 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. Tämä vaatii hieman määrityksiä, mutta on melko suoraviivaista.

Julkaiseminen paikalliseen Maven-repositorioon

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

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

Julkaise plugin nykyisessä tilassaan paikalliseen repositorioosi suorittamalla gradle publishToMavenLocal.

Paikallisesti julkaistun pluginin käyttöönotto

Jotta voit ottaa paikallisesti julkaistun pluginin 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-sulkeumassa. 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ää pluginin paikallista jakeluversiota.

Pluginin jakelu

Käsittelen julkaisemista sekä julkiseen Gradle-plugin-repositorioon että vapaasti valittavaan Artifactory-palvelimeen. Projekti sisältää tarvittavat määritykset kumpaankin. Poista vain se, jota et aio käyttää, ja muokkaa käyttöön jäävää määritystä.

Gradle-plugin-repositorion kautta

Määritys

Esimerkki löytyy tiedostosta:build.gradle

Ota com.gradle.plugin-publish-plugin käyttöön plugin-projektissasi. Määritä se pluginBundle-sulun avulla. Siinä annat pluginistasi hyödyllisiä tietoja, kuten repositorion sijainnin, kuvauksen ja olennaiset 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-plugin tarjoaa tarvittavat tehtävät pluginisi julkaisemiseen plugin-portaalissa.

Suorita gradle login pluginisi repositoriossa ja valtuuta kone pluginin julkaisemiseen ohjeiden mukaan.

Julkaise plugin portaalissa suorittamalla gradle publishPlugins.

Käyttöönotto

Kun plugin on julkaistu, sen voi ottaa käyttöön muissa Gradle-projekteissa plugins-sulun kautta käyttämällä pluginin tunnistetta ja versiota. 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-plugin käyttöön ja määritä se. artifactory-sulussa määrität kaiken, mitä plugin tarvitsee julkaistakseen pluginin 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-plugin, jonka avulla voit määrittää MavenPublication-julkaisun, joka sisältää pluginimme. Esimerkiksi:

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

Julkaiseminen

Julkaise pluginisi suorittamalla gradle artifactoryPublish.

Käyttöönotto

Jotta voit ottaa pluginin käyttöön, se on ensin haettava. Rekisteröi Artifactory-palvelimesi repositorioksi ja lisää pluginisi riippuvuudeksi. Ota se sitten käyttöön kuten mikä tahansa muu plugin. Tässä on esimerkkimääritys projektista, joka käyttää pluginimme:

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 mukautetun Gradle-pluginin käyttöönoton perusteet. Toivottavasti tästä on apua omien hienojen Gradle-pluginien kirjoittamisessa ja jakelussa. Ajatukset, kysymykset ja ehdotukset ovat tervetulleita – jätä ne alla olevaan kommenttiosioon!

Viitteet

• gradle.org - Mukautettujen pluginien kirjoittaminen

• gradle.org - Gradle TestKit

• gradle.org - Mukautettujen tehtävien kirjoittaminen

• gradle.org - ExtraPropertiesExtension

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

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

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

• jfrog.com – Gradle Artifactory -plugin

• tutorialspoint.com . Groovyn yksikkötestaus

• groovy-lang.org – Core Testing -opas

• Lähdedokumentaatioon on linkitetty myös useita viitteitä