Designing and Wri,ng Gradle Plugins Benjamin Muschko 

writing plugins is easy they said… me a couple of years ago 

Designing… 1 

Binary plugins FTW! 

Prefer statically-typed language + @CompileStatic 

Only use public API if possible build.gradle dependencies {
 compile gradleApi()
 }
 Be cau'ous - dependency pulls in full Gradle run'me API 

Minimize external dependencies 

identifying external plugin dependencies build.gradle plugins {
 id "com.github.gradle-guides.site" version "0.1"
 } ./gradlew buildEnvironment > Task :buildEnvironment ------------------------------------------------------------ Root project ------------------------------------------------------------ classpath \--- gradle.plugin.com.github.gradle-guides:gradle-site-plugin:0.1 \--- org.freemarker:freemarker:2.3.26-incubating 

impact on performance 

learn performance tips & tricks Op'mizing Gradle Build Performance h2ps:/ /guides.gradle.org/performance/ 

scan your build Iden'fy and share performance hotspots h2ps:/ /gradle.com/scans/get-started 

dig deep with the Gradle profiler Profiling and benchmarking info h2ps:/ /github.com/gradle/gradle-profiler 

Convention over configuration 

Conventions Out-of-the-box SitePlugin.java public class SitePlugin implements Plugin {
 public void apply(Project project) {
 SitePluginExtension sitePluginExtension = ↵ project.getExtensions().create("site", ↵ SitePluginExtension.class, project); 
 sitePluginExtension.setOutputDir(new ↵ File(project.getBuildDir(), "docs/site"));
 
 ...
 }
 } sets default value 

reconfiguring conventional values build.gradle apply plugin: 'com.github.gradle-guides.site'
 
 site {
 outputDir = file("$buildDir/site")
 websiteUrl = 'http://gradle.org'
 vcsUrl = 'https://github.com/gradle-guides/↵ gradle-site-plugin'
 } User declares the “what” not the “how” overrides defaults 

CAPABIlities vs. conventions 

Common pattern in plugin architecture Java Base Plugin Java Plugin Capabilities Conventions applies 

CAPAbilities vs. conventions public class BaseSitePlugin extends Plugin {
 public void apply(Project project) {
 // define capabilities
 }
 } public class SitePlugin extends Plugin {
 public void apply(Project project) {
 project.getPlugins().apply(BaseSitePlugin.class);
 
 // define conventions
 }
 } SitePlugin.java BaseSitePlugin.java applies plugin 

implementing… 2 

Use the Plugin Development plugin build.gradle dependencies {
 compile 'java-gradle-plugin'
 }
 Reduces boilerplate code significantly 

Prefer writing custom tasks types 

reusing custom tasks import org.gradle.plugins.site.tasks.SiteGenerate task generateDefaultSite(type: SiteGenerate)
 
 task generateSiteWithCustomValues(type: SiteGenerate) {
 outputDir = file("$buildDir/myAwesomeSite")
 
 customData {
 websiteUrl = 'http://gradle.org'
 vcsUrl = 'https://github.com/gradle-guides/↵ gradle-site-plugin'
 }
 } build.gradle Impera've logic is hidden in implementa'on 

modeling DSL-like APIs task generateSiteWithCustomValues(type: SiteGenerate) {
 customData {
 websiteUrl = 'http://gradle.org'
 vcsUrl = 'https://github.com/gradle-guides/↵ gradle-site-plugin'
 }
 } build.gradle site {
 customData {
 websiteUrl = 'http://gradle.org'
 vcsUrl = 'https://github.com/gradle-guides/↵ gradle-site-plugin'
 }
 } or 

avoid closures in Apis SiteGenerate.gradle public class SiteGenerate extends DefaultTask {
 private final CustomData customData = new CustomData();
 
 public void customData(Closure closure) {
 closure.setResolveStrategy(Closure.DELEGATE_FIRST);
 closure.setDelegate(customData);
 closure.call();
 }
 } avoid Harder to use from Java and Kotlin 

