Apache Antの使用

シンプルなビルドファイルの作成

Apache AntのビルドファイルはXMLで記述されます。各ビルドファイルには1つのプロジェクトと少なくとも1つの（デフォルト）ターゲットが含まれています。ターゲットにはタスク要素が含まれます。ビルドファイルの各タスク要素は、id属性を持つことができ、後でこの属性に指定された値で参照できます。この値は一意である必要があります。（詳細については、以下のタスクのセクションを参照してください。）

プロジェクト

プロジェクトには3つの属性があります。

属性	説明	必須
name	プロジェクトの名前。	いいえ
default	ターゲットが指定されていない場合に使用するデフォルトのターゲット。	いいえ。ただし、Ant 1.6.0以降、すべてのプロジェクトには、最上位のタスクや型を含む暗黙的なターゲットが含まれます。このターゲットは、Antが`-projecthelp`オプション付きで実行された場合でも、プロジェクトの初期化の一部として常に実行されます。
basedir	すべてのパス計算が実行されるベースディレクトリ。相対パスは、ビルドファイルを含むディレクトリからの相対パスとして解決されます。	いいえ。プロジェクトの`basedir`または`basedir`プロパティでオーバーライドされない限り、デフォルトではビルドファイルの親ディレクトリになります。

オプションで、プロジェクトの説明をトップレベルの<description>要素として提供できます（description型を参照）。

各プロジェクトは、1つ以上のターゲットを定義します。ターゲットは、実行したいタスクのセットです。Antを起動するときに、実行したいターゲットを選択できます。ターゲットが指定されていない場合は、プロジェクトのdefaultが使用されます。

ターゲット

ターゲットは他のターゲットに依存する場合があります。たとえば、コンパイル用のターゲットと、配布可能なファイルを作成するためのターゲットがある場合があります。配布可能なファイルは、最初にコンパイルした場合にのみビルドできるため、distributeターゲットはcompileターゲットに依存します。Antはこれらの依存関係を解決します。

ただし、Antのdepends属性は、ターゲットが実行される順序のみを指定することに注意してください。依存ターゲットが（実行する必要がないため）実行されなかった場合、依存関係を指定するターゲットが実行されるかどうかには影響しません。

詳細については、専用のマニュアルページを参照してください。

タスク

タスクは、実行できるコードの一部です。

タスクには複数の属性（または引数）を持たせることができます。属性の値にはプロパティへの参照が含まれている場合があります。これらの参照は、タスクが実行される前に解決されます。

タスクには共通の構造があります

<name attribute1="value1" attribute2="value2" ... />

ここで、nameはタスクの名前、attributeNは属性名、valueNはこの属性の値です。

組み込みタスクのセットがありますが、独自のタスクを記述するのも非常に簡単です。

すべてのタスクは、name属性を持つことができます。この属性の値は、Antによって生成されるログメッセージで使用されます。

タスクにはid属性を割り当てることができます

<taskname id="taskID" ... />

ここで、tasknameはタスクの名前、taskIDはこのタスクの一意の識別子です。スクリプトまたは他のタスクで、この名前を介して対応するタスクオブジェクトを参照できます。たとえば、スクリプトでは次のようにすることができます

<script ... >
  task1.setFoo("bar");
</script>

この特定のタスクインスタンスのfoo属性を設定します。別のタスク（Javaで記述）では、project.getReference("task1")を介してインスタンスにアクセスできます。

注1：task1がまだ実行されていない場合、設定されておらず（つまり、属性は設定されていません）、後で設定される予定の場合、インスタンスに対して行ったことはすべて上書きされる可能性があります。

注2：今後のバージョンのAntは、タスクインスタンスが存在せず、プロキシのみになる可能性が高いため、この動作との下位互換性がなくなる可能性が高くなります。

プロパティ

プロパティは、ビルドプロセスをカスタマイズしたり、ビルドファイル内で繰り返し使用される文字列のショートカットを提供したりするための重要な方法です。

