Skip navigation.

Best practices

Here are some recommendations and best practices we have gathered throughout our experience and consultancies with our customers.

Add module descriptors for all your modules

In Ivy world, module descriptors are ivy files, which are basically simple xml files describing both what the module produce as artifact and its dependencies.

It is a good practice to write or download module descriptors for all the modules involved in your development, even for your third party dependencies, and even if they don't provide themselves such module descriptors.

First it will seem like an extra work, and require time. But when you will have several modules using the same third party library, and than you will only need to add one line to your ivy file to get this library and all its own dependencies that you really need (if you have good module descriptors in your repository, especially with the use of module configurations). It will also be very helpful when you want to upgrade a dependency. One single change in your module ivy file and you will get the updated version with its updated (or not) dependencies.

Therefore we recommend to add ivy files for all the modules in your repository, you can even enforce this rule by setting the allownomd attribute to false on your resolvers. Hence you shouldn't need to use the dependency artifact inclusion/exclusion/specification feature of Ivy, which should only be used in very specific cases.

Use your own enterprise repository

This is usually not a valid recommendation for open source projects, but for the enterprise world we strongly suggest to avoid relying on a public repository like maven ibiblio or ivyrep. Why? Well, there are a couple of reasons:

  • control
  • The main problem with this kind of public repositories is that you don't have control over the repository. This means that if a module descriptor is broken you cannot easily fixed it. Sure you can use a chain between a shared repository and the public one and put your fixed module descriptor in the shared repository so that it hide the one on the public repository, but this makes repository browsing and maintenance cumbersome.
    Even more problematic is the possible updates of the repository. We know that versions published in such repositories should be stable and not be updated, but we also frequently see that a module descriptor is buggy, or an artifact corrupted. We even see sometimes a new version published with the same name as the preceding one because the previous one was simply badly packaged. This can occur even to the best, it occured to us with Ivy 1.2 :-) But then we decided to publish the new version with a different name, 1.2a. But if the repository manager allow such updates, this means that what worked before can break. It can thus break your build reproducibility.

  • reliability
  • Ibiblio maven repository is not particularly well known for its reliability (we often experience major slow down or even complete break of the site), and ivyrep is only supported by a small company (yes we are only a small company!). So slow down and site hang occurs also. And if the repository you rely on is down, this can cause major slow down in your development or release process.

  • accuracy
  • a public repository usually contains much more than what you actually need (except maybe ivyrep which certainly features much less than what you need :-)). Is it a problem? We think so. We think that in an enterprise environment the libraries you use should step through some kind of validation process before being used in every projects of your company. And what better way to do so? Setup an enterprise repository with only the libraries you actually want to use. This will not only ensure a better quality of your application dependencies, but help to have the same versions everywhere, and even help when declaring your module dependencies, if you use a tool like IvyDE, the code completion will only show relevant information about your repository, with only the libraries you actually want to see.

Note that it's not because you use an enterprise repository that you have to build it entirely by hand. Ivy features an install task which can be used to install modules from a repository to another one, so it can be used to selectively install modules from a public repository to your enterprise repository, where you will then be able to ensure control, reliability and accuracy.

Always use patterns with at least organisation and module

Ivy is very flexible and can accomodate a lot of existing repositories, using the concept of patterns. But if your repository doesn't exist yet, we strongly recommend to always use the organisation and the module name in your pattern, even for private repository where you put only your own modules (which all the same organisation). Why? Because Ivy listing feature rely on the token it can find in the pattern. If you have no organisation token in your pattern, Ivy won't be able to list the (only?) organisation in your repository. And this can be a problem for code completion in IvyDE, for example, but also for repository wide tasks like install or rereport.

Public ivyconf.xml with public repositories

If you create a public repository, provide an url to corresponding ivyconf.xml. It's pretty easy to do, and if someone want to leverage your repository, he will just have to call configure with the url of your ivyconf.xml, or include it in its own configuration file, which makes it really easy to combine several public repositories.

Dealing with integration versions

Very often especially when working in a team or with several modules, you will need to rely on intermediate, non finalized versions of your modules. These versions are what we call integration versions, because their main objective is to be integrated with other modules to make and test an application or a framework.

If you follow the continuous integration paradigm across modules, these integration versions can be produced by a continuous integration server, very frequently.

So, how can you deal with these, possibly numerous, integration versions?

