diff -r 044383f39525 -r be27ed110b50 buildframework/helium/doc/src/manual/signaling.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/buildframework/helium/doc/src/manual/signaling.rst Wed Oct 28 14:39:48 2009 +0000 @@ -0,0 +1,181 @@ +Configuring Signaling +===================== + +Helium signaling framework offers you a simplest way to control +failures on build flow, and provides you an easy way to get reporting on +some crucial steps of your build. + + +The configuration +----------------- + +The signaling configuration is divided on three parts: + + * the signalConfig: defines the signal (Depreciated - please use signalListenerConfig) + * the signalListenerConfig: defines the signal + * the signalInput: defines what to do when a signal is raised + * the notifierList: defines a set of notifiers + +signalListenerConfig +.................... + +This part of the configuration is not targeted to be overridden by the build manager. + +The following example defines a custom signal named as **customSignal**. +The default configuration must reference a default signalInput configuration using a nested inputRef element, +so the signaling framework knows how to behave when a signal is raised. + +.. code-block:: xml + + + + + + + + + + + +A signal will then be triggered each time the **target-name** completed. The signalInput will then defined how it should be handled. + +Other way to trigger a signal is by using the signal task: + +.. code-block:: xml + + + + + + + + + +signalInput +........... + +This Ant type defines what a signal should do when it is raised. The failbuild attribute defines +if a build failure should be: + + * failing the build now (value: now) + * deferred at the end of the build (value: defer) + * ignored (value: never) + +Then the configuration will accept a reference to a notifierList using the notifierListRef element. + +Example of configurations + +.. code-block:: xml + + + + + +This will run all notifier from the customNotifier configuration then fail the build. + +.. code-block:: xml + + + +This will defer the failure at the end of the build, no notifier will be run. + +notifierList +............ + +The notifierList Ant type allows the user to configure a set of Notifier (e.g Email, execute task): + +The following example configures a notifier list that will send an email and run few echo task to print +some information. + +.. code-block:: xml + + + + + defaultSignalAlwaysNotifier: Signal: ${signal.name} + defaultSignalAlwaysNotifier: Status: ${signal.status} + + + +Detailed documentation of the notifier interface could be found `here <../../helium-antlib/index.html>`_. + + +Example: configuring compileSignal +---------------------------------- + +In this example we will configure the compileSignal to behave this way: + + * send an email to additional users e.g: user@foo.com, user@bar.com + * defer the build failure. + +You configuration should contains (e.g build.xml) + +.. code-block:: xml + + + + ... + + ... + + + + + + + + + + + + +A custom notifierList has been created with **myCustomNotifierList** as reference ID. It defines +a emailNotifier which uses the default email template under Helium (${helium.dir}/tools/common/templates/log/email_new.html.ftl). +It also set the title of you email to be "[signal] My build goes wrong: ${signal.name}" (signal.name property will be replace by the signal name raised). +**notifyWhen** attribute will make the notifier to send a notification only on build failure. +Finally the two additional email addresses will be set using the **additionalrecipients** attribute. + +We then need to link the signal configuration and our custom the notifier list. The signalInput element is use to achieve that. +It must be defined using the same reference ID (see reference overriding howto) as the one in the Helium configuration, the naming convention for this is: **Input**. +Its **failbuild** attribute is set to **defer** which will configure the build to keepgoing, and fail at the end of the build flow. +Finally an embedded notifierListRef element will reference our custom notifier list: **myCustomNotifierList**. + +While failing the signaling framework will execute all notifier defined and then store internally the build failure so it can raise it again at the end of the execution. + + +Example: Report specific errors not included by default +------------------------------------------------------- + +Target prep-work-area has extra log extraction added and output xml is read by a new signal. + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + +