Apache Antの実行

コマンドライン

Antのインストールセクションで説明したようにApache Antをインストールした場合、コマンドラインからAntを実行するのは簡単です。単に ant と入力するだけです。

引数が何も指定されていない場合、Antは現在のディレクトリにある build.xml ファイルを探し、見つかった場合はそのファイルをビルドファイルとして使用し、<project> タグの default 属性で指定されたターゲットを実行します。build.xml 以外のビルドファイルをAntに使用させるには、コマンドラインオプション -buildfile file を使用します。ここで、file は使用したいビルドファイルの名前（または build.xml ファイルを含むディレクトリ）です。

-find [file] オプションを使用すると、Antは最初に現在のディレクトリでビルドファイルを探し、次に親ディレクトリ、というように、ビルドファイルが見つかるか、ファイルシステムのルートに到達するまで検索します。デフォルトでは、build.xml という名前のビルドファイルを探します。build.xml 以外のビルドファイルを検索させるには、ファイル引数を指定します。注: -find フラグの後にコマンドラインで他のフラグまたは引数を含める場合は、見つけたいビルドファイルの名前が build.xml であっても、-find フラグのファイル引数を含める必要があります。

コマンドラインでプロパティを設定することもできます。これは、-Dproperty=value オプションを使用すると設定できます。ここで、property はプロパティの名前、value はそのプロパティの値です。ビルドファイルにも設定されているプロパティ（property タスクを参照）を指定した場合、コマンドラインで指定された値がビルドファイルで指定された値を上書きします。コマンドラインでプロパティを定義することで、環境変数の値を渡すこともできます。Antに -DMYVAR=%MYVAR% (Windows) または -DMYVAR=$MYVAR (Unix) を渡すだけです。ビルドファイル内でこれらの変数を ${MYVAR} としてアクセスできます。property タスクの environment 属性を使用して環境変数にアクセスすることもできます。

Antによるログ出力の量を制御するオプションは次のとおりです。-quiet は、Antにコンソールへの出力情報を減らすように指示します。-verbose は、Antにコンソールに追加情報を出力させます。-debug は、Antにさらに多くの追加情報を出力させます。-silent は、Antにタスク出力とビルド失敗のみを出力させます（スクリプトによるAnt出力のキャプチャに便利です）。

実行する1つ以上のターゲットを指定することもできます。省略した場合、project タグの default 属性で指定されたターゲットが使用されます。

-projecthelp オプションは、ビルドファイルのターゲットのリストを出力します。description 属性を含むターゲットは「メインターゲット」としてリストされ、description を持たないターゲットは「その他のターゲット」としてリストされます。その後、「デフォルト」ターゲットがリストされます（「その他のターゲット」は、メインターゲットがない場合、またはAntが -verbose または -debug モードで起動された場合にのみ表示されます）。

コマンドラインオプションの概要

ant [options] [target [target2 [target3] ...]]
Options:
  -help, -h              print this message and exit
  -projecthelp, -p       print project help information and exit
  -version               print the version information and exit
  -diagnostics           print information that might be helpful to
                         diagnose or report problems and exit
  -quiet, -q             be extra quiet
  -silent, -S            print nothing but task outputs and build failures
  -verbose, -v           be extra verbose
  -debug, -d             print debugging information
  -emacs, -e             produce logging information without adornments
  -lib <path>            specifies a path to search for jars and classes
  -logfile <file>        use given file for log
    -l     <file>                ''
  -logger <classname>    the class which is to perform logging
  -listener <classname>  add an instance of class as a project listener
  -noinput               do not allow interactive input
  -buildfile <file>      use given buildfile
    -file    <file>              ''
    -f       <file>              ''
  -D<property>=<value>   use value for given property
  -keep-going, -k        execute all targets that do not depend
                         on failed target(s)
  -propertyfile <name>   load all properties from file with -D
                         properties taking precedence
  -inputhandler <class>  the class which will handle input requests
  -find <file>           (s)earch for buildfile towards the root of
    -s  <file>           the filesystem and use it
  -nice  number          A niceness value for the main thread:
                         1 (lowest) to 10 (highest); 5 is the default
  -nouserlib             Run ant without using the jar files from ${user.home}/.ant/lib
  -noclasspath           Run ant without using CLASSPATH
  -autoproxy             Java 5+ : use the OS proxies
  -main <class>          override Ant's normal entry point

