Revision 7 as of 2010-09-19 06:45:13

Clear message

Locked History Actions

ivy/QuickStart

クイックスタート

この例ではIvyを使用する最も簡単な方法を示す。 特別な設定無しに、IvyはIvyファイル中に記述された依存をMaven 2のリポジトリを使って解決する。 以下に見てみよう。

このチュートリアルのソースはivyディストリビューションの src/example/hello-ivyディレクトリにおかれている。

ivy.xmlファイル

このファイルにはプロジェクトが他のライブラリに依存することを記述する。以下に例を示す。 

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

このファイルのフォーマットは極めて理解しやすいだろうが、以下に説明する。 まず最初にルート要素のivy-moduleである。ここにはバージョンアトリビュートがあり、どのバージョンのIvyを使用するかを示す。

次にinfoタグがある。これは我々が依存関係を定義しようとするモジュールについての情報を示すものである。 ここではorganizationとモジュール名のみを示している。 ここには何を書いても良いが、ただし空白は避けることが望ましい。

最後に依存関係を定義するdependenciesセクションがある。 このモジュールはcommons-lang, commons-cliという二つのライブラリに依存している。 見ての通りorgとnameは我々が必要とする依存のorganizationとモジュール名である。 rev属性は依存するモジュールのリビジョンを示す。

これらの属性を記述するためには、依存するものの正確な情報を得なければならない。 IvyはデフォルトでMaven 2のリポジトリを使用する。 したがって、欲しいモジュールをさがすには、mvnrepository.comを使用することを推奨する。 それが見つかればmaven POMの依存を宣言する方法を得ることになる。例えば、 

<dependency>
    <groupId>commons-lang</groupId>
    <artifactId>commons-lang</artifactId>
    <version>2.0</version>
</dependency>

これをIvy依存宣言に変換するには、単にgroupIdをorganizationとし、artifactIdをモジュール名とし、そしてversionをリビジョンとすればよい。これは我々がこのチュートリアルで行ったことである。つまり、commons-langとcommons-cliである。

  • commons-langとcommons-cliをorganizationとして使用することは最良の例ではない。むしろord.apache, org.apache.commons, org.apache.commons.langなどを用いた方がよい。しかし、maven2リポジトリにおいてはこの名称で識別されているので、そのままにしておく（あなた自身の作成するリポジトリにおいては、これらの名称を再定義する名前空間を使用できるだろう）。

ivyファイルにおいてその他どのようなことができるのか、ivyファイルのリファレンスドキュメントを参照のこと。

build.xml ファイル

対応する微ウドファイルには複数のターゲットが含まれる。 ivyファイルに宣言された依存を解決し、サンプルコードをコンパイル・実行し、依存解決レポートを作成し、キャッシュやプロジェクト自体を削除するものである。

標準的な"ant -p"コマンドを使えば、使用可能なターゲットのリストを得ることができる。 ファイル全体を見ても良いが、依存解決に関係する部分は以下である。 

<project xmlns:ivy="antlib:org.apache.ivy.ant" name="hello-ivy" default="run">
    
    ...
    
    <!-- ================================= 
          target: resolve              
         ================================= -->
    <target name="resolve" description="--> retrieve dependencies with ivy">
        <ivy:retrieve />
    </target>
</project>

見てわかるように、依存を解決して取得するようivyに伝えるのはとても簡単だ。 antファイル中のXML名前空間の定義のためにivyがきちんとインストールされていることが必要なだけだ(xmlns:ivy="antlib:org.apache.ivy.ant")。 すべてivy antタスクはこの名前空間の元で利用可能になる。

ここではタスクを一つだけ、つまりretrirveタスクのみを、属性無しで使用した。 この場合、依存関係定義としてivy.xmlという名称のファイルをデフォルト設定で使うことになる。 これはまさに我々が必要とすることなので、それ以上のことは行わない。

我々は、resolveというターゲットを定義し、retrieveタスクを呼び出したことに注意。 これは少々混乱させるかもしれない。実際にはretrieveタスクはresolve （依存をresolveしてダウンロードし、キャッシュに格納する）を行い、 retrieve（それらのファイルをローカルプロジェクトディレクトリにコピーする）を行う。 詳細は、How does it work? ページを参照のこと。

プロジェクトを実行する

OK、これで必要なファイルを見渡した。 次はサンプルを実行して何が起こるかを見てみよう。 シェル（あるいはコマンドライン）ウインドウをオープンし、hello-ivyディレクトリに移動する。 そして'ant'を実行してみよう。 