There are basically two ways to deal with them, both ways being supported by Ivy:

  • use a naming convention like a special suffix
  • the idea is pretty simple, each time you publish a new integration of your module you give the same name to the version (in maven world this is for example 1.0-SNAPSHOT). The dependency manager should then be aware that this version is special because it changes over time, so that it does not trust its local cache if it already has the version, but check the date of the version on the repository and see if it hass changed. In Ivy this is supported using the changing attribute on a dependency or by configuring the changing pattern to use for all your modules.

  • create automatically a new version for each
  • in this case you use either a build number or a timestamp to publish each new integration version with a new version name. Then you can use one of the numerous ways in Ivy to express a version constraint. Usually selecting the very latest one (using 'latest.integration' as version constraint) is enough.

So, which way is the best? As often, it depends on your context, and if one of the two was really bad it wouldn't be supported in Ivy :-)

But usually we recommend to use the second one, because using a new version each time you publish a new version better fits the version identity paradigm, and can make all your builds reproducible, even integration one. And this is interesting because it enables, with some work in your build system, to introduce a mechanism to promote an integration build to a more stable status, like a milestone or a release.

Imagine you have a customer which comes on a monday morning and asks your latest version of your software, for testing or demonstration purpose. Obviously he needs it for the afternoon :-) Now if you have a continuous integration process and a good tracking of your changes and your artifacts, it may occur that you are actually able to fulfill his request without needing the use of a dolorean to give you some more time :-) But it may occur also that your latest version stable enough to be used for the purpose of the customer was actually built a few days ago, because the very latest just break a feature or introduce a new one you don't want to deliver. In this case, you can deliver this 'stable' integration build if you want, but be sure that a few days, or weeks, or even months later, the customer will ask for a bug fix on this demo only version. Why? Because it's a customer, and we all know how they are :-)

So, with a build promotion feature of any build in your repository, the solution would be pretty easy: when the customer ask for the version, you not only deliver the integration build, but you also promote it to a milestone status, for example. this promotion indicates that you should keep track of this version in a long period, to be able to come back to it and create a branch if needed.

Unfortunately Ivy does not by its own allow to have such reproducible builds out of the box, simply because Ivy is a dependency manager, not a build tool. But if you publish only versions with a distinct name and use Ivy features like versions constraint replacement during the publication or recursive delivery of modules, it can really help.

On the other hand, the main drawback of this solution is that it can produce a lot of intermediate versions, and you will have to run some cleaning scripts in your repository unless your company name starts with a G and ends with oogle :-)

Inlining dependencies or not?

With Ivy 1.4 you can resolve a dependency without even writing an ivy file. This pratice is called inlining. But what is it good for, and when should it be avoided?

Putting ivy dependencies in a separate file has the following advantages:

  • separate revision cycle
  • if your dependencies may change more often than your build, it's a good idea to separate the two, to isolate the two concepts: describing how to build / describing your project dependencies

  • possibility to publish
  • if you describe dependencies of a module which can itself be reused, you will ant to publish it to a repository. In this case the publication is only possible if you have a separate ivy file

  • more flexible
  • inline dependencies can only be used to express one dependency and only one. An ivy file can be used to express much more complex dependencies

On the other hand, using inline dependencies is very useful when:

  • you want to use a custom task in your ant build Without ivy you usually either copy the custom task jar in ant lib, which requires maintenance of your workstation installation, or use a manual copy or download and a taskdef with the appropriate classpath, which is better. But if you have several custom tasks, or if they have themselves dependencies, it can become cumbersome. Using Ivy with an inline dependency is an elegant way to solve this problem.
  • you want to easily deploy an application
  • If you already build your application and its modules using Ivy, it is really easy to leverage your ivy repository to download your application and all its dependencies on the local filesystem, ready to be executed. If you also put your configuration files as artifacts in your repository (maybee packaged as a zip), the whole installation process can rely on ivy, easing the automatic installation of any version of your application available in your repository!

Hire an expert

Build and dependency management is often considered with a too low level priority in the software development world. We often see build management implemented by developers when they have time. Even if this may seem like a time and money saving in the short term, it often turns out to be a very bad choice in the long term. Building software is not a simple task, when you want to ensure automatic, tested, fully reproducible builds, releases and installations. On the other hand, once a good build system fitting your very specific needs is setup, it can then only rely on a few people with a good understanding of what is going on, with a constant quality ensured.

Therefore hiring a build and dependency expert to analyse and improve your build and release system is most of the time a very good choice (especially if you choose the right one :-))


