Compass Version1.1

Windows Quick Installation Guide and Setup

Compass comes with two executable programs.  The Compass Manager and the Compass Client Driver.  The Compass Manager controls when the Compass Server is running and which machines act as build clients.  In many cases, there is only one machine that is both the Compass Manager and a single Compass Client Driver.  Compass must be installed on the computer that will be used as the Compass server and on each computer that will be used as a build client.  The installation is the same for both the server and the build clients.  After downloading Compass_Setup.exe, simply run it on each computer that Compass will be used on and follow the instructions for each step in the installation.  

The Compass installation will ask to install Python 2.6 and PyWin32.  If these have already been installed then this step can be skipped.

Once the installation has completed.  Both Compass Manager and  Compass Client Driver will have been installed.  To start the Compass server, go to the start menu and run Compass Manager.  This will start the Compass Manager and put an icon in your windows task trey that looks like this:

Right click on the Compass Manager icon and select settings; this will bring up the following dialog:

Check the box for 'Run server on startup' if you want the Compass Server to start when the Compass Manager application is launched.  Also, if you have more than one python installation, make sure the correct version is selected here.  Finally, the Compass master config file is specified here.  For most installations the defaults in this file can be left unmodified.  If you do require changes to this file or for more information about it please refer to the help Compass Config file documentation page. 

Click 'OK'.  Now, right click on the Compass Manager icon in the task trey again and the click 'Start Compass Server'  

Now, the Compass server is started and is running on localhost.  Open a web browser and navigate to 'http://localhost'  You should see a page that looks like this:

 To complete the Compass Server installation enter an administrator username and password and click the 'Install Server' Button.  Once you click this button you will be taken to the server Administration page.  This page has the following 9 sections:

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

Details on each of these are provided in the administrator manual.  To set up a compass server with minimal effort, the only sections that are required to be updated 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 Admin Page'

Create a New Build Plan

On the Project Admin Page there is 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 and the output file or directory you want to save on the server each time this build plan is run.  Both of these can be changed later if need be.  Once you click 'Create' you are taken to the 'Build Plan Editor'. The 'Build Plan Editor' looks like this:

To create your 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, building and testing; to create new scripts see the Scripts Documentation page.  

To add our first script, a check-out script we click the add script 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 immediately - 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 to happen when a repository changes.  The third way is to schedule a build at a regular interval.  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 revision tab and select the source-control server 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 'Date/Time' 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:

Set Up a Build Client

Now that the Compass Server is all set up, with a build plan, ready to start building; it needs a build client to execute the build plan.

The most common Compass configuration is to have a single build client on the same machine as the Compass Manager and Compass Server.  To set this up simply start the Compass Client Driver from the start menu.  This will put a second icon in your task trey that looks like this:

 Right clicking on this icon gives you a menu to control the Compass build client on this machine.  On this menu, the first thing we need to do is change the settings.  Click the settings option and bring up the following dialog:

We need to first give our build client a name, this must be unique and a name is auto-generated but most users prefer to put their name or the name of their machine.  Next make sure that the python location is correct; also make sure that the full path to the client config file is specified.  Additional settings for how the client behaves can be added to this config file; for more details on that see the config file documentation page.  

The last setting we must enter is the address of the Compass Manager.  If this Client Driver is on the same computer as the the Compass Manager then enter 127.0.0.1 or else enter the IP address of the Compass Manager computer.  Due to windows socket limitations this must be an IP address.  

Once we have all the settings correct, click OK.  Now right click on the Client Driver icon again and this time select 'Connect to Manager'.  Once you have connected you can start the build client by clicking on 'Start Build Client' either in the Compass Manager or in the Client Driver menus.  

Finally, to test that the client is correctly started and connected, open a web browser and log in to the Compass web page.   Click on the Build Monitor icon on the top menu and you should see a build client called windows-1:

And now compass is completely set up and ready to go. Builds will start at their next scheduled time or with the next repository change. 

Many more advanced features of Compass are covered in other documentation pages on the Anx Labs partner site.  For questions and comments please contact: This e-mail address is being protected from spambots. You need JavaScript enabled to view it