// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.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.

[[migrating_from_maven]]
= Migrating Builds From Apache Maven

https://maven.apache.org[Apache Maven] is a build tool for Java and other JVM-based projects. It is typical to migrate an existing Maven build to Gradle.

This guide will help with such a migration by explaining the differences and similarities between the two tools and providing steps that you can follow to ease the process.

Converting a build can be scary, but you don't have to do it alone.
You can search our https://docs.gradle.org/[documentation], post on our https://discuss.gradle.org/[community forums], or reach out on our https://gradle.org/slack-invite[Slack channel] if you get stuck.

[[migmvn:making_a_case]]
== Making a case for migration

The primary differences between Gradle and Maven are flexibility, performance, user experience, and dependency management.

A visual overview of these aspects is available in the link:https://gradle.org/maven-vs-gradle[Maven vs Gradle feature comparison].

Since Gradle 3.0, Gradle has invested heavily in making Gradle builds much faster, with features such as link:https://blog.gradle.org/introducing-gradle-build-cache[build caching], link:https://blog.gradle.org/incremental-compiler-avoidance[compile avoidance], and an improved incremental Java compiler.
Gradle is now 2-10x faster than Maven for the vast majority of projects, even without using a build cache.
In-depth performance comparison and business cases for switching from Maven to Gradle can be found link:https://gradle.org/gradle-vs-maven-performance/[here].

[[migmvn:general_guidelines]]
== General guidelines

Gradle and Maven have fundamentally different views on how to build a project.
Gradle provides a flexible and extensible build model that delegates the actual work to the execution of a graph of tasks.
Maven uses a model of fixed, linear phases to which you can attach goals (the things that do the work).
This may make migrating between the two seem intimidating, but migrations can be surprisingly easy because Gradle follows many of the same conventions as Maven -- such as the <<java_plugin#sec:java_project_layout,standard project structure>> -- and its dependency management works in a similar way.

Here we lay out a series of steps for you to follow that will help facilitate the migration of any Maven build to Gradle:

TIP: Keep the old Maven build and new Gradle build side by side.
You know the Maven build works, so you should keep it until you are confident that the Gradle build produces all the same artifacts.
This also means that users can try the Gradle build without creating a new copy of the source tree.

 . link:https://scans.gradle.com[Create a Build Scan for the Maven build].
+
A Build Scan will make it easier to visualize what's happening in your existing Maven build.
For Maven builds, you will be able to see the project structure, what plugins are being used, a timeline of the build steps, and more.
Keep this handy so you can compare it to the Build Scan while converting the project.
+
. Develop a mechanism to verify that the two builds produce the same artifacts.
+
This is a vitally important step to ensure that your deployments and tests don't break.
Even small changes, such as the contents of a manifest file in a JAR, can cause problems.
If your Gradle build produces the same output as the Maven build, this will give you confidence in switching over and make it easier to implement the changes that will provide the greatest benefits.
+
This doesn't mean that you need to verify every artifact at every stage, although doing so can help you quickly identify the source of a problem.
You should focus on the critical output such as final reports and the artifacts that are published or deployed.
+
You will need to factor in some inherent differences in the build output that Gradle produces compared to Maven.
Generated POMs will contain only the information needed for consumption and they will use `<compile>` and `<runtime>` scopes correctly for that scenario.
You might also see differences in the order of files in archives and of files on classpaths.
Most differences will be minor, but it's worth identifying them and verifying that they are acceptable.
+
 . <<migmvn:automatic_conversion,Run an automatic conversion>>.
+
This will create all the Gradle build files you need, even for <<migmvn:multimodule_builds,multi-module builds>>.
For simpler Maven projects, the Gradle build will be ready to run!
+
 . link:https://scans.gradle.com[Create a Build Scan for the Gradle build].
+
A Build Scan will make it easier to visualize what's happening in the build.
For Gradle builds, you'll be able to see the project structure, the dependencies (regular and inter-project ones), what plugins are being used and the console output of the build.
+
Your build may fail at this point, but that's ok; the scan will still run.
Compare the Build Scan for the Gradle build to the one for the Maven build and continue down this list to troubleshoot the failures.
+
We recommend that you regularly generate a Build Scan during the migration to help you identify and troubleshoot problems.
If you want, you can also use a Build Scan to identify opportunities to <<performance.adoc#performance_gradle,improve the performance of the build>>.
+
 . <<migmvn:migrating_deps,Verify your dependencies and fix any problems>>.
