// Copyright (C) 2023 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_wrapper_basics]]
= Gradle Wrapper Basics

The **recommended way to execute any Gradle build** is with the Gradle Wrapper.

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

The _Wrapper_ script invokes a declared version of Gradle, downloading it beforehand if necessary.

image::wrapper-workflow.png[]

The Wrapper is available as a `gradlew` or `gradlew.bat` file.

The Wrapper provides the following benefits:

- Standardizes a project on a given Gradle version.
- Provisions the same Gradle version for different users.
- Provisions the Gradle version for different execution environments (IDEs, CI servers...).

[[sec:using_the_wrapper]]
== Using the Gradle Wrapper

It is always recommended to execute a build with the Wrapper to ensure a reliable, controlled, and standardized execution of the build.

Depending on the operating system, you run `gradlew` or `gradlew.bat` instead of the `gradle` command.

Typical Gradle invocation:

----
$ gradle build
----

To run the Wrapper on a Linux or OSX machine:

----
$ ./gradlew build
----

To run the Wrapper on Windows PowerShell:

----
$ .\gradlew.bat build
----

The command is run in the same directory that the Wrapper is located in.
If you want to run the command in a different directory, you must provide the relative path to the Wrapper:

----
$ ../gradlew build
----

The following console output demonstrates the use of the Wrapper on a Windows machine, in the command prompt (cmd), for a Java-based project:

----
$ gradlew.bat build

include::{snippetsPath}/wrapper/simple/tests/wrapperBatchFileExecution.out[]
----

[[sec:view_the_wrapper]]
== Understanding the Wrapper files

The following files are part of the Gradle Wrapper:

[source,text]
----
.
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar  // <1>
│       └── gradle-wrapper.properties   // <2>
├── gradlew // <3>
└── gradlew.bat // <4>
----
<1> `gradle-wrapper.jar`: This is a small JAR file that contains the Gradle Wrapper code. It is responsible for downloading and installing the correct version of Gradle for a project if it's not already installed.
<2> `gradle-wrapper.properties`: This file contains configuration properties for the Gradle Wrapper, such as the distribution URL (where to download Gradle from) and the distribution type (ZIP or TARBALL).
<3> `gradlew`: This is a shell script (Unix-based systems) that acts as a wrapper around `gradle-wrapper.jar`. It is used to execute Gradle tasks on Unix-based systems without needing to manually install Gradle.
<4> `gradlew.bat`: This is a batch script (Windows) that serves the same purpose as `gradlew` but is used on Windows systems.

IMPORTANT: You should never alter these files.

If you want to view or update the Gradle version of your project, use the command line.
Do not edit the wrapper files manually:

[source, bash]
----
$ ./gradlew --version
$ ./gradlew wrapper --gradle-version 7.2
----

[source, cmd]
----
$ gradlew.bat --version
$ gradlew.bat wrapper --gradle-version 7.2
----

Consult the <<gradle_wrapper.adoc#gradle_wrapper_reference,Gradle Wrapper reference>> to learn more.

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