// 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 <<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

++++
<sample id="applyingBasePlugin" dir="userguide/basePlugin" title="Applying the Base Plugin">
    <sourcefile file="build.gradle" snippet="apply-base-plugin"/>
</sample>
++++

[[sec:base_tasks]]
=== Tasks

`clean` — type: `Delete`::
Deletes the build directory and everything in it, i.e. the path specified by the api:org.gradle.api.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.

`upload__Configuration__` — task rule::
Does the same as `build__Configuration__`, but also uploads all the artifacts attached to the given configuration.

`clean__Task__` — task rule::
Removes the <<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 <<managing_dependency_configurations,configurations for dependencies>>, but it does add the following configurations for <<sec:artifacts_and_configurations,artifacts>>:

`default`::
A fallback configuration used by consumer projects. Let's say you have project B with a _<<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. This results in an `uploadArchives` task for publishing artifacts attached to the `archives` configuration.

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

[[sec:base_plugin_conventions]]
=== Conventions

The Base Plugin only adds conventions related to the creation of archives, such as ZIPs, TARs and JARs. Specifically, it provides the following project properties that you can set:

`archivesBaseName` — default: `$project.name`::
Provides the default api:org.gradle.api.tasks.bundling.AbstractArchiveTask#getBaseName()[] for archive tasks.

`distsDirName` — default: _distributions_::
Default name of the directory in which distribution archives, i.e. non-JARs, are created.

`libsDirName` — default: _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 api:org.gradle.api.tasks.bundling.AbstractArchiveTask[]:

`destinationDir`::
Defaults to __``$buildDir``/``$distsDirName``__ for non-JAR archives and __``$buildDir``/``$libsDirName``__ for JARs and derivatives of JAR, such as WARs.

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

`baseName`::
Defaults to `$archivesBaseName`.
