mirror of https://github.com/apache/ant-ivy
127 lines
8.1 KiB
Plaintext
127 lines
8.1 KiB
Plaintext
////
|
|
Licensed to the Apache Software Foundation (ASF) under one
|
|
or more contributor license agreements. See the NOTICE file
|
|
distributed with this work for additional information
|
|
regarding copyright ownership. The ASF licenses this file
|
|
to you 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
|
|
|
|
https://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.
|
|
////
|
|
|
|
= Ivy Quickstart
|
|
|
|
In this tutorial, you will see one of the simplest ways to use Ivy. With no specific settings, Ivy uses the Maven 2 repository to resolve the dependencies you declare in an Ivy file. Let's have a look at the content of the files involved.
|
|
|
|
_You'll find this tutorial's sources in the Ivy distribution in the src/example/hello-ivy directory._
|
|
|
|
|
|
== The ivy.xml file
|
|
|
|
This file describes the dependencies of the project on other libraries. Here is the sample:
|
|
|
|
[source, xml]
|
|
----
|
|
|
|
<ivy-module version="2.0">
|
|
<info organisation="org.apache" module="hello-ivy"/>
|
|
<dependencies>
|
|
<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
|
|
<dependency org="commons-cli" name="commons-cli" rev="1.0"/>
|
|
</dependencies>
|
|
</ivy-module>
|
|
|
|
----
|
|
|
|
The format of this file should be pretty easy to understand, but let's discuss some details about what is declared here. First, the root element is `ivy-module`, with the `version` attribute telling Ivy which lowest version of Ivy this file is compatible with.
|
|
|
|
Then there is an `info` tag, which provides information about the module for which we are defining dependencies. Here we define only the `organization` and `module` names. You are free to choose whatever you want for them, but we recommend avoiding spaces for both.
|
|
|
|
Finally, the `dependencies` section lets you define dependencies. In this example, this module depends on two libraries: `commons-lang` and `commons-cli`. As you can see, we use the `org` and `name` attributes to define the organization and module name of the dependencies we need. The `rev` attribute is used to specify the version of the module you depend on.
|
|
|
|
To know what to put in these attributes, you need to know the exact information for the libraries you depend on. Ivy uses the Maven 2 central repository by default, so we recommend you use link:https://mvnrepository.com[mvnrepository.com] to look for the module you want. Once you find it, you will have the details of that module in the `pom.xml` file of that module. For instance:
|
|
|
|
[source, xml]
|
|
----
|
|
<project ....>
|
|
<groupId>commons-lang</groupId>
|
|
<artifactId>commons-lang</artifactId>
|
|
<version>2.0</version>
|
|
...
|
|
----
|
|
|
|
To convert this into an Ivy dependency declaration, all you have to do is use the `groupId` as organization, the `artifactId` as module name, and the version as revision. That's what we did for the dependencies in this tutorial, that is `commons-lang` and `commons-cli`. Note that having `commons-lang` and `commons-cli` as `organization` is not the best example of what the organization should be. It would be better to use `org.apache`, `org.apache.commons` or `org.apache.commons.lang`. However, this is how these specific modules were identified in the Maven 2 repository, so the simplest way to get them is to use the details as is (you will see in link:../tutorial/build-repository{outfilesuffix}[Building a repository] that you can use namespaces to redefine these names if you want something cleaner).
|
|
|
|
If you want more details on what you can do in Ivy files, you can have a look at the link:../ivyfile{outfilesuffix}[Ivy files reference documentation].
|
|
|
|
== The build.xml file
|
|
|
|
The corresponding build file contains a set of targets, allowing you to resolve dependencies declared in the Ivy file, to compile and run the sample code, produce a report of dependency resolution, and clean the cache or the project.
|
|
You can use the standard `ant -p` command to get the list of available targets. Feel free to have a look at the whole file, but here is the part relevant to dependency resolution:
|
|
|
|
[source, xml]
|
|
----
|
|
|
|
<project xmlns:ivy="antlib:org.apache.ivy.ant" name="hello-ivy" default="run">
|
|
|
|
...
|
|
|
|
<!-- =================================
|
|
target: resolve
|
|
================================= -->
|
|
<target name="resolve" description="--> retrieve dependencies with Ivy">
|
|
<ivy:retrieve/>
|
|
</target>
|
|
</project>
|
|
|
|
----
|
|
|
|
As you can see, it's very easy to call Ivy to resolve and retrieve dependencies: all you need if Ivy is properly link:../install{outfilesuffix}[installed] is to define an XML namespace in your Ant file (`xmlns:ivy="antlib:org.apache.ivy.ant"`). Then all the link:../ant{outfilesuffix}[Ivy Ant tasks] will be available in this namespace.
|
|
|
|
Here we use only one task: the link:../use/retrieve{outfilesuffix}[retrieve] task. With no attributes, it will use default settings and look for a file named `ivy.xml` for the dependency definitions. That's exactly what we want, so we need nothing more than that.
|
|
|
|
Note that in this case we define a `resolve` target and call the `link:../use/retrieve{outfilesuffix}[retrieve]` task. This may sound confusing, actually the retrieve task performs a link:../use/resolve{outfilesuffix}[resolve] (which resolves dependencies and downloads them to a cache) followed by a retrieve (a copy of those file to a local project directory). Check the link:../principle{outfilesuffix}[How does it work ?] page for details about that.
|
|
|
|
== Running the project
|
|
|
|
OK, now that we have seen the files involved, let's run the sample to see what happens. Open a shell (or command line) window, and go into the `hello-ivy` example directory.
|
|
Then, at the command prompt, run `ant`:
|
|
|
|
[source, shell]
|
|
----
|
|
|
|
include::asciidoc/tutorial/log/hello-ivy-1.txt[]
|
|
|
|
----
|
|
|
|
|
|
|
|
== What happened ?
|
|
|
|
Without any settings, Ivy retrieves files from the Maven 2 repository. That's what happened here.
|
|
The resolve task has found the `commons-lang` and `commons-cli` modules in the Maven 2 central repository, identified that `commons-cli` depends on `commons-logging` and so resolved it as a transitive dependency. Then Ivy has downloaded all corresponding artifacts in its cache (by default in your user home, in a `.ivy2/cache` directory). Finally, the retrieve task copies the resolved jars from the Ivy cache to the default library directory of the project: the `lib` dir (you can change this easily by setting the pattern attribute on the link:../use/retrieve{outfilesuffix}[retrieve] task).
|
|
|
|
You might say that the task took a long time just to write out a "Hello Ivy!" message. But remember that a lot of time was spent downloading the required files from the web. Let's try to run it again:
|
|
|
|
[source,shell]
|
|
----
|
|
|
|
include::asciidoc/tutorial/log/hello-ivy-2.txt[]
|
|
|
|
----
|
|
|
|
|
|
Great! The cache was used, so no download was needed and the build was instantaneous.
|
|
|
|
And now, if you want to generate a report detailing all the dependencies of your module, you can call the report target, and check the generated file in the build directory. You should obtain something looking like link:../samples/apache-hello-ivy-default{outfilesuffix}[this].
|
|
|
|
As you can see, using Ivy to resolve dependencies stored in the Maven 2 repository is extremely easy. Now you can go on with the other tutorials to learn more about link:../tutorial/conf{outfilesuffix}[how to use module configurations] which is a very powerful Ivy specific feature. More tutorials are also available where you will learn how to use Ivy settings to leverage a possibly complex enterprise repository. It may also be a good time to start reading the link:../reference{outfilesuffix}[reference documentation], and especially the introduction material which gives a good overview of Ivy. The link:../bestpractices{outfilesuffix}[best practices] page is also a must read to start thinking about how to use Ant+Ivy to build a clean and robust build system.
|