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

[[build_file_basics]]
= Build File Basics

Generally, a build script (`build.gradle(.kts)`) details *build configuration, tasks, and plugins*.

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

Every Gradle build comprises at least one _build script_.

[[sec:build_script]]
== Build scripts

The build script is either a `build.gradle` file written in Groovy or a `build.gradle.kts` file in Kotlin.

The link:{groovyDslPath}/index.html[Groovy DSL^] and the link:{kotlinDslPath}/index.html[Kotlin DSL^] are the only accepted languages for Gradle scripts.

In multi-project builds, each subproject typically has its own build file located in its root directory.

Inside a build script, you'll typically specify:

- *Plugins*: Tools that extend Gradle's functionality for tasks like compiling code, running tests, or packaging artifacts.
- *Dependencies*: External libraries and tools your project uses.

Specifically, build scripts contain two main types of dependencies:

- *Gradle and Build Script Dependencies*: These include plugins and libraries required by Gradle itself or the build script logic.
- *Project Dependencies*: Libraries required directly by your project's source code to compile and run correctly.

Let's take a look at an example and break it down:

++++
<div style="text-align: right;">
  <a href="https://github.com/gradle/gradle/tree/master/platforms/documentation/docs/src/snippets/fundamentals/running-builds/generated">
    <img src="https://img.shields.io/badge/View%20full%20project-GitHub-blue?logo=github&style=flat" alt="View full sample project on GitHub"/>
  </a>
</div>
++++

====
include::sample[dir="snippets/fundamentals/running-builds/generated/kotlin",files="app/build.gradle.kts[tags=init]"]
include::sample[dir="snippets/fundamentals/running-builds/generated/groovy",files="app/build.gradle[tags=init]"]
====
<1> Add plugins.
<2> Add dependencies.
<3> Use convention properties.

== 1. Add plugins

Plugins extend Gradle's functionality and can contribute tasks to a project.

Adding a plugin to a build is called _applying_ a plugin and makes additional functionality available.

====
include::sample[dir="snippets/fundamentals/running-builds/generated/kotlin",files="app/build.gradle.kts[tags=init-plugins]"]
include::sample[dir="snippets/fundamentals/running-builds/generated/groovy",files="app/build.gradle[tags=init-plugins]"]
====

The `application` plugin facilitates creating an executable JVM application.

Applying the <<application_plugin.adoc#application_plugin,Application plugin>> also implicitly applies the <<java_plugin.adoc#java_plugin,Java plugin>>.
The `java` plugin adds Java compilation along with testing and bundling capabilities to a project.

== 2. Add dependencies

Your project needs external libraries to compile, run, and test.

In this example, the project uses `JUnit Jupiter` for testing and Google’s `Guava` library in the main application code:

====
include::sample[dir="snippets/fundamentals/running-builds/generated/kotlin",files="app/build.gradle.kts[tags=init-dep]"]
include::sample[dir="snippets/fundamentals/running-builds/generated/groovy",files="app/build.gradle[tags=init-dep]"]
====

== 3. Use convention properties

A plugin adds tasks to a project.
It also adds properties and methods to a project.

The `application` plugin defines tasks that package and distribute an application, such as the `run` task.

The Application plugin provides a way to declare the main class of a Java application, which is required to execute the code.

====
include::sample[dir="snippets/fundamentals/running-builds/generated/kotlin",files="app/build.gradle.kts[tags=init-app]"]
include::sample[dir="snippets/fundamentals/running-builds/generated/groovy",files="app/build.gradle[tags=init-app]"]
====

In this example, the main class (i.e., the point where the program's execution begins) is `org.example.App`.

Build scripts are evaluated during the configuration phase of a build, and they serve as the main entry point for defining a (sub)project’s build logic.
In addition to applying plugins and setting convention properties, build scripts can:

* Declare dependencies
* Configure tasks
* Reference shared settings (from version catalogs or convention plugins)

[.text-right]
**Next Step:** <<dependency_management_basics.adoc#dependency_management_basics,Learn about Dependency Management>> >>