最も単純な形式では、プロパティはビルドファイル（たとえば、propertyタスク）で定義されるか、Antの外部で設定される場合があります。プロパティには名前と値があります。名前は大文字と小文字が区別されます。プロパティは、タスク属性の値、またはそれらをサポートするタスクのネストされたテキストで使用できます。これは、属性値の${と}の間にプロパティ名を配置することで行われます。たとえば、値buildを持つbuilddirプロパティがある場合、これは次のような属性で使用できます：${builddir}/classes。これは実行時にbuild/classesとして解決されます。

Ant 1.8.0以降、プロパティの展開は、単純なキーと値のペアよりもはるかに強力になり、詳細についてはこのマニュアルの概念セクションにあります。

ビルドファイルの例

<project name="MyProject" default="dist" basedir=".">
  <description>
    simple example build file
  </description>
  <!-- set global properties for this build -->
  <property name="src" location="src"/>
  <property name="build" location="build"/>
  <property name="dist" location="dist"/>

  <target name="init">
    <!-- Create the time stamp -->
    <tstamp/>
    <!-- Create the build directory structure used by compile -->
    <mkdir dir="${build}"/>
  </target>

  <target name="compile" depends="init"
        description="compile the source">
    <!-- Compile the Java code from ${src} into ${build} -->
    <javac srcdir="${src}" destdir="${build}"/>
  </target>

  <target name="dist" depends="compile"
        description="generate the distribution">
    <!-- Create the distribution directory -->
    <mkdir dir="${dist}/lib"/>

    <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
    <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
  </target>

  <target name="clean"
        description="clean up">
    <!-- Delete the ${build} and ${dist} directory trees -->
    <delete dir="${build}"/>
    <delete dir="${dist}"/>
  </target>
</project>

プロパティをターゲットの外部で宣言していることに注意してください。Ant 1.6以降、すべてのタスクをターゲットの外部で宣言できます（以前のバージョンでは<property>、<typedef>、および<taskdef>のみが許可されていました）。これを行うと、ターゲットが実行される前に評価されます。一部のタスクは、無限ループを引き起こす可能性があるため、ターゲットの外部で使用するとビルドエラーが発生します（たとえば、<antcall>）。

いくつかのターゲットの説明を提供しました。これにより、-projecthelp起動オプションで、それらが説明付きのパブリックターゲットとしてリストされます。もう1つのターゲットは内部であり、リストされていません。

最後に、このターゲットが機能するためには、srcサブディレクトリのソースが、パッケージ名と一致するディレクトリツリーに格納されている必要があります。詳細については、<javac>タスクを確認してください。

トークンフィルター

プロジェクトには、ファイルがコピーされたとき、またはこの動作をサポートするタスクでフィルタリングコピーの動作が選択された場合に、見つかった場合に自動的に展開される可能性のあるトークンのセットを含めることができます。これらは、filterタスクによってビルドファイルで設定される可能性があります。

これは非常に有害な動作になる可能性があるため、ファイル内のトークンは、@token@の形式である必要があります。ここで、tokenは、<filter>タスクで設定されるトークン名です。このトークン構文は、そのようなフィルタリングを実行する他のビルドシステムの構文と一致し、ほとんどのプログラミング言語およびスクリプト言語、およびドキュメントシステムに対して十分に直交しています。

注：@token@形式のトークンがファイルで見つかったが、そのトークンに関連付けられたフィルターがない場合、変更は行われません。したがって、エスケープ方法は利用できませんが、トークンに適切な名前を選択する限り、これは問題を引き起こさないはずです。

警告：フィルタリングをオンにしてバイナリファイルをコピーすると、ファイルが破損する可能性があります。この機能は、テキストファイルのみで使用する必要があります。

パスのような構造

:と;の両方を区切り文字として使用して、PATHおよびCLASSPATHタイプの参照を指定できます。Antは、区切り文字を現在のオペレーティングシステムの正しい文字に変換します。

パスのような値を指定する必要がある場合は常に、ネストされた要素を使用できます。これは、一般的な形式

