Compass Version 1.3

Quick Setup Guide

• Logs
• Language Settings
• Server Settings
• Scripts
• Build Configurations
• User Administration
• Project Administration
• Source-Control Server

Details on each of these are provided in the full Compass documentation. For the purposes of our quick install guide and to set up a compass server with minimal effort, the only sections that are required to be modified are the last three: Users, Projects and Source-Control. The rest of this installation guide sets up a Compass server with one non-admin user, one subversion source-control server, and one project that has a single build that runs whenever the repository changes as well as every 2 hours. Finally we will set up an email notification for when our build fails.

Add a User

The first step is to add a user. Right after installation the user administration section looks something like this:

Add a Source-Control Server

The next step is to add a source control server. In the source-control server section there's a button labeled 'Create New Server'. Click on this button and the new Source-Control Server dialog appears that looks like this:

In this dialog, we give our new source control server a name. This is the name that is used internal to Compass and can be anything you want that describes which source control server this is. The Server URL is the URL to access the server. For a subversion server this would look like: 'svn+ssh:// This e-mail address is being protected from spambots. You need JavaScript enabled to view it /path/ ./'. If the repository requires authentication then check the box for authentication and add a valid username and password in the appropriate fields.

When you have filled out this dialog and click 'Submit', Compass will verify that it can contact the server and if it is successful then the server will be added to the source-control server list on the administration page; and if it is not successful you will recieve an error dialog with the reason Compass failed to add the source-control server.

Create a Project

Now that we've added a user and soure-control server we need to create a project. In the 'Project Administration' section. Click on the 'Create New Project' button and give your new project a name. This can be any name you like that describes what this project will be building and/or testing. Click the 'Create' button and confirm your name and then the 'Project Administration' section looks like this:

The Project Administration page now has one row with our new project in it, and the next step is toadd our new user to the project so they have access to the project when they log in. To do this, click on the 'User Permissions' button. In this dialog you can add and remove users on each project. You can let users be project admins or just regular users. Project admins can schedule builds and help administer the project but do not have site-wide administrative privileges. After adding our user to the project this dialog looks like this:

Now that our project is added and accessible by our users it's time to set up a build plan to build and test our source code. To do this we click on the name of the project. This takes us to the 'Project Details Page'

Create a New Build Plan

After clicking on the project name from the Administrator page we arrive at the Project Details page. On the Project Details Page there are 5 sections as described here:

To create a new build click on 'Create Build' This will ask you for the name you want to give this build plan. Once you click 'Create' you are taken to the 'Build Plan Editor' for your newly created project. The 'Build Plan Editor' looks like this:

To create a build plan, we enter a list of scripts that will be run in order. The scripts can do almost anything you want them to do. In this start-up guide we only use scripts that come with Compass for checking out code, build code and run tests; to create new scripts see the scripts documentation section.

To add our first script, a check-out script, we click the 'Add Build Step' button. This adds a line to the build plan. We give this step a name: 'My Check Out' and we select which script we want to run ' SVN Revision Checkout'. Now the build plan looks like this:

We choose to use an SVN Revision checkout. This will be executed by Compass any time the repository changes, but we also want this build plan to run every 2 hours. For an SVN revision checkout script, Compass determines the server URL and revision number to check out when the build is triggered by the repository change. But, if we also want the HEAD revision to be checked out every 2 hours we have to specify the server URL and revision to use. We provide defaults values by clicking on the defaults button:

This brings up the defaults dialog. The 'Defaults Dialog' provides a way to specify default values for arguments that are passed to each script. In this case we have set up a 'revision checkout' script. In the 'Defaults Dialog' we enter the default value for 'revision' as 'HEAD' and for 'server_url' as 'svn+ssh:// This e-mail address is being protected from spambots. You need JavaScript enabled to view it /path/ ./' as shown here:

We now have a build step that will check out code for either a change to the repository or for a regularily scheduled build. Now we add two more steps, one to build our executable and another to run a pyunit test suite. After adding both of these steps our build plan looks like this:

For the 2nd build step that runs Visual Studio Build we need to edit the defaults to again to specify which project to in the solution to build. This is exactly the same as for the svn revision checkout bu this time we specify the CONFIG_NAME as the parameter like this:

And finally, on the last build step we have to tell Compass to run a unit test parser. We also only want to recieve a warning if this build step fails. To make these changes we open the details dialog:

Clicking this icon brings up the Details dialog and here we can set the unit test parser to use, and also tell Compass to only give us a warning if there is a failed test. After making these changes the 'Details Dialog' looks like this:

After setting the fail condition and the unit test parser and clicking 'OK' we are done setting up steps for our build plan. We just have the build plan configuration steps remaining. These appear after the build steps and control how the build saves data and what configurations to run the build on. Since we are setting up a windows build, the only change we need to make is to uncheck linux from the build configurations list. After doing that our build configuration looks like this:

Now we click 'Save Build' and our Build Plan is complete. The next step is to schedule the build.

Schedule the Build Plan

Just under the Build Plan Editor is the Schedule dialog. To schedule this build plan click on the 'Schedule Build' button. This will bring up the 'Schedule New Build' dialog. This dialog has three tabs to schedule the build three different ways. You can schedule a build to run a single time - this is useful for testing a new build plan or to test new changes in your repository or codebase. The second way is to schedule a build at a regular recurring interval. The third way is to schedule a build to happen when a repository changes. We will schedule our new build plan for both a repository change and a regular interval. To schedule a build when a repository changes click the 'Triggered' tab and select the source-control server binding to watch, you can optionally have Compass watch a specific path in the repository too, in this case we watch the whole repository:

Then click 'OK'; this schedules our first build. Now click on 'Schedule New Build' again and this time open the 'Recurring' tab. We set the date and time we want the build to run for the first time and then select the radio button for a regular build every per min/hour/day and set it to 2 hours. Highlighted below are the two things we just changed in the 'Schedule New Build' Dialog:

After setting these two fields we click 'OK' and now both builds are scheduled and the schedule table looks like this:

Add Email Notification

Finally, we add email notification so that team members get an email any time a build fails. We do this in the email notification box on the project admin page. Go back to the admin page by hitting back in the browser or by clickin on the project link at the top of the 'Build Plan Editor' page. On the admin page simply fill out the email notification box and presto, every time the build plan fails an email will be sent to the team:

Now, the Compass Server is all set up with a build plan that will execute whenever the repository changes and at a regular interval and if there is an error, we will receive an email. There is much more detailed documentation on all of Compass' features in the full Compass documentation and our support team is ready to answer any questions you may have at This e-mail address is being protected from spambots. You need JavaScript enabled to view it