リスナーとロガー

概要

Apache Antには、ビルドプロセスを監視するための2つの関連機能、リスナーとロガーがあります。

リスナー

リスナーは、以下のイベントが通知されます。

• ビルド開始
• ビルド終了
• ターゲット開始
• ターゲット終了
• タスク開始
• タスク終了
• メッセージログ

これらは内部でさまざまな記録やハウスキーピング操作に使用されますが、-listener引数を使用してコマンドラインから新しいリスナーを登録できます。

ロガー

ロガーはリスナーの機能を拡張し、以下の機能を追加します。

• 標準出力およびエラープリントストリームへのハンドルを受け取るため、コンソールまたは-logfileで指定されたファイルに情報をログ出力できます。
• ログレベル（-quiet、-verbose、-debug）を認識します。
• Emacsモードを認識します。

組み込みリスナー/ロガー

DefaultLogger

Antを通常どおり実行するか、

ant -logger org.apache.tools.ant.DefaultLogger

NoBannerLogger

空のターゲット出力の出力を削除します。

ant -logger org.apache.tools.ant.NoBannerLogger

MailLogger

MailLoggerは、DefaultLogger（標準のAnt出力）を通じてログに記録されたすべての出力をキャプチャし、成功および失敗メッセージを個別のメールリストに送信します。成功または失敗メッセージを個別にオフにするための制御も可能です。

MailLoggerの動作を制御するプロパティ

ant -logger org.apache.tools.ant.listener.MailLogger

AnsiColorLogger

AnsiColorLoggerは、ANSIカラーコードエスケープシーケンスをプレフィックスとサフィックスとして追加することにより、標準のAnt出力に色を追加します。これはDefaultLoggerの拡張機能であるため、DefaultLoggerが持つすべての機能を提供します。

AnsiColorLoggerは、メッセージのタイプに応じて異なる色を割り当てることで出力を区別します。

-logfileオプションで使用すると、出力ファイルには、cat、moreなどのアプリケーションを使用してコンソールに表示されたときに、テキストを色付きモードで表示するために必要なすべてのエスケープコードが含まれます。

これは、ANSIカラーコードをサポートするターミナルで動作するように設計されています。XTerm、ETerm、Win9xコンソール（ANSI.SYSがロードされている場合）などで動作します。

注：ANSI.SYSがロードされたCOMMAND.COMコンソールを使用した場合でも、WinNTおよび後継では動作しません。

ユーザーがデフォルトの色をカスタムの色で上書きしたい場合は、カスタムカラーキーと値のペアを0個以上含むファイルを作成する必要があります。認識されるキーとそのデフォルト値を以下に示します。

AnsiColorLogger.ERROR_COLOR=2;31
AnsiColorLogger.WARNING_COLOR=2;35
AnsiColorLogger.INFO_COLOR=2;36
AnsiColorLogger.VERBOSE_COLOR=2;32
AnsiColorLogger.DEBUG_COLOR=2;34

各キーは、属性;前景;背景として定義された色の組み合わせを値として受け取ります。上記の例では、背景値は使用されていません。

このファイルは、ant.logger.defaultsという名前のシステム変数の値として指定し、Antアプリケーションを呼び出すjavaコマンドに-Dオプションを使用して引数として渡す必要があります。これを実現する簡単な方法は、ANT_OPTS環境変数に-Dant.logger.defaults=/path/to/your/fileを追加することです。Antの起動スクリプトはこのフラグを認識し、適切にjavaコマンドに渡します。

フォーマット

AnsiColorLogger.*=Attribute;Foreground;Background

Attribute is one of the following:
0 → Reset All Attributes (return to normal mode)
1 → Bright (Usually turns on BOLD)
2 → Dim
3 → Underline
5 → link
7 → Reverse
8 → Hidden

Foreground is one of the following:
30 → Black
31 → Red
32 → Green
33 → Yellow
34 → Blue
35 → Magenta
36 → Cyan
37 → White

Background is one of the following:
40 → Black
41 → Red
42 → Green
43 → Yellow
44 → Blue
45 → Magenta
46 → Cyan
47 → White

ant -logger org.apache.tools.ant.listener.AnsiColorLogger

Log4jListener

非推奨：Apache Log4j（1）は開発が終了しています。最終リリースは2012年5月26日の1.2.17であり、脆弱性の問題が含まれています。

各ビルドイベントのジェネレーターの完全なクラス名をカテゴリとして使用して、ビルドイベントをLog4jに渡します

• ビルド開始/ビルド終了—org.apache.tools.ant.Project
• ターゲット開始/ターゲット終了—org.apache.tools.ant.Target
• タスク開始/タスク終了—タスクの完全修飾クラス名
• メッセージログ—上記のいずれかのクラス名。たとえば、タスクがメッセージをログに記録する場合、そのクラス名が使用されるカテゴリになります。

