// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.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.

[[plugin_basics]]
= Plugin Basics

Gradle is built on a flexible plugin system.

Out of the box, Gradle provides core infrastructure like dependency resolution, task orchestration, and incremental builds.
Most functionality — like compiling Java, building Android apps, or publishing artifacts — comes from *plugins*.

image::gradle-basic-6.png[]

A plugin is a reusable piece of software that *provides additional functionality to the Gradle build system*.
It can:

* Add new tasks to your build (like `compileJava` or `test`)
* Add new configurations (like `implementation` or `runtimeOnly`)
* Contribute DSL elements (like `application {}` or `publishing {}`)

Plugins are applied to build scripts using the `plugins` block (Kotlin DSL or Groovy DSL), and they bring in all the logic needed for a specific domain or workflow.

== Common plugins

Here are some popular plugins and what they do:

**Java Library Plugin** (`java-library`)::
Compiles Java source code, generates Javadoc, and packages classes into a JAR. Adds tasks like `compileJava`, `javadoc`, and `jar`.

**Google Services Plugin** (`com.google.gms.google-services`)::
Configures Firebase and Google APIs in Android builds. Adds DSL like `googleServices {}` and tasks like `generateReleaseAssets`.

**Gradle Bintray Plugin** (`com.jfrog.bintray`)::
Publishes artifacts to Bintray (or other Maven-style repositories) using a `bintray {}` configuration block.

[[applying_plugins]]
== Applying plugins

*Applying* a plugin to a project allows the plugin to extend the project's capabilities.

You apply plugins in the build script using a *plugin id* (a globally unique identifier / name) and a version:

[source,text]
----
plugins {
    id("«plugin id»").version("«plugin version»")
}
----

For example:

[source,kotlin]
----
plugins {
    id("java-library")
    id("com.diffplug.spotless").version("6.25.0")
}
----

This tells Gradle to:

* Apply the built-in `java-library` plugin, which adds tasks for compiling Java, running tests, and packaging libraries.
* Apply the community-maintained `spotless` plugin (version `6.25.0`), which adds code formatting tasks and integrates tools like `ktlint`, `prettier`, and `google-java-format`.

== Plugin types

Gradle supports three types of plugins:

1. **Script plugins** – Reusable `.gradle` or `.gradle.kts` files that are applied using `apply from:`.
2. **Pre-compiled plugins** – Packaged Kotlin or Groovy code applied with the `plugins {}` block.
3. **Binary plugins** – Packaged and published plugins (often from the Plugin Portal or Maven) that are applied with the `plugins {}` block.

Most modern builds prefer **binary** or **precompiled** plugins.

== Plugin distribution

Gradle plugins come from different sources, and you can choose the right type depending on your use case.

=== 1. Core Plugins (built into Gradle)

Gradle Core plugins are a set of plugins that are included in the Gradle distribution itself.
These plugins provide essential functionality for building and managing projects.

Core plugins are unique in that they provide short names, such as `java-library` for the core link:{javadocPath}/org/gradle/api/plugins/JavaLibraryPlugin.html[JavaLibraryPlugin].
You can apply them by ID with no extra setup:

[source,kotlin]
----
plugins {
    id("java-library")
}
----

These plugins are maintained by the Gradle team.
See the <<plugin_reference#plugin_reference,Core Plugin Reference>> for a full list.

=== 2. Community Plugins (from the Plugin Portal)

Community plugins are plugins developed by the Gradle community, rather than being part of the core Gradle distribution.
These plugins provide additional functionality that may be specific to certain use cases or technologies.

Gradle’s plugin ecosystem includes thousands of open-source plugins shared by the community.
These are published to the link:https://plugins.gradle.org/[Gradle Plugin Portal] and can be applied by ID and version:

[source,kotlin]
----
plugins {
    id("org.springframework.boot").version("3.1.5")
}
----

Gradle will automatically download the plugin when the build runs.

=== 3. Local or Custom Plugins (defined in your build)

You can also write your own plugins — either for use in a single project or shared across multiple projects in the same build.

The most common type of custom plugin is a **convention plugin**, which lives in either a `buildSrc/` directory or a standalone `build-logic` module. These plugins are written in Kotlin or Groovy and follow the same structure as published plugins.

Convention plugins are applied using the `plugins {}` block, just like external plugins:

[source,kotlin]
----
plugins {
    id("my.custom-conventions")
}
----

To learn how to create your own plugin, see the <<custom_plugins.adoc#custom_plugins,Plugin development chapter>>.

[.text-right]
**Next Step:** <<gradle_optimizations.adoc#gradle_optimizations,Learn about Incremental Builds and Build Caching>> >>
