Antのビルドファイルは、XMLで記述します。 各ビルドファイルは、一つのプロジェクトと、一つ以上の(デフォルトの)ターゲットを含んでいます。
各ターゲットにはtask要素があります。ビルドファイルのそれぞれのTask要素は、id属性を持つことができ、
後からこれに与えた値を使って参照できます。
この値は、一意でなくてはいけません。(追加情報は、この下のTaskの節を見てください)
プロジェクト(project)は、次の3つの属性を持っています。
| 属性 | 説明 | 必須 |
| name | projectの名前。 | いいえ |
| default | ターゲットが指定されない時に使用するデフォルトターゲット。 | はい |
| basedir | すべてのパスの処理がおこなわれるベースディレクトリ。
この属性は、"basedir"プロパティを設定することで前もってオーバーライドすることができます。 attributeとpropertyの両方ともに指定されていなかった場合には、ビルドファイルの親ディレクトリが使われます。 |
いいえ |
必要に応じて、プロジェクトの説明を、トップ・レベルの<description>要素に用意することができます。 （ description タイプを見て下さい)
各プロジェクトは、一つ以上のターゲットを定義します。 一つのターゲットは、実行したいタスクの集合です。 Antを起動した時に、どのターゲットを実行したいかを選択することができます。 ターゲットを指定しない場合には、そのプロジェクトのデフォルトが使用されます。
ターゲット(target)は、他の複数のターゲットに依存することができます。 例えば、コンパイルのためのターゲットと、配布物を作成するためのターゲットを持つことが出来ます。 最初にコンパイルが終わっていれば、(コンパイルをスキップして)配布物をビルドすることができます。 これは、配布ターゲットはコンパイルターゲットに依存しているといえます。Antは、これらの依存性を解決します。
しかし、注意しなければならないのは、Antのdepends属性はどのターゲットが実行されるべきかの順序を指定するだけです - もし、あるターゲットが実行されない（実行の必要がない）のなら、これに依存している別のターゲットが実行されるかどうかには影響しません。
Antは、depends属性のターゲットを、出現順(左から右に)実行しようとします。 次に示すように、早く出現するターゲットが他に依存している場合には、それを先に実行しようとすることができることを覚えておいてください。
<target name="A"/> <target name="B" depends="A"/> <target name="C" depends="B"/> <target name="D" depends="C,B,A"/>
ターゲットDを実行したいと仮定します。 このdepends属性から、最初にターゲットCを、次にBを、そしてAを実行すると思うかもしれません。 間違ってます！ CはBに依存し、BはAに依存しているので、最初にA、次にB、次にC、そして最後にDを実行します。
ターゲットは、一つ以上のターゲットがそれに依存している場合でさえも、一回だけ実行しようとします(前の例を見てください)。
ターゲットは、あるプロパティが設定されている(またはされていない)場合に、それを実行する能力も持っています。 たとえば、これによって、システムの状態(Javaのバージョン、OS、コマンドラインプロパティなど)に依存したビルドプロセスをよりうまく制御できるようになります。 ターゲットがこのプロパティを検出できるようにするためには、 ターゲットが反応しなければならないプロパティの名前を持つif (またはunless)属性を、次のように追加しなければいけません。
<target name="build-module-A" if="module-A-present"/><target name="build-own-fake-module-A" unless="module-A-present"/>
最初の例では、もしmodule-A-presentプロパティが（何でも良いので)設定されている場合、ターゲットが実行されます。 二番目の例では、もしmodule-A-presentプロパティが（繰り返しになりますが、何でもかまいません）設定されている場合には、ターゲットは実行されません。
もしifとunless属性が存在しない場合には、ターゲットは常に実行されます。
オプションのdescription属性は、ターゲットについての簡単な説明を用意するために使うことができます。 この説明は、-projecthelpコマンドラインオプションを実行したときに表示されます。このような説明がないターゲットは、内部的にdeemedされ、-verboseオプション、 あるいは-debugオプションのどちらかが使われない限りリストされません。
すべての他のターゲットが依存している、いわゆる初期化ターゲットの中に tstampタスクを配置するのは、良い練習になるでしょう。 ターゲットが他のターゲットの依存リストの中で常に最初であることを確認してください。 このマニュアルでは、大部分の初期化ターゲットは、"init"という名前を持っています。
選択可能なdescription属性は、このターゲットに-projecthelpコマンドラインオプションを使用したときに印字される一行の説明を用意するために使用することができます。
ターゲットは、以下のような属性を持っています。
| 属性 | 説明 | 必須 |
| name | ターゲットの名前。 | はい |
| depends | このターゲットが依存するターゲットの名前のカンマで区切られたリスト。 | いいえ |
| if | このターゲットを実行するために設定されていなければならないプロパティの名前。 あるいは、この名前のプロパティが設定されていると、ターゲットが実行される。 |
いいえ |
| unless | このターゲットを実行するために設定してはいけないプロパティの名前。 あるいは、この名前のプロパティが設定されていると、ターゲットが実行されない。 |
いいえ |
| description | このターゲットの機能の簡単な説明。 | いいえ |
ターゲットの名前は、XMLファイルのエンコーディングとして許容される、任意の アルファベットと数字の組み合わせです。 この集合には、カンマ","やスペース" "がそうであるように、空文字列""も含まれます。 Antの将来のバージョンでは、これらが混乱の原因となるためサポートされないので、これらを使うのは 避けて下さい。 IDE(統合開発環境)での、通常使われないターゲット名やスペースを含むターゲット名のサポート状況は IDEにより異なります。
"-restart"等の、ハイフンで始まるターゲットは有効であり、コマンドラインから直接
呼ばれるべきではないターゲットに名付けて使うことが出来ます。
タスクとは、実行可能なコードです。
タスクは、複数の属性(または、選択した引数)を持つことができます。 属性の値は、プロパティに対する参照を含むことができます。 この参照は、タスクが実行される前に解決されます。
タスクは、次のような共通の構造を持っています。
<name attribute1="value1" attribute2="value2" ... />
このnameはタスクの名前であり、attributeNは属性名、そしてvalueNはこの属性の値です。
組み込みタスクや、オプショナルタスクの集合がありますが、 独自のタスクを記述することも簡単です。
すべてのタスクは、task name属性を共有しています。
この属性の値は、Antが生成するロギングメッセージで使用されます。
タスクにはid属性を割り当てることが出来ます：
<taskname id="taskID" ... >
ここでtasknameはタスクの名前で、taskIDは、このタスクのユニークな識別子です。 このスクリプトや他のタスクから、この名前を通して、対応するタスクオブジェクトを参照することが出来ます。 例えば、このスクリプトの中で、
<script ...>とすることにより、特定のタスク・インスタンスのfoo属性を設定することができます。別の(Javaで書かれた) タスクからの場合には、このインスタンスに対し、project.getReference("task1")を経由してアクセス出来ます。
task1.setFoo("bar");
</script>
注意1: もし"task1"がまだ実行されていない場合には、それはまだ構成(原文configure)されていません (例えば、まだ属性は設定されていません）し、もし後で構成されるのなら、インスタンスに対して 行ったことは上書きされます。
注意2: 将来のバージョンのAntは、おそらくこの振る舞いに対して下位互換性を持たないでしょう。 なぜなら、タスクのインスタンスはまったく存在しないで、proxy(訳注:GOFデザインパターンのProxyパターンの事と思われる)だけがあることに なりそうだからです。
プロジェクトは、プロパティの集合を持つことができます。 これらは、propertyタスクによってビルドファイル中で設定されるかもしれませんし、Antの外で設定されるかもしれません。 プロパティは、名前と値を持っています。名前は 大文字・小文字を区別します。 プロパティは、タスクの属性の値として使用することができます。 これは属性の値の中で "${"と"}"の間にプロパティ名を書くことにより可能です。
例えば、値"build"を持つ"builddir"というプロパティが存在する場合には、属性内で "${builddir}/classes" のように使用することができます。 これは、実行時に、"build/classes"として解決されます。
Antは、すべてのシステムプロパティに対して、 propertyタスクを使って定義してあるかのようにアクセスすることができます。 たとえば、${os.name}は、オペレーティングシステムの名前に展開されます。
システムプロパティのリストについては、 System.getPropertiesのJavadocを見て下さい。
さらに、Antには次のような組み込みプロパティがあります。
<?xml version="1.0" encoding="Shift_JIS"?>
<project name="MyProject" default="dist" basedir=".">
<description>
簡単なビルドファイルの例
</description>
<!-- このビルドのためにグローバルプロパティを設定します -->
<property name="src" value="." />
<property name="build" value="build" />
<property name="dist" value="dist" />
<target name="init">
<!-- タイムスタンプを作成します -->
<tstamp/>
<!-- コンパイルで使用するビルドディレクトリ構造を作成します -->
<mkdir dir="${build}" />
</target>
<target name="compile" depends="init"
description="ソースをコンパイルする " >
<!-- ${src}から${build}に、Javaコードをコンパイルします -->
<javac srcdir="${src}" destdir="${build}" />
</target>
<target name="dist" depends="compile"
description="配布物を生成する" >
<!-- distributionディレクトリを作成します -->
<mkdir dir="${dist}/lib" />
<!-- ${build}の中のすべてのファイルをMyProject-${DSTAMP}.jarファイルに格納します -->
<jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}" />
</target>
<target name="clean"
description="clean up" >
<!-- ${build}と${dist}ディレクトリツリーを削除します -->
<delete dir="${build}" />
<delete dir="${dist}" />
</target>
</project>
[訳注：ビルドファイル中に日本語を入力するには、ファイルの最初に
<?xml version="1.0" encoding="Shift_JIS"?>
のように使用する文字コードを指定する必要があります。
そうしないと、デフォルトの UTF-8 コードであるとみなされ、
BUILD FAILEDのようなエラーメッセージが表示されます。]
Error reading project file: invalid byte 1 of 1-byte UTF-8 sequence (0xb4)
注意していただきたいのは、プロパティは全てターゲットの外部で宣言されていることです。<property>、<typedef>と<taskdef>タスクは どのターゲットの外部でも宣言することができるので、特別です。これらは他のターゲットが実行される前に評価されます。これ以外のタスクは、ターゲットの外では宣言できません。
いくつかのターゲットについて説明しましたが、これは、projecthelp実行オプションを公式なターゲットとしてリストアップし、説明する原因となりました。これ以外のターゲットは 内部で使うものであり、リストアップされていません。
最後に、このターゲットが動作するためには、srcサブディレクトリの中のソースは、パッケージ名にマッチするようにディレクトリ・ツリー中に格納されていなければなりません。
プロジェクトは、フィルタリング-コピーの動作をサポートしているタスクが、これを行うように選択された場合には、 ファイルをコピーする時に、条件にあったファイルを見つけて自動的に展開することができるトークンの集合を持つ ことができます。 これはビルドファイル中で filterタスクを使って設定できます。
これは非常に有害な動作なので、ファイル中のトークンは@token@の形式でなければいけません。 tokenは、filterタスクで設定されたトークン名です。
このトークンの文法は、このようなフィルタリングを行う他のビルドシステムの文法と一致しており、また、 大部分のプログラミング言語やスクリプト言語、及びドキュメンテーションシステムとは独立しています。
注意: @token@の形式のトークンがファイル中に見つかっても、そのトークンに関連づけられたフィルタがない場合には、何も変更されません。 ですから、エスケープする方法はありませんが、トークンに対して適切な名前を選択する限りにおいては、これが問題を引き起こすことはありません。
警告: フィルタリングが有効な状態でバイナリファイルをコピーするとファイルが壊れます。この機能はテキストファイルに対してだけ使うべきです。
":"と";"の両方を区切り文字として使用したPATHとCLASSPATH変数を指定することができます。 Antは、それを現在のオペレーティングシステムの正しい文字に変換します。
PATHのような値を指定する時には、常にネストした要素が使用できます。 これは、次のような一般的な形式を取ります。
<classpath>
<pathelement path="${classpath}" />
<pathelement location="lib/helper.jar" />
</classpath>
location属性は、プロジェクトのベースディレクトリに対して相対的な(または絶対ファイル名の)
単一のファイルまたはディレクトリを指定するのに大して、一方、path属性は
コロンやセミコロンで区切られた位置のリストを受け付けます。
path属性は、すでに定義済みのパスと一緒に使われることを意図しています -
他の場合には、location属性を使った複数の要素が望まれるべきです。
pathとlocation属性をサポートしたPATH要素を記述する早道として、
<classpath>
<pathelement path="${classpath}" />
</classpath>
は、次のように短縮することができます。
<classpath path="${classpath}" />
さらに、DirSet、FileSet
とFileListは、
ネストした<fileset>要素で指定することができます。
注意：PATH類似構造にFileSetを構成するファイルが追加される順番は、定義されていません。
<classpath>
<pathelement path="${classpath}" />
<fileset dir="lib">
<include name="**/*.jar" />
</fileset;>
<pathelement location="classes" />
<dirset dir="${build.dir}">
<include name="apps/**/classes"/>
<exclude name="apps/**/*Test*"/>
</dirset>
<filelist refid="third-party_jars">
</classpath>
これは、${classpath}の値の後に、
libディレクトリ中のすべてのJARファイル、
classesディレクトリ、${build.dir}のapps
サブディレクトリの下の全てのclassesと名付けられたディレクトリを
追加したPATHを構築します。但し、名前にTestを含む場合と、FileListで指定
されたファイルを除きます。
複数のタスクに同じPATH類似構造を使用したい場合には、
それらをtargetと同じレベルで
<path>要素を使って定義し、
そのid属性で参照できます -
例は、参照を見てください。
PATH類似構造は、ネストした<path>要素を使って、他のPATH類似構造に対する参照を含むことができます。
<path id="base.path">
<pathelement path="${classpath}" />
<fileset dir="lib">
<include name="**/*.jar" />
</fileset>
<pathelement location="classes" />
</path>
<path id="tests.path">
<path refid="base.path" />
<pathelement location="testclasses" />
</path>
<classpath>に対して前述したような近道はまた、
<path>に対しても有効です。例えば:
<path id="base.path">
<pathelement path="${classpath}"/>
</path>
は以下のように書けます:
<path id="base.path" path="${classpath}"/>
いくつかのタスクは、別プロセスにコマンドラインで渡す引数を受け取ることができます。 空白文字を含む引数指定を簡単にするために、ネストした要素を使用できます。
| 属性 | 説明 | 必須 |
| value | 単一のコマンドライン引数で、空白文字を含むことができます。 | この中の一つだけです。 |
| line | コマンドライン引数の空白で区切られたリスト。 | |
| file | 単一のコマンドライン引数としてのファイルの名前。 Antが、ファイルの絶対ファイル名に置換します。 | |
| path | 単一のコマンドライン引数として扱われる文字列。 パスセパレータとして;や:を使用できますし、Antはそれをプラットフォームのローカルの規則に変換します。 |
<arg value="-l -a" />
これは、空白文字を含む単一のコマンドライン引数です。
<arg line="-l -a" />
これは、二つのコマンドライン引数を表現しています。
<arg path="/dir;/dir2:\dir3" />
これは
DOSベースのシステム上では\dir;\dir2;\dir3で、
Unix類似システムでは/dir:/dir2:/dir3の値を持つ
単一のコマンドライン引数です。
ビルドファイルの要素のid属性 は、それらを参照するために使えます。
これは、例えば、<classpath>構造を２回以上使うなど、同じXMLの断片を
何度も繰り返し反復しようとするときに役立ちます。
以下の例は:
<project ... >
<target ... >
<rmic ...>
<classpath>
<pathelement location="lib/"/>
<pathelement path="${java.class.path}/"/>
<pathelement path="${additional.path}"/>
</classpath>
</rmic>
</target>
<target ... >
<javac ...>
<classpath>
<pathelement location="lib/"/>
<pathelement path="${java.class.path}/"/>
<pathelement path="${additional.path}"/>
</classpath>
</javac>
</target>
</project>
could be rewritten as:
このように書き直せるでしょう:
<project ... >
<path id="project.class.path">
<pathelement location="lib/"/>
<pathelement path="${java.class.path}/"/>
<pathelement path="${additional.path}"/>
</path>
<target ... >
<rmic ...>
<classpath refid="project.class.path"/>
</rmic>
</target>
<target ... >
<javac ...>
<classpath refid="project.class.path"/>
</javac>
</target>
</project>
PatternSet、FileSet や パス類似構造の代わりにネストしたエレメントを使う全てのタスクでは、同様に、このような構造への参照を受け付けます。
Copyright (C) 2000,2001 Apache Software Foundation. All rights Reserved.
日本語訳の著作権は、Ja-Jakartaプロジェクトが保有します。Copyright (C) 2000,2001 Ja-Jakarta project. All rights Reserved.
[訳注:これは風間、西野が翻訳しました。日本語訳に対するコメントがあれば
こちらに送ってください]