すべての開始イベントはINFOとしてログに記録されます。終了イベントは、ビルドがその段階で失敗したかどうかによって、INFOまたはERRORとしてログに記録されます。メッセージイベントは、Antのログレベルに従ってログに記録され、対応するLog4jレベルに直接マッピングされます。

ant -listener org.apache.tools.ant.listener.Log4jListener

Log4jを使用するには、Log4j JARファイルとlog4j.properties構成ファイルが必要です。両方ともAntクラスパスのどこかに配置する必要があります。log4j.propertiesがプロジェクトのルートフォルダーにある場合は、-libオプションを使用して追加できます。

ant -listener org.apache.tools.ant.listener.Log4jListener -lib .

たとえば、DefaultLoggerによってコンソールに出力されるのと同じ情報をキャプチャし、build.logという名前のファイルに送信する場合は、次の構成を使用できます。

log4j.rootLogger=ERROR, LogFile
log4j.logger.org.apache.tools.ant.Project=INFO
log4j.logger.org.apache.tools.ant.Target=INFO
log4j.logger.org.apache.tools.ant.taskdefs=INFO
log4j.logger.org.apache.tools.ant.taskdefs.Echo=WARN

log4j.appender.LogFile=org.apache.log4j.FileAppender
log4j.appender.LogFile.layout=org.apache.log4j.PatternLayout
log4j.appender.LogFile.layout.ConversionPattern=[%6r] %8c{1} : %m%n
log4j.appender.LogFile.file=build.log

Log4Jの構成の詳細については、ドキュメントページを参照してください。

Log4j 1.2 Bridgeの使用

アプリケーションがLog4j（1.x）APIに対して作成されているが、Log4j 2.xランタイムを使用したい場合は、Log4j Bridgeを使用できます。Antでブリッジを使用するには、以下を追加する必要があります。

• log4j-1.2-api-${log4j.version}.jar
• log4j-api-${log4j.version}.jar
• log4j-core-${log4j.version}.jar
• log4j2.xml

たとえば、-libオプションを使用して、クラスパスに追加します。（ブリッジを使用するには、Ant 1.9.10/1.10.2以降が必要です。）1.xプロパティファイルを2.x XML構文に変換すると、次のようになります。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
  <Appenders>
    <File name="file" fileName="build.log">
      <PatternLayout>
        <Pattern>[%6r] %8c{1} : %m%n</Pattern>
      </PatternLayout>
    </File>
  </Appenders>
  <Loggers>
    <Root level="ERROR">
      <AppenderRef ref="file" level="DEBUG"/>
    </Root>
    <Logger name="org.apache.tools.ant.Project" level="INFO"/>
    <Logger name="org.apache.tools.ant.Project" level="INFO"/>
    <Logger name="org.apache.tools.ant.taskdefs" level="INFO"/>
    <Logger name="org.apache.tools.ant.taskdefs.Echo" level="WARN"/>
  </Loggers>
</Configuration>

XmlLogger

リスナーとして使用すると、すべてのビルド情報をlog.xmlという名前のXMLファイル、またはXmlLogger.fileプロパティの値（存在する場合）に書き出します。ロガーとして使用すると、すべての出力をコンソールまたは-logfileの値のいずれかに書き込みます。リスナーまたはロガーのどちらとして使用しても、タスク、ターゲット、およびプロジェクトのタイミング情報を提供するために情報をバッファリングするため、ビルドが完了するまで出力は生成されません。

デフォルトでは、XMLファイルは現在のディレクトリにあるXSLTファイルlog.xslへの参照を作成します。これらのファイルの1つについては、ANT_HOME/etcを確認してください。スタイルシートへのURIを提供するには、プロパティant.XmlLogger.stylesheet.uriを設定できます。これは、相対または絶対ファイルパス、またはHTTP URLにすることができます。プロパティを空の文字列に設定すると、XSLT変換はまったく宣言されません。

ant -listener org.apache.tools.ant.XmlLogger
ant -logger org.apache.tools.ant.XmlLogger -verbose -logfile build_log.xml

TimestampedLogger

デフォルトのロガーのように動作しますが、最後の成功/失敗メッセージにはビルドが完了した時刻も含まれます。例：

BUILD SUCCESSFUL - at 16/08/05 16:24

このリスナーを使用するには、次のコマンドを使用します。

ant -logger org.apache.tools.ant.listener.TimestampedLogger

BigProjectLogger

このロガーは、特に継続的インテグレーションツールで実行される大規模なビルドのログを簡単に調べられるように設計されています。それは

1. 子プロジェクトに入るとき、その名前とディレクトリを出力します
2. 子プロジェクトを終了するとき、その名前を出力します
3. ターゲットを出力するときにプロジェクト名を含めます
4. 直接タスク出力がないすべてのターゲットの名前のロギングを省略します
5. TimeStampロガーのビルド完了タイムスタンプを含めます

