Macros

Macros provide a way to avoid repetition in your pulse™ files. Macros define named fragments of XML which can be referenced multiple times later in the pulse™ file. The body of the macro itself can be an arbitrary fragment well-formed XML. The fragment is parsed for syntatic correctness but is not evaluated until the macro is referenced. When a reference to the macro is made (using the macro-ref element), the reference is effectively replaced by the body of the macro. It is at this point (within the scope of the reference) that the macro body is evaluated. Macro evaluations are completely independent, i.e. references are not effected in any way by earlier references.

It is possible for a macro body to reference another macro. As the body of a macro is not evaluated until the macro is referenced, the macro body may include references to named entities (properties, post-processors etc) before they are defined. All such entities must be defined at the point that the macro is referenced.

Macros obey the same scoping rules as all other named entities. This means, for example, that macro names must not clash with other named entities within the same scope. See the documentation for the property element for more details on scoping.

Attributes

Child Elements

The macro body is an arbitrary fragment of XML. The fragment must be valid at the points where the macro is referenced.

Examples

A basic macro for a commonly-used command. Note that the mode property is defined differently in each recipe:

<macro name="build-command">
    <command name="build">
        <executable exe="build-it.sh" args="MODE=${mode}"/>
        <artifact name="binary" file="bin/foo"/>
    </command>
</macro>

<recipe name="debug">
    <property name="mode" value="DEBUG"/>
    <macro-ref macro="${build-command}"/>
</recipe>

<recipe name="release">
    <property name="mode" value="RELEASE"/>
    <macro-ref macro="${build-command}"/>
</recipe>