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

[[migrating_from_ant]]
= Migrating Builds From Apache Ant

https://ant.apache.org/[Apache Ant] is a build tool with a long history in the Java world that is still widely used, albeit by a decreasing number of teams. While flexible, it lacks conventions and many of the powerful features that Gradle can provide. Migrating to Gradle is worthwhile so that your builds can become slimmer, simpler and faster, while still retaining the flexibility you enjoy with Ant. You'll also benefit from robust support for multi-project builds and easy-to-use, flexible dependency management.

The biggest challenge in migrating from Ant to Gradle is that there is no such thing as a standard Ant build. That makes it difficult to provide specific instructions. Fortunately, Gradle has some great integration features with Ant that can make the process relatively smooth. And even migrating from https://ant.apache.org/ivy/[Ivy]-based dependency management isn't particularly hard because Gradle has a similar model based on <<dependency_management_terminology#sub:terminology_configuration,dependency configurations>> that works with Ivy-compatible repositories.

We will start by outlining the things you should consider at the outset of migrating a build from Ant to Gradle and offer some general guidelines on how to proceed.

[[migant:general_guidelines]]
== General guidelines

When you undertake to migrate a build from Ant to Gradle, you should keep in mind the nature of both what you already have and where you would like to end up. Do you want a Gradle build that mirrors the structure of the existing Ant build? Or do you want to move to something that is more idiomatic to Gradle? What are the main benefits you are looking for?

To understand the implications, consider the two extreme endpoints that you could aim for:

 * An imported build via <<ant#sec:import_ant_build,`ant.importBuild()`>>
+
This approach is quick, simple and works for many Ant-based builds. You end up with a build that's effectively identical to the original Ant build, except your Ant targets become Gradle tasks. Even the dependencies between targets are retained.
+
The downside is that you're still using the Ant build, which you must continue to maintain. You also lose the advantages of Gradle's conventions, many of its plugins, its dependency management, and so on. You can still enhance the build with <<more_about_tasks#sec:up_to_date_checks,incremental build information>>, but it's more effort than would be the case for a normal Gradle build.
 * An idiomatic Gradle build
+
If you want to future proof your build, this is where you want to end up. Making use of Gradle's conventions and plugins will result in a smaller, easier-to-maintain build, with a structure that is familiar to many Java developers. You will also find it easier to take advantage of Gradle's power features to improve build performance.
+
The main downside is the extra work required to perform the migration, particularly if the existing build is complex and has many inter-project dependencies. But such builds often benefit the most from a switch to idomatic Gradle. In addition, Gradle provides many features that can ease the migration, such as the ability to <<ant#sec:using_ant_tasks,use core and custom Ant tasks>> directly from a Gradle build.

You ideally want to end up somewhere close to the second option in the long term, but you don't have to get there in one fell swoop.

What follows is a series of steps to help you decide the approach you want to take and how to go about it:

 1. Keep the old Ant build and new Gradle build side by side
+
You know the Ant build works, so you should keep it until you are confident that the Gradle build produces all the same artifacts and otherwise does what you need. This also means that users can try the Gradle build without getting a new copy of the source tree.
+
Don't try to change the directory and file structure of the build until after you're ready to make the switch.
 2. 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 Ant build, this will give you and others confidence in switching over and make it easier to implement the big changes that will provide the greatest benefits.
 3. Decide whether you have a multi-project build or not
+
Multi-project builds are generally harder to migrate and require more work than single-project ones. We have provided some dedicated advice to help with the process in the <<migant:multi_project_builds,Migrating multi-project builds>> section.
 4. Work out what plugins to use for each project
+
We expect that the vast majority of Ant builds are for <<building_java_projects#building_java_projects,JVM-based projects>>, for which there are a wealth of plugins that provide a lot of the functionality you need. Not only are there the <<plugin_reference#plugin_reference,core plugins>> that come packaged with Gradle, but you can also find many useful plugins on the https://plugins.gradle.org/[Plugin Portal].
+
Even if the <<java_plugin#java_plugin,Java Plugin>> or one of its derivatives (such as the <<java_library_plugin#java_library_plugin,Java Library Plugin>>) aren't a good match for your build, you should at least consider the <<base_plugin#base_plugin,Base Plugin>> for its lifecycle tasks.
 5. Import the Ant build or create a Gradle build from scratch