-logger および -listener の詳細については、ロガーとリスナーを参照してください。

-inputhandler の詳細については、InputHandlerを参照してください。

終了動作を変更する最も簡単な方法は、元のメインクラスをサブクラス化することです

public class CustomExitCode extends org.apache.tools.ant.Main {
    protected void exit(int exitCode) {
        // implement your own behaviour, e.g. NOT exiting the JVM
    }
}

そして、このクラスへのアクセス (-lib path-to-class) を付けてAntを起動します。

ライブラリディレクトリ

Ant 1.6 より前は、ANT_HOME/lib 内のすべてのjarが、Antの実行に使用される CLASSPATH に追加されていました。これは、Antを起動するスクリプトで行われていました。Ant 1.6 以降、デフォルトで2つのディレクトリがスキャンされ、必要に応じてさらに追加できます。デフォルトでスキャンされるディレクトリは ANT_HOME/lib とユーザー固有のディレクトリ ${user.home}/.ant/lib です。この構成により、Antのインストールを多くのユーザーで共有しながら、各ユーザーが追加のjarをデプロイできます。このような追加のjarは、Antのオプションタスクのサポートjarや、ビルドで使用するサードパーティタスクを含むjarなどがあります。また、メインのAntインストールをロックダウンすることもでき、システム管理者にとって好都合です。

検索対象の追加ディレクトリは、-lib オプションを使用して追加できます。-lib オプションは検索パスを指定します。パスのディレクトリにあるjarまたはクラスは、Antのクラスローダーに追加されます。classpathにjarが追加される順序は次のとおりです

• コマンドラインで -lib オプションで指定された順序でjar
• ${user.home}/.ant/lib のjar (-nouserlib が設定されていない場合)
• ANT_HOME/lib のjar

CLASSPATH 環境変数は、-lib オプションを使用してAntに渡されることに注意してください。Ant自体は、非常に最小限のclasspathで起動されます。Antは、空の CLASSPATH 環境変数でも完全に機能するはずです。-noclasspath オプションは、実際にそれを強制します。classpathの問題（特に引用符の問題）に関するサポートコールが多すぎるため、改善が必要です。

${user.home}/.ant/lib の場所は、JVMに多少依存します。Unixシステムでは、${user.home} はユーザーのホームディレクトリにマップされますが、最近のバージョンのWindowsでは、C:\Users\username\.ant\lib のような場所になります。詳細については、JVMドキュメントを参照する必要があります。

例

ant

現在のディレクトリの build.xml ファイルを使用して、デフォルトターゲットでAntを実行します。

ant -buildfile test.xml

現在のディレクトリの test.xml ファイルを使用して、デフォルトターゲットでAntを実行します。

ant -buildfile test.xml dist

現在のディレクトリの test.xml ファイルを使用して、dist という名前のターゲットでAntを実行します。

ant -buildfile test.xml -Dbuild=build/classes dist

現在のディレクトリの test.xml ファイルを使用して、dist という名前のターゲットでAntを実行し、build プロパティを build/classes の値に設定します。

ant -lib /home/ant/extras

/home/ant/extras の場所から追加のタスクとサポートjarを取得してAntを実行します

ant -lib one.jar;another.jar

ant -lib one.jar -lib another.jar

Antのclasspathに2つのjarを追加します。

ファイル

Unix用のAntラッパースクリプトは、何かの処理を行う前に ~/.antrc ファイルをソース（読み込みと評価）します。Windowsでは、Antラッパーバッチファイルは、起動時に %HOME%\antrc_pre.bat を、終了時に %HOME%\antrc_post.bat を呼び出します。これらのファイルを使用すると、たとえば、Antの実行中にのみ表示される環境変数を設定または設定解除できます。例については、次のセクションを参照してください。

環境変数

ラッパースクリプトは、次の環境変数（設定されている場合）を使用します

