Loading...

All project content is available for reading, but you need to be a member of the project for Subversion checkout of source code, or to create/modify any information.
Login if you are a member. Apply here to request membership (open to all).

Get Started with Automated Builds

This is a tutorial and introduction about how to get started using the CodeResort automated builds, based on Bitten. Each section in this tutorial explains an important aspect of the Builds service, so read and performs steps from top to bottom - by the end you should have your first build executed:

  1. Overview
  2. Permissions
  3. Configuration
  4. Running the slave
  5. Refinement & Further Reading

Overview

The Build service is based on a simple master-slave architecture:

  • master ::: Configures, coordinates and reports builds. This is the part that is available in your web project, under the Builds menu, and in Admin as Builds->Configurations. Additionally it will report builds in Timeline as well as provide email notificaiton if enabled.
  • slave ::: Installed on one or more machines under your control, that will poll the master for available builds, execute them, and report its results back to master.

Permissions

In project Admin->General->Permissions (project-owners only), permissions for the Builds sub-system can be configured. All build-related permissions starts with BUILD_, and allow fine-grained control over the build process.

Start with a simple permissions system, and expand as needed. Here is one possible setup:

Permission Description
BUILD_VIEW Assign this to all your project members so they can see the Build reports. Typically adding it to @member should be sufficient.
BUILD_EXEC Assign this to the users that are to be allowed to run slaves, and execute builds. Typically add the permission to each user.
BUILD_ADMIN For members that aren't @owner, that should be allowed to administrate builds and configurations. Assign to each user.

STEP: Assign permissions now if not already done.

Configuration

The core of the builds system is the build configurations, managed in Admin->Builds->Configurations.

A configuration consists of:

  • Display name and Description ::: Visual information for users about the configuration.
  • Repository mapping ::: Listen to changes for specific parts of the repository, and trigger builds when subpaths match. If you have BranchA and BranchB in your repository, each will typically map to its own configuration and only run builds when changes are seen in its own branch.
  • Recipe ::: The core of the configuration detailing how the build should be executed by the slave. The recipe is an XML document.
  • Target platforms ::: One or more target platforms, where target can be different operating systems, different architectures, or different versions of supporting infrastructure (like .NET 2.0 vs .Net 3.5).

STEP: Go to Build configuration administration, and create one if one doesn't exist. Intital creation requires a shortname, a display name and a subpath in the repository matching the purpose of the configuration.

You should now see a detailed view of the configuration. Let's add a trivial recipe for execution.

STEP: In the 'Recipe' textarea, paste this recipe (changing '<projectname>' to your project name, without < and >):

<build xmlns:svn="http://bitten.edgewall.org/tools/svn"
       xmlns:sh="http://bitten.edgewall.org/tools/sh">
    <step id="checkout" description="Checking out source code">
        <svn:checkout url="https://www.coderesort.com/svn/<projectname>"
            path="${path}" revision="${revision}">
        </svn:checkout>
    </step>
    <step id="start" description="Build start message">
        <sh:exec executable="echo" args="We are building!" />
    </step>
</build>

The recipe consists of 2 steps, each step running one command. Many steps can be added, and many commands can be run as part of each step. The step is a container for a natural and distinct part of the build process.

STEP: Now click 'Save'.

Lastly we need to add a target for this configuration. Targets can be many and complex if needed, or really simple. We will make one target, as simple as possible.

STEP: In 'Add Target' on the right, enter 'Any' as new target. In the page target details page, just click 'Save' to return as we won't add rules at this stage - essentially making our target match any slave that connects.

Now we have a configuration, and last remaining step is to enable it.

STEP: Click Builds->Configurations in the Admin menu on the left to get back to Configurations listing. It should list your newly created configuration, and click the 'Active' checkbox and save using 'Apply changes' button.

Running the slave

For installing and configuring the build slave, there is another simple step-by-step Help page: HelpUser/Builds/Install.

STEP: Follow HelpUser/Builds/Install and install the slave software on your local machine.

The <svn:checkout> command has support for specifying a username and a password, but that is not generally insecure as it will reveal your password, and is not the best option to use if many different users will be running slaves. Instead, we can have the Subversion client connect to our repository and make it store the credentials for later use (ie. when the builds are executed).

STEP: On command-line, run svn info https://www.coderesort.com/svn/<projectname> (again replacing '<projectname>' with your name of your project). Store credentials when asked to.

We are now ready to start the build slave and run our first build.

STEP: Open a command-line prompt, and replacing 'myuser@…' with your CodeResort login, and '<projectname>' in the URL with the name of your project:

C:\Dev> bitten-slave -u myuser@mydomain.com -P https://www.coderesort.com/p/<projectname>/builds
Password:
[INFO    ] Slave launched at 2009-09-09 10:20:13
[INFO    ] Build pending at https://www.coderesort.com/p/<projectname>/builds/1
[INFO    ] Executing build step 'checkout'
....

STEP: Watch it execute, and hit Ctrl-C when it reports 'No pending builds.'. For this tutorial starting and stopping makes more sense, but for production you would normally start a build slave that runs continuously polling at regular intervals fore new builds.

Your slave should now run the two steps we have configured, and report results back to the master. Let's see what that looks like.

STEP: Open https://www.coderesort.com/p/<projectname>/build in a browser. You should see your configurations, and latest builds. Click the name of a configuration to see all builds for it (if you followed the tutorial there should just be one for now), and click the build number to see the details of the build execution. It should have two sections corresponding to our recipe, with results for each.

Refinement & Further Reading

If all is working so far, then you are ready to start refining your recipe - and actually make it do something more useful. As the details all depends on the source that exists in your repository path, no futher detailed examples are possible. It all depends on what you have and what you want to do. However, here are some final steps on how to refine and rerun your build:

STEP: Refine your recipe by adding another command - we'll just add another trivial example just to explain the process: Add a new 'echo' command to the 'start' step for instance, like <sh:exec executable="echo" args="We are expanding!"/>.

As a build for a unique combination of revision, configuration and target can only be done once, we need to invalidate it to have it run again.

STEP: Open web project builds report again, and find the details of the build we ran before. If permissions allow, there should be an 'Invalidate build' button. Click it, and build results should be deleted.

STEP: Run the 'bitten-slave' command-line program again, same parameters. It should now rebuild the same build. When viewing details on the master (web project), it should also display the new message from the second 'echo' command.

You should now have a fundamental understanding of how Builds work at CodeResort. For futher refinement, browse through the Builds reference Help pages:

Also, we'll be compiling a HowTo/Builds/CookBook with various example recipes and steps for popular tools on popular platforms. Check it for ideas and inspiration.