+
 . <<migmvn:integration_tests,Configure integration and functional tests>>.
+
Many tests can simply be migrated by configuring an extra source set.
If you are using a third-party library, such as https://fitnesse.org/FitNesse/UserGuide.html[FitNesse], look to see whether  there is a suitable community plugin available on the https://plugins.gradle.org/[Gradle Plugin Portal].
+
 . Replace Maven plugins with Gradle equivalents.
+
In the case of <<migmvn:common_plugins,popular plugins>>, Gradle often has an equivalent plugin that you can use.
You might also find that you can <<migmvn:unnecessary_plugins,replace a plugin with built-in Gradle functionality>>.
As a last resort, you may need to reimplement a Maven plugin <<migmvn:custom_plugins,via your own custom plugins and task types>>.
+
The rest of this chapter looks in more detail at specific aspects of migrating a build from Maven to Gradle.

[[migmvn:build_lifecycle]]
== Understanding the build lifecycle

Maven builds are based around the concept of https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html[_build lifecycles_] that consist of a set of fixed phases.
This can be a challenge for users migrating to Gradle because the build lifecycle is <<build_lifecycle_intermediate.adoc#build_lifecycle,a new concept>>.
Although it's important to understand how Gradle builds fit into the structure of *initialization*, *configuration*, and *execution* phases, Gradle provides a helper feature that can mimic Maven's phases: <<organizing_tasks.adoc#sec:lifecycle_tasks,_lifecycle tasks_>>.

This feature allow you to define your own "lifecycles" by creating no-action tasks that simply depend on the tasks you're interested in.
And to make the transition to Gradle easier for Maven users, the <<base_plugin#sec:base_tasks,Base Plugin>> -- applied by all the JVM language plugins like the <<java_library_plugin#java_library_plugin,Java Library Plugin>> -- provides a set of lifecycle tasks that correspond to the main Maven phases.

Here is a list of some of the main Maven phases and the Gradle tasks that they map to:

`clean`::
Use the `clean` task provided by the Base Plugin.

`compile`::
Use the `classes` task provided by the <<java_plugin.adoc#sec:java_tasks,Java Plugin>> and other JVM language plugins.
This compiles all classes for all source files of all languages and also performs <<migmvn:filtering_resources,resource filtering>> via the `processResources` task.

`test`::
Use the `test` task provided by the Java Plugin.
It runs the unit tests, and more specifically, the tests that make up the <<java_plugin.adoc#source_sets,`test` source set>>.

`package`::
Use the `assemble` task provided by the Base Plugin.
This builds whatever is the appropriate package for the project; for example, a JAR for Java libraries or a WAR for traditional Java webapps.

`verify`::
Use the `check` task provided by the Base Plugin.
This runs all verification tasks that are attached to it, which typically includes the unit tests, any static analysis tasks -- such as <<checkstyle_plugin#checkstyle_plugin,Checkstyle>> -- and others.
If you want to include integration tests, you will have to <<migmvn:integration_tests,configure these manually>>.

`install`::
Use the `publishToMavenLocal` task provided by the <<publishing_maven#publishing_maven:tasks,Maven Publish Plugin>>.
+
Note that Gradle builds don't require you to "install" artifacts as you have access to more appropriate features like <<declaring_dependencies_basics.adoc#sec:project-dependencies,inter-project dependencies>> and <<composite_builds#composite_builds,composite builds>>.
You should only use `publishToMavenLocal` for interoperating with Maven builds.
+
Gradle also allows you to resolve dependencies against the local Maven cache, as described in the <<migmvn:declaring_repos,Declaring repositories>> section.

`deploy`::
Use the `publish` task provided by the <<publishing_maven#publishing_maven:tasks,Maven Publish Plugin>> -- making sure you switch from the older Maven Plugin (ID: `maven`) if your build is using that one.
This will publish your package to all configured publication repositories.
There are also tasks that allow you to publish to a single repository even when multiple ones are defined.
+
Note that the Maven Publish Plugin does not publish *source and Javadoc JARs* _by default_, but this can easily be activated as explained in <<building_java_projects.adoc#sec:java_packaging,the guide for building java projects>>.

[[migmvn:automatic_conversion]]
== Performing an automatic conversion

Gradle's <<build_init_plugin#build_init_plugin,`init` task>> is typically used to create a new skeleton project, but you can also use it to convert an existing Maven build to Gradle automatically.
Once Gradle is <<installation#installation,installed on your system>>, all you have to do is run the command

[listing.terminal]
----
> gradle init
----