<classpath>
  <pathelement path="${classpath}"/>
  <pathelement location="lib/helper.jar"/>
</classpath>

のようになります。location属性は、プロジェクトのベースディレクトリを基準とした（または絶対ファイル名の）単一のファイルまたはディレクトリを指定します。一方、path属性は、コロンまたはセミコロンで区切られた場所のリストを受け入れます。path属性は、事前定義されたパスで使用することを目的としています。それ以外の場合は、location属性を持つ複数の要素を使用する必要があります。

Ant 1.8.2以降、location属性には、Java 6で導入されたワイルドカードCLASSPATHをサポートするために、最後のパスコンポーネントにワイルドカードを含めることもできます（つまり、*で終わることができます）。Antはワイルドカードを展開または評価せず、結果のパスはCLASSPATH以外では機能しない可能性があります。または、Java 6より前のJVMのCLASSPATHとしても機能しない可能性があります。

ショートカットとして、<classpath>タグは独自のpathおよびlocation属性をサポートするため、

<classpath>
  <pathelement path="${classpath}"/>
</classpath>

は、次のように短縮できます

<classpath path="${classpath}"/>

さらに、1つ以上のリソースコレクションをネストされた要素として指定できます（これらはfileタイプのリソースのみで構成されている必要があります）。さらに、リソースコレクションは検出された順序で処理されますが、fileset、dirset、filesなどの特定のリソースコレクションタイプは順序に関して未定義であることに注意する必要があります。

<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という名前のすべてのディレクトリ（名前にTestというテキストがあるディレクトリを除く）、および参照されているFileListで指定されたファイルを含むパスが構築されます。

いくつかのタスクで同じパスのような構造を使用する場合は、<target>と同じレベルで<path>要素でそれらを定義し、id属性を介してそれらを参照できます。例については参照を参照してください。

デフォルトでは、パスのような構造は、使用されるたびにネストされたすべてのリソースコレクションを再評価します。これにより、ファイルシステムの不要な再スキャンが発生する可能性があります。Ant 1.8.0以降、pathにはオプションのcache属性があります。これがtrueに設定されている場合、パスインスタンスはネストされたリソースコレクションを1回だけスキャンし、ビルド中に変更されないと想定します（cacheのデフォルトは引き続きfalseです）。パスを単一のタスクでのみ使用している場合でも、複雑なネストされた構造を使用している場合は、cacheをtrueに設定すると、全体的なパフォーマンスが向上する可能性があります。

パスのような構造には、ネストされた<path>要素を介して別のパスのような構造（パス自体がリソースコレクション）への参照を含めることができます

<path id="base.path">
  <pathelement path="${classpath}"/>
  <fileset dir="lib">
    <include name="**/*.jar"/>
  </fileset>
  <pathelement location="classes"/>
</path>

<path id="tests.path" cache="true">
  <path refid="base.path"/>
  <pathelement location="testclasses"/>
</path>

<classpath>で前に述べたショートカットは、<path>でも有効です。たとえば

<path id="base.path">
  <pathelement path="${classpath}"/>
</path>

は、次のように記述できます

<path id="base.path" path="${classpath}"/>

パスのショートカット

Ant 1.6以降、プロパティでパスをOS固有の文字列に変換するためのショートカットがあります。式${toString:pathreference}を使用して、パス要素参照をパス引数に使用できる文字列に変換できます。たとえば

<path id="lib.path.ref">
  <fileset dir="lib" includes="*.jar"/>
</path>
<javac srcdir="src" destdir="classes">
  <compilerarg arg="-Xbootclasspath/p:${toString:lib.path.ref}"/>
</javac>

コマンドライン引数

いくつかのタスクは、コマンドラインで別のプロセスに渡される引数を取ります。スペース文字を含む引数を簡単に指定できるように、ネストされたarg要素を使用できます。

