In this example, we will see one of the easiest way to use ivy. No settings 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 <a href="../tutorial.html">tutorials home page</a>, 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 definitely recommended to put it in a separate file. For ivy dependencies, it depends on your usage and is discussed on the <a href="../bestpractices.html">best practices page</a>.

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

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

<h1>The ivy.xml file</h1>
This file is used to describe the dependencies of the project on other libraries.
Here is the sample: 
<code type="xml">
<ivy-module version="1.0">
    <info organisation="jayasoft" module="hello-ivy" />
    <dependencies>
        <dependency org="apache" name="commons-lang" rev="2.0" />
    </dependencies>
</ivy-module>
</code>

<h1>The build.xml file</h1>
The build file corresponding to use it, contains only:
<code type="xml">
<project xmlns:ivy="antlib:fr.jayasoft.ivy.ant" name="hello-ivy" default="run">
    
    ...
    
    
    <target name="resolve" description="--> retrieve dependencies with ivy">
        <ivy:retrieve />
    </target>
</project>
</code>
<h1>Running the project</h1>
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 :
<div class="shell"><pre>
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</pre></div>
<h1>What happened ?</h1>
Without any settings, other than it's default settings, 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:
<div class="shell"><pre>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</pre></div>
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 <a href="../samples/jayasoft-ivyrep-example-default.html">this</a>.

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