Gradle Plugin Concepts: Difference between revisions
(38 intermediate revisions by the same user not shown) | |||
Line 9: | Line 9: | ||
=Overview= | =Overview= | ||
A Gradle plugin is packaged code that uses the Gradle API to provide additional functionality and extend Gradle core. A Gradle plugin applies some configuration to a target object, usually a [[Gradle_Project| | A Gradle plugin is packaged code that uses the Gradle API to provide additional functionality and extend Gradle core. A Gradle plugin applies some configuration to a target object, usually a [[Gradle_Project|project]]. The plugin may introduce new concepts, capabilities, [[Gradle_Task#Overview|tasks]], new domain objects, conventions, project layouts and patterns for a specific problem domain. Plugins may even extend the core objects. Introducing their own conventions, plugins are "opinionated", in that they encourage the user to do things in a certain way. However, well written plugins must provide means to change the default conventions and make it work for non-standard projects. | ||
=Plugin API= | =Plugin API= | ||
{{External|[https://docs.gradle.org/current/javadoc/org/gradle/api/Plugin.html org.gradle.api.Plugin<T>]}} | {{External|[https://docs.gradle.org/current/javadoc/org/gradle/api/Plugin.html org.gradle.api.Plugin<T>]}} | ||
Line 15: | Line 16: | ||
=Script Plugin= | =Script Plugin= | ||
{{External|https://docs.gradle.org/current/userguide/plugins.html#sec:script_plugins}} | {{External|https://docs.gradle.org/current/userguide/plugins.html#sec:script_plugins}} | ||
A script plugin is simply a file containing Gradle DSL code and possibly in-line Java and Groovy code. It can be thought as just another build script | A script plugin is simply a file containing Gradle DSL code and possibly in-line Java and Groovy code. The syntax is no different than [[build.gradle]] syntax. It can be thought as just another modular build script to be imported into a build script. | ||
<syntaxhighlight lang='groovy'> | <syntaxhighlight lang='groovy'> | ||
apply from: 'example.gradle' | apply from: 'example.gradle' | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Conventionally, the file has the ".gradle" extension, but this is not mandatory. The file can be loaded from the local filesystem, or from a remote location. Filesystem location is relative to the [[ | Conventionally, the file has the ".gradle" extension, but this is not mandatory. The file can be loaded from the local filesystem, or from a remote location. Filesystem location is relative to the [[Gradle_Project_Coordinates,_State_and_Configured_Properties#Project_Directory|project directory]]. Remote locations are specified with HTTP URLs. | ||
Script plugins can declare complex Java or Groovy code, including enhanced task definitions. If such code relies on external libraries, the dependency on those libraries can be declared as such: | |||
<syntaxhighlight lang='groovy'> | |||
buildscript { | |||
repositories { | |||
mavenCentral() | |||
} | |||
dependencies { | |||
classpath 'com.dependency:my-dep:1.0.0' | |||
} | |||
} | |||
</syntaxhighlight> | |||
=Binary Plugin= | =Binary Plugin= | ||
Line 25: | Line 38: | ||
=Using a Plugin= | =Using a Plugin= | ||
Plugins can be applied in two ways | Plugins can be applied in two ways, via the [[#apply.28.29_Method|apply]] method or via the [[Gradle_Plugin_Concepts#plugins_Script_Block|plugins script block]]. | ||
==apply() | ==apply() Method== | ||
apply() is a method of the [ | apply() is a method of the [[Gradle PluginAware|PluginAware]] interface that is inherited by [[Gradle Project|Project]], [[Gradle Settings|Settings]] and [[org.gradle.api.invocation.Gradle|Gradle]]. <code>apply</code> DSL keyword is available in [[Gradle_Project#Using_a_Plugin|build.gradle]]. | ||
<syntaxhighlight lang='groovy'> | <syntaxhighlight lang='groovy'> | ||
apply plugin: 'java' | apply plugin: 'java' | ||
</syntaxhighlight> | </syntaxhighlight> | ||
==plugins script block | ==plugins Script Block== | ||
The 'plugins' script block is exposed by [https://docs.gradle.org/current/javadoc/org/gradle/plugin/use/PluginDependenciesSpec.html org.gradle.plugin.use.PluginDependenciesSpec], which is the specialized DSL to declare plugins to use in a script. | |||
<syntaxhighlight lang='groovy'> | <syntaxhighlight lang='groovy'> | ||
plugins { | plugins { | ||
id 'java' | |||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Core Gradle plugin can be declared using their ID. | |||
=Plugin Extension= | =Plugin Extension= | ||
Line 42: | Line 58: | ||
A plugin is a typical use case for an [[Gradle Concepts#Extension|extension]]. | A plugin is a typical use case for an [[Gradle Concepts#Extension|extension]]. | ||
= | =<span id='Standard_Plugins'></span>Core Plugins= | ||
A | {{External|https://docs.gradle.org/current/userguide/plugin_reference.html}} | ||
A core plugin ships with the Gradle runtime. It is also referred to as a "standard" plugin, and it uses the org.gradle namespace. The core plugin exposes a series of [[Gradle_Task#Predefined_Task_Types|predefined task types]]. Gradle ships with the following core plugins: | |||
==Plugin Libraries | ===Base=== | ||
{{Internal|Gradle Base Plugin|Base Plugin}} | |||
===Java=== | |||
{{Internal|Gradle Java Plugin|Java Plugin}} | |||
===Java Library=== | |||
{{Internal|Gradle Java Library Plugin|Java Library Plugin}} | |||
===Java Platform=== | |||
{{Internal|Gradle Java Platform Plugin|Java Platform Plugin}} | |||
===Groovy=== | |||
{{Internal|Gradle Groovy Plugin|Groovy Plugin}} | |||
=Plugin Libraries= | |||
=External Plugins= | =External Plugins= | ||
* [[Gradle_Maven_Publish_Plugin#Overview|Maven Publish]] | |||
* [[com.palantir.docker]] | |||
* [[com.palantir.git-version]] | |||
* [[Gradle Shadow Fat/Uber Jar Plugin#Overview|Shadow Fat/Uber Jar]] | |||
=Writing Custom Plugins= | =Writing Custom Plugins= | ||
{{Internal|Extending_Gradle#Custom_Binary_Plugin|Custom Binary Plugins}} | {{Internal|Extending_Gradle#Custom_Binary_Plugin|Custom Binary Plugins}} | ||
=Plugin Operations= | |||
==Listing Tasks introduced by a Certain Plugin== | |||
There is no know command line support for this operation. It can be coded as such: | |||
<syntaxhighlight lang='groovy'> | |||
def tasksBefore = [], tasksAfter = [] | |||
project.tasks.each { tasksBefore.add(it.name) } | |||
// apply plugin | |||
apply(plugin: 'java') // apply plugin | |||
project.tasks.each { tasksAfter.add(it.name) } | |||
tasksAfter.removeAll(tasksBefore); | |||
println 'tasks introduced by plugin' + tasksAfter; | |||
</syntaxhighlight> | |||
Also see: {{Internal|Gradle_Task#Tasks_and_Plugins|Gradle Task | Tasks and Plugins}} |
Latest revision as of 06:44, 28 March 2021
External
- https://docs.gradle.org/current/userguide/plugins.html
- Gradle Plugin Portal https://plugins.gradle.org/
Internal
TODO
Overview
A Gradle plugin is packaged code that uses the Gradle API to provide additional functionality and extend Gradle core. A Gradle plugin applies some configuration to a target object, usually a project. The plugin may introduce new concepts, capabilities, tasks, new domain objects, conventions, project layouts and patterns for a specific problem domain. Plugins may even extend the core objects. Introducing their own conventions, plugins are "opinionated", in that they encourage the user to do things in a certain way. However, well written plugins must provide means to change the default conventions and make it work for non-standard projects.
Plugin API
Script Plugin
A script plugin is simply a file containing Gradle DSL code and possibly in-line Java and Groovy code. The syntax is no different than build.gradle syntax. It can be thought as just another modular build script to be imported into a build script.
apply from: 'example.gradle'
Conventionally, the file has the ".gradle" extension, but this is not mandatory. The file can be loaded from the local filesystem, or from a remote location. Filesystem location is relative to the project directory. Remote locations are specified with HTTP URLs.
Script plugins can declare complex Java or Groovy code, including enhanced task definitions. If such code relies on external libraries, the dependency on those libraries can be declared as such:
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.dependency:my-dep:1.0.0'
}
}
Binary Plugin
A binary plugin is a class implementing org.gradle.api.Plugin and ancillary classes.
Using a Plugin
Plugins can be applied in two ways, via the apply method or via the plugins script block.
apply() Method
apply() is a method of the PluginAware interface that is inherited by Project, Settings and Gradle. apply
DSL keyword is available in build.gradle.
apply plugin: 'java'
plugins Script Block
The 'plugins' script block is exposed by org.gradle.plugin.use.PluginDependenciesSpec, which is the specialized DSL to declare plugins to use in a script.
plugins {
id 'java'
}
Core Gradle plugin can be declared using their ID.
Plugin Extension
A plugin is a typical use case for an extension.
Core Plugins
A core plugin ships with the Gradle runtime. It is also referred to as a "standard" plugin, and it uses the org.gradle namespace. The core plugin exposes a series of predefined task types. Gradle ships with the following core plugins:
Base
Java
Java Library
Java Platform
Groovy
Plugin Libraries
External Plugins
Writing Custom Plugins
Plugin Operations
Listing Tasks introduced by a Certain Plugin
There is no know command line support for this operation. It can be coded as such:
def tasksBefore = [], tasksAfter = []
project.tasks.each { tasksBefore.add(it.name) }
// apply plugin
apply(plugin: 'java') // apply plugin
project.tasks.each { tasksAfter.add(it.name) }
tasksAfter.removeAll(tasksBefore);
println 'tasks introduced by plugin' + tasksAfter;
Also see: