pulse Files - Pulse v2.0

Syntax

pulse™ files are written in XML syntax, and thus must be written in well-formed XML. No DTD or schema validation is used during the parsing process, validation is left to the semantic requirements of each element. For completeness, you should include an XML prologue in your pulse™ files:

<?xml version="1.0"?>
...

References

In addition to regular XML syntax, pulse™ files can also contain references to named values within XML attributes and text between tags. A reference is denoted with the syntax ${<name>} where <name> is the name of the entity being referred to. Such entities may be simple property values:

<?xml version="1.0"?>
<project>
    <property name="my.dir" value="bin/scripts"/>

    <recipe name="my-recipe">
        <executable exe="${my.dir}/doit.sh"/>
    </recipe>
</project>

In this case the attribute value "${my.dir}/doit.sh" becomes "bin/scripts/doit.sh". In other cases, the entity referred to may itself be a complex object, for example a post-processor:

<?xml version="1.0"?>
<project>
    <post-processor name="my.pp">
        ...
    </post-processor>

    <recipe name="my-recipe">
        <executable exe="ls">
            <process processor="${my.pp}"/>
        </executable>
    </recipe>
</project>

In this case ${my.pp} is used to refer to the post-processor defined earlier. When the value referred to is a complex entity, only a single reference is allowed, with no surrounding string content in the attribute value.

Escaping

If you need to insert a literal dollar sign ($) in a Pulse file, you must escape it with a backslash (\). As backslash has this special meaning, to insert a literal backslash you must also preceed it with a backslash.

Scopes

References are evaluated at the point they appear in the pulse™ file. Thus an entity (property, post-processor, etc) must be defined before it may be referenced. References exist within a scope, and must have a unique name within that scope. Each pulse™ file defines a global scope in which top-level references may be defined. In addition, each tag in the file defines its own scope, nested within scope of the enclosing tag. Thus it is possible to override the value of a reference within a nested tag:

<?xml version="1.0"?>
<project>
    <property name="cc" value="gcc"/>

    <recipe name="default-cc">
        <make args="CC=${cc}"/>
    </recipe>

    <recipe name="new-cc">
        <property name="cc" value="gcc4"/>
        <make args="CC=${cc}"/>
    </recipe>
</project>

In this case, recipe "default" will make with "gcc", whereas recipe "new-cc" will make with "gcc4". The special element "scope" may be used to literally introduce a new scope at any point in the pulse file. This makes it possible to reuse a property in what would otherwise by the same scope:

<?xml version="1.0"?>
<project>
    <macro name="make">
        <make name="make-${make.target}" makefile="GNUmakefile" targets="${make.target}"/>
    </macro>

    <recipe name="default">
        <scope>
            <property name="make.target" value="install"/>
            <macro-ref macro="${make}"/>
        </scope>
        <scope>
            <property name="make.target" value="cppunit"/>
            <macro-ref macro="${make}"/>
        </scope>
    </recipe>
</project>

The scope element has no affect other than to introduce a new scope. In particular, children of the scope element are added to the scope element's parent.

Macros

To reduce repetition in your pulse™ files, you can use macros. Macros allow you to define a fragment of XML which can be reused throughput the rest of the file. To define a macro, use the macro element. You can reference a macro with the macro-ref element. A simple example is show below:

<?xml version="1.0"?>
<project>
    <macro name="common-commands">
        <make name="build" makefile="GNUmakefile" targets="build"/>
        <make name="test" makefile="GNUmakefile" targets="test"/>
    </macro>

    <recipe name="default">
        <macro-ref macro="${common-commands}"/>
    </recipe>
</project>

Imports

You can also tackle repetition by splitting XML fragments out into multiple files and including them using imports. An imported file has all children of its root node evaluated in the context where the import is made. Consider this partitioning of the above macros example:

import/macros.xml

<?xml version="1.0"?>
<root>
    <macro name="common-commands">
        <make name="build" makefile="GNUmakefile" targets="build"/>
        <make name="test" makefile="GNUmakefile" targets="test"/>
    </macro>
</root>

pulse.xml

<?xml version="1.0"?>
<project>
    <import path="import/macros.xml"/>

    <recipe name="default">
        <macro-ref macro="${common-commands}"/>
    </recipe>
</project>

Root Element

By convention, the root element of every pulse™ file is named project (although this convention is not enforced).

Attributes

Attribute	Description	Required?	Default Value
default-recipe	Name of the recipe to build by default (when no recipe is specified).	No	None

Child Elements

At the top level, you can define any number of properties, post-processors and recipes:

Element	Description	Number
ant.pp	Defines an Ant post-processor.	0 or more
bjam.pp	Defines a BJam post-processor.	0 or more
cppunit.pp	Defines a CppUnit report post-processor.	0 or more
cunit.pp	Defines a CUnit report post-processor.	0 or more
gcc.pp	Defines a GCC post-processor.	0 or more
junit.pp	Defines a JUnit report post-processor.	0 or more
junitee.pp	Defines a JUnitEE report post-processor.	0 or more
junit.summary.pp	Defines a JUnit summary output post-processor.	0 or more
make.pp	Defines a make post-processor.	0 or more
maven.pp	Defines a maven post-processor.	0 or more
maven2.pp	Defines a maven 2 post-processor.	0 or more
msbuild.pp	Defines an MsBuild post-processor.	0 or more
ocunit.pp	Defines an OCUnit post-processor.	0 or more
post-processor	Defines a named group of post-processors.	0 or more
property	Defines a named property for later reference.	0 or more
recipe	Defines a sequence of commands for building a project.	1 or more
regex-test.pp	Defines a regular-expression test post-processor.	0 or more
regex.pp	Defines a regular-expression post-processor.	0 or more
unittestpp.pp	Defines a UnitTest++ post-processor.	0 or more
xcodebuild.pp	Defines a xcodebuild post-processor.	0 or more

Example

<?xml version="1.0"?>
<project default-recipe="default">
    <property name="script.dir" value="bin/scripts"/>

    <regex.pp name="my.pp">
       ...
    </regex>

    <recipe name="default">
        <!-- continuous build and test -->
        ...
    </recipe>

    <recipe name="overnight">
        <!-- overnight stress test -->
        ...
    </recipe>
</project>