<!--
  ~ Copyright 2012 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='build_init_plugin'>
    <title>Build Init Plugin</title>
    <note>
        <para>
            The Build Init plugin is currently <link linkend="feature_lifecycle">incubating</link>. Please be aware that the DSL and other configuration may change in later Gradle versions.
        </para>
    </note>
    <para>
        The Gradle Build Init plugin can be used to bootstrap the process of creating a new Gradle build. It supports creating brand new projects of different types
        as well as converting existing builds (e.g. An Apache Maven build) to be Gradle builds.
    </para>
    <para>
        Gradle plugins typically need to be
        <firstterm>applied</firstterm>
        to a project before they can be used (see <xref linkend="sec:using_plugins"/>).
        The Build Init plugin is an automatically applied plugin, which means you do not need to apply it explicitly.
        To use the plugin, simply execute the task named
        <literal>init</literal>
        where you would like to create the Gradle build.
        There is no need to create a “stub”
        <literal>build.gradle</literal>
        file in order to apply the plugin.
    </para>
    <para>
        It also leverages the
        <literal>wrapper</literal>
        task from the Wrapper plugin (see <xref linkend='wrapper_plugin'/>),
        which means that the Gradle Wrapper will also be installed into the project.
    </para>
    <section>
        <title>Tasks</title>
        <para>The plugin adds the following tasks to the project:</para>
        <table>
            <title>Build Init plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>init</literal>
                </td>
                <td>
                    <literal>wrapper</literal>
                </td>
                <td>
                    <apilink class="org.gradle.buildinit.tasks.InitBuild"/>
                </td>
                <td>Generates a Gradle project.</td>
            </tr>
            <tr>
                <td>
                    <literal>wrapper</literal>
                </td>
                <td>-</td>
                <td>
                    <apilink class="org.gradle.api.tasks.wrapper.Wrapper"/>
                </td>
                <td>Generates Gradle wrapper files.
                </td>
            </tr>
        </table>
    </section>
    <section>
        <title>What to set up</title>
        <para>The
            <literal>init</literal>
            supports different build setup <firstterm>types</firstterm>. The type is specified by supplying a
            <literal>--type</literal>
            argument value. For example, to create a Java library project simply execute:
            <literal>gradle init --type java-library</literal>.
        </para>
        <para>
            If a
            <literal>--type</literal>
            parameter is not supplied, Gradle will attempt to infer the type from the environment. For example, it will
            infer a type value of “<literal>pom</literal>” if it finds a
            <literal>pom.xml</literal>
            to convert to a Gradle build.
        </para>
        <para>
            If the type could not be inferred, the type “<literal>basic</literal>” will be used.
        </para>
        <para>All build setup types include the setup of the Gradle Wrapper.</para>
    </section>
    <section>
        <title>Build init types</title>
        <note>
            As this plugin is currently <link linkend="feature_lifecycle">incubating</link>, only a few build init types are currently supported.
            More types will be added in future Gradle releases.
        </note>
        <section>
            <title>“<literal>pom</literal>” (Maven conversion)
            </title>
            <para>
                The “<literal>pom</literal>” type can be used to convert an Apache Maven build to a Gradle build.
                This works by converting the POM to one or more Gradle files.
                It is only able to be used if there is a valid “<literal>pom.xml</literal>”
                file in the directory that the
                <literal>init</literal>
                task is invoked in. This type will be automatically inferred if such a file exists.
            </para>
            <para>
                The Maven conversion implementation was inspired by the
                <ulink url="https://github.com/jbaruch/maven2gradle">maven2gradle tool</ulink>
                that was originally developed by Gradle community members.
            </para>
            <para>
                The conversion process has the following features:
            </para>
            <itemizedlist>
                <listitem>Uses effective POM and effective settings (support for POM inheritance, dependency management, properties)</listitem>
                <listitem>Supports both single module and multimodule projects</listitem>
                <listitem>Supports custom module names (that differ from directory names)</listitem>
                <listitem>Generates general metadata - id, description and version</listitem>
                <listitem>Applies maven, java and war plugins (as needed)</listitem>
                <listitem>Supports packaging war projects as jars if needed</listitem>
                <listitem>Generates dependencies (both external and inter-module)</listitem>
                <listitem>Generates download repositories (inc. local Maven repository)</listitem>
                <listitem>Adjusts Java compiler settings</listitem>
                <listitem>Supports packaging of sources and tests</listitem>
                <listitem>Supports TestNG runner</listitem>
                <listitem>Generates global exclusions from Maven enforcer plugin settings</listitem>
            </itemizedlist>
        </section>
        <section>
            <title>“<literal>java-library</literal>”
            </title>
            <para>
                The “<literal>java-library</literal>” build init type is not inferable. It must be explicitly specified.
            </para>
            <para>
                It has the following features:
            </para>
            <itemizedlist>
                <listitem>Uses the “<literal>java</literal>” plugin
                </listitem>
                <listitem>Uses the “<literal>jcenter</literal>” dependency repository
                </listitem>
                <listitem>Uses <ulink url="http://junit.org">JUnit</ulink>
                 for testing</listitem>
                <listitem>Has directories in the conventional locations for source code</listitem>
                <listitem>Contains a sample class and unit test, if there are no existing source or test files</listitem>
            </itemizedlist>
            <para>
                Alternative test framework can be specified by supplying a <literal>--test-framework</literal> argument value.
                To use a different test framework, execute one of the following commands:
            </para>
            <itemizedlist>
                <listitem><literal>gradle init --type java-library --test-framework spock</literal>: Uses <ulink url="http://code.google.com/p/spock/">Spock</ulink> for testing instead of JUnit</listitem>
                <listitem><literal>gradle init --type java-library --test-framework testng</literal>: Uses <ulink url="http://testng.org/doc/index.html">TestNG</ulink> for testing instead of JUnit</listitem>
            </itemizedlist>
        </section>
        <section>
            <title>“<literal>scala-library</literal>”
            </title>
            <para>
                The “<literal>scala-library</literal>” build init type is not inferable. It must be explicitly specified.
            </para>
            <para>
                It has the following features:
            </para>
            <itemizedlist>
                <listitem>Uses the “<literal>scala</literal>” plugin
                </listitem>
                <listitem>Uses the “<literal>jcenter</literal>” dependency repository
                </listitem>
                <listitem>Uses Scala 2.10</listitem>
                <listitem>Uses <ulink url="http://www.scalatest.org">ScalaTest</ulink> for testing</listitem>
                <listitem>Has directories in the conventional locations for source code</listitem>
                <listitem>Contains a sample scala class and an associated ScalaTest test suite, if there are no existing source or test files</listitem>
            </itemizedlist>
        </section>
        <section>
            <title>“<literal>groovy-library</literal>”
            </title>
            <para>
                The “<literal>groovy-library</literal>” build init type is not inferable. It must be explicitly specified.
            </para>
            <para>
                It has the following features:
            </para>
            <itemizedlist>
                <listitem>Uses the “<literal>groovy</literal>” plugin
                </listitem>
                <listitem>Uses the “<literal>jcenter</literal>” dependency repository
                </listitem>
                <listitem>Uses Groovy 2.x </listitem>
                <listitem>Uses <ulink url="http://spockframework.org">Spock testing framework</ulink> for testing</listitem>
                <listitem>Has directories in the conventional locations for source code</listitem>
                <listitem>Contains a sample Groovy class and an associated Spock specification, if there are no existing source or test files</listitem>
            </itemizedlist>
        </section>
        <section>
            <title>“basic”</title>
            <para>
                The “<literal>basic</literal>” build init type is useful for creating a fresh new Gradle project.
                It creates a sample
                <literal>build.gradle</literal>
                file, with comments and links to help get started.
            </para>
            <para>This type is used when no type was explicitly specified, and no type could be inferred.</para>
        </section>
    </section>
</chapter>