• JAVACMD—Java実行可能ファイルのフルパス。JAVA_HOME/bin/java(.exe) とは異なるJVMを呼び出すために使用します。
• ANT_OPTS—JVMに渡す必要があるコマンドライン引数。たとえば、システムプロパティを定義したり、ここでJavaの最大ヒープサイズを設定したりできます。
• ANT_ARGS—Antコマンドライン引数。たとえば、別のロガーを指定したり、リスナーを含めたり、-find フラグを含めたりするために ANT_ARGS を設定します。
  注: ANT_ARGS に -find を含める場合は、検索するビルドファイルの名前を、ファイルが build.xml という名前であっても含める必要があります。

Javaシステムプロパティ

Antのコアクラスの一部は、システムプロパティを介して構成できます。

以下は、コードベースを検索した結果です。システムプロパティは Project インスタンスからアクセスできるため、

grep -r -n "getPropert" * > ..\grep.txt

コマンドで検索しました。その後、頻繁に使用されるがそれほど重要ではない値（ほとんどが読み取り専用の値）をフィルタリングしました。それらの値は path.separator, ant.home, basedir, user.dir, os.name, line.separator, java.home, java.version, java.version, user.home, java.class.path です
そして、getPropertyHelper アクセスをフィルタリングしました。

新しいプロパティが追加された場合（発生することがあります）、開発者が別のプレフィックスを使用する正当な理由がない限り、ant. および org.apache.tools.ant. プレフィックスの下に表示されると予想してください。したがって、これらのプレフィックスで始まるプロパティの使用は避けてください。これにより、将来の Ant リリースでビルドファイルが破損するのを防ぐことができます。

リターンコード

Ant の起動スクリプト（Windows 版と Unix 版）は、java プログラムのリターンコードを返します。したがって、ビルドが成功した場合は 0 が返され、ビルドが失敗した場合は他の値が返されます。

一時ディレクトリ

Ant を呼び出すときにシステムプロパティを設定することは簡単ではありません。対応するコマンドライン引数を Ant のメインクラスではなく Java 実行可能ファイルに送信する必要があるためです。ant(.cmd) ラッパースクリプトを使用する場合は、ANT_OPTS 環境変数を使用して設定できます。

Ant 1.10.8 以降では、設定されている場合、java.io.tmpdir よりも優先される新しい Ant プロパティ ant.tmpdir が導入されました。これは通常の Ant プロパティであるため、コマンドラインから、またはビルドファイル内からでも設定できます。

一時ディレクトリを使用するタスクと型は、それぞれのマニュアルページにその事実を記載します。また、OpenVMS で外部コマンドを実行するたびに、実際のコマンドを呼び出す DCL スクリプトを保持する一時ファイルが作成されます。

Ant 1.10.9 以降では、Ant は java.io.tmpdir 内に、現在のユーザーのみがアクセスできるようにパーミッションが設定されたビルドプロセス固有の一時ディレクトリを作成しようとし、ant.tmpdir が設定されておらず、Ant が対象のファイルシステムにパーミッションを設定できる場合に使用します。

Ant ディストリビューションで提供されていないタスクは、ant.tmpdir プロパティまたはプロセスサブディレクトリを無視し、Ant 1.10.8 の変更された API に対応していない限り、java.io.tmpdir を使用します。

セキュリティに関する注意：java.io.tmpdir で指定されたデフォルトの一時ディレクトリを使用すると、機密情報が漏洩したり、攻撃者がソースファイルをビルドプロセスに挿入したりする可能性があります。これは、マルチユーザー環境では特に当てはまります。ant.tmpdir を、Ant を実行しているユーザーが所有する、パーミッションが 0700 のディレクトリに設定することをお勧めします。Ant 1.10.8 以降は、それによって作成された一時ファイルを現在のユーザーのみが読み取り/書き込み可能にするように試みますが、OS およびファイルシステムによっては、サイレントに失敗する可能性があります。

Cygwin ユーザー

Ant に付属の Unix 起動スクリプトは、Cygwin で正しく動作します。Cygwin シェルから Ant を起動しても問題ないはずです。ただし、Ant が実行されると、ネイティブ Windows アプリケーションとして動作する JDK の一部となることに注意してください。JDK は Cygwin 実行可能ファイルではないため、Cygwin パスなどを認識しません。特に、<exec> タスクを使用する場合、/bin/sh などの実行可能ファイル名は、Ant が起動された Cygwin シェルから動作する場合でも、機能しません。sh などの実行可能ファイル名を使用し、Windows パスで使用可能なコマンドに依存することができます。

OS/2 ユーザー

