// Copyright 2018 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.

[[base_plugin]]
= The Base Plugin

The Base Plugin provides some tasks and conventions that are common to most builds and adds a structure to the build that promotes consistency in how they are run. Its most significant contribution is a set of <<more_about_tasks.adoc#sec:lifecycle_tasks,_lifecycle_ tasks>> that act as an umbrella for the more specific tasks provided by other plugins and build authors.

[[sec:base_plugin_usage]]
== Usage


.Applying the Base Plugin
====
include::sample[dir="snippets/base/basePlugin/groovy",files="build.gradle[tags=apply-base-plugin]"]
include::sample[dir="snippets/base/basePlugin/kotlin",files="build.gradle.kts[tags=apply-base-plugin]"]
====

[[sec:base_tasks]]
== Task

`clean` — `Delete`::
Deletes the build directory and everything in it, i.e. the path specified by the link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:buildDir[Project.getBuildDir()] project property.

`check` — _lifecycle task_::
Plugins and build authors should attach their verification tasks, such as ones that run tests, to this lifecycle task using `check.dependsOn(__task__)`.

`assemble` — _lifecycle task_::
Plugins and build authors should attach tasks that produce distributions and other consumable artifacts to this lifecycle task. For example, `jar` produces the consumable artifact for Java libraries. Attach tasks to this lifecycle task using `assemble.dependsOn(__task__)`.

`build` — _lifecycle task_::
_Depends on_: `check`, `assemble`
+
Intended to build everything, including running all tests, producing the production artifacts and generating documentation. You will probably rarely attach concrete tasks directly to `build` as `assemble` and `check` are typically more appropriate.

`build__Configuration__` — task rule::
Assembles those artifacts attached to the named configuration. For example, `buildArchives` will execute any task that is required to create any artifact attached to the `archives` configuration.

`clean__Task__` — task rule::
Removes the <<more_about_tasks.adoc#sec:task_inputs_outputs,defined outputs>> of a task, e.g. `cleanJar` will delete the JAR file produced by the `jar` task of the Java Plugin.


[[sec:base_plugin_configurations]]
== Dependency management

The Base Plugin adds no <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,configurations for dependencies>>, but it does add the following configurations:

`default`::
A fallback configuration used by consumer projects. Let's say you have project B with a <<declaring_dependencies.adoc#sub:project_dependencies,project dependency>> on project A. Gradle uses some internal logic to determine which of project A's artifacts and dependencies are added to the specified configuration of project B. If no other factors apply — you don't need to worry what these are — then Gradle falls back to using everything in project A's `default` configuration.
+
*New builds and plugins should not be using the `default` configuration!* It remains for the reason of backwards compatibility.

`archives`::
A standard configuration for the production artifacts of a project.

Note that the `assemble` task generates all artifacts that are attached to the `archives` configuration.

[[sec:base_plugin_extension]]
== Contributed extensions

The Base Plugin adds the link:{groovyDslPath}/org.gradle.api.plugins.BasePluginExtension.html[`base` extension] to the project.
This allows to configure the following properties inside a dedicated DSL block.

.Using the `base` extension
====
include::sample[dir="snippets/files/archivesChangedBaseName/groovy",files="build.gradle[tags=base-plugin-config]"]
include::sample[dir="snippets/files/archivesChangedBaseName/kotlin",files="build.gradle.kts[tags=base-plugin-config]"]
====

`archivesName` — default: `$project.name`::
Provides the default link:{groovyDslPath}/org.gradle.api.tasks.bundling.AbstractArchiveTask.html#org.gradle.api.tasks.bundling.AbstractArchiveTask:archiveBaseName[AbstractArchiveTask.getArchiveBaseName()] for archive tasks.

`distsDirectory` — default: `$buildDir/distributions`::
Default name of the directory in which distribution archives, i.e. non-JARs, are created.

`libsDirectory` — default: `$buildDir/libs`::
Default name of the directory in which library archives, i.e. JARs, are created.

The plugin also provides default values for the following properties on any task that extends link:{groovyDslPath}/org.gradle.api.tasks.bundling.AbstractArchiveTask.html[AbstractArchiveTask]:

`destinationDirectory`::
Defaults to `distsDirectory` for non-JAR archives and `libsDirectory` for JARs and derivatives of JAR, such as WARs.

`archiveVersion`::
Defaults to `$project.version` or 'unspecified' if the project has no version.

`archiveBaseName`::
Defaults to `$archivesBaseName`.

[[sec:base_plugin_conventions]]
== Conventions (deprecated)

The Base Plugin also adds conventions related to the creation of archives, such as ZIPs, TARs and JARs.
These are *deprecated* and superseded by the extension described above.
See the link:{groovyDslPath}/org.gradle.api.plugins.BasePluginConvention.html[BasePluginConvention] DSL documentation for information on them.