from the root project directory.
This consists of parsing the existing POMs and generating the corresponding Gradle build scripts.
Gradle will also create a settings script if you're migrating a <<multi_project_builds#multi_project_builds,multi-project build>>.

You'll find that the new Gradle build includes the following:

 * All the custom repositories that are specified in the POM
 * Your external and inter-project dependencies
 * The appropriate plugins to build the project (limited to one or more of the <<publishing_maven.adoc#publishing_maven,Maven Publish>>, <<java_plugin.adoc#java_plugin,Java>> and <<war_plugin.adoc#war_plugin,War>> Plugins)

See the <<build_init_plugin#sec:pom_maven_conversion,Build Init Plugin chapter>> for a complete list of the automatic conversion features.

One thing to keep in mind is that assemblies are not automatically converted.
This additional conversion will required some manual work.
Options include:

 * Using the <<distribution_plugin#distribution_plugin,Distribution Plugin>>
 * Using the <<java_library_distribution_plugin#java_library_distribution_plugin,Java Library Distribution Plugin>>
 * Using the <<application_plugin#application_plugin,Application Plugin>>
 * <<working_with_files#sec:creating_archives_example,Creating custom archive tasks>>
 * Using a suitable community plugin from the https://plugins.gradle.org/[Gradle Plugin Portal]

If your Maven build does not have many plugins or custom steps, you can simply run

[listing.terminal]
----
> gradle build
----

once the migration has completed.
This will run the tests and produce the required artifacts automatically.

[[migmvn:migrating_deps]]
== Migrating dependencies

Gradle's dependency management system is more flexible than Maven's, but it still supports the same concepts of repositories, declared dependencies, scopes (<<dependency_configurations.adoc#sub:what-are-dependency-configurations,dependency configurations>> in Gradle), and transitive dependencies.
In fact, Gradle works with Maven-compatible repositories which makes it easy to migrate your dependencies.

NOTE: One notable difference between the two tools is in how they manage version conflicts. Maven uses a "closest" match algorithm, whereas Gradle picks the newest.
Don't worry though, you have a lot of control over which versions are selected, as documented in <<dependency_constraints.adoc#dependency-constraints,Managing Transitive Dependencies>>.

Over the following sections, we will show you how to migrate the most common elements of a Maven build's dependency management information.

[[migmvn:declaring_deps]]
=== Declaring dependencies

Gradle uses the same dependency identifier components as Maven: group ID, artifact ID and version.
It also supports classifiers.
All you need to do is substitute the identifier information for a dependency into Gradle's syntax, which is described in the <<declaring_dependencies.adoc#one-declaring-dependencies,Declaring Dependencies>> chapter.

For example, consider this Maven-style dependency on Log4J:

[source,xml]
----
<dependencies>
    <dependency>
        <groupId>log4j</groupId>
        <artifactId>log4j</artifactId>
        <version>1.2.12</version>
    </dependency>
</dependencies>
----

This dependency would look like the following in a Gradle build script:

.Declaring a simple compile-time dependency
====
include::sample[dir="snippets/releases/migrating/basic/kotlin",files="build.gradle.kts[tags=compile-dependencies]"]
include::sample[dir="snippets/releases/migrating/basic/groovy",files="build.gradle[tags=compile-dependencies]"]
====
<1> Attaches version 1.2.12 of Log4J to the `implementation` configuration (scope)

The string identifier takes the Maven values of `groupId`, `artifactId` and `version`, although Gradle refers to them as `group`, `module` and `version`.

The above example raises an obvious question: what is that `implementation` configuration?
It's one of the standard dependency configurations provided by the <<java_plugin#tab:configurations,Java Plugin>> and is often used as a substitute for Maven's default `compile` scope.

Several of the differences between Maven's scopes and Gradle's standard configurations come down to Gradle distinguishing between the dependencies required to build a module and the dependencies required to build a module that depends on it.
Maven makes no such distinction, so published POMs typically include dependencies that consumers of a library don't actually need.

Here are the main Maven dependency scopes and how you should deal with their migration:

`compile`::
Gradle has two configurations that can be used in place of the `compile` scope: `implementation` and `api`.
The former is available to any project that applies the Java Plugin, while `api` is only available to projects that specifically apply the <<java_library_plugin#java_library_plugin,Java Library Plugin>>.

+
In most cases you should simply use the `implementation` configuration, particularly if you're building an application or webapp.
But if you're building a library, you can learn about which dependencies should be declared using `api` in the section on <<building_java_projects#sec:building_java_libraries,Building Java libraries>>.
Even more information on the differences between `api` and `implementation` is provided in the Java Library Plugin chapter linked above.

`runtime`::
Use the `runtimeOnly` configuration.

`test`::
Gradle distinguishes between those dependencies that are required to _compile_ a project's tests and those that are only needed to _run_ them.
+
Dependencies required for test compilation should be declared against the `testImplementation` configuration.
Those that are only required for running the tests should use `testRuntimeOnly`.

`provided`::
Use the `compileOnly` configuration.
+
Note that the <<war_plugin#sec:war_dependency_management,War Plugin>> adds `providedCompile` and `providedRuntime` dependency configurations.
These behave slightly differently from `compileOnly` and simply ensure that those dependencies aren't packaged in the WAR file.
However, the dependencies are included on runtime and test runtime classpaths, so use these configurations if that's the behavior you need.

`import`::
The `import` scope is mostly used within `<dependencyManagement>` blocks and applies solely to POM-only publications.
Read the section on <<migmvn:using_boms,Using bills of materials>> to learn more about how to replicate this behavior.
+
You can also specify a regular dependency on a POM-only publication.
In this case, the dependencies declared in that POM are treated as normal transitive dependencies of the build.
+
For example, imagine you want to use the `groovy-all` POM for your tests.
It's a POM-only publication that has its own dependencies listed inside a `<dependencies>` block.
The appropriate configuration in the Gradle build looks like this:
+
.Consuming a POM-only dependency
====
include::sample[dir="snippets/releases/migrating/basic/kotlin",files="build.gradle.kts[tags=pom-dependencies]"]
include::sample[dir="snippets/releases/migrating/basic/groovy",files="build.gradle[tags=pom-dependencies]"]
====
+
The result of this will be that all `compile` and `runtime` scope dependencies in the `groovy-all` POM get added to the test runtime classpath, while only the `compile` scope dependencies get added to the test compilation classpath.
Dependencies with other scopes will be ignored.

[[migmvn:declaring_repos]]
=== Declaring repositories

Gradle allows you to retrieve declared dependencies from any Maven-compatible or Ivy-compatible repository.
Unlike Maven, it has no default repository and so you have to declare at least one.
In order to have the same behavior as your Maven build, just configure <<declaring_repositories_basics.adoc#sec:maven-central,Maven Central>> in your Gradle build, like this:

.Configuring the build to use Maven Central
====
include::sample[dir="snippets/releases/migrating/basic/kotlin",files="build.gradle.kts[tags=repositories]"]
include::sample[dir="snippets/releases/migrating/basic/groovy",files="build.gradle[tags=repositories]"]
====

You can also use the `repositories {}` block to configure custom repositories, as described in the <<supported_repository_types.adoc#sec:maven-repo,Repository Types>> chapter.

Lastly, Gradle allows you to resolve dependencies against the <<supported_repository_types.adoc#sec:maven-local,local Maven cache/repository>>.
This helps Gradle builds interoperate with Maven builds, but it shouldn't be a technique that you use if you don't need that interoperability.
If you want to share published artifacts via the filesystem, consider configuring a <<supported_repository_types.adoc#sec:maven-repo,custom Maven repository>> with a `file://` URL.

You might also be interested in learning about Gradle's own <<dependency_caching.adoc#sec:dependency-cache,dependency cache>>, which behaves more reliably than Maven's and can be used safely by multiple concurrent Gradle processes.

[[migmvn:controlling_dep_versions]]
=== Controlling dependency versions

The existence of transitive dependencies means that you can very easily end up with multiple versions of the same dependency in your dependency graph.
By default, Gradle will pick the newest version of a dependency in the graph, but that's not always the right solution.
That's why it provides several mechanisms for controlling which version of a given dependency is resolved.

On a per-project basis, you can use:

 * <<dependency_constraints.adoc#sec:adding-constraints-transitive-deps,Dependency constraints>>
 * <<migmvn:using_boms,Bills of materials>> (Maven BOMs)
 * <<dependency_versions.adoc#sec:enforcing-dependency-version,Overriding transitive versions>>

There are even more, specialized options listed in the <<dependency_constraints.adoc#dependency-constraints,controlling transitive dependencies>> chapter.

If you want to ensure consistency of versions across all projects in a multi-project build, similar to how the `<dependencyManagement>` block in Maven works, you can use the <<java_platform_plugin#java_platform_plugin,Java Platform Plugin>>.
This allows you declare a set of dependency constraints that can be applied to multiple projects.
You can even publish the platform as a Maven BOM or using Gradle's metadata format.
See the plugin page for more information on how to do that, and in particular the section on <<java_platform_plugin#sec:java_platform_consumption,Consuming platforms>> to see how you can apply a platform to other projects in the same build.


[[migmvn:excluding_deps]]
=== Excluding transitive dependencies

Maven builds use exclusions to keep unwanted dependencies -- or unwanted _versions_ of dependencies -- out of the dependency graph.
You can do the same thing with Gradle, but that's not necessarily the _right_ thing to do.
Gradle provides other options that may be more appropriate for a given situation, so you really need to understand _why_ an exclusion is in place to migrate it properly.

If you want to exclude a dependency for reasons unrelated to versions, then check out the section on <<dependency_constraints.adoc#sec:adding-constraints-transitive-deps,excluding transitive dependencies>>.
It shows you how to attach an exclusion either to an entire configuration (often the most appropriate solution) or to a dependency.
You can even easily apply an exclusion to all configurations.

If you're more interested in controlling which version of a dependency is actually resolved, see the previous section.

[[migmvn:optional_deps]]
=== Handling optional dependencies

You are likely to encounter two situations regarding optional dependencies:

 * Some of your transitive dependencies are declared as optional
 * You want to declare some of your direct dependencies as optional in your project's published POM

For the first scenario, Gradle behaves the same way as Maven and simply ignores any transitive dependencies that are declared as optional.
They are not resolved and have no impact on the versions selected if the same dependencies appear elsewhere in the dependency graph as non-optional.

As for publishing dependencies as optional, Gradle provides a richer model called <<how_to_create_feature_variants_of_a_library.adoc#feature_variants, feature variants>>, which will let you declare the "optional features" your library provides.

[[migmvn:using_boms]]
== Using bills of materials (BOMs)

Maven allows you to share dependency constraints by defining dependencies inside a `<dependencyManagement>` section of a POM file that has a packaging type of `pom`.
This special type of POM (a BOM) can then be imported into other POMs so that you have consistent library versions across your projects.

Gradle can use such BOMs for the same purpose, using a special dependency syntax based on link:{groovyDslPath}/org.gradle.api.artifacts.dsl.DependencyHandler.html#org.gradle.api.artifacts.dsl.DependencyHandler:platform(java.lang.Object)[platform()] and link:{groovyDslPath}/org.gradle.api.artifacts.dsl.DependencyHandler.html#org.gradle.api.artifacts.dsl.DependencyHandler:enforcedPlatform(java.lang.Object)[enforcedPlatform()] methods.
You simply declare the dependency in the normal way, but wrap the dependency identifier in the appropriate method, as shown in this example that "imports" the Spring Boot Dependencies BOM:

.Importing a BOM in a Gradle build
====
include::sample[dir="snippets/releases/migrating/importBom/kotlin",files="build.gradle.kts[tags=bom]"]
include::sample[dir="snippets/releases/migrating/importBom/groovy",files="build.gradle[tags=bom]"]
====
<1> Applies the Spring Boot Dependencies BOM
<2> Adds a dependency whose version is defined by that BOM

You can learn more about this feature and the difference between `platform()` and `enforcedPlatform()` in the section on <<platforms.adoc#sec:bom-import,importing version recommendations from a Maven BOM>>.

NOTE: You can use this feature to apply the `<dependencyManagement>` information from any dependency's POM to the Gradle build, even those that don't have a packaging type of `pom`. Both `platform()` and `enforcedPlatform()` will ignore any dependencies declared in the `<dependencies>` block.

[[migmvn:multimodule_builds]]
== Migrating multi-module builds (project aggregation)

Maven's multi-module builds map nicely to Gradle's <<multi_project_builds#multi_project_builds,multi-project builds>>.

To migrate a multi-module Maven build, simply follow these steps:

1. Create a settings script that matches the `<modules>` block of the root POM.
+
For example, this `<modules>` block:
+
[source,xml]
----
<modules>
    <module>simple-weather</module>
    <module>simple-webapp</module>
</modules>
----
+
Can be migrated by adding the following line to the settings script:
+
====
include::sample[dir="snippets/releases/migrating/multiModule/kotlin",files="settings.gradle.kts"]
include::sample[dir="snippets/releases/migrating/multiModule/groovy",files="settings.gradle"]
====
<1> Sets the name of the overall project
<2> Configures two subprojects as part of this build

[source,bash]
----
$ ./gradlew projects
----
[source,text]
----
include::{snippetsPath}/releases/migrating/multiModule/tests/projects.out[]
----

[start=2]
. Replace cross-module dependencies with <<declaring_dependencies_basics.adoc#sec:project-dependencies,project dependencies>>.
. Replicate project inheritance with <<sharing_build_logic_between_subprojects#sec:sharing_logic_via_convention_plugins,convention plugins>>.

This basically involves creating a root project build script that injects shared configuration into the appropriate subprojects.

[[migmvn:sub:sharing-versions]]
=== Sharing versions across projects

If you want to replicate the Maven pattern of having dependency versions declared in the `dependencyManagement` section of the root POM file, the best approach is to leverage the `java-platform` plugin.
You will need to add a dedicated project for this and consume it in the regular projects of your build.
See <<java_platform_plugin.adoc#java_platform_plugin,the documentation>> for more details on this pattern.

[[migmvn:profiles_and_properties]]
== Migrating Maven profiles and properties

Maven allows you parameterize builds using properties of various sorts.
Some are read-only properties of the project model, others are user-defined in the POM.
It even allows you to treat system properties as project properties.

Gradle has a similar system of project properties, although it differentiates between those and system properties.
You can, for example, define properties in:

* the build script
* a `gradle.properties` file in the root project directory
* a `gradle.properties` file in the `$HOME/.gradle` directory

Those aren't the only options, so if you are interested in finding out more about how and where you can define properties, check out the <<build_environment#build_environment,Build Environment>> chapter.

One important piece of behavior you need to be aware of is what happens when the same property is defined in both the build script and one of the external properties files: the build script value takes precedence.
Always.
Fortunately, you can mimic the concept of profiles to provide overridable default values.

Which brings us to Maven profiles.
These are a way to enable and disable different configurations based on environment, target platform, or any other similar factor.
Logically, they are nothing more than limited `if` statements.
And since Gradle has much more powerful ways to declare conditions, it does not need to have formal support for profiles (except in the POMs of dependencies).
You can easily get the same behavior by combining conditions with secondary build scripts, as you'll see.

Let's say you have different deployment settings depending on the environment: local development (the default), a test environment, and production.
To add profile-like behavior, you first create build scripts for each environment in the project root: `profile-default.gradle`, `profile-test.gradle`, and `profile-prod.gradle`.
You can then conditionally apply one of those profile scripts based on a <<build_environment.adoc#sec:project_properties,project property>> of your own choice.

The following example demonstrates the basic technique using a project property called `buildProfile` and profile scripts that simply initialize an <<writing_build_scripts_intermediate.adoc#sec:extra_properties,extra project property>> called `message`:

.Mimicking the behavior of Maven profiles in Gradle
====
include::sample[dir="snippets/releases/migrating/profiles/kotlin",files="build.gradle.kts;profile-default.gradle.kts;profile-test.gradle.kts;profile-prod.gradle.kts"]
include::sample[dir="snippets/releases/migrating/profiles/groovy",files="build.gradle;profile-default.gradle;profile-test.gradle;profile-prod.gradle"]
====
<1> Checks for the existence of (Groovy) or binds (Kotlin) the `buildProfile` project property
<2> Applies the appropriate profile script, using the value of `buildProfile` in the script filename
<3> Prints out the value of the `message` extra project property
<4> Initializes the `message` extra project property, whose value can then be used in the main build script

With this setup in place, you can activate one of the profiles by passing a value for the project property you're using -- `buildProfile` in this case:

[source,bash]
----
$ ./gradlew gradle greeting
----
[source,text]
----
include::{snippetsPath}/releases/migrating/profiles/tests/greeting-default.out[]
----

[source,bash]
----
$ ./gradlew -PbuildProfile=test greeting
----
[source,text]
----
include::{snippetsPath}/releases/migrating/profiles/tests/greeting-test.out[]
----

You're not limited to checking project properties.
You could also check environment variables, the JDK version, the OS the build is running on, or anything else you can imagine.

One thing to bear in mind is that high level condition statements make builds harder to understand and maintain, similar to the way they complicate object-oriented code.
The same applies to profiles.
Gradle offers you many better ways to avoid the extensive use of profiles that Maven often requires, for example by configuring multiple tasks that are variants of one another.
See the `publish__PubName__PublicationTo__RepoName__Repository` tasks created by the <<publishing_maven#publishing_maven:tasks,Maven Publish Plugin>>.

For a lengthier discussion on working with Maven profiles in Gradle, look no further than https://blog.gradle.org/maven-pom-profiles[this blog post].


[[migmvn:filtering_resources]]
== Filtering resources

Maven has a phase called `process-resources` that has the goal `resources:resources` bound to it by default.
This gives the build author an opportunity to perform variable substitution on various files, such as web resources, packaged properties files, etc.

The Java plugin for Gradle provides a `processResources` task to do the same thing.
This is a link:{groovyDslPath}/org.gradle.language.jvm.tasks.ProcessResources.html[ProcessResources] task that copies files from the configured resources directory -- `src/main/resources` by default -- to an output directory.
And as with any `ProcessResources` or `Copy` task, you can configure it to perform <<working_with_files#filtering_files,file filtering>>, <<working_with_files#sec:renaming_files,renaming>>, and <<working_with_files#sec:filtering_files,content filtering>>.

As an example, here's a configuration that treats the source files as https://docs.groovy-lang.org/docs/next/html/documentation/template-engines.html#_simpletemplateengine[Groovy `SimpleTemplateEngine`] templates, providing `version` and `buildNumber` properties to those templates:

.Filtering the content of resources via the `processResources` task
====
include::sample[dir="snippets/releases/migrating/basic/kotlin",files="build.gradle.kts[tags=process-resources]"]
include::sample[dir="snippets/releases/migrating/basic/groovy",files="build.gradle[tags=process-resources]"]
====

See the API docs for link:{javadocPath}/org/gradle/api/file/CopySpec.html[CopySpec] to see all the options available to you.


[[migmvn:integration_tests]]
== Configuring integration tests

Many Maven builds incorporate integration tests of some sort, which Maven supports through an extra set of phases: `pre-integration-test`, `integration-test`, `post-integration-test`, and `verify`.
It also uses the Failsafe plugin in place of Surefire so that failed integration tests don't automatically fail the build (because you may need to clean up resources, such as a running application server).

This behavior is easy to replicate in Gradle with source sets, as explained in our chapter on <<java_testing#sec:configuring_java_integration_tests,Testing in Java & JVM projects>>.
You can then configure a clean-up task, such as one that shuts down a test server for example, to always run after the integration tests regardless of whether they succeed or fail using link:{groovyDslPath}/org.gradle.api.Task.html#org.gradle.api.Task:finalizedBy(java.lang.Object++[]++)[Task.finalizedBy()].

If you really don't want your integration tests to fail the build, then you can use the link:{groovyDslPath}/org.gradle.api.tasks.testing.Test.html#org.gradle.api.tasks.testing.Test:ignoreFailures[Test.ignoreFailures] setting described in the <<java_testing#sec:test_execution,Test execution>> section of the Java testing chapter.

Source sets also give you a lot of flexibility on where you place the source files for your integration tests.
You can easily keep them in the same directory as the unit tests or, more preferably, in a separate source directory like `src/integTest/java`.
To support other types of tests, simple add more source sets and link:{groovyDslPath}/org.gradle.api.tasks.testing.Test.html[Test] tasks.

[[migmvn:common_plugins]]
== Migrating common plugins

Maven and Gradle share a common approach of extending the build through plugins.
Although the plugin systems are very different beneath the surface, they share many feature-based plugins, such as:

* Shade/Shadow
* Jetty
* Checkstyle
* JaCoCo
* AntRun (see further down)

Why does this matter? Because many plugins rely on standard Java conventions, migration is just a matter of replicating the configuration of the Maven plugin in Gradle.
As an example, here's a simple Maven Checkstyle plugin configuration:

[source,xml]
----
...
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-checkstyle-plugin</artifactId>
  <version>2.17</version>
  <executions>
    <execution>
      <id>validate</id>
      <phase>validate</phase>
      <configuration>
        <configLocation>checkstyle.xml</configLocation>
        <encoding>UTF-8</encoding>
        <consoleOutput>true</consoleOutput>
        <failsOnError>true</failsOnError>
        <linkXRef>false</linkXRef>
      </configuration>
      <goals>
        <goal>check</goal>
      </goals>
    </execution>
  </executions>
</plugin>
...
----

Everything outside of the configuration block can safely be ignored when migrating to Gradle.
In this case, the corresponding Gradle configuration is as follows:

.Configuring the Gradle Checkstyle Plugin
====
include::sample[dir="snippets/releases/migrating/basic/kotlin",files="build.gradle.kts[tags=checkstyle]"]
include::sample[dir="snippets/releases/migrating/basic/groovy",files="build.gradle[tags=checkstyle]"]
====

The Checkstyle tasks are automatically added as dependencies of the `check` task, which also includes `test`.
If you want to ensure that Checkstyle runs before the tests, then just specify an ordering with the
link:{groovyDslPath}/org.gradle.api.Task.html#org.gradle.api.Task:mustRunAfter(java.lang.Object++[]++)[mustRunAfter(...)] method:

.Controlling when the `checkstyle` task runs
====
include::sample[dir="snippets/releases/migrating/basic/kotlin",files="build.gradle.kts[tags=depends-on]"]
include::sample[dir="snippets/releases/migrating/basic/groovy",files="build.gradle[tags=depends-on]"]
====

As you can see, the Gradle configuration is often much shorter than the Maven equivalent.
You also have a much more flexible execution model since you are no longer constrained by Maven's fixed phases.

While migrating a project from Maven, don't forget about source sets.
These often provide a more elegant solution for handling integration tests or generated sources than Maven can provide, so you should factor them into your migration plans.


[[migmvn:ant_goals]]
=== Ant goals

Many Maven builds rely on the AntRun plugin to customize the build without the overhead of implementing a custom Maven plugin.
Gradle has no equivalent plugin because Ant is a first-class citizen in Gradle builds, via the `ant` object.
For example, you can use Ant's Echo task like this:

.Invoking Ant tasks
====
include::sample[dir="snippets/releases/migrating/ant/kotlin",files="build.gradle.kts"]
include::sample[dir="snippets/releases/migrating/ant/groovy",files="build.gradle"]
====

Even Ant properties and filesets are supported natively.
To learn more, see <<ant#ant,Using Ant from Gradle>>.

[TIP]
====
It may be simpler and cleaner to just <<custom_tasks#custom_tasks,create custom task types>> to replace the work that Ant is doing for you.
You can then more readily benefit from <<incremental_build.adoc#incremental_build,incremental build>> and other useful Gradle features.
====

[[migmvn:unnecessary_plugins]]
== Understanding which plugins you don't need

It's worth remembering that Gradle builds are typically easier to extend and customize than Maven ones.
In this context, that means you may not need a Gradle plugin to replace a Maven one.
For example, the Maven Enforcer plugin allows you to control dependency versions and environmental factors, but these things can easily be configured in a normal Gradle build script.


[[migmvn:custom_plugins]]
== Dealing with uncommon and custom plugins

You may come across Maven plugins that have no counterpart in Gradle, particularly if you or someone in your organisation has written a custom plugin.
Such cases rely on you understanding how Gradle (and potentially Maven) works, because you will usually have to write your own plugin.

For the purposes of migration, there are two key types of Maven plugins:

* Those that use the Maven project object.
* Those that don't.

Why is this important? Because if you use one of the latter, you can trivially reimplement it as a <<custom_tasks#custom_tasks,custom Gradle task type>>.
Simply define task inputs and outputs that correspond to the mojo parameters and convert the execution logic into a task action.

If a plugin depends on the Maven project, then you will have to rewrite it.
Don't start by considering how the Maven plugin works, but look at what problem it is trying to solve.
Then try to work out how to solve that problem in Gradle.
You will probably find that the two build models are different enough that "transcribing" Maven plugin code into a Gradle plugin just won't be effective.
On the plus side, the plugin is likely to be much easier to write than the original Maven one because Gradle has a much richer build model and API.

If you do need to implement custom logic, either via build scripts or plugins, check out the https://gradle.org/guides/?q=Plugin%20Development[Guides related to plugin development].
Also be sure to familiarize yourself with Gradle's link:{groovyDslPath}/[Groovy DSL Reference], which provides comprehensive documentation on the API that you'll be working with.
It details the standard configuration blocks (and the objects that back them), the core types in the system (`Project`, `Task`, etc.), and the standard set of task types.
The main entry point is the link:{groovyDslPath}/org.gradle.api.Project.html[Project] interface as that's the top-level object that backs the build scripts.

[[migmvn:further_reading]]
== Further reading

This chapter has covered the major topics that are specific to migrating Maven builds to Gradle. All that remain are a few other areas that may be useful during or after a migration:

 * Learn how to configure Gradle's <<build_environment#build_environment,build environment>>, including the JVM settings used to run it
 * Learn how to <<organizing_gradle_projects#organizing_gradle_projects,structure your builds effectively>>
 * <<logging#logging,Configure Gradle's logging>> and use it from your builds