OS/2 起動スクリプトは、複雑なタスクを実行するために開発されました。Ant を呼び出す ant.cmd と、Ant の環境を設定する antenv.cmd の 2 つの部分で構成されています。ほとんどの場合、上記と同じコマンドラインオプションを使用して ant.cmd を呼び出すだけです。この動作は、以下で説明するいくつかの方法で変更できます。

スクリプト ant.cmd は、まず Ant 環境が正しく設定されているかどうかを確認します。要件は次のとおりです。

1. 環境変数 JAVA_HOME が設定されている。
2. 環境変数 ANT_HOME が設定されている。
3. 環境変数 CLASSPATH が設定されており、JAVA_HOME から少なくとも 1 つの要素と、ANT_HOME から少なくとも 1 つの要素が含まれている。

これらの条件のいずれかが満たされていない場合、スクリプト antenv.cmd が呼び出されます。このスクリプトは、最初に存在する場合、構成スクリプトを呼び出します。 %ETC% ディレクトリからのシステム全体の構成 antconf.cmd と、%HOME% ディレクトリからのユーザー構成 antrc.cmd です。この時点で、JAVA_HOME と ANT_HOME の両方を定義する必要があります。これは、antenv.cmd が classes.zip または tools.jar（JVM のバージョンによって異なります）と、%ANT_HOME%\lib から ant-*.jar を除くすべてを CLASSPATH に追加するためです。最後に、ant.cmd はディレクトリごとの構成 antrc.cmd を呼び出します。ant.cmd で行われたすべての設定はローカルであり、スクリプトが終了すると元に戻ります。antenv.cmd で行われた設定は、シェル (もちろん ant.cmd から自動的に呼び出されない限り) の有効期間中は永続的です。したがって、antenv.cmd を手動で呼び出し、ant.cmd を呼び出す前にいくつかの設定を変更することが可能です。

スクリプト envset.cmd と runrc.cmd は、補助的なタスクを実行します。すべてのスクリプトには、内部にドキュメントがあります。

Unix(-like) システムで Ant をバックグラウンドプロセスとして実行する

ant & のように Ant をバックグラウンドプロセスとして開始し、ビルドプロセスが別のプロセスを作成する場合、Ant はすぐに標準入力から読み取ろうとし、その結果、プロセスが中断される可能性が高くなります。これを回避するには、Ant の標準入力をリダイレクトするか、対応するタスクの入力関連属性を介して、生成された各プロセスに明示的に入力を提供する必要があります。

このような新しいプロセスを作成するタスクには、fork 属性が true の場合の <exec>、<apply>、または <java> があります。

Java 経由で Ant を実行する

Ant を自分でインストールした場合、Ant は次の 2 つのエントリポイントのいずれかから起動できます。

java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]

java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher [options] [target]

最初の方法は、Ant の従来のエントリポイントを実行します。2 番目の方法は、Ant 1.6 で導入された Ant ランチャーを使用します。前者の方法は -lib オプションをサポートしておらず、必要なすべてのクラスは CLASSPATH からロードされます。必要なすべての jar が利用可能であることを確認する必要があります。少なくとも、CLASSPATH には以下を含める必要があります。

• ant.jar および ant-launcher.jar
• XML パーサー用の jar/クラス
• JDK の必須 jar/zip ファイル

後者の方法は、-lib、-nouserlib、-noclasspath オプションをサポートしており、指定された ANT_HOME から jar をロードします。後者は可能な限り最小限のクラスパスで起動する必要があります。一般的には、ant-launcher.jar のみです。

Ant は、<java> コマンドを介して Ant 内で起動できます。以下に例を示します。

<java classname="org.apache.tools.ant.launch.Launcher"
      fork="true"
      failonerror="true"
      dir="${sub.builddir}"
      timeout="4000000"
      taskname="startAnt">
    <classpath>
        <pathelement location="${ant.home}/lib/ant-launcher.jar"/>
    </classpath>
    <arg value="-buildfile"/>
    <arg file="${sub.buildfile}"/>
    <arg value="-Dthis=this"/>
    <arg value="-Dthat=that"/>
    <arg value="-Dbasedir=${sub.builddir}"/>
    <arg value="-Dthe.other=the.other"/>
    <arg value="${sub.target}"/>
</java>