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

[[gradle]]
= Core Concepts

Gradle *automates building, testing, and deployment of software* from information in *build scripts*.

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

== Core concepts

++++
<p>
  <div style="position:relative;padding-top:56.25%;">
    <iframe src="https://www.youtube-nocookie.com/embed/Vw39uWQ08Go?si=Qt7qceGy2EDgkU0a&rel=0" frameborder="0" allowfullscreen
      style="position:absolute;top:0;left:0;width:100%;height:100%;"></iframe>
  </div>
</p>
++++

Gradle builds are defined in terms of *projects* and *tasks*, configured using *build scripts* written in *Groovy* or *Kotlin*.

[cols="1,2", options="header"]
|===
| Concept        | What It Means

| Build
| The process and environment for producing outputs. A *build* includes one or more *projects* and their *build scripts*.

| Project
| A piece of software that can be built, such as an application or library. A *build* may have a single root *project* or multiple *subprojects*.

| Task
| A basic unit of work, like compiling code or running tests. *Tasks* are declared in *build scripts* or added by *plugins*.

| Build Script
| A configuration file (`build.gradle(.kts)`) that defines *tasks*, *dependencies*, and other instructions that tell Gradle how to build a *project*.

| Plugin
| Used to extend Gradle's capabilities (like the `Java` plugin). *Plugins* often add tasks and conventions to *projects*.

| Dependency
| External or internal resources required by a *project*. Gradle automatically resolves these during the *build*.

|===

== Project structure

Many developers will interact with Gradle for the first time through an existing project.

The presence of the `gradlew` and `gradlew.bat` files in the root directory of a project is a clear indicator that Gradle is used.

A Gradle project will look similar to the following:

[source,text]
----
project
├── gradle                          // <1>
├── gradlew                             // <2>
├── gradlew.bat                         // <2>
├── settings.gradle(.kts)           // <3>
├── subproject-a
│   ├── build.gradle(.kts)              // <4>
│   └── src/                        // <5>
└── subproject-b
    ├── build.gradle(.kts)              // <4>
    └── src/                        // <5>
----
<1> Gradle directory to store wrapper files and more
<2> Gradle *wrapper scripts* - _THIS IS A GRADLE PROJECT!_
<3> Gradle *settings file* to define a root project name and subprojects
<4> Gradle *build scripts* of the two subprojects - `subproject-a` and `subproject-b`
<5> *Source code* and/or additional files for the projects

== Invoking Gradle

=== In the IDE

Gradle is <<gradle_ides.adoc#gradle_ides,built-in to many IDEs>> including Android Studio, IntelliJ IDEA, Visual Studio Code, Eclipse, and NetBeans.

Gradle can be automatically invoked when you build, clean, or run your app in the IDE.

image::gradle-ide-invocation.gif[]

Consult the manual for the IDE of your choice to learn more about how Gradle can be used and configured.

=== On the Command Line

Gradle can be invoked in the command line once <<installation.adoc#installation, installed>>:

[source,text]
----
$ gradle build
----

[source,text]
----
$ gradle test
----

[source,text]
----
$ gradle clean build
----

Most projects do not use the installed version of Gradle but rather the Gradle Wrapper.

=== With the Gradle Wrapper

The wrapper is a script that invokes a declared version of Gradle and is *the recommended way to execute a Gradle build*:

[source,text]
----
$ ./gradlew build
----

image::gradle-terminal-invocation.gif[]

[.text-right]
**Next Step:** <<gradle_wrapper_basics.adoc#gradle_wrapper_basics,Learn about the Gradle Wrapper>> >>
