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 several advantages over built-in projects:
- The full power and flexibility afforded by pulse™ commands and post-processors is only available to pulse™ file projects.
- Maintaining complex configurations becomes cumbersome using a graphical interface, it is more easily managed using a text file.
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™ servers.
We recommend all but the most trivial projects are built using versioned projects for these reasons.
Types of Pulse File Projects
Pulse file projects are split into two further types:
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="${script.dir}/prepare.sh">
<process processor="${failure.processor}"/>
</executable>
<make name="build" makefile="GNUmakefile"/>
</recipe>
<recipe name="acceptance-tests">
<executable name="prepare" exe="${script.dir}/prepare.sh">
<process processor="${failure.processor}"/>
</executable>
<make name="build" makefile="GNUmakefile" targets="all"/>
<command>
<make name="test" makefile="GNUmakefile" targets="acceptance-test">
<artifact name="junit.report" file="reports/TESTS-TestSuites.xml">
<process processor="${junit.processor}"/>
</artifact>
</command>
</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
