asciidoc/tutorial/conf.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 introduces the use of module configurations in Ivy files. Ivy module configurations are 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 poured :-)

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

 Reference documentation on configurations can be found link:../terminology{outfilesuffix}[here] and link:../ivyfile/configurations{outfilesuffix}[here].

 == Introduction

 Source code is 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 filter-framework library project produces 3 artifacts:

   - the API jar,
   - an implementation jar with no external dependencies,
   - a second implementation jar that needs commons-collections to perform.

 The application only needs the API jar to compile and can use either of the two implementations at runtime.


 == The library project

 The first project we'll look at in this tutorial is filter-framework. In order to have a fine-grained artifact publication definition, we defined several configurations, each of which maps to a set of artifacts that other projects can make use of.

 === The ivy.xml file


 [source]
 ----

 <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 4 configurations, with 3 being public and 1 private (the JUnit dependency for testing).
 The 2 implementation configurations, *homemade-impl* and *cc-impl* extend the *api* configuration so that all artifacts defined in *api* will also be part of the extending configuration.

 In the publications tag, we defined the artifacts we produce (jars in this case) and we assign them to a configuration. When others use our library they will have a flexible way to ask for what they need.


 === See it in action

 The filter-framework project is built using Ant. Open a shell in the root directory of the project and type `ant`.

 [source,shell]
 ----

 include::asciidoc/tutorial/log/configurations-lib.txt[]

 ----


 The Ant default target is publish. This target uses Ivy to publish our library binaries to a local repository. Since we do not specify any repository path, the default one is used. (`${home.dir}/.ivy2/local/org.apache/filter-framework/`) At this point, we are ready to use our library.


 == The application project


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

 === The `ivy.xml` file


 [source]
 ----

 <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 different ways we want to use the application. The *build* configuration defines the compile-time dependencies, and thus only needs the api conf from the filter-framework project. The other two configurations define runtime dependencies. One will only use our "home-made" jar, and the other will use an external jar.

 We also defined a dependency on our previously built library. In this dependency, we use configuration mappings to match ours with the dependency's configurations. You can find more information about configuration mapping link:../ivyfile/configurations{outfilesuffix}[here]


 . *build->api* : here we tell Ivy that our *build* configuration depends on the *api* configuration of the dependency +

 . *noexternaljar->homemade-impl* : here we tell Ivy that our *noexternaljar* configuration depends on the *homemade-impl* configuration of the dependency. +

 . *withexternaljar->cc-impl* : here we tell Ivy that our *withexternaljar* configuration depends on the *cc-impl* configuration of the dependency +

 Note that we never declare any of the dependency's artifacts we need in each configuration: it's the dependency module's Ivy file that declares the published artifacts which should be used in each configuration.

 In the Ant `build.xml` file, we defined a 'resolve' target as follow:


 [source]
 ----

 <target name="resolve" description="--> retrieve 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 after a call to this target:

 [source,shell]
 ----

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

 01/24/2006  11:19 AM    <REP>          build
 01/24/2006  11:19 AM    <REP>          noexternaljar
 01/24/2006  11:19 AM    <REP>          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, we have a set of jars for each configuration now.

 Let's try to launch our app.


 === See it in action

 Use Ant to run the application. The default Ant target is __run-cc__ and will launch the application using the Apache commons-collections implementation.

 [source,shell]
 ----

 include::asciidoc/tutorial/log/configurations-runcc.txt[]

 ----


 Launching the application using the homemade implementation is also straightforward.
 type `ant run-hm`


 [source,shell]
 ----

 include::asciidoc/tutorial/log/configurations-runhm.txt[]
 ----


 Nice! We got the same result, but we can see that the implementation classes are different.


 == Conclusion

 *You should use configurations as often as possible.* Configurations are a very important concept in Ivy. They allow you to group artifacts and give the group a meaning. When you write Ivy files for projects that are intended for use by others, use configurations to allow people to get only what they need, without having to specify them one by one in their own dependency list.
	////
	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 introduces the use of module configurations in Ivy files. Ivy module configurations are 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 poured :-)

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

	Reference documentation on configurations can be found link:../terminology{outfilesuffix}[here] and link:../ivyfile/configurations{outfilesuffix}[here].

	== Introduction

	Source code is 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 filter-framework library project produces 3 artifacts:

	- the API jar,
	- an implementation jar with no external dependencies,
	- a second implementation jar that needs commons-collections to perform.

	The application only needs the API jar to compile and can use either of the two implementations at runtime.


	== The library project

	The first project we'll look at in this tutorial is filter-framework. In order to have a fine-grained artifact publication definition, we defined several configurations, each of which maps to a set of artifacts that other projects can make use of.

	=== The ivy.xml file




	[source]
	----

	<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 4 configurations, with 3 being public and 1 private (the JUnit dependency for testing).
	The 2 implementation configurations, homemade-impl and cc-impl extend the api configuration so that all artifacts defined in api will also be part of the extending configuration.

	In the publications tag, we defined the artifacts we produce (jars in this case) and we assign them to a configuration. When others use our library they will have a flexible way to ask for what they need.


	=== See it in action

	The filter-framework project is built using Ant. Open a shell in the root directory of the project and type `ant`.

	[source,shell]
	----

	include::asciidoc/tutorial/log/configurations-lib.txt[]

	----


	The Ant default target is publish. This target uses Ivy to publish our library binaries to a local repository. Since we do not specify any repository path, the default one is used. (`${home.dir}/.ivy2/local/org.apache/filter-framework/`) At this point, we are ready to use our library.


	== The application project


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

	=== The `ivy.xml` file




	[source]
	----

	<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 different ways we want to use the application. The build configuration defines the compile-time dependencies, and thus only needs the api conf from the filter-framework project. The other two configurations define runtime dependencies. One will only use our "home-made" jar, and the other will use an external jar.

	We also defined a dependency on our previously built library. In this dependency, we use configuration mappings to match ours with the dependency's configurations. You can find more information about configuration mapping link:../ivyfile/configurations{outfilesuffix}[here]


	. build->api : here we tell Ivy that our build configuration depends on the api configuration of the dependency +

	. noexternaljar->homemade-impl : here we tell Ivy that our noexternaljar configuration depends on the homemade-impl configuration of the dependency. +

	. withexternaljar->cc-impl : here we tell Ivy that our withexternaljar configuration depends on the cc-impl configuration of the dependency +

	Note that we never declare any of the dependency's artifacts we need in each configuration: it's the dependency module's Ivy file that declares the published artifacts which should be used in each configuration.

	In the Ant `build.xml` file, we defined a 'resolve' target as follow:


	[source]
	----

	<target name="resolve" description="--> retrieve 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 after a call to this target:

	[source,shell]
	----

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

	01/24/2006 11:19 AM <REP> build
	01/24/2006 11:19 AM <REP> noexternaljar
	01/24/2006 11:19 AM <REP> 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, we have a set of jars for each configuration now.

	Let's try to launch our app.


	=== See it in action

	Use Ant to run the application. The default Ant target is __run-cc__ and will launch the application using the Apache commons-collections implementation.

	[source,shell]
	----

	include::asciidoc/tutorial/log/configurations-runcc.txt[]

	----


	Launching the application using the homemade implementation is also straightforward.
	type `ant run-hm`


	[source,shell]
	----

	include::asciidoc/tutorial/log/configurations-runhm.txt[]
	----


	Nice! We got the same result, but we can see that the implementation classes are different.


	== Conclusion

	You should use configurations as often as possible. Configurations are a very important concept in Ivy. They allow you to group artifacts and give the group a meaning. When you write Ivy files for projects that are intended for use by others, use configurations to allow people to get only what they need, without having to specify them one by one in their own dependency list.