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


The Gradle Build Init plugin can be used to create 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` in the directory 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` task supports different build init _types_, which determines exactly what files will be generated. The available types are listed <<sec:build_init_types,below>>.

The simplest, and recommended, way to use the `init` task is to run `gradle init` from an interactive console. Gradle will list the available init types and ask you to select one. It will then ask some additional questions to allow you to fine-tune the result.

There are several command-line options available for the `init` task that control what it will generate. You can use these when Gradle is not running from an interactive console.

The build init type can be specified by using the `--type` command-line option. For example, to create a Java library project simply run: `gradle init --type java-library`.

If a `--type` option is not provided, Gradle will attempt to infer the type from the environment. For example, it will infer a type of “`pom`” if it finds a `pom.xml` file to convert to a Gradle build. If the type could not be inferred, the type “`basic`” will be used.

The `init` task also supports generating build scripts using either the Gradle Groovy DSL or the Gradle Kotlin DSL. The build script DSL defaults to the Groovy DSL for most build init types and to the Kotlin DSL for Kotlin build types. The DSL can be selected by using the `--dsl` command-line option. For example, to create a Java library project with Kotlin DSL build scripts simply execute: `gradle init --type java-library --dsl kotlin`.

You can change the name of the generated project using the `--project-name` option. It defaults to the name of the directory where the `init` task is run.

You can change the package used for generated source files using the `--package` option. It defaults to the project name.

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

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


[[sec:pom_maven_conversion_]]
=== `pom` build init type (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.

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

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 <<publishing_maven,Maven Publish>>, <<java_plugin,Java>> and <<war_plugin,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, tests, and javadocs
* Supports TestNG runner
* Generates global exclusions from Maven enforcer plugin settings


[[sec:javaapplication_]]
=== `java-application` build init type

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` build init type

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:kotlinapplication_]]
=== `kotlin-application` build init type

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

It has the following features:

* Uses the “`org.jetbrains.kotlin.jvm`” and "`application`" plugins to produce a command-line application implemented in Kotlin
* Uses the “`jcenter`” dependency repository
* Uses Kotlin 1.x
* Uses https://kotlinlang.org/api/latest/kotlin.test/index.html[Kotlin test library] for testing
* Has directories in the conventional locations for source code
* Contains a sample Kotlin class and an associated Kotlin test class, if there are no existing source or test files


[[sec:kotlinlibrary_]]
=== `kotlin-library` build init type

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

It has the following features:

* Uses the “`org.jetbrains.kotlin.jvm`” plugin to produce a library Jar
* Uses the “`jcenter`” dependency repository
* Uses Kotlin 1.x
* Uses https://kotlinlang.org/api/latest/kotlin.test/index.html[Kotlin test library] for testing
* Has directories in the conventional locations for source code
* Contains a sample Kotlin class and an associated Kotlin test class, if there are no existing source or test files


[[sec:scalalibrary_]]
=== `scala-library` build init type

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.11
* 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` build init type

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` build init type

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:cppapplication_]]
=== `cpp-application` build init type

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

It has the following features:

* Uses the “`cpp-application`” plugin
* Uses the “`cpp-unit-test`” plugin to build and run simple unit tests
* Has directories in the conventional locations for source code
* Contains a sample C++ class, a private header file and an associated test class, if there are no existing source or test files

[[sec:cpplibrary_]]
=== `cpp-library` build init type

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

It has the following features:

* Uses the “`cpp-library`” plugin
* Uses the “`cpp-unit-test`” plugin to build and run simple unit tests
* Has directories in the conventional locations for source code
* Contains a sample C++ class, a public header file and an associated test class, if there are no existing source or test files

[[sec:basic]]
=== `basic` build init type

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

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