これは、<subant>を使用して多数の小さなプロジェクトから大きなプロジェクトをビルドする場合に役立ちます。出力は、どの特定のプロジェクトがビルドしているかを示します。これは、「clean」が多数の子プロジェクトに対して呼び出され、そのうちの一部だけが処理を実行する例です

======================================================================
Entering project "xunit"
In /home/ant/components/xunit
======================================================================

xunit.clean:
   [delete] Deleting directory /home/ant/components/xunit/build
   [delete] Deleting directory /home/ant/components/xunit/dist

======================================================================
Exiting project "xunit"
======================================================================

======================================================================
Entering project "junit"
In /home/ant/components/junit
======================================================================

======================================================================
Exiting project "junit"
======================================================================

この例では、開始と終了のメッセージが非常に冗長ですが、大規模なプロジェクトで多数の子コンポーネントをコンパイルまたはテストする場合、メッセージは、どのプロジェクトが担当しているか、より重要なのは、どのプロジェクトが失敗しているかを明確に示すための区切り記号になります。

このリスナーを使用するには、次のコマンドを使用します。

ant -logger org.apache.tools.ant.listener.BigProjectLogger

SimpleBigProjectLogger

Ant 1.8.1 以降

BigProjectLogger と同様に、プロジェクト修飾されたターゲット名が出力されます。これはサブプロジェクトを含む大規模なビルドに役立ちます。それ以外の場合は NoBannerLogger と同様に静かです。

Buildfile: /sources/myapp/build.xml

myapp-lib.compile:
Created dir: /sources/myapp/lib/build/classes
Compiling 1 source file to /sources/myapp/lib/build/classes

myapp-lib.jar:
Building jar: /sources/myapp/lib/build/lib.jar

myapp.compile:
Created dir: /sources/myapp/build/classes
Compiling 2 source files to /sources/myapp/build/classes

myapp.jar:
Building jar: /sources/myapp/build/myapp.jar

BUILD SUCCESSFUL
Total time: 1 second

このリスナーを使用するには、次のコマンドを使用します。

ant -logger org.apache.tools.ant.listener.SimpleBigProjectLogger

ProfileLogger

Ant 1.8.0 以降

このロガーは、タスク、ターゲット、およびビルド全体を実行するために必要な時間を保存し、これらの情報を出力します。出力には、ビルド、ターゲット、またはタスクに入るときにタイムスタンプが含まれ、終了するときにはタイムスタンプと必要な時間が含まれます。

例

<project>
    <target name="aTarget">
        <echo>echo-task</echo>
        <zip destfile="my.zip">
            <fileset dir="${ant.home}"/>
        </zip>
    </target>
    <target name="anotherTarget" depends="aTarget">
        <echo>another-echo-task</echo>
    </target>
</project>

ant -logger org.apache.tools.ant.listener.ProfileLogger anotherTarget を実行すると、次の出力が得られます（もちろん、タイムスタンプと期間は異なります ;-)

Buildfile: ...\build.xml

Target aTarget: started Thu Jan 22 09:01:00 CET 2009

echo: started Thu Jan 22 09:01:00 CET 2009
     [echo] echo-task

echo: finished Thu Jan 22 09:01:00 CET 2009 (250ms)

zip: started Thu Jan 22 09:01:00 CET 2009
      [zip] Building zip: ...\my.zip

zip: finished Thu Jan 22 09:01:01 CET 2009 (1313ms)

Target aTarget: finished Thu Jan 22 09:01:01 CET 2009 (1719ms)

Target anotherTarget: started Thu Jan 22 09:01:01 CET 2009

echo: started Thu Jan 22 09:01:01 CET 2009
     [echo] another-echo-task

echo: finished Thu Jan 22 09:01:01 CET 2009 (0ms)

Target anotherTarget: finished Thu Jan 22 09:01:01 CET 2009 (0ms)

BUILD SUCCESSFUL
Total time: 2 seconds

独自のロガーの作成

開発者向けの ビルドイベント セクションを参照してください。

注意

• リスナーまたはロガーは、messageLogged() メソッドで標準出力またはエラーに出力してはなりません。Ant はこれらを内部的にキャプチャし、無限ループを引き起こします。
• ログは同期処理です。すべてのリスナーとロガーは、ビルドが処理されるまでブロックされ、順番に呼び出されます。ログが遅いと、ビルドが遅くなります。
• ビルドが開始され、BuildListener.buildStarted(BuildEvent event) が呼び出されると、プロジェクトは完全に機能しているわけではありません。ビルドは開始されました。はい、event.getProject() メソッド呼び出しは Project インスタンスを返しますが、そのプロジェクトは JVM および Ant プロパティで初期化されており、ビルドファイルをまだ解析していません。Project.getProperty() を呼び出してプロパティを検索したり、Project.getName() を呼び出してプロジェクト名を取得したりすることはできません（null が返されます）。
• org.apache.tools.ant.SubBuildListener を実装するクラスは、子プロジェクトの開始と停止時に通知を受け取ります。