// 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_dashboard_plugin]]
= The Build Dashboard Plugin

WARNING: The Build Dashboard Plugin is not compatible with the <<configuration_cache_status.adoc#config_cache:plugins:core,Configuration Cache>>.
When the `buildDashboard` task is part of the build, the Configuration Cache is gracefully disabled for that build.

The Build Dashboard plugin can be used to generate a single HTML dashboard that provides a single point of access to all of the reports generated by a build.

[[sec:build_dashboard_usage]]
== Usage

To use the Build Dashboard plugin, include the following in your build script:

====
include::sample[dir="snippets/reference/core-plugins/buildDashboard/kotlin",files="build.gradle.kts[tags=use-build-dashboard-plugin]"]
include::sample[dir="snippets/reference/core-plugins/buildDashboard/groovy",files="build.gradle[tags=use-build-dashboard-plugin]"]
====

Applying the plugin adds the `buildDashboard` task to your project. The task aggregates the reports for all tasks that implement the link:{groovyDslPath}/org.gradle.api.reporting.Reporting.html[Reporting] interface from _all projects_ in the build. It is typically only applied to the root project.

The `buildDashboard` task does not depend on any other tasks. Instead, the plugin configures every reporting task in the build to be _finalized by_ `buildDashboard`, so the dashboard is regenerated automatically after any reporting task runs. It will only aggregate the reporting tasks that are independently being executed as part of the build run. For example, "`gradle buildDashboard build`" will generate a dashboard for all of the reporting tasks that are dependents of the `build` task.

[[sec:build_dashboard_tasks]]
== Tasks

The Build Dashboard plugin adds the following task to the project:

`buildDashboard` — link:{groovyDslPath}/org.gradle.api.reporting.GenerateBuildDashboard.html[GenerateBuildDashboard]::
Generates build dashboard report.

[[sec:build_dashboard_project_layout]]
== Project layout

The Build Dashboard plugin does not require any particular project layout.

[[sec:build_dashboard_dependency_management]]
== Dependency management

The Build Dashboard plugin does not define any dependency configurations.

[[sec:build_dashboard_configuration]]
== Configuration

By default, the dashboard is generated at `layout.buildDirectory.dir("reports/buildDashboard")`. You can influence the location of build dashboard generation via link:{groovyDslPath}/org.gradle.api.reporting.ReportingExtension.html[ReportingExtension].
