From 48a59fa35bee951ceaa835426fd85bbf503e6ec6 Mon Sep 17 00:00:00 2001 From: Jan Materne Date: Thu, 22 Jan 2009 09:05:45 +0000 Subject: [PATCH] Document ProfileLogger git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@736594 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/listeners.html | 119 ++++++++++++++++++++++++------------- 1 file changed, 79 insertions(+), 40 deletions(-) diff --git a/docs/manual/listeners.html b/docs/manual/listeners.html index c44d0f16f..d88f0ec8d 100644 --- a/docs/manual/listeners.html +++ b/docs/manual/listeners.html @@ -122,31 +122,30 @@ listeners and loggers.

BuildLogger -

DefaultLogger

-

Simply run Ant normally, or:

-
+

DefaultLogger

+

Simply run Ant normally, or:

+

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

-
-

NoBannerLogger

-

Removes output of empty target output.

+

NoBannerLogger

+

Removes output of empty target output.

-

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

-
-

MailLogger

+ +

MailLogger

The MailLogger captures all output logged through DefaultLogger (standard Ant output) and will send success and failure messages to unique e-mail lists, with control for turning off success or failure messages individually.

+

Properties controlling the operation of MailLogger:

@@ -257,12 +256,13 @@ control for turning off success or failure messages individually.

No
-
+

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

-
+ +

AnsiColorLogger

The AnsiColorLogger adds color to the standard Ant output @@ -333,16 +333,14 @@ Background is one of the following: 47 -> White

-

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

-
-

Log4jListener

+ +

Log4jListener

Passes build events to Log4j, using the full classname's of the generator of each build event as the category:

-
  • build started / build finished - org.apache.tools.ant.Project
  • target started / target finished - org.apache.tools.ant.Target
    • @@ -350,16 +348,13 @@ each build event as the category:

  • message logged - the classname of one of the above, so if a task logs a message, its classname is the category used, and so on.
-

All start events are logged as INFO.  Finish events are either logged as INFO or ERROR depending on whether the build failed during that stage. Message events are logged according to their Ant logging level, mapping directly to a corresponding Log4j level.

-

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

-

To use Log4j you will need the Log4j JAR file and a 'log4j.properties' @@ -376,7 +371,6 @@ console by the DefaultLogger and send it to a file named 'build.log', you could use the following configuration:

- 
log4j.rootLogger=ERROR, LogFile
 log4j.logger.org.apache.tools.ant.Project=INFO
 log4j.logger.org.apache.tools.ant.Target=INFO
@@ -388,41 +382,37 @@ log4j.appender.LogFile.layout=org.apache.log4j.PatternLayout
 log4j.appender.LogFile.layout.ConversionPattern=[%6r] %8c{1} : %m%n
 log4j.appender.LogFile.file=build.log
-

For more information about configuring Log4J see its documentation page.

-

XmlLogger

+ +

XmlLogger

Writes all build information out to an XML file named log.xml, or the value of the XmlLogger.file property if present, when used as a listener. When used as a logger, it writes all output to either the console or to the value of -logfile. Whether used as a listener or logger, the output is not generated until the build is complete, as it buffers the information in order to provide timing information for task, -targets, and the project. -

-By default the XML file creates -a reference to an XSLT file "log.xsl" in the current directory; look in -ANT_HOME/etc for one of these. You can set the property +targets, and the project.

+

By default the XML file creates a reference to an XSLT file "log.xsl" in the current directory; +look in ANT_HOME/etc for one of these. You can set the property ant.XmlLogger.stylesheet.uri to provide a uri to a style sheet. this can be a relative or absolute file path, or an http URL. If you set the property to the empty string, "", no XSLT transform -is declared at all. -

+is declared at all.

-

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

-
-

TimestampedLogger

+ +

TimestampedLogger

Acts like the default logger, except that the final success/failure message also includes the time that the build completed. For example: @@ -433,13 +423,12 @@ is declared at all.

To use this listener, use the command:

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

BigProjectLogger

+ +

BigProjectLogger

This logger is designed to make examining the logs of a big build easier, especially those run under continuous integration tools. It @@ -488,14 +477,67 @@ Exiting project "junit" are reduced to becoming clear delimiters of where different projects are in charge -or more importantly, which project is failing.

-

To use this listener, use the command:

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

ProfileLogger

+

This logger stores the time needed for executing a task, target and the whole build and prints +these information. The output contains a timestamp when entering the build, target or task and a timestamp and the needed time when exiting. +

+ +

since Ant 1.8.0

+

Example

+Having that buildfile +
+<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>
+
+and executing with ant -logger org.apache.tools.ant.listener.ProfileLogger anotherTarget gives that output (with other timestamps and duration of course ;) : +
+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: finishedThu Jan 22 09:01:00 CET 2009 (250ms)
+
+zip: started Thu Jan 22 09:01:00 CET 2009
+      [zip] Building zip: ...\my.zip
+
+zip: finishedThu Jan 22 09:01:01 CET 2009 (1313ms)
+
+Target aTarget: finishedThu 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: finishedThu Jan 22 09:01:01 CET 2009 (0ms)
+
+Target anotherTarget: finishedThu Jan 22 09:01:01 CET 2009 (0ms)
+
+BUILD SUCCESSFUL
+Total time: 2 seconds
+
+ + +

Writing your own

See the Build Events section for @@ -522,10 +564,7 @@ developers.

Classes that implement org.apache.tools.ant.SubBuildListener receive notifications when child projects start and stop. - - -