<commit_before>// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[plugins]]
= Using Gradle Plugins

Gradle at its core intentionally provides very little for real world automation. All of the useful features, like the ability to compile Java code, are added by _plugins_. Plugins add new tasks (e.g. link:{groovyDslPath}/org.gradle.api.tasks.compile.JavaCompile.html[JavaCompile]), domain objects (e.g. link:{groovyDslPath}/org.gradle.api.tasks.SourceSet.html[SourceSet]), conventions (e.g. Java source is located at `src/main/java`) as well as extending core objects and objects from other plugins.

In this chapter we discuss how to use plugins and the terminology and concepts surrounding plugins.


[[sec:what_plugins_do]]
== What plugins do

Applying a plugin to a project allows the plugin to extend the project's capabilities. It can do things such as:

* Extend the Gradle model (e.g. add new DSL elements that can be configured)
* Configure the project according to conventions (e.g. add new tasks or configure sensible defaults)
* Apply specific configuration (e.g. add organizational repositories or enforce standards)

By applying plugins, rather than adding logic to the project build script, we can reap a number of benefits. Applying plugins:

* Promotes reuse and reduces the overhead of maintaining similar logic across multiple projects
* Allows a higher degree of modularization, enhancing comprehensibility and organization
* Encapsulates imperative logic and allows build scripts to be as declarative as possible


[[sec:types_of_plugins]]
== Types of plugins

There are two general types of plugins in Gradle, _script_ plugins and _binary_ plugins. Script plugins are additional build scripts that further configure the build and usually implement a declarative approach to manipulating the build. They are typically used within a build although they can be externalized and accessed from a remote location. Binary plugins are classes that implement the link:{javadocPath}/org/gradle/api/Plugin.html[Plugin] interface and adopt a programmatic approach to manipulating the build. Binary plugins can reside within a build script, within the project hierarchy or externally in a plugin jar.

A plugin often starts out as a script plugin (because they are easy to write) and then, as the code becomes more valuable, it's migrated to a binary plugin that can be easily tested and shared between multiple projects or organizations.

[[sec:using_plugins]]
== Using plugins

To use the build logic encapsulated in a plugin, Gradle needs to perform two steps. First, it needs to _resolve_ the plugin, and then it needs to _apply_ the plugin to the target, usually a link:{groovyDslPath}/org.gradle.api.Project.html[Project].

_Resolving_ a plugin means finding the correct version of the jar which contains a given plugin and adding it the script classpath. Once a plugin is resolved, its API can be used in a build script. Script plugins are self-resolving in that they are resolved from the specific file path or URL provided when applying them. Core binary plugins provided as part of the Gradle distribution are automatically resolved.

_Applying_ a plugin means actually executing the plugin's link:{javadocPath}/org/gradle/api/Plugin.html#apply-T-[Plugin.apply(T)] on the Project you want to enhance with the plugin. Applying plugins is _idempotent_. That is, you can safely apply any plugin multiple times without side effects.

The most common use case for using a plugin is to both resolve the plugin and apply it to the current project. Since this is such a common use case, it's recommended that build authors use the <<#sec:plugins_block,plugins DSL>> to both resolve and apply plugins in one step.

[[sec:script_plugins]]
== Script plugins


.Applying a script plugin
====
include::sample[dir="snippets/userguide/organizingGradleProjects/configureProjectUsingScript/groovy", files="build.gradle[]"]
include::sample[dir="snippets/userguide/organizingGradleProjects/configureProjectUsingScript/kotlin", files="build.gradle.kts[]"]
====

Script plugins are automatically resolved and can be applied from a script on the local filesystem or at a remote location. Filesystem locations are relative to the project directory, while remote script locations are specified with an HTTP URL. Multiple script plugins (of either form) can be applied to a given target.

[[sec:binary_plugins]]
== Binary plugins

You apply plugins by their _plugin id_, which is a globally unique identifier, or name, for plugins. Core Gradle plugins are special in that they provide short names, such as `'java'` for the core link:{javadocPath}/org/gradle/api/plugins/JavaPlugin.html[JavaPlugin]. All other binary plugins must use the fully qualified form of the plugin id (e.g. `com.github.foo.bar`), although some legacy plugins may still utilize a short, unqualified form. Where you put the plugin id depends on whether you are using the <<#sec:plugins_block,plugins DSL>> or the <<#sec:old_plugin_application,buildscript block.>>


[[sec:binary_plugin_locations]]
=== Locations of binary plugins

