What's the difference between plugin conventions vs plugin extensions?

Can someone please explain the difference between plugin conventions and plugin extensions? Its not immediately obvious to me the different reading the user guide. It would appear they could both be used to serve the same purpose – configuring your plugin.

For example, I found this link (from 2010) that goes on to explain how to configure a plugin using plugin conventions:


And the Gradle documentation does something similar using plugin extensions –


How do you decide when to use one vs the other? What are the pros and cons?



1 Like

Extensions and conventions are similar (but not identical) ways to dynamically extend the build model. Extensions are the newer concept and have largely replaced conventions. In short, only use extensions, don’t use conventions.

One of the things I wanted to do was take advantage of plugin conventions to inject new methods into my build scripts that apply the plugin as described here:


Can this same thing be done with extentions, and if so can you provide a reference or example? I don’t have success getting this to work.

An extension is an instance of an arbitrary (typically user-defined) class that’s attached to the build model under a user-defined name. The extension class can define arbitrary methods. Assuming it is attached to a ‘Project’ object, an extension allows you to add ‘project.foo.someMethod’, but not ‘project.someMethod’. Since each extension has its own namespace (‘foo’ in this case), the chance of name collisions is greatly reduced (compared to conventions).