+
This step very much depends on the requirements of your build. If a selection of Gradle plugins can do the vast majority of the work your Ant build does, then it probably makes sense to create a fresh Gradle build script that doesn't depend on the Ant build and either implements the missing pieces itself or <<ant#sec:using_ant_tasks,utilizes existing Ant tasks>>.
+
The alternative approach is to <<ant#sec:import_ant_build,import the Ant build>> into the Gradle build script and gradually replace the Ant build functionality. This allows you to have a working Gradle build at each stage, but it requires a bit of work to get the Gradle tasks working properly with the Ant ones. You can learn more about this approach in <<migant:imported_builds,Working with an imported build>>.
 6. Configure your build for the existing directory and file structure
+
Gradle makes use of conventions to eliminate much of the boilerplate associated with older builds and to make it easier for users to work with new builds once they are familiar with those conventions. But that doesn't mean you have to follow them.
+
Gradle provides many configuration options that allow for a good degree of customization. Those options are typically made available through the plugins that provide the conventions. For example, the standard source directory structure for production Java code — `src/main/java` — is provided by the Java Plugin, which allows you to <<building_java_projects#sec:custom_java_source_set_paths,configure a different source path>>. Many paths can be modified via properties on the link:{groovyDslPath}/org.gradle.api.Project.html[Project] object.
 7. Migrate to standard Gradle conventions if you wish
+
Once you're confident that the Gradle build is producing the same artifacts and other resources as the Ant build, you can consider migrating to the standard conventions, such as for source directory paths. Doing so will allow you to remove the extra configuration that was required to override those conventions. New team members will also find it easier to work with the build after the change.
+
It's up to you to decide whether this step is worth the time, energy and potential disruption that it might incur, which in turn depends on your specific build and team.

The rest of the chapter covers some common scenarios you will likely deal with during the migration, such as dependency management and working with Ant tasks.

[[migant:imported_builds]]
== Working with an imported build

The first step of many migrations will involve <<ant#sec:import_ant_build,importing an Ant build>> using `ant.importBuild()`. If you do that, how do you then move towards a standard Gradle build without replacing everything at once?

The important thing to remember is that the Ant targets become real Gradle tasks, meaning you can do things like modify their task dependencies, attach extra task actions, and so on. This allows you to substitute native Gradle tasks for the equivalent Ant ones, maintaining any links to other existing tasks.

As an example, imagine that you have a Java library project that you want to migrate from Ant to Gradle. The Gradle build script has the line that imports the Ant build and now want to use the standard Gradle mechanism for compiling the Java source files. However, you want to keep using the existing `package` task that creates the library's JAR file.

In diagrammatic form, the scenario looks like the following, where each box represents a target/task:

image::ant-task-migration.png[]

The idea is to substitute the standard Gradle `compileJava` task for the Ant `build` task. There are several steps involved in this substitution:

 1. Applying the <<java_library_plugin#java_library_plugin,Java Library Plugin>>
+
This provides the `compileJava` task shown in the diagram.
 2. Renaming the old `build` task
+
The name `build` conflicts with the standard `build` task provided by the <<base_plugin#base_plugin,Base Plugin>> (via the Java Library Plugin).
 3. Configuring the compilation to use the existing directory structure
+
There's a good chance the Ant build does not conform to the standard Gradle directory structure, so you need to tell Gradle where to find the source files and where to place the compiled classes so `package` can find them.
 4. Updating task dependencies
+
`compileJava` must depend on `prepare`, `package` must depend on `compileJava` rather than `ant_build`, and `assemble` must depend on `package` rather than the standard Gradle `jar` task.

Applying the plugin is as simple as inserting a  `plugins {}` block at the beginning of the Gradle build script, i.e. before `ant.importBuild()`. Here's how to apply the Java Library Plugin:

