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:
- 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™ masters.
We recommend using built-in projects when you are starting out, but you should consider migrating to 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
