ivy教程(8)-使用ivy模块配置

这个教程介绍ivy文件中的模块配置的使用。ivy模块配置事实上是一个非常重要的概念。某些人甚至告诉我使用ivy而不用ivy配置就像吃乳酪而不动就在你旁边的Chateau Margaux 1976！

    严肃的说，ivy中的配置可以更好的理解为你的模块的视图，你将可以看到在这里他们将如何被高效地使用。

    关于配置的参考文件可以在这里 和这里 找到。

    1) Introduction

    源文件在这里 src/example/configurations/multi-projects.
    我们有两个项目：

- filter-framework 是一个类库，定义一个api来过滤字符串数组，这个api有两个实现.
- myapp 是一个使用filter-framework的非常小的应用.

    这个类库产生3个制品:
- api的jar
- 一个没有外部依赖的实现的jar
- 另一个需要commons-collections来执行的实现jar

    应用仅仅需要api来编译，在运行时可以使用两个实现中的任意一个。

    2) 类库项目

    在这个教程中我们定义的第一个项目是filter-framework.
    为了得到一个良好处理的制品发布定义，我们定义配置来计划让其他人使用我们的类库的使用方式。

    1. ivy.xml 文件

< 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 >

    2. 解释

    如你所见，我们定义了3个公共配置和一个私有配置(为测试定义junit依赖)。
    2个实现配置homemade-impl, cc-impl 继承自api配置，因此在api中定义的制品在它的继承配置中同样是需要的。
    在publications标签中，我们定义了我们要产生的制品(在这里它们是jar)并给他们使用了配置。
    后面当其他模块要使用我们的类库时，他们将有非常灵活的方式来定义他们需要的东西。

    3. 在实战中检验
    The library project is build using ant. Open a shell in the root directory of the project and type ant.
    类库项目使用ant来构建。在项目的根目录下打开一个shell，并输入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

    ant的默认target是publish。
    这个target使用ivy发布我们的类库到本地仓库。
    因为我们没有指定任何仓库路径，因此使用默认仓库。({home.dir}/.ivy2/local/org.apache/filter-framework/)现在我们准备好了使用我们的类库。

    3) 应用项目

    现在我们已经完成了我们美妙的类库，我们想用它！
    这个教程带来一个名为myapp的示例应用。
 
    1. ivy.xml文件

< 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 >

    2. 解释

    我们创建了3个配置来定义我们想使用应用的方式。
    build配置定义了编译时的依赖，而这个只需要来自filter-framework的api conf。
    其他配置定义了运行时依赖。一个将仅仅使用"home-made"的jars，而另一个将使用外部的jars。

    我们同样定义了对于上面类库的依赖。
    在依赖中我们使用配置映射来匹配我们和类库的配置。
    你可以在这里 找到更多的关于配置映射的信息。

   1. build->api : 这里我们告诉ivy，我们的build配置依赖于依赖的api配置。
   2. noexternaljar->homemade-impl : 这里我们告诉ivy，我们的noexternaljar 配置依赖于依赖的homemade-impl配置。
   3. withexternaljar->cc-impl : 这里我们告诉ivy，我们的的withexternaljar 配置依赖于依赖的cc-impl配置。

    注意我们从不定义在每个配置中需要的任何依赖制品：依赖模块文件将定义发布的制品和将被哪个配置使用。

    在ant的build.xm文件中我们定义解析的target如下：

< target  name ="resolve"  description ="--> retreive dependencies with ivy" >
     < ivy:retrieve  pattern ="${ivy.lib.dir}/[conf]/[artifact].[ext]" />
</ target >

    当我们调用这个target时，ivy将使用我们的在root文件夹中的ivy.xml来做解析并随后获取所有的制品。制品被获取并分别保存在和他们所属的配置对应目录下。在调用这个target后你的lib目录将看起来像这样：

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

    如你所见对于每个配置我们现在都有了一个jar的集合。

    让我们试试启动我们的app。

    3. 在实战中检验

    使用ant来运行应用。
    默认ant target是run-cc，将使用apache commons-collections实现来启动应用。

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

    仅使用自制jars来启动应用时很直接的。
    键入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

    很好，我们得到了同样的结果，但是我们可以看到实现的类是不一样的。

    4) 结论
    你应该尽可能多的使用配置。
    配置是ivy中非常重要的概念。他们容许你按照意愿来分组制品。
    当你书写假定要被重用的项目的ivy文件时，使用配置来容许人们只获取他们需要的东西，而不需要通过在依赖块中使用制品标签来手工指定。