<!--
  ~ 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='bootstrap_plugin'>
    <title>Bootstrap Plugin</title>
    <para>The Gradle bootstrap plugin prepares the current project for Gradle.
        Typically it will create the relevant build.gradle, settings.gradle files.
        At the moment only conversion from maven3 is supported.</para>
    <para>
        The plugin is currently *incubating* which means it is already useful
        but not everything might work perfectly.
        The api, plugin and task names may change before the final release.
        Please let us know your feedback or report any issues.</para>
    <para>
        The plugin works by obtaining the effective POM of the current project
        by executing external 'mvn' command. Then it reads the dependencies
        and other information to generate build.gradle scripts.</para>
    <para>
        The plugin is inspired by the <ulink url="https://github.com/jbaruch/maven2gradle">maven2gradle tool</ulink>
        founded and maintained by recognized leaders of Gradle community;
        created by Baruch Sadogursky with contributions from Antony Stubbs, Matthew McCullough and others.
    </para>

    <section>
        <title>Maven conversion - features</title>
        <itemizedlist>
            <listitem>Uses effective POM and effective settings
            (support for POM inheritance, dependency management, properties)</listitem>
            <listitem>Supports both single module and multimodule projects.
                Generates settings.gradle for 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>

        <para>
            (*) - Note: Your project will be considered multi-module
            only if your reactor is also a parent of at least one of your modules.
            Why so? Reactor project is built last, when Parent project is built first.
            The reactor has to be built first, because effective-pom Mojo generates needed output
            only if it finds modules in first project it encounters.
            Making reactor also a parent achieves this.
        </para>
    </section>

    <section>
        <title>Usage</title>
        <para>To convert a Maven project follow the steps:</para>
        <itemizedlist>
            <listitem>Make sure your Maven project builds and uses maven3.</listitem>
            <listitem>Make sure <code>mvn</code> command can be executed and it runs maven3.</listitem>
            <listitem>Create <filename>build.gradle</filename> file in the root folder of your Maven project.</listitem>
            <listitem>Specify <code>apply plugin: 'maven2Gradle'</code> and nothing else
                in the <filename>build.gradle</filename> file.</listitem>
            <listitem>Make sure you are using the Gradle version that contains the plugin.
                If necessary download the required Gradle version.
                Until Gradle 1.2 is released you should use the
                <ulink url="website:nightly">nightly build</ulink>.
                You only need this version for conversion of the Maven project.
                When converting is complete feel free to use the desired Gradle version, for example 1.1.
            </listitem>
            <listitem>Run <code>gradle tasks</code>. You should see <code>maven2Gradle</code> task available.</listitem>
            <listitem>Run <code>gradle maven2Gradle</code>.</listitem>
            <listitem>Advanced users: you can configure following boolean properties on the <code>maven2Gradle</code> task:
                <code>verbose</code> (shows more output, including the effective POM)
                and <code>keepFile</code> (keeps the obtained effective POM file).</listitem>
        </itemizedlist>
    </section>
</chapter>