.Applying the Java Library Plugin
====
include::sample[dir="snippets/antMigration/importBuild/groovy",files="build.gradle[tags=apply-plugin]"]
include::sample[dir="snippets/antMigration/importBuild/kotlin",files="build.gradle.kts[tags=apply-plugin]"]
====

To rename the `build` task, use the variant of link:{javadocPath}/org/gradle/api/AntBuilder.html#importBuild-java.lang.Object-org.gradle.api.Transformer-[AntBuilder.importBuild()] that accepts a transformer, like this:

.Renaming targets on import
====
include::sample[dir="snippets/antMigration/importBuild/groovy",files="build.gradle[tags=import-build]"]
include::sample[dir="snippets/antMigration/importBuild/kotlin",files="build.gradle.kts[tags=import-build]"]
====
<1> Renames the `build` target to `ant_build` and leaves all other targets unchanged

Configuring a different path for the sources is described in the <<building_java_projects#sec:custom_java_source_set_paths,Building Java & JVM projects>> chapter, while you can change the output directory for the compiled classes in a similar way.

Let's say the original Ant build stores these paths in Ant properties, `src.dir` for the Java source files and `classes.dir` for the output. Here's how you would configure Gradle to use those paths:

.Configuring the source sets
====
include::sample[dir="snippets/antMigration/importBuild/groovy",files="build.gradle[tags=source-sets]"]
include::sample[dir="snippets/antMigration/importBuild/kotlin",files="build.gradle.kts[tags=source-sets]"]
====

You should eventually aim to switch the standard directory structure for your type of project if possible and then you'll be able to remove this customization.

The last step is also straightforward and involves using the link:{groovyDslPath}/org.gradle.api.Task.html#org.gradle.api.Task:dependsOn[Task.dependsOn] property and link:{groovyDslPath}/org.gradle.api.Task.html#org.gradle.api.Task:dependsOn(java.lang.Object++[]++)[Task.dependsOn()] method to detach and link tasks. The property is appropriate for _replacing_ dependencies, while the method is the preferred way to add to the existing dependencies.

Here is the required task dependency configuration required by the example scenario, which should come after the Ant build import:

.Configuring the task dependencies
====
include::sample[dir="snippets/antMigration/importBuild/groovy",files="build.gradle[tags=task-dependencies]"]
include::sample[dir="snippets/antMigration/importBuild/kotlin",files="build.gradle.kts[tags=task-dependencies]"]
====
<1> Makes compilation depend on the `prepare` task
<2> Detaches `package` from the `ant_build` task and makes it depend on `compileJava`
<3> Detaches `assemble` from the standard Gradle `jar` task and makes it depend on `package` instead

That's it! These four steps will successfully replace the old Ant compilation with the Gradle implementation. Even this small migration will be a big help because you'll be able to take advantage of Gradle's <<java_plugin#sec:incremental_compile,incremental Java compilation>> for faster builds.

[TIP]
====
This is just a demonstration of how to go about performing a migration in stages. It may make more sense to include resource processing — like with properties files — and packaging with the compilation in this stage, since all three aspects are well integrated in Gradle.
====

One important question you will have to ask yourself is how many tasks to migrate in each stage. The larger the chunks you can migrate in one go the better, but this must be offset against how many custom steps within the Ant build will be affected by the changes.

For example, if the Ant build follows a fairly standard approach for compilation, static resources, packaging and unit tests, then it is probably worth migrating all those together. But if the build performs some extra processing on the compiled classes, or does something unique when processing the static resources, it is probably worth splitting those tasks into separate stages.

[[migant:managing_dependencies]]
== Managing dependencies

Ant builds typically take one of two approaches to dealing with binary <<dependency_management_terminology#sub:terminology_dependency,dependencies>> (such as libraries):

 * Storing them with the project in a local "lib" directory
 * Using https://ant.apache.org/ivy/[Apache Ivy] to manage them

