asciidoc/tutorial/dependence.adoc - ant-ivy - Git at Google

 ////
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      https://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
 ////

 This tutorial will show you how to use Ivy when one of your projects depends on another.

 For our example, we will have two projects, depender and dependee, where the depender project uses/requires the dependee project. This example will help illustrate two things about Ivy:


 * that dependencies defined by parent projects (dependee) will automatically be retrieved for use by child projects (depender) +

 * that child projects can retrieve the "latest" version of the dependee project +


 == Projects used


 === dependee

 The dependee project is very simple. It depends on the Apache library commons-lang and contains only one class: `standalone.Main` which provides two services:


 * return the version of the project +

 * capitalize a string using `org.apache.commons.lang.WordUtils.capitalizeFully` +

 Here is the content of the project:


 * build.xml: the Ant build file for the project +

 * ivy.xml: the project Ivy file +

 * src/standalone/Main.java: the only class of the project +

 Take a look at the *ivy.xml* file:

 [source]
 ----

 <ivy-module version="1.0">
     <info organisation="org.apache" module="dependee"/>
     <dependencies>
         <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
     </dependencies>
 </ivy-module>

 ----

 The Ivy file declares only one dependency, that being the Apache commons-lang library.

 === depender

 The depender project is very simple as well. It declares only one dependency on the latest version of the dependee project, and it contains only one class, `depending.Main`, which does 2 things:


 * gets the version of the standalone project by calling `standalone.Main.getVersion()` +

 * transforms a string by calling `standalone.Main.capitalizeWords(str)` +

 Take a look at the `ivy.xml` file:

 [source]
 ----

 <ivy-module version="1.0">
     <info organisation="org.apache" module="depender"/>
     <dependencies>
         <dependency name="dependee" rev="latest.integration"/>
     </dependencies>
 </ivy-module>

 ----


 == Settings

 The Ivy settings are defined in two files located in the settings directory:


 * `ivysettings.properties`: a property file +

 * `ivysettings.xml`: the file containing the settings +


 Let's have a look at the `ivysettings.xml` file:

 [source]
 ----

 <ivysettings>
     <properties file="${ivy.settings.dir}/ivysettings.properties"/>
     <settings defaultResolver="libraries"/>
     <caches defaultCacheDir="${ivy.settings.dir}/ivy-cache"/>
     <resolvers>
         <filesystem name="projects">
             <artifact pattern="${repository.dir}/[artifact]-[revision].[ext]"/>
             <ivy pattern="${repository.dir}/[module]-[revision].xml"/>
         </filesystem>
         <ibiblio name="libraries" m2compatible="true" usepoms="false"/>
     </resolvers>
     <modules>
         <module organisation="org.apache" name="dependee" resolver="projects"/>
     </modules>
 </ivysettings>

 ----

 The file contains four main tags: properties, settings, resolvers and modules.

 === properties

 This tag loads some properties for the Ivy process, just like Ant does.

 === settings

 This tag initializes some parameters for the Ivy process. In this case, the directory that Ivy will use to cache artifacts will be in a sub directory called ivy-cache of the directory containing the `ivysettings.xml` file itself.
 The second parameter, tells Ivy to use a resolver named "libraries" as its default resolver. More information can be found in the link:../settings{outfilesuffix}[settings reference documentation].

 === resolvers

 This tag defines the resolvers to use. Here we have two resolvers defined: "projects" and "libraries".
 The filesystem resolver called "projects" is able to resolve the internal dependencies by locating them on the local filesystem.
 The ibiblio resolver called "libraries" is able to find dependencies on the Maven 2 repository, but doesn't use Maven POMs.

 === modules

 The modules tag allows you to configure which resolver should be used for which module. Here the setting tells Ivy to use the "projects" resolver for all modules having an organisation of `org.apache` and module name of `dependee`. This actually corresponds to only one module, but a regular expression could be used, or many other types of expressions (like glob expressions).

 All other modules (i.e. all modules but org.apache#dependee), will use the default resolver ("libraries").

 == Walkthrough


 === Step 1: Preparation

 Open a shell (or command line) window, and go to the `src/example/dependence` directory.


 === Step 2: Clean directory tree

 At the prompt, type: `ant`
 This will clean up the entire project directory tree. You can do this each time you want to clean up this example.


 === Step 3: Publication of dependee project

 Go to `dependee` directory  and publish the project

 [source,shell]
 ----

 include::asciidoc/tutorial/log/dependence-standalone.txt[]

 ----


 What we see here:


 * the project depends on 1 library (1 artifact) +

 * the library was not in the Ivy cache and so was downloaded (1 downloaded) +

 * the project has been released under version number 1 +


 As you can see, the call to the publish task has resulted in two main things:


 * the delivery of a resolved Ivy file to `build/ivy.xml`. +
 This has been done because by default, the publish task not only publishes artifacts, but also its Ivy file. So it has looked to the path where the Ivy file to publish should be, using the artifactspattern: `${build.dir}/[artifact].[ext]`. For an Ivy file, this resolves to `build/ivy.xml`. Because this file does not exist, it automatically makes a call to the deliver task which delivers a resolved Ivy file to this destination.


 * the publication of artifact 'dependee' and its resolved Ivy file to the repository. +
 Both are just copies of the files found in the current project, or more precisely, those in the `build` directory. This is because the artifactspattern has been set to `${build.dir}/[artifact].[ext]`, so the dependee artifact is found at `build/dependee.jar` and the Ivy file in `build/ivy.xml`. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to `repository/dependee-1.jar` and to `repository/dependee-1.xml`, respecting the artifact and Ivy file patterns of our settings (see above).


 === Step 4: Running the depender project

 Go to directory depender and run `ant`

 [source,shell]
 ----

 include::asciidoc/tutorial/log/dependence-depending.txt[]

 ----


 What we see here:


 * the project depends on 2 libraries (2 artifacts) +

 * one of the libraries was in the cache because there was only 1 download (1 downloaded) +

 * Ivy retrieved version 1 of the project "dependee". The call to `standalone.Main.getVersion()` has returned 1. If you look in the `depender/lib` directory, you should see `dependee-1.jar` which is the version 1 artifact of the project "dependee" +

 * the call to `standalone.Main.capitalizeWords(str)` succeed, which means that the required library was in the classpath. If you look at the `lib` directory, you will see that the library `commons-lang-2.0.jar` was also retrieved. This library was declared as a dependency of the "dependee" project, so Ivy retrieves it (transitively) along with the dependee artifact. +


 === Step 5: New version of dependee project

 Like we did before in step 3, publish the dependee project again. This will result in a new version of the project being published.

 [source,shell]
 ----

 include::asciidoc/tutorial/log/dependence-standalone-2.txt[]

 ----


 Now if you look in your repository folder, you will find 2 versions of the dependee project.
 Let's look at it:

 [source,shell]
 ----
 I:\dependee>dir ..\settings\repository /w

 [.]                [..]               dependee-1.jar   dependee-1.xml   dependee-2.jar   dependee-2.xml

 I:\dependee>
 ----


 OK, now our repository contains two versions of the project *dependee*, so other projects can refer to either version.


 === Step 6: Get the new version in _depender_ project

 What should we expect if we run the depender project again? It should:


 * retrieve version 2 as the latest.integration version of the dependee project +

 * display version 2 of dependee project +

 Let's try it!!

 [source,shell]
 ----

 include::asciidoc/tutorial/log/dependence-depending-2.txt[]

 ----


 OK, we got what we expected as the `run` target shows that we are using version 2 of the main class of the dependee project. If we take a look at the resolve target results, we see that one artifact has been downloaded to the Ivy cache. In fact, this file is the same version 2 of the dependee project that is in the repository, but now all future retrievals will pull it from your ivy-cache directory.
	////
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	https://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	////

	This tutorial will show you how to use Ivy when one of your projects depends on another.

	For our example, we will have two projects, depender and dependee, where the depender project uses/requires the dependee project. This example will help illustrate two things about Ivy:


	* that dependencies defined by parent projects (dependee) will automatically be retrieved for use by child projects (depender) +

	* that child projects can retrieve the "latest" version of the dependee project +


	== Projects used


	=== dependee

	The dependee project is very simple. It depends on the Apache library commons-lang and contains only one class: `standalone.Main` which provides two services:


	* return the version of the project +

	* capitalize a string using `org.apache.commons.lang.WordUtils.capitalizeFully` +

	Here is the content of the project:


	* build.xml: the Ant build file for the project +

	* ivy.xml: the project Ivy file +

	* src/standalone/Main.java: the only class of the project +

	Take a look at the ivy.xml file:

	[source]
	----

	<ivy-module version="1.0">
	<info organisation="org.apache" module="dependee"/>
	<dependencies>
	<dependency org="commons-lang" name="commons-lang" rev="2.0"/>
	</dependencies>
	</ivy-module>

	----

	The Ivy file declares only one dependency, that being the Apache commons-lang library.

	=== depender

	The depender project is very simple as well. It declares only one dependency on the latest version of the dependee project, and it contains only one class, `depending.Main`, which does 2 things:


	* gets the version of the standalone project by calling `standalone.Main.getVersion()` +

	* transforms a string by calling `standalone.Main.capitalizeWords(str)` +

	Take a look at the `ivy.xml` file:

	[source]
	----

	<ivy-module version="1.0">
	<info organisation="org.apache" module="depender"/>
	<dependencies>
	<dependency name="dependee" rev="latest.integration"/>
	</dependencies>
	</ivy-module>

	----


	== Settings

	The Ivy settings are defined in two files located in the settings directory:


	* `ivysettings.properties`: a property file +

	* `ivysettings.xml`: the file containing the settings +


	Let's have a look at the `ivysettings.xml` file:

	[source]
	----

	<ivysettings>
	<properties file="${ivy.settings.dir}/ivysettings.properties"/>
	<settings defaultResolver="libraries"/>
	<caches defaultCacheDir="${ivy.settings.dir}/ivy-cache"/>
	<resolvers>
	<filesystem name="projects">
	<artifact pattern="${repository.dir}/[artifact]-[revision].[ext]"/>
	<ivy pattern="${repository.dir}/[module]-[revision].xml"/>
	</filesystem>
	<ibiblio name="libraries" m2compatible="true" usepoms="false"/>
	</resolvers>
	<modules>
	<module organisation="org.apache" name="dependee" resolver="projects"/>
	</modules>
	</ivysettings>

	----

	The file contains four main tags: properties, settings, resolvers and modules.

	=== properties

	This tag loads some properties for the Ivy process, just like Ant does.

	=== settings

	This tag initializes some parameters for the Ivy process. In this case, the directory that Ivy will use to cache artifacts will be in a sub directory called ivy-cache of the directory containing the `ivysettings.xml` file itself.
	The second parameter, tells Ivy to use a resolver named "libraries" as its default resolver. More information can be found in the link:../settings{outfilesuffix}[settings reference documentation].

	=== resolvers

	This tag defines the resolvers to use. Here we have two resolvers defined: "projects" and "libraries".
	The filesystem resolver called "projects" is able to resolve the internal dependencies by locating them on the local filesystem.
	The ibiblio resolver called "libraries" is able to find dependencies on the Maven 2 repository, but doesn't use Maven POMs.

	=== modules

	The modules tag allows you to configure which resolver should be used for which module. Here the setting tells Ivy to use the "projects" resolver for all modules having an organisation of `org.apache` and module name of `dependee`. This actually corresponds to only one module, but a regular expression could be used, or many other types of expressions (like glob expressions).

	All other modules (i.e. all modules but org.apache#dependee), will use the default resolver ("libraries").

	== Walkthrough



	=== Step 1: Preparation

	Open a shell (or command line) window, and go to the `src/example/dependence` directory.



	=== Step 2: Clean directory tree

	At the prompt, type: `ant`
	This will clean up the entire project directory tree. You can do this each time you want to clean up this example.



	=== Step 3: Publication of dependee project

	Go to `dependee` directory and publish the project

	[source,shell]
	----

	include::asciidoc/tutorial/log/dependence-standalone.txt[]

	----


	What we see here:


	* the project depends on 1 library (1 artifact) +

	* the library was not in the Ivy cache and so was downloaded (1 downloaded) +

	* the project has been released under version number 1 +


	As you can see, the call to the publish task has resulted in two main things:


	* the delivery of a resolved Ivy file to `build/ivy.xml`. +
	This has been done because by default, the publish task not only publishes artifacts, but also its Ivy file. So it has looked to the path where the Ivy file to publish should be, using the artifactspattern: `${build.dir}/[artifact].[ext]`. For an Ivy file, this resolves to `build/ivy.xml`. Because this file does not exist, it automatically makes a call to the deliver task which delivers a resolved Ivy file to this destination.


	* the publication of artifact 'dependee' and its resolved Ivy file to the repository. +
	Both are just copies of the files found in the current project, or more precisely, those in the `build` directory. This is because the artifactspattern has been set to `${build.dir}/[artifact].[ext]`, so the dependee artifact is found at `build/dependee.jar` and the Ivy file in `build/ivy.xml`. And because we have asked the publish task to publish them using the "projects" resolver, these files are copied to `repository/dependee-1.jar` and to `repository/dependee-1.xml`, respecting the artifact and Ivy file patterns of our settings (see above).




	=== Step 4: Running the depender project

	Go to directory depender and run `ant`

	[source,shell]
	----

	include::asciidoc/tutorial/log/dependence-depending.txt[]

	----


	What we see here:


	* the project depends on 2 libraries (2 artifacts) +

	* one of the libraries was in the cache because there was only 1 download (1 downloaded) +

	* Ivy retrieved version 1 of the project "dependee". The call to `standalone.Main.getVersion()` has returned 1. If you look in the `depender/lib` directory, you should see `dependee-1.jar` which is the version 1 artifact of the project "dependee" +

	* the call to `standalone.Main.capitalizeWords(str)` succeed, which means that the required library was in the classpath. If you look at the `lib` directory, you will see that the library `commons-lang-2.0.jar` was also retrieved. This library was declared as a dependency of the "dependee" project, so Ivy retrieves it (transitively) along with the dependee artifact. +




	=== Step 5: New version of dependee project

	Like we did before in step 3, publish the dependee project again. This will result in a new version of the project being published.

	[source,shell]
	----

	include::asciidoc/tutorial/log/dependence-standalone-2.txt[]

	----


	Now if you look in your repository folder, you will find 2 versions of the dependee project.
	Let's look at it:

	[source,shell]
	----
	I:\dependee>dir ..\settings\repository /w

	[.] [..] dependee-1.jar dependee-1.xml dependee-2.jar dependee-2.xml

	I:\dependee>
	----



	OK, now our repository contains two versions of the project dependee, so other projects can refer to either version.


	=== Step 6: Get the new version in _depender_ project

	What should we expect if we run the depender project again? It should:


	* retrieve version 2 as the latest.integration version of the dependee project +

	* display version 2 of dependee project +

	Let's try it!!

	[source,shell]
	----

	include::asciidoc/tutorial/log/dependence-depending-2.txt[]

	----


	OK, we got what we expected as the `run` target shows that we are using version 2 of the main class of the dependee project. If we take a look at the resolve target results, we see that one artifact has been downloaded to the Ivy cache. In fact, this file is the same version 2 of the dependee project that is in the repository, but now all future retrievals will pull it from your ivy-cache directory.