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

[[project_report_plugin]]
= The Project Report Plugin

The Project report plugin adds some tasks to your project which generate reports containing useful information about your build. These tasks generate the same content that you get by executing the `tasks`, `dependencies`, and `properties` tasks from the command line (see <<command_line_interface.adoc#sec:command_line_project_reporting,Command-line project reporting>>). In contrast to the command line reports, the report plugin generates the reports into a file. There is also an aggregating task that depends on all report tasks added by the plugin.

We plan to add much more to the existing reports and create additional ones in future releases of Gradle.


[[sec:project_reports_usage]]
== Usage

To use the Project report plugin, include the following in your build script:

[source,groovy]
----
plugins {
    id 'project-report'
}
----


[[sec:project_reports_tasks]]
== Tasks

The project report plugin defines the following tasks:

`dependencyReport` — link:{groovyDslPath}/org.gradle.api.tasks.diagnostics.DependencyReportTask.html[DependencyReportTask]::
Generates the project dependency report.

`htmlDependencyReport` — link:{groovyDslPath}/org.gradle.api.reporting.dependencies.HtmlDependencyReportTask.html[HtmlDependencyReportTask]::
Generates an HTML dependency and dependency insight report for the project or a set of projects.

`propertyReport` — link:{groovyDslPath}/org.gradle.api.tasks.diagnostics.PropertyReportTask.html[PropertyReportTask]::
Generates the project property report.

`taskReport` — link:{groovyDslPath}/org.gradle.api.tasks.diagnostics.TaskReportTask.html[TaskReportTask]::
Generates the project task report.

`projectReport` — link:{groovyDslPath}/org.gradle.api.Task.html[Task]::
_Depends on_: `dependencyReport`, `propertyReport`, `taskReport`, `htmlDependencyReport`
+
Generates all project reports.


[[sec:project_reports_project_layout]]
== Project layout

The project report plugin does not require any particular project layout.

[[sec:project_reports_dependency_management]]
== Dependency management

The project report plugin does not define any dependency configurations.

[[sec:project_reports_convention_properties]]
== Convention properties

The project report defines the following convention properties:

`projects` — `Set&lt;Project&gt;`::
The projects to generate the reports for. _Default value_: A one element set with the project the plugin was applied to.

`projectReportDirName` — `String`::
The name of the directory to generate the project report into, relative to the reports directory. _Default value_: `"project"`.

`projectReportDir` — `File` (read-only)::
The directory to generate the project report into. _Default value_: `__reportsDir__/__projectReportDirName__`.

`reportsDirName` — `String`::
The name of the directory to generate the project report into, relative to the reports directory. _Default value_: `"reports"`.

`reportsDir` — `File` (read-only)::
The directory to generate the project reports into. _Default value_: `__buildDir__/__reportsDirName__`.

These convention properties are provided by a convention object of type link:{groovyDslPath}/org.gradle.api.plugins.ProjectReportsPluginConvention.html[ProjectReportsPluginConvention].

Configuring the project report tasks via the plugin's convention properties is **deprecated**. If you need to change from the default values, configure the appropriate tasks directly. If you want to configure all report tasks of the same type in the project, use link:{javadocPath}/org/gradle/api/DomainObjectCollection.html#withType-java.lang.Class-[tasks.withType(...).configureEach(...)] (where the type can be `HtmlDependencyReportTask` for example).