属性	説明	必須
value	単一のコマンドライン引数。スペース文字を含めることができます。	これらのうち、1つだけ。
file	単一のコマンドライン引数としてのファイルの名前。ファイルの絶対ファイル名に置き換えられます。
path	パスのような文字列として扱われる文字列で、単一のコマンドライン引数として扱われます。; または : をパス区切り文字として使用できます。Antは、これをプラットフォームのローカルな規約に変換します。
pathref	他の場所で定義されたパスへの参照。Antは、これをプラットフォームのローカルな規約に変換します。
line	空白で区切られたコマンドライン引数のリスト。
prefix	引数の前に配置される固定文字列。行が複数の部分に分割されている場合は、すべての部分の前に配置されます。Ant 1.8以降。	いいえ
suffix	引数の直後に配置される固定文字列。行が複数の部分に分割されている場合は、すべての部分の後に配置されます。Ant 1.8以降。	いいえ

可能な限り、line バージョンの使用は避けることを強くお勧めします。Antは、(Unix)シェルが行うのと同様の方法でコマンドラインを分割しようとしますが、状況によっては期待とは大きく異なるものを作成する可能性があります。

例

<arg value="-l -a"/>

は、スペース文字を含む単一のコマンドライン引数であり、個別のオプション -l および -a ではありません。

<arg line="-l -a"/>

これは、2つの個別のオプション -l および -a を持つコマンドラインです。

<arg path="/dir;/dir2:\dir3"/>

は、DOSベースのシステムでは値が \dir;\dir2;\dir3 で、Unix(類似)システムでは /dir:/dir2:/dir3 の単一のコマンドライン引数です。

参照

すべてのプロジェクト要素には、その id 属性を使用して識別子を割り当てることができます。ほとんどの場合、要素は、同じタイプの要素で refid 属性を指定することで、後で参照できます。これは、同じXMLスニペットを何度も繰り返し使用する場合（たとえば、<classpath>構造を複数回使用する場合）に役立ちます。

次の例

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

は、次のように書き換えることができます。

<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、ZipFileSet、またはパスのような構造にネストされた要素を使用するすべてのタスクは、例に示すようにこれらの構造への参照を受け入れます。タスクで refid を使用すると、通常は同じ効果 (すでに宣言されているタスクを参照する) がありますが、この属性の解釈は、それが指定されている要素の実装に依存することに注意する必要があります。一部のタスク (たとえば、property タスク) は、意図的に refid に異なる意味を割り当てています。

外部タスクの使用

Antは、サードパーティのタスクを使用するためのプラグインメカニズムをサポートしています。それらを使用するには、2つの手順を実行する必要があります。

Antがそれらを見つけることができる場所に実装を配置します。
それらを宣言します。

CLASSPATH 環境変数には何も追加しないでください。これは、しばしば非常に不可解なエラーの原因になります。ライブラリを追加するには、Ant自身のメカニズムを使用してください。

コマンドライン引数 -lib 経由
${user.home}/.ant/lib に追加
${ant.home}/lib に追加

宣言にはいくつかの方法があります。

命令ごとに単一のタスクを <taskdef name="taskname" classname="ImplementationClass"/> を使用して宣言します。
<taskdef name="for" classname="net.sf.antcontrib.logic.For"/> <for ... />
taskname–ImplementationClassペアを保持するpropertiesファイルと <taskdef> を使用して、タスクのバンドルを宣言します。
<taskdef resource="net/sf/antcontrib/antcontrib.properties"/> <for ... />
これらのtaskname-ImplementationClassペアを保持するxmlファイルと <taskdef> を使用して、タスクのバンドルを宣言します。
<taskdef resource="net/sf/antcontrib/antlib.xml"/> <for ... />
antlib.xmlという名前のxmlファイル、XML名前空間、およびantlib: プロトコルハンドラーを使用して、タスクのバンドルを宣言します。
<project xmlns:ac="antlib:net.sf.antcontrib"/> <ac:for ... />

特別な機能が必要な場合は、以下を行う必要があります。

Antは多くのタスクを提供しているため、このマニュアルを参照してください。
外部タスクページオンラインを参照してください。
外部タスクwikiページを参照してください。
Antユーザーリストで質問してください。
独自のものを実装（および共有）してください。