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