Quick Start

In this example, we will see one of the easiest way to use ivy. No configuration or other complicated files to write, only the list of libraries the project will use.

If you have already followed the go-ivy tutorial on the tutorials home page, this tutorial will be already familiar. It is actually pretty much the same, except that it requires ivy to be installed in your ant lib, and the java source and the ivy dependencies are available in separate files. For the java source, it's definitly recommended to put it in a separate file. For ivy dependencies, it depends on your usage and is discussed on the best pratices page.

But enough introduction material, let's go with this simple tutorial!

You'll find this tutorial sources in the ivy distribution in the src/example/hello-ivy directory.

The ivy.xml file

This file is used to describe the dependencies of the project on other libraries.
Here is the sample:

The build.xml file

The build file corresponding to use it, contains only:

Running the project

To run the sample, open a dos (or shell) window, and go under the hello-ivy example directory.
Then, on the command prompt, just run ant :

I:\hello-ivy>ant
Buildfile: build.xml

resolve:
:: Ivy 1.0-rc3 - 20050421161206 :: http://ivy.jayasoft.org/ ::
no configuration file found, using default...
:: resolving dependencies :: jayasoft/hello-ivy-working@xmen
        confs: [default]
downloading http://www.ibiblio.org/maven/commons-lang/jars/commons-lang-2.0.jar(2.0) ...
..................................... (165kB)
        [SUCCESSFUL ] apache/commons-lang-2.0/commons-lang.jar[jar] (4688ms)
:: resolution report ::
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   1   |   1   |   0   |   0   ||   1   |   1   |
        ---------------------------------------------------------------------
:: retrieving :: jayasoft/hello-ivy
        confs: [default]
        1 artifacts copied, 0 already retrieved

run:
    [mkdir] Created dir: I:\hello-ivy\build
    [javac] Compiling 1 source file to I:\hello-ivy\build
     [java] standard message : hello ivy !
     [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !

BUILD SUCCESSFUL
Total time: 8 seconds

What happened ?

Without any configuration, other than it's default configuration, ivy retrieve files from the maven ibiblio libraries repository. That's what happened here.
The resolve task has downloaded the commons-lang.jar file from ibiblio, then copied it to the ivy cache and then dispatch it in the default library directory of the project : the lib dir.
Some will say that the task was long to achieve. Yeah, it's true it was, but it has downloaded from the web the needed file. Let's try to run it again:

I:\hello-ivy>ant
Buildfile: build.xml

resolve:
:: resolving dependencies :: jayasoft/hello-ivy-null :: [default]
:: resolution report ::
        [default] jayasoft/hello-ivy-working@rahan: 1 artifacts (0 downloaded)
:: retrieving :: jayasoft/hello-ivy :: [default]

run:
     [java] standard message : hello ivy !
     [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !

BUILD SUCCESSFUL
Total time: 1 second

Great ! the cache was used, no download was needed and the build was instantaneous.

If you want to check the content of the cache, by default it is put in your user home in a .ivy/cache directory.

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

You are now ready to go to the next tutorials to go one step beyond using ivy transitive dependencies management.