监听器和日志记录器

概述

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）等。

注意：它不适用于 WinNT 及其后续版本，即使使用加载了 ANSI.SYS 的 COMMAND.COM 控制台也是如此。

如果用户希望使用自定义颜色覆盖默认颜色，则必须创建一个包含零个或多个自定义颜色键值对的文件。识别的键及其默认值如下所示

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

每个键都采用定义为 Attribute;Foreground;Background 的颜色组合作为值。在上面的示例中，没有使用背景值。

此文件必须指定为名为 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> 从许多较小的项目构建大型项目时很有用——输出显示正在构建哪个特定项目。以下是一个示例，其中对许多子项目调用“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 接口的类会在子项目启动和停止时收到通知。