These best practices are the reflect of our own experience, but we do not pretend to own the unique truth about dependency management or even Ivy use.

So feel free to comment on this page to add your own experience feedback, suggestions or opinion.

a few use cases


I want to share with you a few use cases from my work.

1. XML schema module

Create a project (with its own Ivy module name) for XML schema sources.
The project contains just raw XSD (XML Schema) source files.
The "generated" artifacts are nothing but a zip file containing all the sources.

The benefits of using Ivy here is the versioning: any "publish" task increments the build number and stores in the repository artifacts like: my-schema-1.0, my-schema-1.1, my-schema-2.0, etc.

Now you can "import" the schema sources to any other Ivy project (see below) as a dependency.

If you define and use versioning scheme correctly, you can also instantly see if a new version of XML schema sources is backwards-compatible (say it is 1.x) or not (say 2.0 and above). Latest strategy of "1.1+" would do the work.

2. Language specific auto code generation from XML Schema

Motivation: I have an XML Schema (see 1 above) and want to generate both Java and .NET web service code based on that schema.
(Schema in this context means XSD and WSDL files.)

I create two projects: Java web-service implementation and .NET web-service client. Both use the same version of the XML schema because both have the same Ivy dependency defined.

The Java project use Apache Axis and its wsdl2java to auto generate java webservice code.

The .NET project use Microsoft's "wsdl.exe" to auto generate c# web service client code.

I use Ivy to correctly version both Java and .NET projetcs and to import the same XML schema sources from the repository.

3. Ivy project for XML namespace to package mapping

Sometimes, you find yourself copying again and again the same settings or properties that are common to many projects.

For example, when Castor auto generate Java code from XML schema, it can use "namespace to package" properties file telling it how to map each XML namespace to Java package name.

Defining the XML-to-namespace as an Ivy project let you share these mappings between projects and to version the mapping itself.
Any project who does Castor auto Java code generation is declared to be depend on that mapping project, and the XML-namespace-to-Java-packages properties automatically included in your classpath thanks to Ivy "cachepath" task.

These are examples of how I use Ivy in my work. I will be glad to read another examples.


Very interesting use cases,

Very interesting use cases, thanks for sharing these ideas. What is interesting with what you show is that you do things that are possible to do without Ivy, but so painful that you never do them. Using a dependency manager tool like Ivy makes these things easy, then you can see your software packaging differently, isolating modules which are not necessarily only java modules.

In the same order of idea, for a customer I've setup a build which package configuration files and run scripts with applications. You can then do an install of any version published like that (i.e. any continuous integration build in their case) very easily. Using the retrieve task with the new inline mode, the install script is very simple. And installing the application can be done by running only one script, which retrieves the jars, the application files (configuration and run scripts), process them a little bit to adjust to the environment (automatically), and then launch the application. This is very simple to use and ease a lot the testing of the application.
Xavier Hanin
Jayasoft team member

Another use case

Another idea I have (not yet implemented it) is treating configuration, branding and localization as a separate modules. This makes it very easy to change application customization.

I will give a short example:

Let's say you have a simple "hello world" application that support localization. You want to be able to show "hello world" in any possible language.

Of course you use the i18n package and use resource boundles.

You actually have 3 parts in your application:
1. The application itself printing the message.
2. Per-language properties file containing a single key such as "helloWorld=bonjour monde"
3. A property file listing all the localized KEYS. Currently - only one: "helloWOrld".

Now, let's add another key to the application: "bye".

We have added it to (1) and (3) and to the french version of (2) but not to all other languages of (2).

the result? The application would fail on non-french installations Sad

The solution? Easy! Use Ivy! Smiling

1 depends on 3
2 also depends on 3

The version of (3) that has two dictionary words is 2.0. Not 1.0 as before. The application now depends also in dictionary-2.0 (3) to opeate properly.

The french localization has been enhanced to supprt the word "bye" so it's "dictionary-2.0 compliant", but the Italian localization is still "dictionary-1.0" compliant, so it's now easy to see that it could not work with the new application.

The next step is to enforce in runtime the dependencies and that really an easy job for Ivy...

The idea of the example is also usable for configuration keys, for branding keys (e.g. company logo URL in a web site), in API between client and server and so on.

The idea is simple: define both parties to be depend on the contract. Every one of those 3 parties (server, client and contract) is a separate module with its own version, managed by Ivy.


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.