= クイックスタート =
この例ではIvyを使用する最も簡単な方法を示す。
特別な設定無しに、IvyはIvyファイル中に記述された依存をMaven 2のリポジトリを使って解決する。
以下に見てみよう。
このチュートリアルのソースはivyディストリビューションの src/example/hello-ivyディレクトリにおかれている。
== ivy.xmlファイル ==
このファイルにはプロジェクトが他のライブラリに依存することを記述する。以下に例を示す。
{{{
}}}
このファイルのフォーマットは極めて理解しやすいだろうが、以下に説明する。
まず最初にルート要素のivy-moduleである。ここにはバージョンアトリビュートがあり、どのバージョンのIvyを使用するかを示す。
次にinfoタグがある。これは我々が依存関係を定義しようとするモジュールについての情報を示すものである。
ここではorganizationとモジュール名のみを示している。
ここには何を書いても良いが、ただし空白は避けることが望ましい。
最後に依存関係を定義するdependenciesセクションがある。
このモジュールはcommons-lang, commons-cliという二つのライブラリに依存している。
見ての通りorgとnameは我々が必要とする依存のorganizationとモジュール名である。
rev属性は依存するモジュールのリビジョンを示す。
これらの属性を記述するためには、依存するものの正確な情報を得なければならない。
IvyはデフォルトでMaven 2のリポジトリを使用する。
したがって、欲しいモジュールをさがすには、mvnrepository.comを使用することを推奨する。
それが見つかればmaven POMの依存を宣言する方法を得ることになる。例えば、
{{{
commons-lang
commons-lang
2.0
}}}
これを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"コマンドを使えば、使用可能なターゲットのリストを得ることができる。
ファイル全体を見ても良いが、依存解決に関係する部分は以下である。
{{{
...
}}}
見てわかるように、依存を解決して取得するようivyに伝えるのはとても簡単だ。
antファイル中のXML名前空間の定義のためにivyがきちんとインストールされていることが必要なだけだ(xmlns:ivy="antlib:org.apache.ivy.ant")。
すべてivy antタスクはこの名前空間の元で利用可能になる。
ここではタスクを一つだけ、つまりretrirveタスクのみを、属性無しで使用した。
この場合、依存関係定義としてivy.xmlという名称のファイルをデフォルト設定で使うことになる。
これはまさに我々が必要とすることなので、それ以上のことは行わない。
我々は、resolveというターゲットを定義し、retrieveタスクを呼び出したことに注意。
これは少々混乱させるかもしれない。実際にはretrieveタスクはresolve
（依存をresolveしてダウンロードし、キャッシュに格納する）を行い、
retrieve（それらのファイルをローカルプロジェクトディレクトリにコピーする）を行う。
詳細は、[[http://ant.apache.org/ivy/history/latest-milestone/principle.html|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リポジトリからファイルを取り出してくる。それがここで起こったことだ。
resolveタスクはmaven2リポジトリの中でcommons-langとcommons-cliモジュールを見つけ、commons-cliはcommons-loggingに依存していることを発見するので、それも推移的依存としてresolveされる。
Ivyはすべての関連するアーティファクトをキャッシュ（デフォルトではユーザホームの.ivy/cacheディレクトリ）にダウンロードする。
最後にretrieveタスクはivyキャッシュ中のresolveされたjarをプロジェクトのデフォルトライブラリディレクトリにコピーする。
これはlibディレクトリであるが、retrieveタスクのpattern属性を設定することにより簡単に変更できる。
"Hello Ivy!"というメッセージを表示するのに、えらい時間がかかるじゃ無いかというかもしれないが、
大部分の時間はウェブから必要なファイルをダウンロードするのに費やされている。
もう一度起動してみよう。
{{{
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
}}}
素晴らしい！キャッシュが使われている。今回はダウンロードが必要ない。
もし、君のモジュールのすべての依存についてのレポートを表示して欲しいのであれば、reportターゲットを使うことだ。
そして、ビルドディレクトリ中の生成ファイルをチェックしてみよう。
[[http://ant.apache.org/ivy/history/latest-milestone/samples/apache-hello-ivy-default.html|こんなもの]]が見られると思う。
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.