idiomatic gradle plugin writing - gradlesummit 2016

#GradleSummit Gradle Summit 2016

IDIOMATIC GRADLE

PLUGIN WRITINGSchalk W. Cronjé

1

ABOUT ME

Email:

Twitter / Ello : @ysb33r

[email protected]

Gradle plugins authored/contributed to: VFS, Asciidoctor,JRuby family (base, jar, war etc.), GnuMake, Doxygen, Bintray

3

ABOUT THIS PRESENTATIONWritten in Asciidoctor (1.5.3.2)

Styled by asciidoctor-revealjs extension

Built using:

Gradle

gradle-asciidoctor-plugin

gradle-vfs-plugin

4

GET YOUR DAILY GRADLE DOSE

@DailyGradle

#gradleTip

5

6

THE PROBLEMThere is no consistency in the way plugin authors craft extensions

to the Gradle DSL today

QUALITY ATTRIBUTES OF DSL

Readability

Consistency

Flexibility

Expressiveness

7

PROJECT LAYOUT

Figure 1. Plugin project �le layout

8

BUILD SCRIPTrepositories { jcenter() }

apply plugin : 'groovy'

dependencies { compile localGroovy() compile gradleApi() testCompile ("org.spockframework:spock-core:1.0-groovy-2.3") { exclude module : 'groovy-all' } }

9 . 1

9 . 2

TRICK : SPOCK VERSIONext { spockGrVer = GroovySystem.version.replaceAll(/\.\d+$/,'') }

dependencies { testCompile ("org.spockframework:spock-core:1.0-${spockGrVer}") { exclude module : 'groovy-all' } }

CREATE PLUGIN CLASSpackage idiomatic.gradle.authoring

import org.gradle.api.Plugin import org.gradle.api.Project

class MyExamplePlugin implements Plugin<Project> {

void apply(Project project) { } }

10 . 1

10 . 2

CREATE PROPERTIES FILE

META-INF/gradle-plugins/idiomatic.authored.example.properties

implementation-class=idiomatic.gradle.authoring.MyExamplePlugin

Name of �le must match plugin identi�er

11

NEED 2 KNOW : PLUGINS

Plugin author has no control over order in which plugins

will be applied

Handle both cases of related plugin applied before or after

yours

FOR BEST COMPATIBILITY

Support same JDK range as Gradle

Gradle 1.x - mininum JDK5

Gradle 2.x - minimum JDK6

Build against Gradle 2.0

… unless proper compatibility testing is in place

Suggested baseline at Gradle 2.12 (for new model)

Only use later versions if speci�c new functionality is

required.

12 . 1

JDK COMPATIBILITY// build.gradle targetCompatibility = 1.6 sourceCompatibility = 1.6

project.tasks.withType(JavaCompile) { task -> task.sourceCompatibility = project.sourceCompatibility task.targetCompatibility = project.targetCompatibility }

project.tasks.withType(GroovyCompile) { task -> task.sourceCompatibility = project.sourceCompatibility task.targetCompatibility = project.targetCompatibility }

(Fixed in 2.14)

12 . 2

12 . 3

GRADLE BUILD VERSION

gradle/wrapper/gradle-wrapper.properties

distributionUrl=https\://..../distributions/gradle-2.0-all.zip

STYLE : TASKSProvide a default instantiation of your new task class

Keep in mind that user would want to create additionaltasks of same type

Make it easy for them!!

13 . 1

CREATE TASK CLASSpackage idiomatic.gradle.authoring

import org.gradle.api.DefaultTask import org.gradle.api.tasks.TaskAction

class MyExampleTasks extends DefaultTask {

@TaskAction void exec() { } }

13 . 2

14 . 1

HONOUR OFFLINEgradle --offline

The build should operate without accessingnetwork resources.

14 . 2

HONOUR OFFLINEUnset the enabled property, if build is of�ine

task VfsCopy extends DefaultTask { VfsCopy() {

enabled = !project.gradle.startParameter.isOffline()

}

}

PREFER METHODS OVER PROPERTIES( IOW To assign or not to assign )

Methods provide more �exibility

Tend to provide better readability

Assignment is better suited towards

One-shot attribute setting

Overriding default attributes

Non-lazy evaluation

15

HOW NOT 2 : COLLECTION OF FILESTypical implementation …

class MyTask extends DefaultTask {

@InputFiles List<File> mySources

}

leads to ugly DSL

task myTask( type: MyTask ) {

myTask = [ file('foo/bar.txt'), new File( 'bar/foo.txt') ]

}

16 . 1

