Overview

Local builds are typically run in a local checkout of your project's source code. This replicates the environment used on the pulse™ server to execute a build of your project.

Preparing

To execute a local build, you need to have a copy of the pulse file for your project. If you are using a versioned project, you will already have a copy of the pulse™ file in your working copy. For other project types, the pulse™ file is available for every build on the "pulse file" tab of the build view. A link is provided to download the pulse™ file to your local machine. The file can be downloaded anywhere, but it is most convenient to place it in the same location as pulse™ would when performing a checkout. To confirm where the file is placed by pulse™, refer to the "working copy" tab for the corresponding build result.

Running

Local builds are executed by running the "local" command using the pulse script (or pulse.bat for Windows users). This command has the following usage:

local

Executes a local build in the current working directory.  A local build reads
a local pulse file (pulse.xml by default) and executes a specified recipe in
your development source tree.  This is useful for reproducing pulse builds
exactly and for debugging pulse files when making changes.

Available options:
-r [--recipe] recipe      : set recipe to execute [default: the default recipe]
-p [--pulse-file] file    : use specified pulse file [default: pulse.xml]
-o [--output-dir] dir     : write output to directory [default: pulse.out]
-e [--resources-file] file: use specified resources file [default: <none>]

If you run pulse local with no options, it will use defaults for the pulse™ file, output directory and recipe (the default recipe is specified in the pulse™ file).

Warning Note that if a directory with the same name as the output directory already exists it will be removed by the local build command.

A Sample Invocation

To illustrate how local builds work, a sample invocation is shown below:

jsankey@shiny:~/pulse/local$ pulse local
pulse file      : 'pulse.xml'
output directory: 'pulse.out'

[<default>]
  commenced: < 1 sec ago
  [bootstrap]
    commenced: < 1 sec ago
    completed: < 1 sec ago
    elapsed  : < 1 sec
    result   : success

  [hello]
    commenced: < 1 sec ago
    completed: < 1 sec ago
    elapsed  : < 1 sec
    result   : success
    artifacts:
      * command output
        * pulse.out/00000001-hello/command output/output.txt
          warning features:
            * Hello, world!

  completed: < 1 sec ago
  elapsed  : < 1 sec
  result   : success

Build report saved to '/home/jsankey/pulse/local/build.log'.

The corresponding pulse™ file has a default recipe with a single command that echos "Hello, World!". Additionally, a post-processor picks up "Hello" as a warning. The output above shows how local build reports what it is doing:

• The pulse™ file and output directories used are printed, in this case the defaults are used.
• The recipe chosen "[<default>]" is printed.
• For each command, the command name is given (e.g. "[hello]") along with time stamps and the command result.
• All artifacts produced by the command are listed, including features detected in those artifacts.
• The result and time stamps for the entire build are reported.
• Finally, a copy of the output is saved to the given build log.

When running a local build, all artifacts are captured as they normally would be, including the output of each command. Thus the output does not appear on the console. The artifacts are captured under the output directory specified, in the same layout as used on a pulse™ server. This allows you to see exactly what will be captured when executing a build on the server.

Resources

When running a local build, the pulse™ build core will not have access to the resources configured on the pulse™ build server. Thus if your pulse™ file references resources, you may need to tell local build about them. For simple cases, local build uses the same resource auto-discovery as a pulse™ server. This may locate the resources for you without you needing to provide any extra information. For custom resources, however, you may need to configure the resources using a simple XML file. Refer to Local Build Resources for details.