A plugin is simply any class that implements the link:{javadocPath}/org/gradle/api/Plugin.html[Plugin] interface. Gradle provides the core plugins (e.g. `JavaPlugin`) as part of its distribution which means they are automatically resolved. However, non-core binary plugins need to be resolved before they can be applied. This can be achieved in a number of ways:

* Including the plugin from the plugin portal or a <<#sec:custom_plugin_repositories,custom repository>> using the plugins DSL (see <<#sec:plugins_block,Applying plugins using the plugins DSL>>).
* Including the plugin from an external jar defined as a buildscript dependency (see <<#sec:applying_plugins_buildscript,Applying plugins using the buildscript block>>).
* Defining the plugin as a source file under the buildSrc directory in the project (see <<organizing_gradle_projects.adoc#sec:build_sources,Using buildSrc to extract functional logic>>).
* Defining the plugin as an inline class declaration inside a build script.

For more on defining your own plugins, see <<custom_plugins.adoc#custom_plugins,Custom Plugins>>.

[[sec:plugins_block]]
=== Applying plugins with the plugins DSL

The plugins DSL provides a succinct and convenient way to declare plugin dependencies. It works with the http://plugins.gradle.org[Gradle plugin portal] to provide easy access to both core and community plugins. The plugins DSL block configures an instance of link:{javadocPath}/org/gradle/plugin/use/PluginDependenciesSpec.html[PluginDependenciesSpec].

To apply a core plugin, the short name can be used:

.Applying a core plugin
====
include::sample[dir="snippets/plugins/dsl/groovy", files="build.gradle[tags=use-plugin]"]
include::sample[dir="snippets/plugins/dsl/kotlin", files="build.gradle.kts[tags=use-plugin]"]
====

To apply a community plugin from the portal, the fully qualified plugin id must be used:

.Applying a community plugin
====
include::sample[dir="snippets/plugins/dsl/groovy", files="build.gradle[tags=use-community-plugin]"]
include::sample[dir="snippets/plugins/dsl/kotlin", files="build.gradle.kts[tags=use-community-plugin]"]
====

See link:{javadocPath}/org/gradle/plugin/use/PluginDependenciesSpec.html[PluginDependenciesSpec] for more information on using the Plugin DSL.


[[plugins_dsl_limitations]]
==== Limitations of the plugins DSL

This way of adding plugins to a project is much more than a more convenient syntax. The plugins DSL is processed in a way which allows Gradle to determine the plugins in use very early and very quickly. This allows Gradle to do smart things such as:

* Optimize the loading and reuse of plugin classes.
* Allow different plugins to use different versions of dependencies.
* Provide editors detailed information about the potential properties and values in the buildscript for editing assistance.

This requires that plugins be specified in a way that Gradle can easily and quickly extract, before executing the rest of the build script. It also requires that the definition of plugins to use be somewhat static.

There are some key differences between the `plugins {}` block mechanism and the “traditional” `apply()` method mechanism. There are also some constraints, some of which are temporary limitations while the mechanism is still being developed and some are inherent to the new approach.


[[sec:constrained_syntax]]
===== Constrained Syntax

The `plugins {}` block does not support arbitrary code. It is constrained, in order to be idempotent (produce the same result every time) and side effect free (safe for Gradle to execute at any time).

The form is:

====
[.multi-language-sample]
=====
.build.gradle
[source,groovy]
----
plugins {
    id «plugin id»                                            // <1>
    id «plugin id» version «plugin version» [apply «false»]   // <2>
}
----
<1> for core Gradle plugins or plugins already available to the build script
<2> for binary Gradle plugins that need to be resolved
=====

[.multi-language-sample]
=====
.build.gradle.kts
[source,kotlin]
----
plugins {
    `«plugin id»`                                             // <1>
    id(«plugin id»)                                           // <2>
    id(«plugin id») version «plugin version» [apply «false»]  // <3>
}
----
<1> for core Gradle plugins
<2> for core Gradle plugins or plugins already available to the build script
<3> for binary Gradle plugins that need to be resolved
=====
====

[.multi-language-text.lang-groovy]
Where `«plugin id»` and `«plugin version»` must be constant, literal, strings and the `apply` statement with a `boolean` can be used to disable the default behavior of applying the plugin immediately (e.g. you want to apply it only in `subprojects`). No other statements are allowed; their presence will cause a compilation error.

[.multi-language-text.lang-kotlin]
Where `«plugin id»`, in case `#1` is a static Kotlin extension property, named after the core plugin ID ; and in cases `#2` and `#3` is a string.
`«plugin version»` is also a string.
The `apply` statement with a `boolean` can be used to disable the default behavior of applying the plugin immediately (e.g. you want to apply it only in `subprojects`).

See <<#sec:plugin_version_management,plugin version management>> if you want to use a variable to define a plugin version.

The `plugins {}` block must also be a top level statement in the buildscript. It cannot be nested inside another construct (e.g. an if-statement or for-loop).

If the restrictions of the `plugins {}` block are prohibitive, the recommended approach is to apply plugins using the <<#sec:applying_plugins_buildscript,buildscript {} block>>.

[[sec:subprojects_plugins_dsl]]
==== Applying plugins to subprojects

If you have a <<multi_project_builds.adoc#multi_project_builds,multi-project build>>, you probably want to apply plugins to some or all of the subprojects in your build, but not to the `root` or `master` project. The default behavior of the `plugins {}` block is to immediately `resolve` _and_  `apply` the plugins. But, you can use the `apply false` syntax to tell Gradle not to apply the plugin to the current project and then use `apply plugin: «plugin id»` in the `subprojects` block or use the `plugins {}` block in sub projects build scripts:

.Applying plugins only on certain subprojects
====
include::sample[dir="snippets/plugins/multiproject/groovy", files="settings.gradle[tags=include-subprojects];build.gradle[tags=plugins-on-subprojects];goodbyeC/build.gradle[]"]
include::sample[dir="snippets/plugins/multiproject/kotlin", files="settings.gradle.kts[tags=include-subprojects];build.gradle.kts[tags=plugins-on-subprojects];goodbyeC/build.gradle.kts[]"]
====

If you then run `gradle hello` you'll see that only the helloA and helloB subprojects had the hello plugin applied.


.Output of `gradle hello`
====
[source]
----
> gradle hello
:helloA:hello
:helloB:hello
Hello!
Hello!<commit_msg>Update plugins documentation<commit_after>// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[plugins]]
= Using Gradle Plugins

Gradle at its core intentionally provides very little for real world automation. All of the useful features, like the ability to compile Java code, are added by _plugins_. Plugins add new tasks (e.g. link:{groovyDslPath}/org.gradle.api.tasks.compile.JavaCompile.html[JavaCompile]), domain objects (e.g. link:{groovyDslPath}/org.gradle.api.tasks.SourceSet.html[SourceSet]), conventions (e.g. Java source is located at `src/main/java`) as well as extending core objects and objects from other plugins.

In this chapter we discuss how to use plugins and the terminology and concepts surrounding plugins.


[[sec:what_plugins_do]]
== What plugins do

Applying a plugin to a project allows the plugin to extend the project's capabilities. It can do things such as:

* Extend the Gradle model (e.g. add new DSL elements that can be configured)
* Configure the project according to conventions (e.g. add new tasks or configure sensible defaults)
* Apply specific configuration (e.g. add organizational repositories or enforce standards)

By applying plugins, rather than adding logic to the project build script, we can reap a number of benefits. Applying plugins:

* Promotes reuse and reduces the overhead of maintaining similar logic across multiple projects
* Allows a higher degree of modularization, enhancing comprehensibility and organization
* Encapsulates imperative logic and allows build scripts to be as declarative as possible


[[sec:types_of_plugins]]
== Types of plugins

There are two general types of plugins in Gradle, _script_ plugins and _binary_ plugins. Script plugins are additional build scripts that further configure the build and usually implement a declarative approach to manipulating the build. They are typically used within a build although they can be externalized and accessed from a remote location. Binary plugins are classes that implement the link:{javadocPath}/org/gradle/api/Plugin.html[Plugin] interface and adopt a programmatic approach to manipulating the build. Binary plugins can reside within a build script, within the project hierarchy or externally in a plugin jar.

A plugin often starts out as a script plugin (because they are easy to write) and then, as the code becomes more valuable, it's migrated to a binary plugin that can be easily tested and shared between multiple projects or organizations.

[[sec:using_plugins]]
== Using plugins

To use the build logic encapsulated in a plugin, Gradle needs to perform two steps. First, it needs to _resolve_ the plugin, and then it needs to _apply_ the plugin to the target, usually a link:{groovyDslPath}/org.gradle.api.Project.html[Project].

_Resolving_ a plugin means finding the correct version of the jar which contains a given plugin and adding it the script classpath. Once a plugin is resolved, its API can be used in a build script. Script plugins are self-resolving in that they are resolved from the specific file path or URL provided when applying them. Core binary plugins provided as part of the Gradle distribution are automatically resolved.

_Applying_ a plugin means actually executing the plugin's link:{javadocPath}/org/gradle/api/Plugin.html#apply-T-[Plugin.apply(T)] on the Project you want to enhance with the plugin. Applying plugins is _idempotent_. That is, you can safely apply any plugin multiple times without side effects.

The most common use case for using a plugin is to both resolve the plugin and apply it to the current project. Since this is such a common use case, it's recommended that build authors use the <<#sec:plugins_block,plugins DSL>> to both resolve and apply plugins in one step.

[[sec:script_plugins]]
== Script plugins


.Applying a script plugin
====
include::sample[dir="snippets/userguide/organizingGradleProjects/configureProjectUsingScript/groovy", files="build.gradle[]"]
include::sample[dir="snippets/userguide/organizingGradleProjects/configureProjectUsingScript/kotlin", files="build.gradle.kts[]"]
====

Script plugins are automatically resolved and can be applied from a script on the local filesystem or at a remote location. Filesystem locations are relative to the project directory, while remote script locations are specified with an HTTP URL. Multiple script plugins (of either form) can be applied to a given target.

[[sec:binary_plugins]]
== Binary plugins

You apply plugins by their _plugin id_, which is a globally unique identifier, or name, for plugins. Core Gradle plugins are special in that they provide short names, such as `'java'` for the core link:{javadocPath}/org/gradle/api/plugins/JavaPlugin.html[JavaPlugin]. All other binary plugins must use the fully qualified form of the plugin id (e.g. `com.github.foo.bar`), although some legacy plugins may still utilize a short, unqualified form. Where you put the plugin id depends on whether you are using the <<#sec:plugins_block,plugins DSL>> or the <<#sec:old_plugin_application,buildscript block.>>


[[sec:binary_plugin_locations]]
=== Locations of binary plugins

A plugin is simply any class that implements the link:{javadocPath}/org/gradle/api/Plugin.html[Plugin] interface. Gradle provides the core plugins (e.g. `JavaPlugin`) as part of its distribution which means they are automatically resolved. However, non-core binary plugins need to be resolved before they can be applied. This can be achieved in a number of ways:

* Including the plugin from the plugin portal or a <<#sec:custom_plugin_repositories,custom repository>> using the plugins DSL (see <<#sec:plugins_block,Applying plugins using the plugins DSL>>).
* Including the plugin from an external jar defined as a buildscript dependency (see <<#sec:applying_plugins_buildscript,Applying plugins using the buildscript block>>).
* Defining the plugin as a source file under the buildSrc directory in the project (see <<organizing_gradle_projects.adoc#sec:build_sources,Using buildSrc to extract functional logic>>).
* Defining the plugin as an inline class declaration inside a build script.

For more on defining your own plugins, see <<custom_plugins.adoc#custom_plugins,Custom Plugins>>.

[[sec:plugins_block]]
=== Applying plugins with the plugins DSL

The plugins DSL provides a succinct and convenient way to declare plugin dependencies. It works with the http://plugins.gradle.org[Gradle plugin portal] to provide easy access to both core and community plugins. The plugins DSL block configures an instance of link:{javadocPath}/org/gradle/plugin/use/PluginDependenciesSpec.html[PluginDependenciesSpec].

To apply a core plugin, the short name can be used:

.Applying a core plugin
====
include::sample[dir="snippets/plugins/dsl/groovy", files="build.gradle[tags=use-plugin]"]
include::sample[dir="snippets/plugins/dsl/kotlin", files="build.gradle.kts[tags=use-plugin]"]
====

To apply a community plugin from the portal, the fully qualified plugin id must be used:

.Applying a community plugin
====
include::sample[dir="snippets/plugins/dsl/groovy", files="build.gradle[tags=use-community-plugin]"]
include::sample[dir="snippets/plugins/dsl/kotlin", files="build.gradle.kts[tags=use-community-plugin]"]
====

See link:{javadocPath}/org/gradle/plugin/use/PluginDependenciesSpec.html[PluginDependenciesSpec] for more information on using the Plugin DSL.


[[plugins_dsl_limitations]]
==== Limitations of the plugins DSL

This way of adding plugins to a project is much more than a more convenient syntax. The plugins DSL is processed in a way which allows Gradle to determine the plugins in use very early and very quickly. This allows Gradle to do smart things such as:

* Optimize the loading and reuse of plugin classes.
* Allow different plugins to use different versions of dependencies.
* Provide editors detailed information about the potential properties and values in the buildscript for editing assistance.

This requires that plugins be specified in a way that Gradle can easily and quickly extract, before executing the rest of the build script. It also requires that the definition of plugins to use be somewhat static.

There are some key differences between the `plugins {}` block mechanism and the “traditional” `apply()` method mechanism. There are also some constraints, some of which are temporary limitations while the mechanism is still being developed and some are inherent to the new approach.


[[sec:constrained_syntax]]
===== Constrained Syntax

The `plugins {}` block does not support arbitrary code. It is constrained, in order to be idempotent (produce the same result every time) and side effect free (safe for Gradle to execute at any time).

The form is:

====
[.multi-language-sample]
=====
.build.gradle
[source,groovy]
----
plugins {
    id «plugin id»                                            // <1>
    id «plugin id» version «plugin version» [apply «false»]   // <2>
}
----
<1> for core Gradle plugins or plugins already available to the build script
<2> for binary Gradle plugins that need to be resolved
=====

[.multi-language-sample]
=====
.build.gradle.kts
[source,kotlin]
----
plugins {
    `«plugin id»`                                             // <1>
    id(«plugin id»)                                           // <2>
    id(«plugin id») version «plugin version» [apply «false»]  // <3>
}
----
<1> for core Gradle plugins
<2> for core Gradle plugins or plugins already available to the build script
<3> for binary Gradle plugins that need to be resolved
=====
====

[.multi-language-text.lang-groovy]
Where `«plugin id»` and `«plugin version»` must be constant, literal, strings and the `apply` statement with a `boolean` can be used to disable the default behavior of applying the plugin immediately (e.g. you want to apply it only in `subprojects`). No other statements are allowed; their presence will cause a compilation error.

[.multi-language-text.lang-kotlin]
Where `«plugin id»`, in case `#1` is a static Kotlin extension property, named after the core plugin ID ; and in cases `#2` and `#3` is a string.
`«plugin version»` is also a string.
The `apply` statement with a `boolean` can be used to disable the default behavior of applying the plugin immediately (e.g. you want to apply it only in `subprojects`).

See <<#sec:plugin_version_management,plugin version management>> if you want to use a variable to define a plugin version.

The `plugins {}` block must also be a top level statement in the buildscript. It cannot be nested inside another construct (e.g. an if-statement or for-loop).

[[sec:build_scripts_only]]
===== Can only be used in build scripts and settings file

The `plugins {}` block can currently only be used in a project's build script and the settings.gradle file. It cannot be used in script plugins or init scripts.

_Future versions of Gradle will remove this restriction._

If the restrictions of the `plugins {}` block are prohibitive, the recommended approach is to apply plugins using the <<#sec:applying_plugins_buildscript,buildscript {} block>>.

[[sec:subprojects_plugins_dsl]]
==== Applying plugins to subprojects

If you have a <<multi_project_builds.adoc#multi_project_builds,multi-project build>>, you probably want to apply plugins to some or all of the subprojects in your build, but not to the `root` or `master` project. The default behavior of the `plugins {}` block is to immediately `resolve` _and_  `apply` the plugins. But, you can use the `apply false` syntax to tell Gradle not to apply the plugin to the current project and then use `apply plugin: «plugin id»` in the `subprojects` block or use the `plugins {}` block in sub projects build scripts:

.Applying plugins only on certain subprojects
====
include::sample[dir="snippets/plugins/multiproject/groovy", files="settings.gradle[tags=include-subprojects];build.gradle[tags=plugins-on-subprojects];goodbyeC/build.gradle[]"]
include::sample[dir="snippets/plugins/multiproject/kotlin", files="settings.gradle.kts[tags=include-subprojects];build.gradle.kts[tags=plugins-on-subprojects];goodbyeC/build.gradle.kts[]"]
====

If you then run `gradle hello` you'll see that only the helloA and helloB subprojects had the hello plugin applied.


.Output of `gradle hello`
====
[source]
----
> gradle hello
:helloA:hello
:helloB:hello
Hello!
Hello!
{'fraction_non_alphanumeric': 0.07940807034071283, 'fraction_numerical': 0.0016486104569006124, 'mean_word_length': 4.732898289828983, 'pattern_counts': {'":': 0, '<': 67, '<?xml version=': 0, '>': 69, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7150682', 'n_tokens_mistral': 6625, 'n_tokens_neox': 6313, 'n_words': 3294}