They each require a different technique for the migration to Gradle, but you will find the process straightforward in either case. We look at the details of each scenario in the following sections.

[[migant:filesystem_deps]]
=== Serving dependencies from a directory

When you are attempting to migrate a build that stores its dependencies on the filesystem, either locally or on the network, you should consider whether you want to eventually move to managed dependencies using remote repositories. That's because you can incorporate filesystem dependencies into a Gradle build in one of two ways:

 * Define a <<declaring_repositories.adoc#sub:flat_dir_resolver,flat-directory repository>> and use standard dependency declarations
 * Attach the files directly to the appropriate dependency configurations (<<declaring_dependencies#sub:file_dependencies,file dependencies>>)

It's easier to migrate to managed dependencies served from Maven- or Ivy-compatible repositories if you take the first approach, but doing so requires all your files to conform to the naming convention "<moduleName>-<version>.<extension>".

[NOTE]
====
If you store your dependencies in the standard Maven repository layout — `<repoDir>/<group>/<module>/<version>` — then you can define a <<declaring_repositories.adoc#sec:declaring_custom_repository,custom Maven repository>> with a "file://" URL.
====

To demonstrate the two techniques, consider a project that has the following library JARs in its `libs` directory:

[listing]
libs
├── our-custom.jar
├── log4j-1.2.8.jar
└── commons-io-2.1.jar

The file `our-custom.jar` lacks a version number, so it has to be added as a file dependency.
But the other two JARs match the required naming convention and so can be declared as normal <<declaring_dependencies#sub:module_dependencies,module dependencies>> that are retrieved from a flat-directory repository.

The following sample build script demonstrates how you can incorporate all of these libraries into a build:

.Declaring dependencies served from the filesystem
====
include::sample[dir="snippets/antMigration/fileDeps/groovy",files="build.gradle[tags=file-deps]"]
include::sample[dir="snippets/antMigration/fileDeps/kotlin",files="build.gradle.kts[tags=file-deps]"]
====
<1> Specifies the path to the directory containing the JAR files
<2> Declares a _file dependency_ for the unversioned JAR
<3> Declares dependencies using standard dependency coordinates — note that no group is specified, but each identifier has a leading `:`, implying an empty group

The above sample will add `our-custom.jar`, `log4j-1.2.8.jar` and `commons-io-2.1.jar` to the `implementation` configuration, which is used to compile the project's code.

[NOTE]
====
You can also specify a group in these module dependencies, even though they don't actually have a group. That's because the flat-directory repository simply ignores the information.

If you then add a normal Maven- or Ivy-compatible repository at a later date, Gradle will preferentially download the module dependencies that are declared with a group from that repository rather than the flat-directory one.
====

[[migant:ivy_deps]]
=== Migrating Ivy dependencies

Apache Ivy is a standalone dependency management tool that is widely used with Ant. It works in a similar fashion to Gradle. In fact, they both allow you to

 * Define your own <<dependency_management_terminology#sub:terminology_configuration,configurations>>
 * Extend configurations from one another
 * Attach dependencies to configurations
 * Resolve dependencies from Ivy-compatible repositories
 * Publish artifacts to Ivy-compatible repositories

The most notable difference is that Gradle has standard configurations for specific types of projects.
For example, the <<java_plugin#tab:configurations,Java Plugin>> defines configurations like `implementation`, `testImplementation` and `runtimeOnly`.
You can still <<declaring_dependencies.adoc#sec:defining-custom-configurations,define your own dependency configurations>>, though.

This similarity means that it's usually quite straightforward to migrate from Ivy to Gradle:

 * Transcribe the dependency declarations from your module descriptors into the link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:dependencies(groovy.lang.Closure)[dependencies {}] block of your Gradle build script, ideally using the standard configurations provided by any plugins you apply.
 * Transcribe any configuration declarations from your module descriptors into the link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:configurations(groovy.lang.Closure)[configurations {}] block of the build script for any custom configurations that can't be replaced by Gradle's standard ones.
 * Transcribe the resolvers from your Ivy settings file into the link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:repositories(groovy.lang.Closure)[repositories {}] block of the build script.

See the chapters on <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,Managing Dependency Configurations>>, <<declaring_dependencies.adoc#sec:dependency-types,Declaring Dependencies>> and <<declaring_repositories.adoc#declaring-repositories,Declaring Repositories>> for more information.

Ivy provides several Ant tasks that handle Ivy's process for fetching dependencies. The basic steps of that process consist of:

 1. _Configure_ — applies the configuration defined in the Ivy settings file
 2. _Resolve_ — locates the declared dependencies and downloads them to the cache if necessary
 3. _Retrieve_ — copies the cached dependencies to another directory

Gradle's process is similar, but you don't have to explicitly invoke the first two steps as it performs them automatically. The third step doesn't happen at all — unless you create a task to do it — because Gradle typically uses the files in the dependency cache directly in classpaths and as the source for assembling application packages.

Let's look in more detail at how Ivy's steps map to Gradle:

Configuration::
Most of Gradle's dependency-related configuration is baked into the build script, as you've seen with elements like the `dependencies {}` block. Another particularly important configuration element is link:{groovyDslPath}/org.gradle.api.artifacts.ResolutionStrategy.html[resolutionStrategy], which can be accessed from dependency configurations. This provides many of the features you might get from Ivy's conflict managers and is a powerful way to control transitive dependencies and caching.
+
Some Ivy configuration options have no equivalent in Gradle. For example, there are no lock strategies because Gradle ensures that its dependency cache is concurrency safe, period. Nor are there "latest strategies" because it's simpler to have a reliable, single strategy for conflict resolution. If the "wrong" version is picked, you can easily override it using forced versions or other resolution strategy options.
+
See the chapter on <<dependency_constraints.adoc#dependency-constraints,controlling transitive dependencies>> for more information on this aspect of Gradle.

Resolution::
At the beginning of the build, Gradle will automatically resolve any dependencies that you have declared and download them to its cache.
It searches the repositories for those dependencies, with the search order defined by <<declaring_repositories.adoc#sec:declaring_multiple_repositories,the order in which the repositories are declared>>.
+
It's worth noting that Gradle supports the same dynamic version syntax as Ivy, so you can still use versions like `1.0.+`. You can also use the special `latest.integration` and `latest.release` labels if you wish. If you decide to use such <<dynamic_versions.adoc#sub:declaring_dependency_with_dynamic_version,dynamic>> and <<dynamic_versions.adoc#sub:declaring_dependency_with_changing_version,changing>> dependencies, you can configure the caching behavior for them via link:{groovyDslPath}/org.gradle.api.artifacts.ResolutionStrategy.html[resolutionStrategy].
+
You might also want to consider <<dependency_locking#dependency-locking,dependency locking>> if you're using dynamic and/or changing dependencies. It's a way to make the build more reliable and allows for https://reproducible-builds.org/[reproducible builds].

Retrieval::
As mentioned, Gradle does not automatically copy files from the dependency cache. Its standard tasks typically use the files directly. If you want to copy the dependencies to a local directory, you can use a link:{groovyDslPath}/org.gradle.api.tasks.Copy.html[Copy] task like this in your build script:
+
.Copying dependencies to a local directory
====
include::sample[dir="snippets/antMigration/fileDeps/groovy",files="build.gradle[tags=retrieve-deps]"]
include::sample[dir="snippets/antMigration/fileDeps/kotlin",files="build.gradle.kts[tags=retrieve-deps]"]
====
+
A configuration is also a file collection, hence why it can be used in the `from()` configuration. You can use a similar technique to attach a configuration to a compilation task or one that produces documentation. See the chapter on <<working_with_files#working_with_files,Working with Files>> for more examples and information on Gradle's file API.

[[migant:ivy_publishing]]
== Publishing artifacts

Projects that use Ivy to manage dependencies often also use it for publishing JARs and other artifacts to repositories. If you're migrating such a build, then you'll be glad to know that Gradle has built-in support for publishing artifacts to Ivy-compatible repositories.

Before you attempt to migrate this particular aspect of your build, read the <<publishing_setup.adoc#publishing_overview,Publishing>> chapter to learn about Gradle's publishing model.
That chapter's examples are based on Maven repositories, but the same model is used for Ivy repositories as well.

The basic migration process looks like this:

 * Apply the <<publishing_ivy#publishing_ivy,Ivy Publish Plugin>> to your build
 * <<publishing_ivy#publishing_ivy:publications,Configure at least one publication>>, representing what will be published (including additional artifacts if desired)
 * <<publishing_ivy#publishing_ivy:repositories,Configure one or more repositories to publish artifacts to>>

Once that's all done, you'll be able to generate an Ivy module descriptor for each publication and publish them to one or more repositories.

Let's say you have defined a publication named "myLibrary" and a repository named "myRepo". Ivy's Ant tasks would then map to the Gradle tasks like this:

 * `<deliver>` -> `generateDescriptorFileForMyLibraryPublication`
 * `<publish>` -> `publishMyLibraryPublicationToMyRepoRepository`

There is also a convenient `publish` task that publishes _all_ publications to _all_ repositories.
If you'd prefer to limit which publications go to which repositories, check out the <<publishing_customization.adoc#sec:publishing_maven:conditional_publishing,relevant section of the Publishing chapter>>.

.On dependency versions
[NOTE]
====
Ivy will, by default, automatically replace dynamic versions of dependencies with the resolved "static" versions when it generates the module descriptor. Gradle does _not_ mimic this behavior: declared dependency versions are left unchanged.

You can replicate the default Ivy behavior by using the https://plugins.gradle.org/plugin/nebula.ivy-resolved-dependencies[Nebula Ivy Resolved Plugin]. Alternatively, you can link:{groovyDslPath}/org.gradle.api.publish.ivy.IvyModuleDescriptorSpec.html#org.gradle.api.publish.ivy.IvyModuleDescriptorSpec:withXml(org.gradle.api.Action)[customize the descriptor file] so that it contains the versions you want.
====

[[migant:custom_tasks]]
== Dealing with custom Ant tasks

One of the advantages of Ant is that it's fairly easy to create a custom task and incorporate it into a build. If you have such tasks, then there are two main options for migrating them to a Gradle build:

 * <<ant#sec:using_custom_ant_tasks,Using the custom Ant task>> from the Gradle build
 * Rewriting the task as a <<custom_tasks#custom_tasks,custom Gradle task type>>

The first option is usually quick and easy, but not always. And if you want to integrate the task into incremental build, you must use the <<more_about_tasks#sec:task_input_output_runtime_api,incremental build runtime API>>. You also often have to work with Ant paths and filesets, which are clunky.

The second option is preferable in the long term, if you have the time. Gradle task types tend to be simpler than Ant tasks because they don't have to work with an XML-based interface. You also gain access to Gradle's rich APIs. Lastly, this approach can make use of the <<more_about_tasks#sec:task_input_output_annotations,type-safe incremental build API>> based on typed properties.

[[migant:working_with_files]]
== Working with files

Ant has many tasks for working with files, most of which have Gradle equivalents. As with other areas of Ant to Gradle migration, you can <<ant#sec:using_ant_tasks,use those Ant tasks>> from within your Gradle build. However, we strongly recommend migrating to native Gradle constructs where possible so that the build benefits from:

 * <<more_about_tasks#sec:up_to_date_checks,Incremental build>>
 * Easier integration with other parts of the build, such as dependency configurations
 * More idiomatic build scripts

That said, it can be convenient to use those Ant tasks that have no direct equivalents, such as `<checksum>` and `<chown>`. Even then, in the long run it may be better to convert these to native Gradle task types that make use of standard Java APIs or third-party libraries to achieve the same thing.

Here are the most common file-related elements used by Ant builds, along with the Gradle equivalents:

 * `<copy>` — prefer the Gradle link:{groovyDslPath}/org.gradle.api.tasks.Copy.html[Copy] task type
 * `<zip>` (plus Java variants) — prefer the link:{groovyDslPath}/org.gradle.api.tasks.bundling.Zip.html[Zip] task type (plus link:{groovyDslPath}/org.gradle.api.tasks.bundling.Jar.html[Jar], link:{groovyDslPath}/org.gradle.api.tasks.bundling.War.html[War], and link:{groovyDslPath}/org.gradle.plugins.ear.Ear.html[Ear])
 * `<unzip>` — prefer using the link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:zipTree(java.lang.Object)[Project.zipTree()] method with a `Copy` task

You can see several examples of Gradle's file API and learn more about it in the <<working_with_files#working_with_files,Working with Files>> chapter.

.On paths and filesets
[NOTE]
====
Ant makes use of the concepts of path-like structures and filesets to enable users to work with collections of files and directories. Gradle has a simpler, more powerful model based on link:{javadocPath}/org/gradle/api/file/FileCollection.html[FileCollection]s and link:{javadocPath}/org/gradle/api/file/FileTree.html[FileTree]s that can be treated as objects from within the build. Both types allow filtering based on Ant's glob syntax, e.g. `++**/books_*++`. Learn more about these types and other aspects of Gradle's file API in the <<working_with_files#working_with_files,Working with Files>> chapter.

You can still construct Ant paths and filesets from within your build via the `ant` object if you need to interact with an Ant task that requires them. The chapter on <<ant#ant,Ant integration>> has examples that use both `<path>` and `<fileset>`. There is even link:{javadocPath}/org/gradle/api/file/FileCollection.html#addToAntBuilder-java.lang.Object-java.lang.String-org.gradle.api.file.FileCollection.AntType-[a method on `FileCollection`] that will convert a file collection to a fileset or similar Ant type.
====

[[migant:properties]]
== Migrating Ant properties

Ant makes use of a properties map to store values that can be reused throughout the build. The big downsides to this approach are that property values are all strings and the properties themselves behave like global variables.

.Interacting with Ant properties in Gradle
[TIP]
====
Sometimes you will want to make use of an Ant task directly from your Gradle build and that task requires one or more Ant properties to be set. If that's the case, you can easily set those properties via the `ant` object, as described in the <<ant#sec:ant_properties,Using Ant from Gradle>> chapter.
====

Gradle does use something similar in the form of <<build_environment#sec:project_properties,project properties>>, which are a reasonable way to parameterize a build. These can be set from the command line, in a <<build_environment#sec:gradle_configuration_properties,`gradle.properties` file>>, or even via specially named system properties and environment variables.

If you have existing Ant properties files, you can copy their contents into the project's `gradle.properties` file. Just be aware of two important points:

 * Properties set in `gradle.properties` **do not** override <<writing_build_scripts#sec:extra_properties,extra project properties>> defined in the build script with the same name
 * Imported Ant tasks will not automatically "see" the Gradle project properties — you must copy them into the Ant properties map for that to happen

Another important factor to understand is that a Gradle build script works with an object-oriented API and it's often best to use the properties of tasks, source sets and other objects where possible. For example, this build script fragment creates tasks for packaging Javadoc documentation as a JAR and unpacking it, linking tasks via their properties:

.Using task properties in place of project properties
====
include::sample[dir="snippets/antMigration/fileDeps/groovy",files="build.gradle[tags=properties]"]
include::sample[dir="snippets/antMigration/fileDeps/kotlin",files="build.gradle.kts[tags=properties]"]
====
<1> Packages all ``javadoc``'s output files — equivalent to `from javadoc.destinationDir`
<2> Uses the location of the Javadoc JAR held by the `javadocJar` task
<3> Uses an project property called `tmpDistDir` to define the location of the 'dist' directory

As you can see from the example with `tmpDistDir`, there is often still a need to define paths and the like through properties, which is why Gradle also provides <<writing_build_scripts#sec:extra_properties,extra properties>> that can be attached to the project, tasks and some other types of objects.

[[migant:multi_project_builds]]
== Migrating multi-project builds

Multi-project builds are a particular challenge to migrate because there is no standard approach in Ant for either structuring them or handling inter-project dependencies. Most of them likely use the `<ant>` task in some way, but that's about all that one can say.

Fortunately, Gradle's multi-project support can handle fairly diverse project structures and it provides much more robust and helpful support than Ant for constructing and maintaining multi-project builds. The `ant.importBuild()` method also handles `<ant>` and `<antcall>` tasks transparently, which allows for a phased migration.

We will suggest one process for migration here and hope that it either works for your case or at least gives you some ideas. It breaks down like this:

 1. Start by learning <<multi_project_builds#multi_project_builds,how Gradle configures multi-project builds>>.
 2. Create a Gradle build script in each project of the build, setting their contents to this line:
+
[source.multi-language-sample,groovy]
----
ant.importBuild 'build.xml'
----
+
[source.multi-language-sample,kotlin]
----
ant.importBuild("build.xml")
----
+
Replace `build.xml` with the path to the actual Ant build file that corresponds to the project. If there is no corresponding Ant build file, leave the Gradle build script empty. Your build may not be suitable in that case for this migration approach, but continue with these steps to see whether there is still a way to do a phased migration.
 3. Create a settings file that link:{groovyDslPath}/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:include(java.lang.String++[]++)[includes all the projects] that now have a Gradle build script.
 4. Implement inter-project dependencies.
+
Some projects in your multi-project build will depend on artifacts produced by one or more other projects in that build. Such projects need to ensure that those projects they depend on have produced their artifacts and that they know the paths to those artifacts.
+
Ensuring the production of the required artifacts typically means calling into other projects' builds via the `<ant>` task. This unfortunately bypasses the Gradle build, negating any changes you make to the Gradle build scripts. You will need to replace targets that use `<ant>` tasks with Gradle <<more_about_tasks#sec:adding_dependencies_to_tasks,task dependencies>>.
+
For example, imagine you have a web project that depends on a "util" library that's part of the same build. The Ant build file for "web" might have a target like this:
+
====
include::sample[dir="snippets/antMigration/multiProject/groovy",files="web/build.xml[tags=build-required]"]
====
<1> `root.dir` would have to be defined by the build
+
This can be replaced by an inter-project task dependency in the corresponding Gradle build script, as demonstrated in the following example that assumes the "web" project's "compile" task is the thing that requires "util" to be built beforehand:
+
====
include::sample[dir="snippets/antMigration/multiProject/groovy",files="web/build.gradle[]"]
include::sample[dir="snippets/antMigration/multiProject/kotlin",files="web/build.gradle.kts[]"]
====
+
This is not as robust or powerful as Gradle's <<declaring_dependencies_between_subprojects#sec:project_jar_dependencies,project dependencies>>, but it solves the immediate problem without big changes to the build. Just be careful to remove or override any dependencies on tasks that delegate to other subprojects, like the `buildRequiredProjects` task.
 5. Identify the projects that have no dependencies on other projects and migrate them to idiomatic Gradle builds scripts.
+
Just follow the advice in the rest of this guide to migrate individual project builds. As mentioned elsewhere, you should ideally use Gradle standard plugins where possible. This may mean that you need to add an extra copy task to each build that copies the generated artifacts to the location expected by the rest of the Ant builds.
 6. Migrate projects as and when they depend solely on projects with fully migrated Gradle builds.
+
At this point, you should be able to switch to using proper project dependencies attached to the appropriate dependency configurations.
 7. Clean up projects once no part of the Ant build depends on them.
+
We mentioned in step 5 that you might need to add copy tasks to satisfy the requirements of dependent Ant builds. Once those builds have been migrated, such build logic will no longer be needed and should be removed.

At the end of the process you should have a Gradle build that you are confident works as it should, with much less build logic than before.

== Further reading

This chapter has covered the major topics that are specific to migrating Ant 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

As a final note, this guide has only touched on a few of Gradle's features and we encourage you to learn about the rest from the other chapters of the user manual and from our link:../samples/index.html[step-by-step samples].
