There are two ways to install default logging configuration depending on what you’re trying to accomplish. Both methods require that you predefine your logging configuration in a separate Log4Ant <emit:configuration> object and then use the <emit:manage> administration task to install that object into your Ant fixture where it is picked up by the various Log4Ant components.

In Log4Ant, the term “default configuration” really represents a LIFO list of configurations plus one ‘fall back’. The list is comprised of configurations you install; each newly installed configuration is put at the front of the list and gets to respond first if any Log4Ant component asks for the current “default configuration”. If the list is empty (you never installed anything) or no configuration in the list has overridden the requested attribute, then the ‘fall back’ configuration gets to respond.

If you have a single logging setup that you want all Log4Ant components to use, installing a fall back configuration with <emit:manage> is the most straightforward thing to do as shown in the next snippet. Note that there can be only ONE fall back configuration for the entire Ant execution cycle— regardless of whether you’re doing a master and independent sub-builds, and you should install the fall back before using any Log4Ant emit or capture component. While you don’t have to uninstall a fall back configuration, you can by passing ‘uninstall-fallback’ as an action for the <emit:manage> task as demonstrated below.

 1: [Declare your logging configuration…]
 2: <emit:configuration id="app.log.conf"
 3:   wrt="longdate" to="MyApp".../>
 4:
 5: [Install your configuration as default…]
 6: <emit:manage action="install-fallback">
 7:   <parameter name="app.log.conf"/>
 8: </emit:manage>
 9:
10: [Log4Ant tasks will pick up fall back as defaults…]
11: <emit:show messageid="LF.build.started"/>
12: <emit:checkpoint/>
13:
14: [If you have a "shutdown" include this...]
15: <emit:manage action="uninstall-fallback"/>

You can also use <emit:manage> to install a configuration temporarily to either block or complement the existing fall back configuration. Unlike a fall back configuration, you can install as many of these configurations as you like– provided you eventually uninstall them. Each newly installed configuration is installed “at the front of” the Log4Ant default configuration list, so if a task asks Log4Ant for the “default configuration”, the front most configuration is queried first.

 1: [Declare our local 'docs' logging configuration…]
 2: <emit:configuration id="docs.log.conf"
 3:   wrt="default" to="Documentation" echo="off"/>
 4:
 5: [Install 'docs' configuration as frontmost…]
 6: <emit:manage action="install">
 7:   <parameter name="docs.log.conf"/>
 8: </emit:manage>
 9:
10: [Log4Ant will pick up 'docs' -AND- others in list…]
11: <protect>
12:   <emit:show messageid="LF.docs.generation.started"/>
13:   <parallel failonany="yes" timeout="${10mins}">
14:     <apidocs-complete/>
15:     <coverage-reports-complete/>
16:     <style-reports-complete/>
17:     <change-reports asof="${ci.asof.datetime}"/>
18:   </parallel>
19:   <hackystat-trendreports/>
20:
21:   [Uninstall our 'docs' configuration...we're done]
22:   <always>
23:     <emit:manage action="uninstall">
24:       <parameter name="docs.log.conf"/>
25:     </emit:manage>
26:   </always>
27: </protect>

Instead of installing a configuration temporarily as a default, you can also use the <emit:overlay> taskset to apply configuration to a local set of tasks. So what’s the difference?

Well, from a implementation details perspective, not much really– both tasks affect the same internal Log4Ant configuration LIFO list. However, the context under which you use one over the other is what matters. The <emit:manage> route lets you install and uninstall the configuration disjointly; meaning, you can install the configuration in one project or target, and uninstall it (if ever) in another project or target at some unknown later time. With <emit:overlay> the entire install-uninstall process must occur in a single place, within the context of a single taskset.

So depending on your requirements, you should choose the method that better suits your needs. As a demonstration, if the previous example was really just part of a single Ant target, we could just have easily done it with <emit:overlay> as shown below with much more succinct Ant script. The overlay does the job of installing and uninstalling configuration around the enclosed components.

 1: [Declare our local 'docs' logging configuration…]
 2: <emit:configuration id="docs.log.conf"
 3:   wrt="default" to="Documentation" echo="off"/>
 4:
 5: [Log4Ant will pick up 'docs' -AND- others in list…]
 6: <emit:overlay with="docs.log.conf">
 7:   <emit:show messageid="LF.docs.generation.started"/>
 8:   <parallel failonany="yes" timeout="${10mins}">
 9:     <apidocs-complete/>
10:     <coverage-reports-complete/>
11:     <style-reports-complete/>
12:     <change-reports asof="${ci.asof.datetime}"/>
13:   </parallel>
14:   <hackystat-trendreports/>
15: </emit:overlay>

• How do I setup Logger hierarchies?
• How do I get the Ant script location in messages?