監聽器和記錄器

概觀

Apache Ant 有兩個相關功能，允許監控建置程序：監聽器和記錄器。

監聽器

監聽器會收到下列事件的警示

• 建置開始
• 建置完成
• 目標開始
• 目標完成
• 任務開始
• 任務完成
• 訊息記錄

這些訊息會在內部用於各種記錄和管理作業，不過新的監聽器可以使用 -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 會在標準 Ant 輸出加上顏色，方法是加上 ANSI 顏色碼跳脫序列作為字首和字尾。它只是 DefaultLogger 的延伸，因此提供 DefaultLogger 的所有功能。

AnsiColorLogger 會根據訊息類型指派不同的顏色，以區分輸出。

如果與 -logfile 選項一起使用，輸出檔將包含所有必要的跳脫碼，以便在使用 cat、more 等應用程式在主控台中顯示時，以彩色模式顯示文字。

這項設計適用於支援 ANSI 顏色碼的終端機。它可以在 XTerm、ETerm、Win9x 主控台（已載入 ANSI.SYS）等終端機上執行。

注意：即使已載入載入 ANSI.SYS 的 COMMAND.COM 主控台，它也不適用於 WinNT 和後續版本。

如果使用者想要以自訂顏色覆寫預設顏色，則必須建立一個包含零個或多個自訂顏色金鑰值配對的檔案。已識別的金鑰及其預設值如下所示

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 的系統變數的值，並使用 -D 選項傳遞為引數給呼叫 Ant 應用程式的 java 命令。要輕鬆達成此目的，一個簡單的方法是將 -Dant.logger.defaults=/path/to/your/file 新增至 ANT_OPTS 環境變數。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 橋接器

如果您應用程式是針對 Log4j (1.x) API 編寫，但您想使用 Log4j 2.x 執行時期，您可以使用 Log4j 橋接器。要將橋接器與 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 的參考；在 ANT_HOME/etc 中尋找其中一個。您可以設定屬性 ant.XmlLogger.stylesheet.uri 以提供樣式表的 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> 從許多較小的專案建置大型專案時，這項功能很有用，輸出會顯示正在建置的特定專案。以下是一個範例，其中會對所有子專案呼叫「清除」，其中只有部分專案會執行工作

======================================================================
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 的類別會在子專案啟動和停止時收到通知。