// 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_scans]]
= Build Scan Basics

A Build Scan is a *representation of metadata captured* as you run your build.

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

[[sec:about_build_scan]]
== About Build Scan

Gradle <<#sec:captured-information,captures your build metadata>> and sends it to the link:https://scans.gradle.com/[Build Scan Service].
The service then transforms the metadata into information you can analyze and share with others.

image::build-scan-1.png[]

The information that Build Scan collects can be an invaluable resource when troubleshooting, collaborating on, or optimizing the performance of your builds.

For example, with a Build Scan, it’s no longer necessary to copy and paste error messages or include all the details about your environment each time you want to ask a question on Stack Overflow, Slack, or the Gradle Forum.
Instead, copy the link to your latest Build Scan.

image::build-scan-2.png[]

[[sec:enable_build_scan]]
== Enable Build Scan

To enable a Build Scan on a Gradle command, add `--scan` to the command line option:

[source,bash]
----
$ ./gradlew build --scan
----

You may be prompted to agree to the terms to use Build Scan.

Visit link:https://scans.gradle.com/[Develocity at gradle.com] to learn more.

=== Publishing to a specific Develocity server

If you have a Develocity server, you can publish your Build Scan reports to that server instead of link:https://scans.gradle.com/[Develocity at gradle.com].

You enable this with the `--develocity-url` command line option:

[source,text]
----
 ./gradlew build --develocity-url=https://develocity.example.com
----

Check the https://docs.gradle.com/develocity/gradle/current/gradle-plugin/#publish_no_modify[Develocity Gradle plugin documentation] for more details.

[[sec:captured-information]]
== Captured Information

To see what data is captured and sent in a Build Scan, refer to the link:https://docs.gradle.com/develocity/gradle-plugin/current/#captured_information[Captured Information] section in the Gradle Develocity Plugin documentation.

Ready to build something? Start with the <<part1_gradle_init.adoc#part1_gradle_init,Beginner Tutorial>>.

[.text-right]
**Next Step:** <<part1_gradle_init.adoc#part1_gradle_init,Start the Tutorial>> >>
