<!--
  ~ Copyright 2009 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.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.
  -->
<chapter id="project_reports_plugin" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The Project Report Plugin</title>

    <para>The Project report plugin adds some tasks to your project which generate reports containing useful
        information about your build. Those tasks generate exactly the same content as the command line reports triggered
        by <userinput>gradle tasks</userinput>, <userinput>gradle dependencies</userinput> and
        <userinput>gradle properties</userinput> (see<xref linkend="sec:obtaining_information_about_your_build"/>).
        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.
    </para>
    <para>
        We plan to add much more to the existing reports and create additional ones in future releases of Gradle.
    </para>

    <section>
        <title>Usage</title>
        <para>To use the Project report plugin, include in your build script:</para>
<programlisting language="java">
apply plugin: 'project-report'
</programlisting>
    </section>

    <section>
        <title>Tasks</title>
        <para>The project report plugin defines the following tasks:</para>
        <table>
            <title>Project report plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>dependencyReport</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.diagnostics.DependencyReportTask"/></td>
                <td>Generates the project dependency report.</td>
            </tr>
            <tr>
                <td>
                    <literal>propertyReport</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.diagnostics.PropertyReportTask"/></td>
                <td>Generates the project property report.</td>
            </tr>
            <tr>
                <td>
                    <literal>taskReport</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.tasks.diagnostics.TaskReportTask"/></td>
                <td>Generates the project task report.</td>
            </tr>
            <tr>
                <td>
                    <literal>projectReport</literal>
                </td>
                <td>
                    <literal>dependencyReport</literal>, <literal>propertyReport</literal>, <literal>taskReport</literal>
                </td>
                <td><apilink class="org.gradle.api.Task"/></td>
                <td>Generates all project reports.</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Project layout</title>
        <para>The project report plugin does not require any particular project layout.</para>
    </section>

    <section>
        <title>Dependency management</title>
        <para>The project report plugin does not define any dependency configurations.</para>
    </section>

    <section>
        <title>Convention properties</title>
        <para>The project report defines the following convention properties:</para>
        <table>
            <title>Project report plugin - convention properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <xi:include href="reportingBasePluginProperties.xml"/>
            <tr>
                <td>
                    <literal>projects</literal>
                </td>
                <td>
                    <classname>Set&lt;Project&gt;</classname>
                </td>
                <td>
                    <literal>A one element set with the project the plugin was applied to.</literal>
                </td>
                <td>
                    The projects to generate the reports for.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>projectReportDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>project</literal>
                </td>
                <td>
                    The name of the directory to generate the project report into, relative to the reports directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>projectReportDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>reportsDir</replaceable>/<replaceable>projectReportDirName</replaceable></literal>
                </td>
                <td>
                    The directory to generate the project report into.
                </td>
            </tr>
        </table>

        <para>These convention properties are provided by a convention object of type <apilink class="org.gradle.api.plugins.ProjectReportsPluginConvention"/>.</para>
    </section>
    
</chapter>