--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/buildframework/helium/doc/src/tutorials/configuration/HowtoCreateANewSignal.rst	Wed Oct 28 14:39:48 2009 +0000
@@ -0,0 +1,113 @@
+How to create a new signal
+==========================
+
+This document will help you implementing a new signal in your configuration.  
+
+Use case
+--------
+You have one target named **custom-action** which
+should generate an artifact in some know location, and you would like the build to continue as far 
+as possible even if that artifact is missing, but being informed during the build it is not going as expected. 
+
+
+Base configuration
+------------------
+
+The following code snippet will be the base configuration for this exercise.   
+
+build.xml
+
+.. code-block:: xml
+
+   <?xml version="1.0" ?>
+   <project name="config" default="test" xmlns:hlm="http://www.nokia.com/helium"> 
+      <property environment="env"/>
+      <import file="${helium.dir}/helium_preinclude.ant.xml"/>
+
+      <!-- Location of the artifact -->    
+      <property name="artifact" location="artifact.txt"/>
+            
+      <import file="${helium.dir}/helium.ant.xml"/>
+
+      <!-- The target -->
+      <target name="custom-action">
+         <delete failonerror="false" file="${artifact}"/>
+         <if>
+            <istrue value="${create.artifact}"/>
+            <then>
+               <echo file="${artifact}">My artifact</echo>
+            </then>
+         </if>
+      </target>
+      
+      <target name="custom-dummy">
+        <echo message="Dummy action"/>
+      </target>
+   
+   </project>   
+
+
+
+To declare a new signal to the framework you need to define a new signalConfig reference.
+You also need to create a signalInput configuration to define your signal behaviour.
+
+.. code-block:: xml
+ 
+   <hlm:signalInput id="customActionSignalInput" failbuild="defer"/>
+   
+   <hlm:signalListenerConfig id="customActionSignal" name="custom-action" message="custom-action target ended.">
+      <signalNotifierInput>
+          <signalInput refid="customActionSignalInput" />
+          <notifierInput file="${artifact}" />
+      </signalNotifierInput>
+      <hlm:targetCondition>
+         <not><available file="${artifact}"/></not>            
+      </hlm:targetCondition>
+   </hlm:signalConfig>
+
+
+The signalListenerConfig defines which target to listen and raise signal for. The target name is defined through the **name** attribute.
+Then the nested **targetCondition** element is used to configure how the signal should be triggered.
+This element accepts any nested `Ant conditions <http://ant.apache.org/manual/CoreTasks/conditions.html>`_.
+In this case the signal will get raised only id the file is not present after the execution of the **custom-action** target.
+
+The framework then uses the defined signalInput from the signalNotifierInput configuration to know how to behave when the signal is raised. In the previous example it will
+simply keep running and fail the build at the end. Then files defined by the nested notifierInput will be passed to the notifier.
+
+The execution of the **custom-action custom-dummy** build sequence will happen entirely even if the artifact is not 
+created properly, then fail the build mentioning the faulty target::
+
+   > hlm custom-action custom-dummy
+   Internal data listening enabled.
+   Buildfile: build.xml
+        [echo]  Using build drive X:
+   
+   custom-action:
+   18:21:14,503  INFO - Signal customActionSignal will be deferred.
+   
+   custom-dummy:
+        [echo] Dummy action
+   
+   BUILD FAILED
+   customActionSignal: custom-action target ended. : custom-action
+   
+   
+   Total time: 2 seconds
+
+
+If you enable the artifact creation then the build will proceed successfully::
+
+   >hlm custom-action custom-dummy -Dcreate.artifact=true
+   Internal data listening enabled.
+   Buildfile: build.xml
+        [echo]  Using build drive X:
+   
+   custom-action:
+   
+   custom-dummy:
+        [echo] Dummy action
+   
+   BUILD SUCCESSFUL
+   Total time: 2 seconds
+
+   
\ No newline at end of file