== What and Why === [[what-is-ivy]]What is Apache Ivy™ ? Apache Ivy™ is a powerful dependencies manager with transitive dependencies support and much more link:features.html[features]. With Apache Ivy you define the dependencies of your module in an xml file, called an ivy-file. Then you usually ask Apache Ivy to retrieve your dependencies to a local lib dir, and it does it for you by locating the artifacts of your dependencies in repositories, such as a maven2 repository for instance. === [[why-should-i-use-a-dependencies-manager]]Why should I use a dependencies manager ? Without a dependencies manager, two solutions are often used to store the dependencies of a project: a project lib dir or direct access to a shared repository. The major drawback of the project lib dir is that the same dependencies are stored in multiple location if you have several projects using the same dependencies. Moreover, we often see project where dependencies revisions are not documented, which can cause problems for maintenance. With the shared repository the problem is often to maintain the list of dependencies of the project. This list is often lost within the build file, which does not help maintenance. Moreover, this solution often requires a download of the whole repository, unless home made dependencies management solution has been used. Another major drawback of these solutions is that they do not use transitive dependencies. Transitive dependencies are the dependencies of your dependencies. Managing transitive dependencies let you declare dependencies only on what you really need, and not what the module you use themselves need. This not only eases your dependencies declaration, but it also improves a lot the maintenability of your project, especially in multi-project environment. Imagine you develop a component used in several other projects. Then each time your component needs a new dependency, without transitive dependencies, you have to update all the projects using your component ! And this could really take a lot of time ! === [[why-should-i-use-ivy]]Why should I use Apache Ivy ? If you are convinced of using a dependencies manager, you may wonder why using Apache Ivy and not another tool. We are not able to answer this question without being biased, but have a look at Apache Ivy link:features.html[features] and the link:m2comparison.html[product comparison] we provide, and you will certainly see that Apache Ivy is one of the best dependencies manager currently available ;-) === [[how-does-ivy-differ-from-maven-2]]How does Apache Ivy differ from Apache Maven™ ? The answer to this question is too long, so it deserves its own page link:m2comparison.html[here]. == Apache Ivy in use === [[i-dont-understand-whats-happening]]I don't understand what's happening... The first thing to do when you don't understand what's going wrong is to try to change the message level. If you use Apache Ant™, you can use the -debug or -verbose options to get more detailed messages and better understand what's happening. === [[ivy-seems-to-fail-connecting]]Apache Ivy seems to fail connecting to ibiblio... First, check if the ibiblio site is ok with your favorite browser. If the site is ok, maybe it's a problem of proxy configuration. Set your ANT_OPTS environment variable to configure your proxy if you have one. For instance: [source] ---- set ANT_OPTS=-Dhttp.proxyHost=myproxy -Dhttp.proxyPort=3128 ---- Or for authenticated proxy: [source] ---- set ANT_OPTS=-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=myproxyusername -Dhttp.proxyPassword=myproxypassword -Dhttps.proxyHost=myproxyhost -Dhttps.proxyPort=8080 ---- If it still doesn't work, maybe it's your dependency file which is not ok. Check if the module name you depend on is actually a name of directory under link:http://www.ibiblio.org/maven/[www.ibiblio.org/maven/]. If this is the case, check if the jar with a name like [module]-[revision].jar is present under the jars directory of this module on ibiblio. For instance: link:http://www.ibiblio.org/maven/commons-httpclient/jars/commons-httpclient-2.0.jar[www.ibiblio.org/maven/commons-httpclient/jars/commons-httpclient-2.0.jar] If this is the case, check your configuration to see if you actually use the ibiblio resolver. Finally, you can check if the files were downloaded but corrupted by checking your lib directory and opening the jars if any with an unzip program. Apache Ivy has sha1/md5 checking, but not all repositories contains such checksums. If you still have problems post your issue on the link:mailing-lists.html[Mailing lists] mentioning your OS, your version of Apache Ant, your version of Apache Ivy, your configuration file and your ivy-file. === [[ivy-fails-to-get-an-artifact]]Apache Ivy fails to get an artifact on my http server. What's wrong? The first thing to do is to ensure the setting is correct. Apache Ivy should log the url it tried, copy this url and paste it in your favorite browser, and verify you get no error. If this is ok, check if you don't need any proxy setting nor authentication. For proxy setting, you can use for instance this: [source] ---- set ANT_OPTS=-Dhttp.proxyHost=myproxy -Dhttp.proxyPort=3128 ---- Or for authenticated proxy: [source] ---- set ANT_OPTS=-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=myproxyusername -Dhttp.proxyPassword=myproxypassword -Dhttps.proxyHost=myproxyhost -Dhttps.proxyPort=8080 ---- For http authentication, fill in the appropriate data at link:history/latest-milestone/use/configure.html[configuration] time. If you still have no idea of what is wrong, then link:#httpclient-lib-install[setup Ivy to use Apache HTTP Client library] and turn on the debug logging for that library. You will then have very detailed information on how your url is handled. If you still have problem, ask for help on the link:mailing-lists.html[Mailing lists]. === [[getting-rid-of-lib-directory]]What if I do not want to put my library files in the lib directory ? No problem, you just have to set an ant property: [source] ---- ---- === [[getting-rid-of-revision]]What if I do not want the revision of the files I retrieve to appear in the file name ? A typical question for people using an IDE like eclipse and often changing dependency revision: it's a bit boring to change your IDE project just to tell him to use comp-build2596.jar instead of comp-build2595.jar, when you have already changed your ivy file (and even if you haven't changed it, if you use the continuous integration feature !). No problem, you have a total control on the files retrieved using the pattern attribute in the retrieve task: Here is the default pattern: [source] ---- ---- And here is one which do not suffix file name with dependency revision: [source] ---- ---- And one which makes your lib directory have the same layout as the ibiblio repository: [source] ---- ---- Not too difficult, and really flexible, isn't it ? And check the retrieve task reference documentation to learn more about it... === [[why-two-xml-files]]Why two xml files ? Apache Ivy uses two types of xml files: settings files and ivy files. In fact, Apache Ivy distinguishes two different steps to describe and get your dependencies: * You write ivy files to describe the dependencies of your module, independently of how you retrieve them. * Then you configure Apache Ivy to indicate where it can find your dependencies. Thus you can easily share your ivy files, even if you have internal dependencies which are not resolved the same way in your environment as in the target development environment. You just need to write two settings files, one in your default development environment, and one in the target development environment with the *same ivy files*. === [[how-do-i-separate-dependencies]]How do I separate the dependencies I need at xxx time and the one I need at yyy time ? Apache Ivy uses a concept called __configurations__ to handle this, and many more. As explained in the link:history/latest-milestone/terminology.html[terminology page], a __configuration__ of your module can be thought as a way to use your module (__note: this has nothing to do with the configuration of Apache Ivy itself, through the use of configuration file__). You can describe what dependencies are needed in each configuration. Moreover, because the dependencies are modules too, they can also have configurations. What is extremely powerful with Apache Ivy is that you can define configurations mapping, i.e. which conf of the dependency is needed in which conf of your module. Thus what is needed at 'runtime' of a dependency can be needed for 'test' of your module. Finally, the configurations are unlimited, defined in each module, and can extend each other. This contributes a lot to the flexibility of Apache Ivy. === [[no-artifact]]Can I write an ivy file for a module with no artifact at all ? Yes, this is what is called a 'virtual' module. Having a module which has no publication and only dependencies can be useful in many cases. In particular, you can in this way define a set of dependencies used in several projects. Once defined, you can simply add a dependency on this virtual module to get all its dependencies, thanks to transitive dependencies management. It can also be useful if you want to define a flexible framework. In your framework, you will certainly have several modules, each having its own dependencies. But for the users of your framework, it can be interesting to provide a virtual module, representing the framework as a whole, and using configurations to let the user choose what he really wants to use in your framework, in a very flexible and effective way. But the problem is that Apache Ivy considers by default that a module publishes one artifact, with the same name as the module itself. So the way to define a virtual module is to add to its ivy file a publications section with no publication inside: [source] ---- ---- === [[ibiblio-module-missing]]I do not manage to get xxx module on ibiblio. What's wrong ? The problem can come from several places... usually it comes from the fact that some modules on ibiblio do not respect a clean structure. For instance, opensymphony projects are all in an opensymphony directory, which does not respect the [module]/[artifact]-[revision].[ext] pattern. In this case the only way to go with this is to configure another resolver with the appropriate pattern, and configure Apache Ivy to use this resolver for opensymphony only. Another similar problem is to have several modules in one directory, such xerces and xmlapis in the xerces directory. The problem is that if you consider the two as one module, you will be tempted to declare a dependency on two revisions of this module. This is not the right approach, because this does not match the Apache Ivy definition of a module. A better approach is similar to the preceding one with a special configuration for this only. Another solution is to setup a local repository for those modules that are not cleanly deployed on ibiblio. Using this local repository first and the ibiblio repository after is a good way to turn around the problems of ibiblio and still benefit from the huge number of artifacts that can be found. === [[module-update]]When I update an ivy file in my repository ivy do not take the change into account. Is this normal ? This the default behaviour of Apache Ivy, which relies on the revision and on its cache to avoid too many downloads. However, this can be changed on each resolver using the _checkmodified_ attribute, or globally by setting _ivy.resolver.default.check.modified_ variable to true. === [[threaded-use]]When I use Ivy within an ant parallel task, I get surprising behavior. What's going on here? The majority of Ivy's code is not written to be thread-safe. At this time, such usage is not supported behavior. === [[httpclient-lib-install]]How do I setup Ivy to use Apache HTTP Client library? Ivy doesn't mandate the use of Apache HTTP client library, for dealing with HTTP backed resolvers. By default, Ivy uses necessary APIs available in Java for handling HTTP access. However, we do recommend the usage of Apache HTTP client library, given that its more feature rich and performant than the basic implementation shipped in Java. Starting 2.5.0-rc1 of Ivy, we use link:https://hc.apache.org/httpcomponents-client-4.5.x/index.html[4.5.x version of Apache HTTP client]. In order to make Ivy use this library, place this library's jar and its dependency jars in Ivy's build classpath. Please refer to the Apache HTTP client library's project documentation for details about where to get the jar and its dependencies from. == Misc === [[release-notes]]Where are the release notes ? Release notes can be found in the link:history/latest-milestone/index.html[documentation]. === [[more-information]]Where can I get more information? If you need more information about Ivy than the one found in the documentation, you can see the link:links.html[links] page, use the link:mailing-lists.html[Mailing lists] to ask your question to the community, or use your favorite search engine. For search engine search, we advise to use ivy + ant or java as base keywords, since ivy alone is a very common word.