In its simpliest form the EmitTask can be considered a custom <echo> replacement. EmitTask allows an executing build to send scoped, complex messages to an external logging system without having to create a custom build listener. A build manager can use any Log4J viewing system to track a build's progress (there are a few free Log4j viewing systems). And because it it based on the MsgTask, EmitTask includes all the message customization features of that task as well.
On its own the EmitTask is pretty handy. However, the EmitConfigureTask adds a level of build-process support to remove some of the administration and maintenance issues associated with specifying lots of options with every <emit> call. The <emitconfigure> task lets you setup defaults for any enclosed emit tasks (including those triggered from antcall's to other targets and/or those triggered from ant calls to sub-builds). The only runtime requirement is that the affected tasks remain within the same Java Virtual Machine and thread-of-execution as the <emitconfigure> task. Here is an example:
<emitconfigure defaultNoiseLevel="${build.noiselevel}" defaultFrom="builds.nightly.AntX"> <antcall target="checkout-tag-sources"/> <antcall target="compile"/> <antcall target="compile-optional-bits"/> <antcall target="acceptance-tests"/> <antcall target="docs"/> <antcall target="build-distrib"/> <antcall target="broadcast-distrib-ready"/> </emitconfigure>The EmitConfigurationType completes the trio. The <emitconfiguration> type allows you to specify a set of default configuration information that an embedded <emitconfigure> can reference; for example:
<emitconfiguration id="build.logging.defaults"> <from="build.nightly.AntX"/> <noiselevel="verbose"/> <emitterFactory="mycompany.builds.AntLogEmitter"/> </emitconfiguration> ... <emitconfigure defaultsRefid="build.logging.defaults"...> ...
For a 'log4j.properties' file: log4j.renderer.com.idaremedia.antx.ErrorSnapshot=\ com.idaremedia.antx.feedback.ErrorSnapshotRenderer For a 'log4j.xml' file: <renderer renderedClass="com.idaremedia.antx.ErrorSnapshot" renderingClass="com.idaremedia.antx.feedback.ErrorSnapshotRenderer">
The error-snapshot support of the <emit> task is often used in conjunction with a protected series of tasks (see JWare/AntX's build-flowcontrol package). If/when a build failure occurs, the emit task ensures that context information and specific fault information is passed on to the diagnostics system. The <protect>/<iferror> tasks provide a mechanism for creating error snapshots; the feedback system provides a mechanism for reporting them. Below is a example demonstrating how these tasks work together:
<protect haltiferror="false"> <iferror capturesnapshot="javadoc.err"> <emit level="error" msgid="msg.javadoc.problem" thrown="javadoc.err" properties="all"/> </iferror> ... <javadoc ... /> </protect>
Using EmitTask: <emit msgid="precompile-checks-done" echo="yes"/> <emit level="debug" properties="all" message="Hi" echo="no"/> <emit from="${feedback.compile}" message="Past precompile checks" echo="yes"/> <emit level="fatal" thrown="${err.last}" msgid="build.failed" properties="all"/> <emit message="javac.options" properties="javac.debug,javac.depend" level="verbose"/> <emit timestamp="on" echo="off" properties="none"/> <emit from="${feedback.distrib}.web" msgid="checkpoint.upload.finished"/> <emit from="${grp.compiling}.apis" task="javac[templates]" msgid="banner.compiling"/> <emit snapshot="build.error" level="fatal"/> Using EmitConfigureTask: <emitconfigure defaultNoiseLevel="info" emitterfactory="my.logging.EmitterFactory"> <emit msgid="msg.compile.start"/> ... </emitconfigure> <emitconfigure />
The JWare/AntX feedback package has been verified against Log4J versions 1.2.6. Several GUI-based appenders (LogFactor5 and ChainSaw) have been tested and work fine. Please report any incompatibilities with standard Log4J distributions to the JWare/AntX developers.