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

[[build_init_plugin]]
= Build Init Plugin


[NOTE]
====

The Build Init plugin is currently <<feature_lifecycle.adoc#feature_lifecycle,incubating>>. Please be aware that the DSL and other configuration may change in later Gradle versions.

====

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.

Gradle plugins typically need to be _applied_ to a project before they can be used (see <<plugins.adoc#sec:using_plugins,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 `init` where you would like to create the Gradle build. There is no need to create a “stub” `build.gradle` file in order to apply the plugin.

It also leverages the `wrapper` task to <<gradle_wrapper.adoc#sec:adding_wrapper,generate the Gradle Wrapper files>> for the project.


[[sec:build_init_tasks]]
== Tasks

The plugin adds the following tasks to the project:

`init` — link:{groovyDslPath}/org.gradle.buildinit.tasks.InitBuild.html[InitBuild]::
_Depends on_: `wrapper`
+
Generates a Gradle project.

`wrapper` — link:{groovyDslPath}/org.gradle.api.tasks.wrapper.Wrapper.html[Wrapper]::
Generates Gradle wrapper files.

[[sec:what_to_set_up]]
== What to set up

The `init` supports different build setup _types_. The type is specified by supplying a `--type` argument value. For example, to create a Java library project simply execute: `gradle init --type java-library`.

If a `--type` parameter is not supplied, Gradle will attempt to infer the type from the environment. For example, it will infer a type value of “`pom`” if it finds a `pom.xml` to convert to a Gradle build.

If the type could not be inferred, the type “`basic`” will be used.

The `init` plugin also supports generating build scripts using either the Gradle Groovy DSL or the Gradle Kotlin DSL. The build script DSL to use defaults to the Groovy DSL and is specified by supplying a `--dsl` argument value. For example, to create a Java library project with Kotlin DSL build scripts simply execute: `gradle init --type java-library --dsl kotlin`.

All build setup types include the setup of the Gradle Wrapper.

Note that the migration from Maven builds only supports the Groovy DSL for generated build scripts.

[[sec:build_init_types]]
== Build init types


[NOTE]
====
As this plugin is currently <<feature_lifecycle.adoc#feature_lifecycle,incubating>>, only a few build init types are currently supported. More types will be added in future Gradle releases.
====


[[sec:pom_maven_conversion_]]
=== `pom` (Maven conversion)

The “`pom`” 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 “`pom.xml`” file in the directory that the `init` task is invoked in or, if invoked via the "`-p`" <<command_line_interface.adoc#command_line_interface,command line option>>, in the specified project directory. This “`pom`” type will be automatically inferred if such a file exists.

The Maven conversion implementation was inspired by the https://github.com/jbaruch/maven2gradle[maven2gradle tool] that was originally developed by Gradle community members.

The conversion process has the following features:

* Uses effective POM and effective settings (support for POM inheritance, dependency management, properties)
* Supports both single module and multimodule projects
* Supports custom module names (that differ from directory names)
* Generates general metadata - id, description and version
* Applies maven, java and war plugins (as needed)
* Supports packaging war projects as jars if needed
* Generates dependencies (both external and inter-module)
* Generates download repositories (inc. local Maven repository)
* Adjusts Java compiler settings
* Supports packaging of sources and tests
* Supports TestNG runner
* Generates global exclusions from Maven enforcer plugin settings


[[sec:javaapplication_]]
=== `java-application`

The “`java-application`” build init type is not inferable. It must be explicitly specified.

It has the following features:

* Uses the “`application`” plugin to produce a command-line application implemented using Java
* Uses the “`jcenter`” dependency repository
* Uses http://junit.org[JUnit] for testing
* Has directories in the conventional locations for source code
* Contains a sample class and unit test, if there are no existing source or test files

Alternative test framework can be specified by supplying a `--test-framework` argument value. To use a different test framework, execute one of the following commands:

* `gradle init --type java-application --test-framework spock`: Uses http://code.google.com/p/spock/[Spock] for testing instead of JUnit
* `gradle init --type java-application --test-framework testng`: Uses http://testng.org/doc/index.html[TestNG] for testing instead of JUnit


[[sec:javalibrary_]]
=== `java-library`

The “`java-library`” build init type is not inferable. It must be explicitly specified.

It has the following features:

* Uses the “`java`” plugin to produce a library Jar
* Uses the “`jcenter`” dependency repository
* Uses http://junit.org[JUnit] for testing
* Has directories in the conventional locations for source code
* Contains a sample class and unit test, if there are no existing source or test files

Alternative test framework can be specified by supplying a `--test-framework` argument value. To use a different test framework, execute one of the following commands:

* `gradle init --type java-library --test-framework spock`: Uses http://code.google.com/p/spock/[Spock] for testing instead of JUnit
* `gradle init --type java-library --test-framework testng`: Uses http://testng.org/doc/index.html[TestNG] for testing instead of JUnit


[[sec:scalalibrary_]]
=== `scala-library`

The “`scala-library`” build init type is not inferable. It must be explicitly specified.

It has the following features:

* Uses the “`scala`” plugin to produce a library Jar
* Uses the “`jcenter`” dependency repository
* Uses Scala 2.10
* Uses http://www.scalatest.org[ScalaTest] for testing
* Has directories in the conventional locations for source code
* Contains a sample scala class and an associated ScalaTest test suite, if there are no existing source or test files
* Uses the Zinc Scala compiler by default


[[sec:groovylibrary_]]
=== `groovy-library`

The “`groovy-library`” build init type is not inferable. It must be explicitly specified.

It has the following features:

* Uses the “`groovy`” plugin to produce a library Jar
* Uses the “`jcenter`” dependency repository
* Uses Groovy 2.x
* Uses http://spockframework.org[Spock testing framework] for testing
* Has directories in the conventional locations for source code
* Contains a sample Groovy class and an associated Spock specification, if there are no existing source or test files


[[sec:groovyapplication_]]
=== `groovy-application`

The “`groovy-application`” build init type is not inferable. It must be explicitly specified.

It has the following features:

* Uses the “`groovy`” plugin
* Uses the “`application`” plugin to produce a command-line application implemented using Groovy
* Uses the “`jcenter`” dependency repository
* Uses Groovy 2.x
* Uses http://spockframework.org[Spock testing framework] for testing
* Has directories in the conventional locations for source code
* Contains a sample Groovy class and an associated Spock specification, if there are no existing source or test files


[[sec:basic]]
=== `basic`

The “`basic`” build init type is useful for creating a fresh new Gradle project. It creates a sample `build.gradle` file, with comments and links to help get started.

This type is used when no type was explicitly specified, and no type could be inferred.
