Page tree
Skip to end of metadata
Go to start of metadata

Overview

Pulse file projects are the most flexible category of pulse™ project. Rather than providing configuration via the web interface, pulse™ file projects are configured using an XML file referred to as a "pulse file". These files describe the commands used to build the project, along with customised artifact capturing and post-processors rules.

Advantages

Although they require more initial configuration effort, pulse™ file projects have advantages over built-in projects:

  • Maintaining complex configurations can become cumbersome using a graphical interface, it is more easily managed using a text file.
  • Configuration may be shared in different ways, e.g. via imports and macros.

In addition, when using a versioned project, you gain the following advantages:

  • The pulse™ file is checked into your SCM, so it is versioned along with your project source code.
  • It is easier to maintain project configuration across multiple branches, as the pulse™ file may be branched and merged using your SCM tools.
  • The same pulse™ file can be used to build the project on multiple pulse™ masters.

We recommend using built-in projects when you are starting out, but you may consider migrating to versioned projects for these reasons.

Types of Pulse File Projects

Pulse file projects are split into two further types:

Type

Description

Custom Projects

The pulse™ file is edited and stored on the pulse™ server.

Versioned Projects

The pulse™ file is stored with your source code in your SCM

An Example Pulse File

As mentioned, pulse™ files are written in XML syntax. An example pulse™ file is shown below:

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

    <regex.pp name="failure.processor">
        <pattern category="error" expression="[Ff]ail(ure)?"/>
    </regex.pp>

    <junit.pp name="junit.processor"/>

    <recipe name="default">
        <executable name="prepare" exe="bash" args="$(script.dir)/prepare.sh">
            <process processor="$(failure.processor)"/>
        </executable>
        <make name="build" makefile="GNUmakefile"/>
    </recipe>

    <recipe name="acceptance-tests">
        <executable name="prepare" exe="bash" args="$(script.dir)/prepare.sh">
            <process processor="$(failure.processor)"/>
        </executable>
        <make name="build" makefile="GNUmakefile" targets="all"/>
        <make name="test" makefile="GNUmakefile" targets="acceptance-test">
            <artifact name="junit.report" file="reports/TESTS-TestSuites.xml">
                <process processor="$(junit.processor)"/>
            </artifact>
        </make>
    </recipe>
</project>

As shown, the pulse™ files are simple descriptions of commands sequences (recipes) used to build your project. The pulse™ file is intended to use your already-existing build system: it is not intended to serve as a build system itself. For this reason, pulse™ files do not support any scripting language or build system features: there are already tools that fill these purposes.

The example illustrates many of the common features of pulse™ files:

  • properties: simple named values that can be used to avoid repetition in the build file. Properties (and other named entities) are referenced using the $(<name>) syntax.
  • post-processors: any number of post processors (regex.pp, junit.pp, etc) can be defined at the top level of the pulse™ file. Each is given a name that may be used to refer to the processor later.
  • recipes: any number of recipes can be defined at the top level. Recipes are sequences of commands executed during a build. Different recipes can be used for different types of builds, for example short, continuous testing builds or long, overnight builds.
  • commands: each recipe consists of one or more commands (executable, make, etc). These commands are executed in the order given when the recipe is built.
  • artifacts: commands may produce artifacts (including the command output) that you may wish to capture and/or apply post-processing to.

Pulse File Reference

As pulse files are extensible via plugins, the exact set of supported commands, post-processors and so on depends on your pulse™ server setup. For this reason, reference documentation for pulse files is built-in to the master server. To access the documentation, click the book link in the top right-hand corner of the web interface.

  • No labels