generation of closure method SiteGenerate.gradle task generateSiteWithCustomValues(type: SiteGenerate) {
 customData {
 ... }
 } public class SiteGenerate extends DefaultTask {
 private final CustomData customData = new CustomData();
 
 public void customData(Action action) {
 action.execute(customData);
 }
 } build.gradle do this 

Enable tasks to be incremental 

Declare inputs & outputs public class SiteGenerate extends DefaultTask {
 private final PropertyState outputDir;
 private final CustomData customData;
 
 ...
 @Nested
 public CustomData getCustomData() {
 return customData;
 }
 
 @OutputDirectory
 public File getOutputDir() {
 return outputDir.get();
 }
 } SiteGenerate.java use annotations 

Lazy evaluation of properties 

typical use case SiteGenerate.java SitePluginExtension.java build.gradle Capture user-provided input Hold user-provided values Lazily evaluate and apply user-provided values Capture values during configura'on phase Evaluate and use value during execu'on 'me 

Evaluate property at execution time public class SiteGenerate extends DefaultTask {
 private final PropertyState outputDir;
 
 public SiteGenerate() {
 this.outputDir = getProject().property(File.class);
 }
 
 @OutputDirectory
 public File getOutputDir() {
 return outputDir.get();
 }
 
 @TaskAction
 public void generate() {
 getOutputDir();
 }
 } SiteGenerate.java lazily evaluate value 

avoid applying plugins if possible project.getPlugins().apply(JavaPlugin.class);
 JavaPluginConvention javaConvention = project.getConvention()↵ .getPlugin(JavaPluginConvention.class);
 projectDescriptor.setJavaProject(new JavaProjectDescriptor(↵ javaConvention.getSourceCompatibility().toString(),↵ javaConvention.getTargetCompatibility().toString()) SitePlugin.java Imposes poten'ally unnecessary conven'ons avoid 

React to applied plugins project.getPlugins().withType(JavaPlugin.class, new Action() {
 @Override
 public void execute(JavaPlugin javaPlugin) {
 JavaPluginConvention javaConvention = project.getConvention()↵ .getPlugin(JavaPluginConvention.class);
 projectDescriptor.setJavaProject(↵ new JavaProjectDescriptor(↵ javaConvention.getSourceCompatibility().toString(),↵ javaConvention.getTargetCompatibility().toString()));
 }
 }); SitePlugin.java do this 

Assign appropriate plugin identifiers . !"" src !"" main !"" resources !"" META-INF !"" gradle-plugins #"" com.github.gradle-guides.base-site.properties !"" com.github.gradle-guides.site.properties 
 Add domain to ensure uniqueness src/main/resources/META-INF/gradle-plugins 

What could be next? 

top 10 internal apis on github Class Name Count org.gradle.internal.reflect.Instantiator 1103 org.gradle.api.internal.file.FileResolver 868 org.gradle.util.GradleVersion 680 org.gradle.internal.os.OperatingSystem 680 org.gradle.util.ConfigureUtil 608 org.gradle.internal.service.ServiceRegistry 546 org.gradle.util.GFileUtils 329 org.gradle.util.TestUtil 258 org.gradle.api.internal.ConventionTask 195 org.gradle.api.internal.project.IsolatedAntBuilder 114 Poten'al candidates for public APIs 

public apis with bigger impact ➞ Separa'on between internal & public API ➞ Declaring custom repository types ➞ BeQer support for wri'ng language plugins ➞ Improved TestKit fixtures ➞ Publishing custom ar'facts 

better documentation, more guides ➞ Improved user guide documenta'on ➞ More sample projects ➞ Guides on tes'ng & documen'ng plugins ➞ Tutorial for wri'ng a plugin by example 

improvements to Plugin Ecosystem ➞ Feature-rich plugin portal ➞ Cross-version compa'bility tes'ng ➞ Development support by plugin dev plugin ➞ BeQer IDE support 

We want your feedback! 

Resources Designing Gradle plugins h2ps:/ /guides.gradle.org/designing-gradle-plugins/ Implemen'ng Gradle plugins h2ps:/ /guides.gradle.org/implemen,ng-gradle-plugins/ Gradle Site Plugin h2ps:/ /github.com/gradle-guides/gradle-site-plugin/ 

w Thank you Gradle Summit 2017