diff -r 59bb7c4d6172 -r 0f5e3a7fb6af buildframework/helium/doc/src/manual/signaling.rst --- a/buildframework/helium/doc/src/manual/signaling.rst Fri Feb 05 11:59:41 2010 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,181 +0,0 @@ -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 - - - - - - > - - - - - - - - - - - - - - - -