Using Ivy Module Configurations


This tutorial introduces the use of module configurations in ivy files. Ivy module configurations is indeed a very important concept. Someone even told me one day that using Ivy without using configurations is like eating a good cheese without touching the glass of Chateau Margaux 1976 you have just aside :-)

More seriously, configurations in ivy can be better understood as views on your module, and you will see how they can be used efficiently here.

Reference documentation on configurations can be found here and here.

Introduction

Source code available in src/example/configurations/multi-projects.
We have two projects :
- filter-framework is a library that defines an api to filter String arrays and two implementations of this api.
- myapp is a very small app that uses filter-framework.

The library produces 3 artifacts:
- the api jar,
- an implementation jar with no external dependency,
- an other implementation that needs commons-collections to perform.

The application only need api to compile and can use any of the two implementation at runtime.

The library project

The first project we defined in this tutorial is the filter-framework.
In order to have a fine grained artifacts publication definition, we defined configurations to map usage other can make of our library.

The ivy.xml file

<ivy-module version="1.0">
    <info organisation="org.apache" module="filter-framework"/>
    <configurations>
    	<conf name="api"  description="only provide filter framework API"/>
    	<conf name="homemade-impl" extends="api" description="provide a home made implementation of our api"/>
    	<conf name="cc-impl" extends="api" description="provide an implementation that use apache common collection framework"/>
    	<conf name="test" extends="cc-impl" visibility="private" description="for testing our framework"/>
    </configurations>
    <publications>
    	<artifact name="filter-api" type="jar"  conf="api" ext="jar"/>
    	<artifact name="filter-hmimpl" type="jar"  conf="homemade-impl" ext="jar"/>
    	<artifact name="filter-ccimpl" type="jar"  conf="cc-impl" ext="jar"/>    	
    </publications>
    <dependencies>
        <dependency org="commons-collections" name="commons-collections" rev="3.1" conf="cc-impl->default"/>
        <dependency org="junit" name="junit" rev="3.8" conf="test->default"/>
    </dependencies>
</ivy-module>

Explanation

As you can see we defined 3 public configurations and a private one (defined junit dependency for testing).
The 2 implementations conf homemade-impl, cc-impl extends api configuration so artifacts defined in api will also be required in its extending conf.
In the publications tag we defined the artifacts we produce (here it's jars) and we affect them a configuration.
Later when others will use our library they will have a very flexible way to define what they need.

See it in action

The library project is build using ant. Open a shell in the root directory of the project and type ant. 
Buildfile: src\example\configurations\multi-projects\filter-framework\build.xml

clean:

resolve:
[ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071105200109 - 20071105200109 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] No ivy:settings found for the default reference 'ivy.instance'.  A default instance will be used
[ivy:retrieve] no settings file found, using default...
[ivy:retrieve] :: loading settings :: url = jar:file:/c:/dev/data/opensource_workspace/ivy/build/artifact/ivy-core.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: [ org.apache | filter-framework | working@BEN-ScokartG ]
[ivy:retrieve] 	confs: [api, homemade-impl, cc-impl, test]
[ivy:retrieve] 	found [ commons-collections | commons-collections | 3.1 ] in public
[ivy:retrieve] 	found [ junit | junit | 3.8 ] in public
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-collections/commons-collections/3.1/commons-collections-3.1.jar ...
[ivy:retrieve] .............................................................................
[ivy:retrieve] ..............................................................................................
[ivy:retrieve] .................................................
[ivy:retrieve] ..................................................................................................
[ivy:retrieve] ................................................... (546kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] 	[SUCCESSFUL ] [ commons-collections | commons-collections | 3.1 ]/commons-collections.jar[jar] (8322ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/junit/junit/3.8/junit-3.8.jar ...
[ivy:retrieve] ...............................................................................
[ivy:retrieve] ...... (118kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] 	[SUCCESSFUL ] [ junit | junit | 3.8 ]/junit.jar[jar] (3015ms)
[ivy:retrieve] :: resolution report ::
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|        api       |   0   |   0   |   0   |   0   ||   0   |   0   |
	|   homemade-impl  |   0   |   0   |   0   |   0   ||   0   |   0   |
	|      cc-impl     |   1   |   1   |   0   |   0   ||   1   |   1   |
	|       test       |   2   |   2   |   0   |   0   ||   2   |   2   |
	---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: [ org.apache | filter-framework ]
[ivy:retrieve] 	confs: [api, homemade-impl, cc-impl, test]
[ivy:retrieve] 	3 artifacts copied, 0 already retrieved

build:
    [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\build
    [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\distrib
    [javac] Compiling 4 source files to C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\build
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.
      [jar] Building jar: C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\distrib\filter-api.jar
      [jar] Building jar: C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\distrib\filter-hmimpl.jar
      [jar] Building jar: C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\distrib\filter-ccimpl.jar

test:
    [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\build\test-report
    [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\build\test-classes
    [javac] Compiling 3 source files to C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\build\test-classes
    [junit] Running filter.ccimpl.CCFilterTest
    [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0.02 sec
    [junit] Running filter.hmimpl.HMFilterTest
    [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 0 sec

publish:
[ivy:publish] :: delivering :: [ org.apache | filter-framework | working@BEN-ScokartG ] :: 1.3 :: release :: Mon Nov 05 21:10:46 CET 2007
[ivy:publish] 	delivering ivy file to C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\filter-framework\distrib/ivy.xml
[ivy:publish] :: publishing :: [ org.apache | filter-framework ]
[ivy:publish] 	published filter-hmimpl to C:\Documents and Settings\scokartg\.ivy2\local/org.apache/filter-framework/1.3/jars/filter-hmimpl.jar
[ivy:publish] 	published filter-api to C:\Documents and Settings\scokartg\.ivy2\local/org.apache/filter-framework/1.3/jars/filter-api.jar
[ivy:publish] 	published filter-ccimpl to C:\Documents and Settings\scokartg\.ivy2\local/org.apache/filter-framework/1.3/jars/filter-ccimpl.jar
[ivy:publish] 	published ivy to C:\Documents and Settings\scokartg\.ivy2\local/org.apache/filter-framework/1.3/ivys/ivy.xml
     [echo] project filter-framework released with version 1.3

BUILD SUCCESSFUL
Total time: 20 seconds
The ant's default target is publish.
This target uses ivy to publish our library binaries in a local repository.
As we do not specify any repository path the default one is used. ({home.dir}/.ivy2/local/org.apache/filter-framework/)
Now we are ready to use our library.

The application project

Now that we have shipped our fantastic library, we want to use it!
The tutorial comes with a sample application called myapp.

The ivy.xml file

<ivy-module version="1.0">
    <info organisation="org.apache" module="myapp"/>
    
    <configurations>
       	<conf name="build" visibility="private" description="compilation only need api jar" />
    	<conf name="noexternaljar" description="use only company jar" />
    	<conf name="withexternaljar" description="use company jar and third party jars" />    
    </configurations>
    
    <dependencies>
        <dependency org="org.apache" name="filter-framework" rev="latest.integration" conf="build->api; noexternaljar->homemade-impl; withexternaljar->cc-impl"/>
    </dependencies>
</ivy-module>

Explanation

We create 3 configurations that define the way we want to use the application.
The build configuration defines the compile-time dependencies, and thus only needs the api conf from filter-framework.
The other configurations define runtime dependencies. One will only use "home-made" jars, and the other will use external jars.

We also defined a dependency on the previous library.
In the dependency we use configuration mapping to match ours and library configurations.
You can found more information on configuration mapping here
  1. build->api : here we tell ivy that our build configuration depends on the api configuration of the dependcy
  2. noexternaljar->homemade-impl : here we tell ivy that our noexternaljar configuration depends on the homemade-impl configuration of the dependcy.
  3. withexternaljar->cc-impl : here we tell ivy that our withexternaljar configuration depends on the cc-impl configuration of the dependcy
Note that we never declare any of the dependency artifacts we need in each configuration: it's the dependency module file which declares the published artifacts and which should be used in each configuration.

In the ant buld.xml file we defined a resolve target as follow:
<target name="resolve" description="--> retreive dependencies with ivy">
    <ivy:retrieve pattern="${ivy.lib.dir}/[conf]/[artifact].[ext]"/>
</target>
When we call this target, Ivy will do a resolve using our ivy.xml file in the root folder and then retrieve all the artifacts. The artifacts retrieved are kept in separate folders according to the configurations they belong to. Here is how your lib directory should look like after a call to this target: 
 Repertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib

01/24/2006  11:19 AM              build
01/24/2006  11:19 AM              noexternaljar
01/24/2006  11:19 AM              withexternaljar
               0 fichier(s)                0 octets

 Repertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib\build

01/24/2006  10:53 AM             1,174 filter-api.jar
               1 fichier(s)            1,174 octets

 Repertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib\noexternaljar

01/24/2006  10:53 AM             1,174 filter-api.jar
01/24/2006  10:53 AM             1,030 filter-hmimpl.jar
               2 fichier(s)            2,204 octets

 Repertoire de D:\ivy\src\example\configurations\multi-projects\myapp\lib\withexternaljar
01/24/2006  10:53 AM           559,366 commons-collections.jar
01/24/2006  10:53 AM             1,174 filter-api.jar
01/24/2006  10:53 AM             1,626 filter-ccimpl.jar
               3 fichier(s)          562,166 octets
As you can see for each configuration we have now a set of jars.

Let's try to launch our app.

See it in action

Use ant to run the application.
Default ant target is run-cc and will launch application using the Apache commons-collections implementation. 
Buildfile: src\example\configurations\multi-projects\myapp\build.xml

resolve:
[ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071104204849 - 20071104204849 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] No ivy:settings found for the default reference 'ivy.instance'.  A default instance will be used
[ivy:retrieve] no settings file found, using default...
[ivy:retrieve] :: loading settings :: url = jar:file:/c:/dev/data/opensource_workspace/ivy/build/artifact/ivy-core.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: [ org.apache | myapp | working@BEN-ScokartG ]
[ivy:retrieve] 	confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] 	found [ org.apache | filter-framework | 1.3 ] in local
[ivy:retrieve] 	[1.3] [ org.apache | filter-framework | latest.integration ]
[ivy:retrieve] 	found [ commons-collections | commons-collections | 3.1 ] in public
[ivy:retrieve] downloading C:\Documents and Settings\scokartg\.ivy2\local\org.apache\filter-framework\1.3\jars\filter-api.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] 	[SUCCESSFUL ] [ org.apache | filter-framework | 1.3 ]/filter-api.jar[jar] (40ms)
[ivy:retrieve] downloading C:\Documents and Settings\scokartg\.ivy2\local\org.apache\filter-framework\1.3\jars\filter-hmimpl.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] 	[SUCCESSFUL ] [ org.apache | filter-framework | 1.3 ]/filter-hmimpl.jar[jar] (20ms)
[ivy:retrieve] downloading C:\Documents and Settings\scokartg\.ivy2\local\org.apache\filter-framework\1.3\jars\filter-ccimpl.jar ...
[ivy:retrieve] .. (1kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve] 	[SUCCESSFUL ] [ org.apache | filter-framework | 1.3 ]/filter-ccimpl.jar[jar] (80ms)
[ivy:retrieve] :: resolution report ::
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|       build      |   1   |   1   |   0   |   0   ||   1   |   1   |
	|   noexternaljar  |   1   |   1   |   0   |   0   ||   2   |   2   |
	|  withexternaljar |   2   |   1   |   0   |   0   ||   3   |   2   |
	---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: [ org.apache | myapp ]
[ivy:retrieve] 	confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] 	6 artifacts copied, 0 already retrieved

build:
    [mkdir] Created dir: C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\myapp\build
    [javac] Compiling 1 source file to C:\dev\data\opensource_workspace\ivy\src\example\configurations\multi-projects\myapp\build

run-cc:
     [java] Filtering with:class filter.ccimpl.CCFilter
     [java] Result :[two, tree]

BUILD SUCCESSFUL
Total time: 4 seconds
Launching application with only home made jars is straightforward.
type ant run-hm
Buildfile: src\example\configurations\multi-projects\myapp\build.xml

resolve:
[ivy:retrieve] :: Ivy 2.0.0-beta1-local-20071104204849 - 20071104204849 :: http://ant.apache.org/ivy/ ::
[ivy:retrieve] No ivy:settings found for the default reference 'ivy.instance'.  A default instance will be used
[ivy:retrieve] no settings file found, using default...
[ivy:retrieve] :: loading settings :: url = jar:file:/c:/dev/data/opensource_workspace/ivy/build/artifact/ivy-core.jar!/org/apache/ivy/core/settings/ivysettings.xml
[ivy:retrieve] :: resolving dependencies :: [ org.apache | myapp | working@BEN-ScokartG ]
[ivy:retrieve] 	confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] 	found [ org.apache | filter-framework | 1.3 ] in local
[ivy:retrieve] 	[1.3] [ org.apache | filter-framework | latest.integration ]
[ivy:retrieve] 	found [ commons-collections | commons-collections | 3.1 ] in public
[ivy:retrieve] :: resolution report ::
	---------------------------------------------------------------------
	|                  |            modules            ||   artifacts   |
	|       conf       | number| search|dwnlded|evicted|| number|dwnlded|
	---------------------------------------------------------------------
	|       build      |   1   |   1   |   0   |   0   ||   1   |   0   |
	|   noexternaljar  |   1   |   1   |   0   |   0   ||   2   |   0   |
	|  withexternaljar |   2   |   1   |   0   |   0   ||   3   |   0   |
	---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: [ org.apache | myapp ]
[ivy:retrieve] 	confs: [build, noexternaljar, withexternaljar]
[ivy:retrieve] 	0 artifacts copied, 6 already retrieved

build:

run-hm:
     [java] Filtering with:class filter.hmimpl.HMFilter
     [java] Result :[two, tree]

BUILD SUCCESSFUL
Total time: 3 seconds
Nice we got the same result but we can see that implementation classes are different.

Conclusion

You should use configurations as often as possible
Configurations are very important concept in ivy. They allow you to group artifacts by meaning.
When you write ivy file for projects that are supposed to be reused, use configurations to allow people to get only they what they need without having to specify it by hand using artifact tag in dependency section.