I:\hello-ivy>ant
Buildfile: src\example\hello-ivy\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 | hello-ivy | working@BEN-ScokartG ]
[ivy:retrieve]  confs: [default]
[ivy:retrieve]  found [ commons-lang | commons-lang | 2.0 ] in public
[ivy:retrieve]  found [ commons-cli | commons-cli | 1.0 ] in public
[ivy:retrieve]  found [ commons-logging | commons-logging | 1.0 ] in public
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-lang/commons-lang/2.0/commons-lang-2.0.jar ...
[ivy:retrieve] .......................................................................................
[ivy:retrieve] .............................. (165kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve]  [SUCCESSFUL ] [ commons-lang | commons-lang | 2.0 ]/commons-lang.jar[jar] (3335ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-cli/commons-cli/1.0/commons-cli-1.0.jar ...
[ivy:retrieve] ...................... (29kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve]  [SUCCESSFUL ] [ commons-cli | commons-cli | 1.0 ]/commons-cli.jar[jar] (2053ms)
[ivy:retrieve] downloading http://repo1.maven.org/maven2/commons-logging/commons-logging/1.0/commons-logging-1.0.jar ...
[ivy:retrieve] ................. (21kB)
[ivy:retrieve] .. (0kB)
[ivy:retrieve]  [SUCCESSFUL ] [ commons-logging | commons-logging | 1.0 ]/commons-logging.jar[jar] (1933ms)
[ivy:retrieve] :: resolution report ::
[ivy:retrieve]  :: evicted modules:
[ivy:retrieve]  [ commons-lang | commons-lang | 1.0 ] by [[ commons-lang | commons-lang | 2.0 ]] in [default]
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   4   |   3   |   0   |   1   ||   3   |   3   |
        ---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: [ org.apache | hello-ivy ]
[ivy:retrieve]  confs: [default]
[ivy:retrieve]  3 artifacts copied, 0 already retrieved

run:
     [java] standard message : hello ivy !
     [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !

BUILD SUCCESSFUL
Total time: 14 seconds

何が起こるのか？

何の設定もなければivyはmaven2リポジトリからファイルを取り出してくる。

Without any settings, Ivy retrieves files from the maven 2 repository. That's what happened here. The resolve task has found the commons-lang and commons-cli modules in the maven 2 repository, identified that commons-cli depends on commons-logging and so resolved it as a transitive dependency. Then Ivy has downloaded all corresponding artifacts in its cache (by default in your user home, in a .ivy2/cache directory). Finally, the retrieve task copies the resolved jars from the ivy cache to the default library directory of the project: the lib dir (you can change this easily by setting the pattern attribute on the retrieve task).

You might say that the task took a long time just to write out a "Hello Ivy !" message. But remember that a lot of time was spent downloading the required files from the web. Let's try to run it again: 

I:\hello-ivy>ant
Buildfile: src\example\hello-ivy\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 | hello-ivy | working@BEN-ScokartG ]
[ivy:retrieve]  confs: [default]
[ivy:retrieve]  found [ commons-lang | commons-lang | 2.0 ] in public
[ivy:retrieve]  found [ commons-cli | commons-cli | 1.0 ] in public
[ivy:retrieve]  found [ commons-logging | commons-logging | 1.0 ] in public
[ivy:retrieve] :: resolution report ::
[ivy:retrieve]  :: evicted modules:
[ivy:retrieve]  [ commons-lang | commons-lang | 1.0 ] by [[ commons-lang | commons-lang | 2.0 ]] in [default]
        ---------------------------------------------------------------------
        |                  |            modules            ||   artifacts   |
        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
        ---------------------------------------------------------------------
        |      default     |   4   |   0   |   0   |   1   ||   3   |   0   |
        ---------------------------------------------------------------------
[ivy:retrieve] :: retrieving :: [ org.apache | hello-ivy ]
[ivy:retrieve]  confs: [default]
[ivy:retrieve]  0 artifacts copied, 3 already retrieved

run:
     [java] standard message : hello ivy !
     [java] capitalized by org.apache.commons.lang.WordUtils : Hello Ivy !

BUILD SUCCESSFUL
Total time: 3 seconds

Great! the cache was used, no download was needed and the build was instantaneous.

And now, if you want to generate a report detailing all the dependencies of your module, you can call the report target, and check the generated file in the build directory. You should obtain something looking like this.

As you can see, using Ivy to resolve dependencies stored in the maven 2 repository is extremely easy. Now you can go on with the next tutorials to learn more about how to use module configurations which is a very powerful Ivy specific feature. Other tutorials are also available where you will learn how to use Ivy settings to leverage a possibly complex enterprise repository. It may also be a good time to start reading the reference documentation, and especially the introduction material which gives a good overview of Ivy. The best practices page is also a must read to start thinking about how to use Ant+Ivy to build a clean and robust build system.