COLLECTION OF FILESmyTask { mySources file( 'path/foobar' ) mySources new File( 'path2/foobar' ) mySources 'file3', 'file4' mySources { "lazy evaluate file name later on" } }

Allow ability to:

Use strings and other objects convertible to File

Append lists

Evaluate as late as possible

Reset default values

16 . 2

COLLECTION OF FILES

Ignore Groovy shortcut; use three methods

class MyTask extends DefaultTask { @InputFiles

FileCollection getDocuments() {

project.files(this.documents) // magic API method }

void setDocuments(Object... docs) { this.documents.clear()

this.documents.addAll(docs as List) }

void documents(Object... docs) { this.documents.addAll(docs as List) }

private List<Object> documents = [] }

16 . 3

KNOW YOUR TASK ANNOTATIONS

@Input

@InputFile

@InputFiles

@InputDirectory

@Nested

@OutputFile

@OutputFiles

@OutputDirectory

@OutputDirectories

@Optional

17

COLLECTION OF STRINGSimport org.gradle.util.CollectionUtils

Ignore Groovy shortcut; use three methods

@Input

List<String> getScriptArgs() {

// stringize() is your next magic API method CollectionUtils.stringize(this.scriptArgs)

}

void setScriptArgs(Object... args) { this.scriptArgs.clear()

this.scriptArgs.addAll(args as List) }

void scriptArgs(Object... args) { this.scriptArgs.addAll(args as List) }

private List<Object> scriptArgs = []

18

HOW NOT 2 : MAPSTypical implementation …

class MyTask extends DefaultTask {

@Input

Map myOptions

}

leads to ugly DSL

task myTask( type: MyTask ) {

myOptions = [ prop1 : 'foo/bar.txt', prop2 : 'bar/foo.txt' ]

}

19 . 1

19 . 2

MAPStask myTask( type: MyTask ) {

myOptions prop1 : 'foo/bar.txt', prop2 : 'bar/foo.txt'

myOptions prop3 : 'add/another'

// Explicit reset myOptions = [:]

}

MAPS@Input

Map getMyOptions() {

this.attrs

}

void setMyOptions(Map m) { this.attrs=m

}

void myOptions(Map m) { this.attrs+=m

}

private Map attrs = [:]

19 . 3

20 . 1

COMPATIBILITY TESTING

How can a plugin author test a plugin against multiple Gradle

versions?


Gradle 2.7 added TestKit

2.9 added multi-distribution testing

Really became useful in 2.12/2.13

What to do for Gradle 2.0 - 2.8?

20 . 2


GradleTest plugin to the rescue

buildscript { dependencies { classpath "org.ysb33r.gradle:gradletest:0.5.4" } }

apply plugin : 'org.ysb33r.gradletest'

http://bit.ly/1LfUUU4

20 . 3


Create src/gradleTest/NameOfTest folder.

Add build.gradle

Add task runGradleTest

Add project structure

20 . 4


Add versions to main build.gradle

gradleTest { versions '2.0', '2.2', '2.4', '2.5', '2.9' }

Run it!

./gradlew gradleTest

20 . 5

TRICK : SAFE FILENAMESAbility to create safe �lenames on all platforms from inputdata

Example: Asciidoctor output directories based uponbackend names

// WARNING: Using a very useful internal API import org.gradle.internal.FileUtils

File outputBackendDir(final File outputDir, final String backend) { // FileUtils.toSafeFileName is your magic method new File(outputDir, FileUtils.toSafeFileName(backend)) }

21

22 . 1

CONVERTING EXTENSION TO NEW MODEL

Quickly convert an existing extension to be useable withinmodel

Easy migration path for existing users of a plugin

Little rewrite of code

CONVERTING EXTENSION TO NEW MODEL

Existing extension code

class ExternalToolExtension { String executable = 'make' List<String> execArgs = []

void execArgs(String... args) { this.execArgs.addAll(args as List) } }

In plugin apply

project.extensions.create('externalTool',ExternalToolExtension)

22 . 2

22 . 3

LINKING EXTENSION TO NEW MODEL

Old build script style

externalTool { executable 'gmake' execArgs '-s','-B' }


New model style

model { externalTool { executable 'gmake' executable = 'gmake' execArgs = ['-i'] execArgs '-s','-B' } }

22 . 4

22 . 5


Create model rule

class ExtensionContainerRules extends RuleSource { @Model ExternalToolExtension externalTool(ExtensionContainer ext) { ext.getByType(ExternalToolExtension) } }


Disadvantages

Changes made in the extension automatically re�ects new

model.

Order of new model evaluation and

project.afterEvaluate execution not guaranteed.

Gradle can never guarantee the con�guration to be

immutable.

22 . 6

MIGRATING EXTENSION TO UNMANAGED MODEL

Eliminate some of the issues of linking.

Similar minimal code changes as for linking.

Need to take care of decoration yourself.

Remove creation of extension when plugin is applied.

23 . 1


Modify extension class

class ExternalToolExtension { String executable = 'make' List<String> execArgs = []

void execArgs(String... args) { this.execArgs.addAll(args as List) }

void executable(String exe) { // <-- Add this this.executable = exe } }

23 . 2

23 . 3


Model rule remains unchanged

class ExtensionContainerRules extends RuleSource { @Model ExternalToolExtension externalTool(ExtensionContainer ext) { ext.getByType(ExternalToolExtension) } }

23 . 4


Disadvantages

Gradle can never guarantee the con�guration to beimmutable.

Gradle will not decorate the extension with any othermethods.

TRICK : SELF-REFERENCING PLUGINNew plugin depends on functionality in the plugin

Apply plugin direct in build.gradle

apply plugin: new GroovyScriptEngine( ['src/main/groovy','src/main/resources']. collect{ file(it).absolutePath } .toArray(new String[2]), project.class.classLoader ).loadScriptByName('book/SelfReferencingPlugin.groovy')

24

GET THE BOOKS

https://leanpub.com/b/idiomaticgradle

25

THANK YOUKeep your DSL extensions beautiful

Don’t spring surprising behaviour on the user

Email:


#idiomaticgradle

[email protected]

26

ADVANCED CONCEPTS

User override library version

Extend (decorate) existing task

Add generated JVM source sets

Operating system

27

USER OVERRIDE LIBRARY VERSION

Ship with prefered (and tested) version of dependentlibrary set as default

Allow user �exibility to try a different version of suchlibrary

Dynamically load library when needed

Still use power of Gradle’s dependency resolution

28 . 1


Example DSL from Asciidoctor

asciidoctorj { version = '1.6.0-SNAPSHOT' }

Example DSL from JRuby Base

jruby { execVersion = '1.7.12'}

28 . 2

28 . 3


1. Create Extension

2. Add extension object in plugin apply

3. Create custom classloader


Step 1: Create project extension

class MyExtension {

// Set the default dependent library version String version = '1.5.0'

MyExtension(Project proj) { project= proj }

@PackageScope Project project }

28 . 4


Step 2: Add extension object in plugin apply

class MyPlugin implements Plugin<Project> { void apply(Project project) {

// Create the extension & configuration project.extensions.create('asciidoctorj',MyExtension,project) project.configuration.maybeCreate( 'int_asciidoctorj' )

// Add dependency at the end of configuration phase project.afterEvaluate { project.dependencies { int_asciidoctorj "org.asciidoctor:asciidoctorj" + "${project.asciidoctorj.version}" } } } }

28 . 5

USER OVERRIDE LIBRARY VERSION (2.5+)

Step 2: Add extension object Gradle 2.5+

class MyPlugin implements Plugin<Project> { void apply(Project project) {

// Create the extension & configuration project.extensions.create('asciidoctorj',MyExtension,project) def conf = configurations.maybeCreate( 'int_asciidoctorj' )

conf.defaultDependencies { deps -> deps.add( project.dependencies.create( "org.asciidoctor:asciidoctorj:${asciidoctorj.version}") ) } } }

28 . 6


Step 3: Custom classloader (usually loaded from task action)

// Get all of the files in the `asciidoctorj` configuration def urls = project.configurations.int_asciidoctorj.files.collect { it.toURI().toURL() }

// Create the classloader for all those files def classLoader = new URLClassLoader(urls as URL[], Thread.currentThread().contextClassLoader)

// Load one or more classes as required def instance = classLoader.loadClass( 'org.asciidoctor.Asciidoctor$Factory')

28 . 7

NEED 2 KNOW : 'AFTEREVALUATE'

afterEvaluate adds to a list of closures to be executed

at end of con�guration phase

Execution order is FIFO

Plugin author has no control over the order

28 . 8

STYLE : PROJECT EXTENSIONS

Treat project extensions as you would for any kind of globalcon�guration.

With care!

Do not make the extension con�guration block a taskcon�guration.

Task instantiation may read defaults from extension.

Do not force extension values onto tasks

28 . 9

EXTEND EXISTING TASKTask type extension by inheritance is not always bestsolution

Adding behaviour to existing task type better in certaincontexts

Example: jruby-jar-plugin wants to semanticallydescribe bootstrap �les rather than force user to usestandard Copy syntax

29 . 1

EXTEND EXISTING TASKjruby-jar-plugin without extension

jrubyJavaBootstrap { // User gets exposed (unnecessarily) to the underlying task type // Has to craft too much glue code from( { // @#$$!!-ugly code goes here } ) }

jruby-jar-plugin with extension

jrubyJavaBootstrap { // Expressing intent & context. jruby { initScript = 'bin/asciidoctor' } }

29 . 2

29 . 3

EXTEND EXISTING TASK1. Create extension class

2. Add extension to task

3. Link extension attributes to task attributes (for caching)

EXTEND EXISTING TASKCreate extension class

class MyExtension { String initScript

MyExtension( Task t ) {

// TODO: Add Gradle caching support // (See later slide) }

}

29 . 4

EXTEND EXISTING TASKAdd extension class to task

class MyPlugin implements Plugin<Project> { void apply(Project project) { Task stubTask = project.tasks.create ( name : 'jrubyJavaBootstrap', type : Copy )

stubTask.extensions.create( 'jruby', MyExtension, stubTask ) }

29 . 5

EXTEND EXISTING TASKAdd Gradle caching support

class MyExtension { String initScript

MyExtension( Task t ) {

// Tell the task the initScript is also a property t.inputs.property 'jrubyInitScript' , { -> this.initScript } } }

29 . 6

NEED 2 KNOW : TASK EXTENSIONS

Good way extend existing tasks in composable way

Attributes on extensions are not cached

Changes will not cause a rebuild of the task

Do the extra work to cache and provide the user with abetter experience.

29 . 7

ADD GENERATED JVM SOURCE SETS

May need to generate code from template and add to

current sourceset(s)

Example: Older versions of jruby-jar-plugin added

a custom class �le to JAR

Useful for separation of concerns in certain generative

programming environments

30 . 1


1. Create generator task using Copy task as transformer

2. Con�gure generator task

3. Update SourceSet

4. Add dependency between generation and compilation

30 . 2


Step1 : Add generator task

class MyPlugin implements Plugin<Project> { void apply(Project project) { Task stubTask = project.tasks.create ( name : 'myGenerator', type : Copy )

configureGenerator(stubTask) addGeneratedToSource(project) addTaskDependencies(project) }

void configureGenerator(Task t) { /* TODO: <-- See next slides */ } void addGeneratedToSource(Project p) { /* TODO: <-- See next slides */ } void addTaskDependencies(Project p) { /* TODO: <-- See next slides */ } }

This example uses Java, but can apply to any kind of sourcesetthat Gradle supports

30 . 3


Step 2 : Con�gure generator task

/* DONE: <-- See previous slide for apply() */ void configureGenerator(Task stubTask) { project.configure(stubTask) { group "Add to correct group" description 'Generates a JRuby Java bootstrap class'

from('src/template/java') { include '*.java.template' } into new File(project.buildDir,'generated/java')

rename '(.+)\\.java\\.template','$1.java' filter { String line -> /* Do something in here to transform the code */ } } }

30 . 4


Step 3 : Add generated code to SourceSet

/* DONE: <-- See earlier slide for apply() */

void addGeneratedToSource(Project project) {

project.sourceSets.matching { it.name == "main" } .all { it.java.srcDir new File(project.buildDir,'generated/java') }

}

30 . 5


Step 4 : Add task dependencies

/* DONE: <-- See earlier slide for apply() */

void addTaskDependencies(Project project) { try { Task t = project.tasks.getByName('compileJava')

if( t instanceof JavaCompile) { t.dependsOn 'myGenerator'

}

} catch(UnknownTaskException) { project.tasks.whenTaskAdded { Task t ->

if (t.name == 'compileJava' && t instanceof JavaCompile) { t.dependsOn 'myGenerator'

}

}

}

}

30 . 6

TRICK : OPERATING SYSTEM

Sometimes customised work has to be done on a speci�c

O/S

Example: jruby-gradle-plugin needs to set TMP in

environment on Windows

// This is the public interface API import org.gradle.nativeplatform.platform.OperatingSystem

// But to get an instance the internal API is needed instead import org.gradle.internal.os.OperatingSystem

println "Are we on Windows? ${OperatingSystem.current().isWindows()}

31

GET THE BOOKS

https://leanpub.com/b/idiomaticgradle

32

THANK YOUKeep your DSL extensions beautiful

Don’t spring surprising behaviour on the user

Email:


#idiomaticgradle

[email protected]

idiomatic gradle plugin writing - gradlesummit 2016

Software