Admin Manual [PDF]

Table of Contents

Preface ...... xiii About This Manual ...... xiii Audience ...... xiii Technical Support ...... xiii 1. Load Balancing and Failover ...... 1 Automatic Load Balancing ...... 1 Transparent Failover ...... 1 2. Monitoring Build Statuses ...... 2 List View Mode ...... 2 Detailed View Mode ...... 2 Monitoring Other Build Statuses While in the Detailed View Mode ...... 2 Recent Builds Mode ...... 2 Build Control Commands ...... 2 Controlling Build Execution Using Change Messages ...... 3 3. Monitoring Agent Statuses ...... 4 Monitoring Agent Load ...... 4 Agent List View ...... 4 Monitoring Builds on Single Agent ...... 4 Build Control Commands ...... 4 4. System Administration ...... 5 Parabuild will display a list of configuration options on the right size of the screen ...... 5 E-Mail Settings ...... 5 Instant Messaging Settings ...... 7 Global Version Control User to E-mail Map ...... 8 General System Settings ...... 9 Appearance Settings ...... 9 Stability Settings ...... 13 Display Groups ...... 15 Projects ...... 16 Global Variables ...... 17 Managing Build Infrastructure ...... 18 Managing Build Agents ...... 18 Managing Build Farms ...... 19 Entering Parabuild License ...... 20 Configuring LDAP Authentication ...... 20 Connection URL ...... 21 Connection Principal And Connection Credentials ...... 21 Connection Security Level ...... 21 Processing Referrals ...... 21 User Distinguished Name Template ...... 21 User Search Template ...... 22 Base Element for User Searches ...... 22 Search Entire Subtree ...... 22 User Password Attribute Name ...... 22 Credentials Digest Algorithm ...... 23 User E-Mail Attribute Name ...... 23 Add First-Time Users To Group ...... 23 Using LDAP to Map Names of Version Control Users to E-mails ...... 23 Testing LDAP Configuration ...... 23 Integrating With Active Directory ...... 23 5. Configuring a Build ...... 24 Overview ...... 24 General Settings Form ...... 24

iv Viewtier Parabuild 4.2

Naming a Build ...... 24 Selecting Build Type ...... 25 Automatic Builds ...... 25 Scheduled Builds ...... 25 Manual Builds ...... 26 Parallel Builds ...... 26 Selecting Build Results Access ...... 26 Detailed Build Configuration ...... 27 Adding Build Steps ...... 27 Common Version Control Settings ...... 29 Configuring Accurev Access ...... 29 Configuring Bazaar Access ...... 31 Configuring ClearCase Access ...... 32 Configuring CVS Access ...... 35 Configuring Watching for File System Changes ...... 40 Configuring Generic Version Control System Access ...... 42 Configuring Git Access ...... 44 Configuring Mercurial Access ...... 46 Configuring MKS Access ...... 46 Configuring Perforce Access ...... 48 Configuring Serena Version Manager (PVCS) Access ...... 53 Configuring StarTeam Access ...... 55 Configuring Subversion Access ...... 56 Configuring Surround Access ...... 59 Configuring Vault Access ...... 61 Configuring Visual SourceSafe Access ...... 63 Configuring Build Schedule ...... 65 Configuring Build Labeling ...... 68 Configuring Dependent Build ...... 68 Notification Settings Tab ...... 68 Setting Notification Policy ...... 69 Mapping Names of Users of a Version Control System to E-mail ...... 69 Using E-mails Provided by Version Control System ...... 69 Setting Default E-mail Domain ...... 69 Notifying Other Users ...... 70 Understanding Relative Paths ...... 70 Build Logs Tab ...... 71 Setting Up Build Logs Compression ...... 71 Adding Custom Logs ...... 71 Adding Single Text File Log ...... 72 Adding Directory with Text File Logs ...... 72 Adding Directory with Boost Unit Test Framework Logs ...... 72 Adding GoogleTest XML Log ...... 72 Adding Single HTML File Log ...... 72 Adding HTML Directory Log ...... 72 Adding Generic Test Results ...... 73 Adding Squish XML Log ...... 73 Using Template Parameters in Log Path ...... 74 Build Results Tab ...... 74 Setting Up Automatic Deleting of Old Build Results ...... 74 Configuring Single File Result ...... 75 Configuring Directory Result ...... 75 Configuring An External URL Result ...... 75 Accessing Externally Stored Build Results ...... 76 Using Template Parameters in Result Path ...... 76 Publishing Build Results Automatically ...... 77 Ignoring Result Time Stamp ...... 77 Reporting Results of Parallel Builds On Leader Result Page ...... 77

v Viewtier Parabuild 4.2

Debugging Build Result Path ...... 77 Release Notes Tab ...... 78 Linking Release Notes And Changes ...... 78 Retrieving Release Notes From Bugzilla ...... 79 Parameters Tab ...... 80 Version Counter ...... 80 Parameters ...... 82 6. Managing Build Results ...... 83 Managing Build Result Groups ...... 83 Adding A Build Result Group ...... 83 Editing A Build Result Group ...... 83 Deleting A Build Result Group ...... 83 Publishing Build Results ...... 83 7. Managing Users And Groups ...... 84 Simplified Security Mode ...... 84 Adding a User ...... 84 Login Name ...... 84 Full Name ...... 84 Login Password ...... 84 Retype Password ...... 84 E-Mail ...... 85 Admin User ...... 85 Instant Messaging ...... 85 Instant Messaging Address ...... 85 Notify About ...... 85 Accessibility ...... 85 User Belongs to Group(s) ...... 86 Modifying a User ...... 86 Deleting a User ...... 86 Adding a Group ...... 86 Group Name ...... 86 Group Description ...... 86 Allowed to Access Builds ...... 86 Rights ...... 86 Modifying a Group ...... 87 Deleting a Group ...... 87 8. Managing Builds ...... 88 Runtime Commands ...... 88 Stopping Build ...... 88 Stopping Group ...... 88 Resuming Build ...... 88 Resuming Group ...... 88 Starting Build ...... 89 Deactivating Build ...... 89 Activating Build ...... 89 Requesting Clean Checkout ...... 90 Re-Running Build ...... 90 Configuration Commands ...... 90 Editing Build Configuration ...... 90 Copying Build Configuration ...... 90 Deleting Build Configuration ...... 90 Changing Schedule Type ...... 90 Miscellaneous Commands ...... 91 Diff Command ...... 91 Maintenance Commands ...... 91 Cleanup Logs Command ...... 91 Cleanup Results Command ...... 91 Maintenance Commands ...... 92

vi Viewtier Parabuild 4.2

Cleanup Logs Command ...... 92 Cleanup Results Command ...... 92 9. Managing Build Results ...... 93 Publishing Build Results ...... 93 Pinning Build Results At Publish Time ...... 93 10. Configuring Remote Builds ...... 94 Startup Procedure for Build Manager and Remote Agents ...... 94 Shutdown Procedure for Build Manager and Remote Agents ...... 94 11. Viewing System Errors ...... 95 12. Build Script Environment Variables ...... 96 PARABUILD_BUILD_DATE ...... 96 PARABUILD_BUILD_DIR ...... 96 PARABUILD_BUILD_NAME ...... 96 PARABUILD_BUILD_ID ...... 96 PARABUILD_BUILD_NUMBER ...... 96 PARABUILD_BUILD_RUN_ID ...... 96 PARABUILD_BUILD_STARTED_BY_USER ...... 96 PARABUILD_BUILD_TIMESTAMP ...... 96 PARABUILD_CHANGE_LIST_NUMBER ...... 97 PARABUILD_CLEAN_CHECKOUT ...... 97 PARABUILD_CHECKOUT_DIR ...... 97 PARABUILD_LAST_GOOD_BUILD_NUMBER ...... 97 PARABUILD_LAST_GOOD_BUILD_DATETIME ...... 97 PARABUILD_LAST_GOOD_CHANGE_LIST_NUMBER ...... 97 PARABUILD_LAST_GOOD_CHANGE_LIST_DATETIME ...... 97 PARABUILD_PREVIOUS_CHANGE_LIST_NUMBER ...... 98 PARABUILD_PREVIOUS_CHANGE_LIST_DATETIME ...... 98 PARABUILD_PROJECT_ID ...... 98 PARABUILD_PROJECT_NAME ...... 98 PARABUILD_STEP_NAME ...... 98 PARABUILD_PREVIOUS_STEPS ...... 98 PARABUILD_VERSION ...... 98 PARABUILD_SEQUENCE_NUMBER ...... 99 Environment Variables for Perforce Builds ...... 99 PARABUILD_P4CLIENT ...... 99 PARABUILD_P4PASSWD ...... 99 PARABUILD_P4PORT ...... 99 PARABUILD_P4USER ...... 99 Environment Variables for CVS Builds ...... 99 PARABUILD_CVS_ROOT ...... 99 PARABUILD_CVS_BRANCH ...... 100 Environment Variables for Git Builds ...... 100 PARABUILD_GIT_BRANCH ...... 100 Environment Variables for Parallel Builds ...... 100 PARABUILD_LEADING_BUILD_ID ...... 100 PARABUILD_LEADING_BUILD_NAME ...... 100 PARABUILD_LEADING_BUILD_RUN_ID ...... 100 Environment Variables for Dependent Builds ...... 100 PARABUILD_UPSTREAM_BUILD_ID ...... 100 PARABUILD_UPSTREAM_BUILD_NAME ...... 100 PARABUILD_UPSTREAM_BUILD_RUN_ID ...... 101 13. Starting And Stopping Parabuild Service Under Windows ...... 102 Starting Parabuild Service ...... 102 Stopping Parabuild Service ...... 102 Changing Parabuild Service User Under Windows ...... 103 Embedding Build Status Into Web Pages ...... 103 14. Backing Up Parabuild Installation ...... 105 15. Build Server Security Implications ...... 106

vii Viewtier Parabuild 4.2

16. Undocumented Commands ...... 107 Glossary ...... 108

viii List of Figures

4.1. Enabling Using Change List Numbers as Build Numbers ...... 14 5.1. Entering Regular Expressions in Ignore List ...... 29 5.2. Example: Configuring Accurev Access ...... 30 5.3. Mercurial Configuration Example ...... 46 5.4. Configuring Dependent Build ...... 68 5.5. Setting Cut-off Time for Old Build Results ...... 75 5.6. Setting Global Minimum Result Retention Time ...... 75 5.7. Selecting Result Group for Automatic Build Result Publishing ...... 77 5.8. Ignoring Result Time Stamp ...... 77 5.9. Reporting Results of Parallel Builds On Leader Result Page ...... 77 5.10. Configuring Perforce Jobs ...... 78 5.11. Configuring Bugzilla Integration ...... 79 5.12. Enabling Using First Parameter Value as Default ...... 82 7.1. Enabling Using Change List Numbers as Build Numbers ...... 85 7.2. Selecting Default Display Group ...... 86 8.1. Entering Perforce Change List Number for Manual Build ...... 89 8.2. Starting Build Immediately After Saving Build Configuration ...... 89 9.1. Accessing Published Build Results ...... 93 9.2. Publishing Build Results ...... 93 9.3. Pinning Build Result At Publish Time ...... 93

ix List of Tables

5.1. Template Parameters for Log Path ...... 74 5.2. Template Parameters for Result Path ...... 76

x List of Examples

2.1. Including PARABUILD_PRIORITY to Change Message ...... 3 2.2. Using PARABUILD_PRIORITY to Set Up Shell Variable ...... 3 4.1. Custom Regex Allowing Dots in The Build Name ...... 10 4.2. Custom Regex Allowing Dots in The Variable Name ...... 10 4.3. LDAP Connection URL ...... 21 4.4. LDAP User Distinguished Name Template ...... 22 4.5. LDAP User Search Template ...... 22 4.6. LDAP User Search Template ...... 22 5.1. Composing Build Name ...... 25 5.2. Path To cleartool Executable ...... 30 5.3. Path to Bazaar Executable Field ...... 31 5.4. Bazaar Branch Path Field Using SSH Protocol ...... 32 5.5. Path To cleartool Executable ...... 33 5.6. Snapshot View Config Spec ...... 33 5.7. CVS root for pserver authentication ...... 35 5.8. Single line CVS repository path ...... 36 5.9. Multi-line CVS repository path ...... 36 5.10. Path to CVS executable field ...... 36 5.11. Connecting to CVS using SSH As Remote Shell Under Unix ...... 37 5.12. The Most Commonly Used Forms of ViewVC URLs ...... 39 5.13. The Most Commonly Used Forms of FishEye URLs ...... 39 5.14. The Most Commonly Used Form of WebSVN URL ...... 40 5.15. Path to Git Executable Field ...... 45 5.16. Git Repository Field Using SSH Protocol ...... 45 5.17. Single Line Git Repository Path ...... 45 5.18. Multi-path Git Repository Path ...... 45 5.19. Path to P4 executable field ...... 49 5.20. P4 port field ...... 49 5.21. Single-line P4 Client View ...... 49 5.22. Multi-path P4 Client View ...... 49 5.23. Advanced Mode Client View And Relative Build Directory ...... 50 5.24. Path to sscm Executable ...... 53 5.25. PVCS Project ...... 54 5.26. Multi-path PVCS Project ...... 54 5.27. Field Path to Subversion Executable ...... 57 5.28. Path to Subversion Executable Using a Parameter ...... 57 5.29. Subversion URL Field Using HTTP Protocol ...... 57 5.30. Subversion URL Field using svn Protocol ...... 57 5.31. Single Line Subversion Repository Path ...... 58 5.32. Multi-path Subversion Repository Path ...... 58 5.33. Non-Recursive Subversion Repository Path ...... 58 5.34. The Most Commonly Used Forms of ViewVC URLs ...... 59 5.35. The Most Commonly Used Forms of FishEye URLs ...... 59 5.36. Path to sscm Executable ...... 60 5.37. Surround Repository ...... 61 5.38. Vault Repository Path ...... 62 5.39. Vault Repository Path for Multi-path Vault Project ...... 62 5.40. VSS database path ...... 64 5.41. VSS Project Path ...... 64 5.42. Multi-path VSS Project ...... 64 5.43. Path to VSS Client ...... 65 5.44. Path to VSS Client With Spaces in It ...... 65 5.45. Composing Build Label Template ...... 68

xi Viewtier Parabuild 4.2

5.46. Composing an e-mail address from user name and default e-mail domain ...... 70 5.47. Using Predefined Template Parameters in Log Path ...... 74 5.48. Using Global Template Parameters in Log Path ...... 74 5.49. Using Template Parameter in Result Path ...... 76 5.50. Using Global Template Parameters in Log Path ...... 77 5.51. Bugzilla Bug URL Template ...... 80 12.1. Example of PARABUILD_PREVIOUS_STEPS Value ...... 98 13.1. Embedding Build Status Into Web Pages ...... 103 13.2. Using Parameters To Alter Appearance of Embedded Build Status Box ...... 104

xii Preface About This Manual

This manual is for Parabuild users or administrators responsible for administrative tasks such as creating and maintaining build configuration, managing remote servers, and administering user and group accounts.

Viewtier Parabuild (Parabuild) is an automated multi-platform software build management server. Par- abuild provides continuous integration builds, scheduled and manual builds. Automatic builds are fired upon every check-in or a group of check-ins into a project source line. Scheduled builds are fired at a configured time. Manual build are fired upon a build manager's request. Audience

This guide is intended for anyone who is responsible for administration of a Parabuild server or a remote agent on a computer running a supported version of Microsoft Windows, Linux or Unix. It assumes a basic knowledge of corresponding operating systems and their conventions. Technical Support

If you have any problems with the software or documentation, please contact Viewtier Technical Sup- port via online support forums, electronic mail, fax, or as described below. For information regarding other support information, click the Support link on the Viewtier Web site atwww.viewtier.com [http://www.viewtier.com].

Support Forum: http://forums.viewtier.com/viewforum.php?f=1 [http://forums.viewtier.com/viewforum.php?f=1]

Electronic Mail: [email protected] [mailto:[email protected]]

Fax: 650-240-4455

xiii xiv Chapter 1. Load Balancing and Failover Automatic Load Balancing

Remote multiplatform builds is a standard feature of a modern build management system. Parabuild provided this feature since its first release. Yet, as the number of builds grows, so does the load on remote build agent machines. Uneven load negatively impacts build performance. Manually assigning builds to agent machines to ensure even load often is a non-trivial and time-consuming task. Parabuild provides fully automatic load balancing across a build farm by selecting agents to run a build in a round- robin fashion. Parabuild tries to randomly select an agent from the pool of idle agents. Parabuild applies round-robin selection if there are no idle agents. Transparent Failover

Increasing number of agent machines complicates management of the distributed build infrastructure. Agent machines may go down for maintenance, network connections can fail and agent hardware can break. Agent failures require manual re-assigning builds to operational agent machines and generally cause build delays and significant administrative headache. Parabuild introduces transparent failover for the distributed build infrastructure. Parabuild automatically excludes failed agent machines from the build farm and continues to run builds on operational agent machines.

1 Chapter 2. Monitoring Build Statuses

Build statuses page shows the configured builds and their current statuses. This page refreshes automatically every thirty seconds. The content of the page depends on the “page view” mode. There are four view modes: dashboard view, list view, detailed view and recent builds. To switch between the two modes click "Dashboard View, "List view", "Detailed view" or "Recent Builds" links, respectively. The differences between the modes are described below. List View Mode

This mode allows you to see the overview of all build statuses on a single page. It is suitable for ongoing surveillance of build statuses. When in the list view mode, the build statuses page shows a table with a list of builds and their current statuses (waiting, building e.t.c.) and a link to a page with the last build result, if it exists. The link is in red if the last build failed or in green if the last build was successful. The caption of the link shows the last build number and time. Control commands for each build are available only if the user has logged in as an administrator. Detailed View Mode

This mode allows you to monitor the detailed status of a selected build. In the detailed view mode the page is split into two parts. On the left side there is a vertical navigation bar that allows you to select a particular build to view. The right side of the page contains detailed information about the current build status including:

• Build name with the current build status.

• Currently running build steps.

• Links to the last build result including build logs, error quotes, and changes in the last build, such as build history, and date and time thereof.

• Link to the last clean build, if it exists.

• List of changes in the currently running build (or changes in the last build if the build is not running).

Monitoring Other Build Statuses While in the Detailed View Mode

While in the detailed view mode, Parabuild adds a small throbber to the names of the build that are running: Recent Builds Mode

While in the recent builds mode, Parabuild shows a talbe with a system-wide list of recently completed builds. This mode allows to quickly access results of the most recent builds. The number of lines in the table is configured using users preferences. The default number of lines in the recent builds table is 20. Build Control Commands

2 Monitoring Build Statuses

If a user logged in as an administrator, the build statuses page shows a list of build control commands. The following commands are available:

Start This command starts the build if the build is idle.

Stop This command forcefully stops the build if the build is running.

Activate All builds are originally inactive. Use this command to activate a new build.

Edit This command opens the build configuration page.

Add build This command opens a new build configuration page.

Controlling Build Execution Using Change Messages

By default, Parabuild will sync to the last detected change list of a project and build all changes since the last build. However, Parabuild provides 'comment log control' over this behaviour. If a change message has a marker string "PARABUILD_PRIORITY" in the comment field, Parabuild will see all changes, but will only sync to the change that has the marker to and do the build. At the next poll interval, Par- abuild will then build changes after the change that has the marker. The marker should be separated from the content of the message by spaces.

Example 2.1. Including PARABUILD_PRIORITY to Change Message

Added third-party library. PARABUILD_PRIORITY

Further, Parabuild priority marker provides an ability to set up shell variables that that will be passed to the build.

Example 2.2. Using PARABUILD_PRIORITY to Set Up Shell Variable

PARABUILD_PRIORITY=ENV_VARIABLE_A=FOO;ENV_VARIABLE_B=BAR;

3 Chapter 3. Monitoring Agent Statuses

Parabuild provides a page to monitor statuses of remote build agents. Click on "Agents" link on the top navigation bar to visit the agent monitoring page: Monitoring Agent Load

To monitor agent load, click on link "Agent load view". Parabuild will show a page with charts displaying load for the last 24 hours. A green marker denotes an agent that is currently offline. A red marker denotes an agent that is currently offline: Agent List View

Agent list view page allows to take a quick look at agent statuses. This page shows an agent table with the following columns

• Agent address

• Status

• Link to the list of build configurations attached to a build agent

• List of builds currently running on a build agent

Monitoring Builds on Single Agent

Parabuild allows to monitor builds on a single agent. Go to Agent List View and click on the "Build Configurations" link:

Parabuild will show a list of builds currently running on the selected agent. In addition to monitoring builds, this page can be used to stop and resume all builds on this agent. Build Control Commands

If a user logged in as an administrator, the build statuses page shows a list of build control commands. The following commands are available:

Start This command starts the build if the build is idle.

Stop This command forcefully stops the build if the build is running.

Activate All builds are originally inactive. Use this command to activate a new build.

Edit This command opens the build configuration page.

Add build This command opens a new build configuration page.

4 Chapter 4. System Administration

Parabuild provides a single, convenient place to manage all aspects of the system configuration. Click on link "Administration" on the top navigation bar to access various aspects of Parabuild configuration: Parabuild will display a list of configuration options on the right size of the screen

Parabuild server provides a set of system-wide configuration parameters. Parabuild will request you to fill the mandatory settings before builds can be created. These settings include:

• Build administrator name

• Build administrator e-mail

• SMTP server

• Build manager host

• Date format

• Date and time format

• Default build status refresh rate

• Administrator's password

In order to enter the mandatory system settings or modify optional settings, login to Parabuild as admin and select "System configuration" link on the top navigation bar. The system configuration page shows a list of links for editing system and instant messaging settings, and security. To edit general system settings, select "General Settings Link". After a system settings window shows up, edit the settings and press "Save" button. If modifications are correct, a message saying that the system configuration has been saved successfully will be displayed. The meaning of each system setting is discussed below. E-Mail Settings Build Administrator Name

Build administrator name is used for specifying a name for the e-mail notifications that Parabuild will send. The default value for this setting is "Build Administrator". This is a mandatory setting. Build Administrator E-mail Address

Parabuild uses Build administrator e-mail setting to compose an e-mail part of a build result notification message. Parabuild will also use this e-mail to report exceptional conditions. The Build administrator e- mail should be a valid e-mail. This is a mandatory setting. Default E-mail Domain

Parabuild uses a default e-mail domain to compose notification e-mails regarding the build results from the names of users in your version control system. If the default e-mail domain is set and the version

5 System Administration

control user name is not explicitly mapped to an e-mail through the notification settings of a particular build configuration, Parabuild will compose an e-mail by per-pending a name of the user with "@" followed by the default e-mail domain. For instance, if the version control user name were "john," and the default domain were mycompany.com, the resulting e-mail would be [email protected]. Default e- mail domain is an optional setting. SMTP Server

SMTP server setting is a DNS name of an SMTP server Parabuild uses to send notification e-mails. This is a mandatory setting. SMTP server requires encrypted connection (SSL)

This box should be checked if your SMTP server requires an encrypted connection. SMTP Server Port

SMTP server port allows to set a port number the SMTP server listens on. This is a mandatory setting. A default value is port number 25. SMTP Login Name

Enter an SMTP login name if your SMTP server requires explicit login. SMTP Server Password

Enter an SMTP server password if your SMTP server requires explicit login. Using Git User E-mails as User Names

Parabuild provides an ability to use Git user's e-mail as a name of the user that submitted a change list. This allows to send build e-mails to Git users automatically. To enable this feature, check box "Use Git user's e-mail". Case-sensitive Perforce User Names

This box is used to configure correct resolution of user names to e-mails for Perforce. Projects running Perforce under Windows should uncheck the option "Case sensitive Perforce user names" that is available in the system-wide e-mail settings: Include Links To Results Into Messages

Parabuild supports including links to results into e-mail messages that Parabuild sends when a build step finishes. To enable including links to results, check box "Include links to results into messages". By default including links to results into e-mail messages is disabled. System Messages Prefix

Content of this field will be added to subject lines of all system messages sent by Parabuild. The system message prefix can be used for easy filtering of system messages. Message Subject Templates

Parabuild provides an ability to configure the content of the subject lines for messages that are sent when a build step starts and finishes through templates.

6 System Administration

Build Step Started

This field may contain a template for a subject line of a message that Parabuild sends when a build step is started. The following template parameters are supported:build.name, build.number, build.host andbuild.step. The default template is ${build.step} for ${build.name} (#${build.number}) started on ${build.host}. Build Step Finished

This field may contain a template for a subject line of a message that Parabuild sends when a build step finishes. The following template parameters are supported:build.name, build.number, build.host, build.step,result.string, and result.description . The default template is${build.step} for ${build.name} (#${build.number}) on ${build.host} ${result.string}: ${result.description}. Configuring Email Message Priority

Parabuild allows setting the priority of e-mail messages that Parabuild sends when a build is broken or critical system errors occur. The priority can be set to either "Normal" or "High" using drop-down lists "Failed builds" and "System errors" Notifying Users with Edit Rights about Build Results

To enable self-service, Parabuild allows to notify users having edit rights on a particular build about build results and system errors. If there is a problem with the build, such users can modify the build configuration to address the problem without going to a Parabuild administrator. By default this feature is enabled. To disable, un-check box "Notify users with edit rights". Notifying Only Administrator and User that Stopped the Build

Parabuild allows to reduce the amount of e-mail messages sent to build participants while the build configuration is adjusted by providing a check box called 'Advanced stop notification'. Check this box to have Parabuild send e-mail notifications after a build was stopped only to the Parabuild administrator and the user that stopped the build. If this box is not checked (this ia default setting), Parabuild will send the message to all build participants. Instant Messaging Settings

Parabuild supports sending notifications about build results using instant messaging. Parabuild can also send system errors notification to build administrators. Parabuild accesses the following instant messaging systems:

• Jabber (XMPP)

In order to enter or modify the instant messaging settings, login to Parabuild as admin and select "Admin- istration" link on the top navigation bar. The system configuration page shows a list of system configuration links. To edit instant messaging settings, select "Instant Messaging Settings" link. After a instant messaging settings window shows up, edit the settings and press "Save" button. The meaning of each instant messaging setting is discussed below. Jabber Configuration

Use the "Jabber Configuration" group to enter settings for a Jabber server. Parabuild will use these setting to send instant messages about build results and system notifications.

7 System Administration

Parabuild uses user's e-mail address to find an instant messaging address of a user. When Parabuild is ready to send a message, it will use user's e-mail address to look up a user in the list of Parabuild users. If a user is found and instant messaging is enabled for the user, Parabuild will send the message. Note

To enable sending instant messages to a user, a user should be entered into the list of Parabuild users as described in User Management section, and user's e-mail address should be matched user's name used to access version control system for a build. The match is configured under the "Notification" tab for a particular build configuration.

The following settings are available to configure access to a Jabber server. All these settings are mandatory:

• "Jabber server address" is a DNS name of the Jabber server.

• "Jabber server port" is a port number used to access the jabber server with the configured server address. The default port number is 5222.

• "Jabber login name" is a name used to log in into the Jabber server. This is a name part of an instant messaging address.

• "Jabber password" is a password used to log in into the Jabber server.

• Check box "Send if no presence" if Parabuild should send a message even if presence of Jabber client cannot be confirmed.

To disable Jabber instant messaging, check "Disabled" check box. Global Version Control User to E-mail Map

The global version control user to e-mail map provides system-wide mappings that significantly simplify managing of customised user e-mails. Parabuild uses a mapping to compose an e-mail address of a version control user to send notifications about build results. The mappings can be overridden by notification settings for a particular build configuration. To manage the mappings click on the link "VCS User to Email Map". Parabuild will display a list of mappings with controls that allow to add, edit and remove the mappings: Adding Mapping

To add a mapping click on link "Add new mapping". An entry form for a new mapping will appear. Fill fields "Version control user name", "E-mail" and "Note". Click on "Save" button to save the new mapping. Click on "Cancel" button to discard the edits. Editing Mapping

To edit a mapping click on link "Edit" for the selected mapping. An entry form for the selected mapping will appear. Modify fields "Version control user name", "E-mail" and "Note". Click on "Save" button to save the changes in this mapping. Click on "Cancel" button to discard the edits. Deleting Mapping

To delete a mapping click on link "Delete" for the selected mapping. After receiving a confirmation Par- abuild will delete the mapping.

8 System Administration

General System Settings

Parabuild server provides a set of system-wide configuration parameters. Parabuild will request you to fill the mandatory settings before builds can be created. These settings include:

• Build administrator name

• Build administrator e-mail

• SMTP server

• Build manager host

• Date format

• Date and time format

• Default build status refresh rate

• Administrator's password

Parabuild uses value entered in the "Build manager host" to form a URL used in e-mail and instant messages. This value overrides default host name detection.

If this field is left blank Parabuild will try to detect the host name it runs on automatically. If the host name cannot be detected Parabuild will use numeric IP address. Setting Generated URL Protocol

Parabuild uses value entered in the "Generated URL protocol" to form the protocol part of a URL used in e-mail and instant messages. Setting Date Format

Parabuild uses Date format to present dates on various screens and in notification messages. Select a format that is appropriate for your country. The following formats are available through a drop-down menu on "General system settings" screen. Consider a date of December 24th, 2003:

• MM/dd/yyyy format will render to 12/24/2003

• dd/MM/yyyy format will render to 24/12/2003

• dd-MM-yyyy format will render to 24-12-2003

9 System Administration

• dd MMM yyyy format will render to 24 Dec 2003

• MMM dd yyyy format will render to Dec 24 2003

Setting Date And Time Format

Parabuild uses Date and time format to present times on various screens and in notification messages. Select a format that is appropriate for your country. The following formats are available through a drop- down menu on "General system settings" screen. Consider a date and time of December 24th, 2003, 12:00 PM:

• "MM/dd/yyyy hh:mm a" format will render to 12/24/2003 12:00 pm

• "hh:mm a MM/dd/yyyy" format will render to 12:00 pm 12/24/2003

• "dd/MM/yyyy HH:mm" format will render to 24/12/2003 24:00

• "HH:mm dd-MM-yyyy" format will render to 24:00 24-12-2003

Setting Default Build Status Refresh Rate

This setting defines the default rate for automatic refresh of build status pages. The refresh rate is set in seconds and applied to all anonymous users and to users who have not set the refresh rate in their per- sonal preferences. Configuring Build Name Validation

Parabuild allows to set up a custom regex for validating build names. The default regex is[a-zA-Z][-a-zA-Z_0-9]*. This regex supports using a build name as a part of a label in all version control systems. Sometimes the default regex may be too restrictive. To use a custom regex, go to a setting named "Build Name Validation" and select "Custom" radio button. Enter the regex in a corresponding entry field. Below is an example of a regex that allows to have dots in the build name.

Example 4.1. Custom Regex Allowing Dots in The Build Name

[a-zA-Z][-a-zA-Z_\.0-9]*

Configuring Variable Name Validation

Parabuild allows to set up a custom regex for validating variable names. The default regex is[a-zA-Z][-a-zA-Z_0-9]*. This regex supports using a variable name in the most operating systems and as a part of a label in all version control systems. Sometimes the default regex may be too restrictive. To use a custom regex, go to a setting named "Variable Name Validation" and select "Custom" radio button. Enter the regex in a corresponding entry field. Below is an example of a regex that allows to have dots in the variable name.

Example 4.2. Custom Regex Allowing Dots in The Variable Name

[a-zA-Z][-a-zA-Z_\.0-9]*

10 System Administration

Setting Output Encoding

Output encoding can be used in multi-lingual environments to set encoding of pages and e-mail messages produced by Parabuild. For instance, if Parabuild runs under an operating system that uses Cyrillic locale, this field can be set to Cp1251 to allow Parabuild to present descriptions of change lists properly. Changing List Description Quote

This field contains maximum length of a change list description that will be used in notification messages sent by Parabuild. Setting Error Line Quote Length

When a build step fails, Parabuild will send a notification message. Subject line of the message may include a error line from the main build log that was used by Parabuild to make a decision about the build failure. It is possible that the line is long so that it is inconvenient to use it, for example, when responding to the message. Error line quote length defines a number of characters to that Parabuild will truncate the quoted error line. The default value is 60 characters. Setting this value to zero will disable quoting error line in the subject line of the message. This is an optional parameter. Setting Error Log Quote Size

When a build step fails, Parabuild will send a notification message. It will include lines from a build log at and around a line matching the build failure pattern. This allows for a quick view at the build failure line and preceding lines so it is possible to find a source of the error from the notification message without looking into the whole build log. Error log quote size defines a number of lines of the build log that will be included in the notification message. The optimal value depends on your project build script and should be identified experimentally. The default value is 50 lines. Setting this value to zero will disable quoting log lines in the build failure notification message. This is an optional parameter. Setting Branding

Branding is a title that Parabuild shows at every page header. Use it to display your company name, your department name or whatever you feel is appropriate. For example, if your company name is "My- Company," you may want to change the branding setting to "MyCompany Build Server". If not set, "Viewtier Parabuild 4.2" will be displayed. This is an optional parameter. Showing Link To Projects

Check this box to enable displaying a link to projects on the top navigation bar. The default is not to show the link to projects. The project list is also available through Administration menu. Showing RSS Links

Check this box to enable displaying links to RSS feeds containing information about build status changes. Enabling Advanced Settings

By default Parabuild uses a simplified configuration mode. The simplified mode hides advanced configuration items in order to reduce complexity of the user interface. Check this box if advanced build configuration is required. Following chapters explicitly mention if a particular item requires advanced configuration. Displaying Next Build Time

11 System Administration

Parabuild allows to view an optional column on the list of build statuses that displays the next build time. Displaying next build time is enabled on the User Interface Settings by checking box "Show next build time on status list page":

When the this options is enabled, Parabuild will show the next build time. Automatic builds show "Auto- matic" in the this column: Setting Dashboard Row Size

Entry field "Dashboard row size" defines how many build configurations Parabuild shows on a dashboard row. This setting applies to anonymous users. Parabuild uses this setting to populate preferences for a new user. Showing Parallel Builds on List View

By default Parabuild includes parallel builds into the list view of build statuses. Unchecking this box hides excludes parallel builds from the list view. The helps reduce clutter on the screen and simplify monitoring. Parallel builds are always shown on the detailed status view page along with their leader build. Parabuild uses indentation to mark parallel builds on the detailed view page. Show Build and Change Number on Dashboard

To show build and change number of the build dashboard, check box "Show build and change number on dashboard". To see the build finish time, hover the mouse pointer over the build status: Showing IP Address on List View

To show IP address of the build agent on the list view, check box "Show IP address on status list page". Parabuild will show an IP address with a suffix (BM) if the build is configured to run on the build manager. Showing Next Build on List View

To show the time a build is going to run next time, check box "Show next build time on status list page". Parabuild won't show the next build time if a build configuration is inactive. Automatic builds will show "Automatic". Manual builds will show "Manual". Allowing Anonymous Access To Protected Feeds

By default Parabuild protects access to build statuses through RSS feeds and Windows tray client. Check this box to allow anonymous users unrestricted access to build statuses through RSS feeds and Windows tray client. Coloring Errors in Build Logs

Parabuild simplifies spotting errors in the build log by marking red the lines that match failure patterns as defined by the build configuration:

Parabuild also provides a system-wide list of markers that are configured using field "Text log markers": Security Settings Allow Anonymous Users

Check this box to allow anonymous users accessing build statuses through web user interface. Built-in

12 System Administration

security group "Anonymous" allows to configure what builds can be accessed by anonymous users. Important

To secure your Parabuild installation, change the default password immediately after completing installation and starting Parabuild for the first time.

To change the admin password, enter a new password and re-type it in the "Confirm password" entry field. Enabling Hiding Change List Descriptions

Check this box to hide descriptions of change lists from anonymous users. Stability Settings Stability Settings Overview

System-wide stability settings allow to configure core behavior of Parabuild as a build and release management system. Below is an example of the stability settings panel: Enabling Schedule Gap

Schedule gap defines a system-wide interval when Parabuild will not try to access a version control system or to launch a build. This feature can be used to define time intervals when a scheduled back up is performed on the version control system. Setting Default Version Control Timeout

Default version control timeout defines a system-wide timeout in minutes for executable commands that Parabuild uses to access version control systems. A command will be terminated and Parabuild administrator will receive a warning message if execution time for a version control client exceeds this timeout. Setting Default Build Step Timeout

Parabuild uses default build step timeout when you create new build steps through the user interface. Setting Maximum Change List Size

Maximum change list size defines how many files per change list will be recorded. The default value is 500 files per change list. Setting Initial Number of Change Lists

Initial number of change lists defines how many change lists may be retrieved from a version control system for the first build run. The default value is 1 change list. Setting Maximum Number of Change Lists

Maximum number of change lists defines how many changes lists may be retrieved from a version control system between two builds. By default this field is not set which means that the number is unlimited. Setting Maximum Cool Down Attempts

13 System Administration

Maximum cool down attempts define number of times Parabuild will try to wait for quiet in a code base being watched for changes. Parabuild considers this setting only if a cool down period set for a build configuration. Setting Minimum Build Results Retention

Minimum build results retention defines minimum number of days Parabuild will allow to enter in the build configuration field for automatic deletion of old build results. This value serves as a safety guard preventing accidental deleting of archived build results by entering too short expiration intervals. Enabling No-checkout Builds

The default Parabuild behaviour is to synchronize the build workspace with the version control before starting a build (check out). Some environments may prefer to synchronize the build workspace by using their own scripts. Usually this is done by adding a checkout step to the normal sequence of build steps.

If you wish to be able to alter the default behaviour, check box "Enable no-checkout builds". If no- checkout builds are enabled, and if the version control integration supports no-checkout builds, the version control tab on the build configuration screen will display a check box "Do not sync" or "Do not checkout". Checking that box will disable automatic workspace synchronization.

Note: As of this this writing, the automatic workspace synchronization can be disable only for Perforce builds. Serializing Automatic Builds

Enabling option "Serialize Automatic Builds" causes Parabuild to run builds on a build agent one by one. This option is useful in environments that support running only a single build at a time such as a build configuration using Incredibuild as a build tool. Another example is an environment where all resources of the build agent should be dedicated to a single build process such as a long-running image renderer. Queueing Serialized Builds

If a build is manually started in an environment where one build per agent can run, the start request will either succeed or fail because there are no free agents available. Enabling this option defers the start, when the builds starts automatically as soon as resources are available. Respecting Intermediate Steps Failures

Parabuild allows to continue running build steps if an intermediate build step fails. This is done by checking build step's box "Continue if failed". The option "Respecting intermediate step failures" controls the final build result. If this option is enabled (default), the resulting build will fail if any of intermediate steps fails.

If this option is enabled, Parabuild will ignore failures of the intermediate steps. Instead, Parabuild will use the result of the last step as a result of the whole build. Using Change List Numbers as Build Numbers

Certain release management environments require using change list numbers as build numbers instead of automatically incremented counters. A configuration option "Use change list number as build number" enables this feature:

Figure 4.1. Enabling Using Change List Numbers as Build Numbers

14 System Administration

Retrying Version Control Commands

Retrying version control commands may be helpful in the environments that experience frequent intermittent failures when accessing a version control system. Such failures should not cause build error and can be addressed by retrying the failed command. Option "Retry version control commands" allows to configure how many times a filed version control command should be retried, the time interval between attempts and the regex patterns that should be present in the error message to retry the command execution. This example shows the configuration that accounts for a particular intermittent inability to log in to a Perforce server: Pushing Server Upgrades to Remote Agents

Parabuild commonly runs in environments were a single build farm contains tens of remote build agents. Upgrading such a build infrastructure can be a time-consuming task. Parabuild makes upgrading remote build agents a zero-effort exercise by providing an ability to push server upgrades to remote agents. Once a version mismatch is detected, Parabuild will automatically upgrade and re-start the affected remote agents. Pushing server upgrades to remote agents is enabled by checking box "Automatic agent upgrade". Maximum Parallel Agent Upgrades

If pushing server upgrades to remote agents is enabled, this setting limits the number upgrades the build manager may perform in parallel. Setting this number too high may overload the build manager. Setting it low will increase the time needed to complete the upgrade but will reduce the memory use on the build manager. With default memory settings, this number should be set between 2 and 5. The default value is 2. Enabling Debug Logging

Check this box to enable debug logging. Parabuild will send debug output to a file named par- abuid_debug.log under logs directory if debug logging is enabled. Debug logs may be useful when com- municating with Viewtier support. During normal operation debug logging should be disabled. Display Groups

As number of build configurations managed by Parabuild grows it may become inconvenient to monitor and to control the significant number of builds while they are all presented on a single build status page. Parabuild provides a convenient way to limit number of build shown on the build status pages. This is done by using display groups. A display group is a list of builds grouped together under a group name.

Once the display groups are configured they are available for selection in the right top corner of build status pages

To manage display groups select link "Display Groups" in "System settings" section of the system configuration. Parabuild will display a list of display groups and corresponding controls. Adding Display Group

To add a display group click on link "Add new display group". An entry form for the new display group will appear. Fill fields "Display group name" and "Display group description". Check boxes for build configurations that should be included in this display group. Click on "Save" button to save the new display group. Click on "Cancel" button to discard the edits. Editing Display Group

15 System Administration

To edit a display group click on link "Edit" for the selected display group. An entry form for the selected display group will appear. Modify fields "Display group name" and "Display group description". Check boxes for build configurations that you would like to be included in this display group. Click on "Save" button to save the changes in this display group. Click on "Cancel" button to discard the edits. Deleting Display Group

To delete a display group click on link "Delete" for the selected display group. After receiving a confirmation Parabuild will delete the display group. Built-in Display Groups

To simplify navigation, Parabuild provides a set of built-in display groups: Displaying Broken Builds Only

Often a build administrator is mostly concerned about broken builds only. Parabuild provides a built-in display group that is appears as "BROKEN" in the group selection list. If this group is selected Parabuild will show only broken builds on the build status pages. This allows a build administrator to spot broken builds quickly. Displaying Running Builds Only

Selecting the display group "BUILDING" limits displaying build statuses only to those builds that are currently running. Displaying Scheduled Builds Only

The display group "SCHEDULED" simplifies build monitoring and management in the environments with significant number of scheduled builds: Projects

To manage projects select link "Projects" in "System settings" section of the system configuration. Par- abuild will display a list of projects and corresponding controls. Adding Project

To add a project click on link "Add new project". An entry form for a new project will appear. Fill fields "Project name", "Project key" and "Project description". Click on "Save" button to save the new project. Click on "Cancel" button to discard the edits. Editing Project

To edit a project click on link "Edit" for the selected project. An entry form for the selected project will appear. Modify fields "Project name", "Project key" and "Project description". Click on "Save" button to save the changes in this project. Click on "Cancel" button to discard the edits. Deleting Project

To delete a project click on link "Delete" for the selected project. After receiving a confirmation Par- abuild will delete the project and the associated users, groups and build configurations. Modifying Project Variables

16 System Administration

Parabuild provides an ability to define a set of project-wide variables that are made available to build scripts as shell variables. The variable names can also be used as template parameters when configuring version control settings for a build. To view the list of global variables, click on link "Variables" for the selected project:

Parabuild will show a table with already defined variables and controls necessary to add and edit the variables: Note

Project variables overwrite global variables Adding Project Variable

To add a variable click on link "Add variable". An entry form for a new variable will appear. Fill fields "Shell variable name", "Value" and "Description". Click on "Save" button to save the new variable. Click on "Cancel" button to discard the edits: Editing Project Variable

To edit a variable click on link "Edit" for the selected variable. An entry form for the selected variable will appear. Variable name will be read-only. Modify fields "Value" and "Description". Click on "Save" button to save the changes in this variable. Click on "Cancel" button to discard the edits. Deleting Project Variable

To delete a variable click on link "Delete" for the selected variable. After receiving a confirmation Par- abuild will delete the variable. Using Project Variable in Version Control Settings

To use the variable as a template parameter in the version control settings for a build, wrap it's name into parameter tokens, "${" and "}". This example shows using a variable as a template parameter when de- fining a repository path for Subversion-based build: Global Variables

Parabuild provides an ability to define a set of system-wide variables that are made available to build scripts as shell variables. The variable names can also be used as template parameters when configuring version control settings for a build. To view the list of global variables, go to "Global Variables" section of the Administration screen. Parabuild will show a table with already defined variables and controls necessary to add and edit the variables: Adding Global Variable

17 System Administration

To delete a variable click on link "Delete" for the selected variable. After receiving a confirmation Par- abuild will delete the variable. Using Global Variable in Version Control Settings

A build agent is a machine that runs Parabuild in the remote agent mode. In this manual terms "build agent", "remote agent", "agent" and "build machine" are used interchangeably. A build agent executes builds as requests by Parabuild. A build agent can belong to one or more build farms. Managing build farms is discussed below. To add, configure or remove build agents select link "Agents" in "Infrastruc- ture" section of the system configuration. Parabuild will display a list of agents and corresponding controls: Adding Agent

To add an agent click on link "Add agent". An entry form for a new agent will appear. Fill fields "Agent host and port" and "Description". Click on "Save" button to save the new agent. Click on "Cancel" button to discard the edits: Editing Agent

To edit an agent click on link "Edit" for the selected agent. An entry form for the agent will appear. Modify fields "Agent host and port" and "Description". Click on "Save" button to save the changes for the agent. Click on "Cancel" button to discard the edits.

Parabuild provides an ability to enable build serialization on a per-agent basis. To enable serializing builds on the agent, check box "Serialize builds on this agent". Note that Parabuild will always serialize builds on an agent if the system-wide build serialization is enabled.

Parabuild allows to configure agents to handle load according to agents' power. Field "Capacity" allows to set a estimated, composite, relative power of a build machine. The capacity is measured in relative points that express administrator's estimate of how fast the machine can run builds. For instance a machine that can run twice more builds in parallel than another machine can have the capacity set to 2; in a simple case of two machines in a build farm, Parabuild will run twice more builds on that machine than on a machine with the capacity set to 1. The default setting for capacity is 1. In a cluster consisting of equality powered machines the capacity should be left set to 1.

To limit a number of builds that can run on an agent at the same time, use field 'Maximum concurrent builds'. Value '0' (zero) means that there is no limit for the number of builds running on the agent at the same time. Deleting Agent

To delete an agent click on link "Delete" for the selected agent. After receiving a confirmation Parabuild will delete the agent. Parabuild will display a warning message and will cancel the deletion process if the agent is a last agent in any of the configured builds farms. Modifying Agent Variables

18 System Administration

Parabuild provides an ability to define a set of agent-specific variables that are made available to build scripts as shell variables. The variable names can also be used as template parameters when configuring version control settings for a build. To view the list of agent variables, click on link "Variables" for the selected agent. Parabuild will show a table with already defined variables and controls necessary to add and edit the variables. Note

Agent variables overwrite global and project variables Adding Agent Variable

To delete a variable click on link "Delete" for the selected variable. After receiving a confirmation Par- abuild will delete the variable. Using Agent Variable in Version Control Settings

To use the variable as a template parameter in the version control settings for a build, wrap it's name into the parameter tokens, "${" and "}". Managing Build Farms

A build farm is a cluster of build machines that runs builds and provides automatic load balancing and transparent fail-over. A build farm may consist of one or more build machines. To add, configure or remove build farms select link "Build Farms" in the "Infrastructure" section of the system configuration. Parabuild will display a list of build farms and corresponding controls: Adding Build Farm

To add a build farm click on link "Add build farm". An entry form for a new build farm will appear. Fill fields "Build farm name" and "Description". Click on "Save" button to save the new build farm. Click on "Cancel" button to discard the edits: Editing Build Farm

To edit a build farm click on link "Edit" for the selected build farm. An entry form for the build farm will appear. Modify fields "Build farm name" and "Description". Click on "Save" button to save the changes for the build farm. Click on "Cancel" button to discard the edits. Deleting Build Farm

To delete a build farm click on link "Delete" for the selected build farm. After receiving a confirmation Parabuild will delete the build farm. Parabuild will display a warning message and will cancel the deletion process if any of the build configuration uses this build farm.

19 System Administration

Adding Agents to Build Farm

To add an agent to a build farm, go to the build farm list and click on the build farm name. Parabuild will show a list of agents in the build farm and controls to add or detach agents: Adding Agent to Build Farm

To add an agent to the build farm click on link "Add agent to Build Farm". An entry form for a new agent will appear. Select an agent from the list of available agents. Click on "Save" button to attached the new agent to the build farm. Click on "Cancel" button to discard the edits: Detaching Agent from Build Farm

To detach an agent "Detach" for the selected agent. After receiving a confirmation Parabuild will detach the agent from the build farm. Entering Parabuild License

You receive a license file after ordering Parabuild. In order to install your Parabuild license login to Par- abuild as admin and select "Administration" link on the top navigation bar. The system configuration page shows a list of links. To install Parabuild licenses system settings, select "Parabuild licenses" link. After a license window shows up, copy into clipboard the content of the license file and paste it into the license entry field. To save the changes click on "Save" button. If modifications are correct, a message saying that the license has been saved successfully will be displayed.

Under some rare circumstances it may be necessary to re-start Parabuild service to active the license. Note

To obtain an evaluation license, please visit http://www.viewtier.com/downloads.htm [http://www.viewtier.com/downloads.htm] . Configuring LDAP Authentication

Parabuild supports authentication of its users through LDAP. To enable authentication through LDAP go to system configuration at "LDAP" and check box "Enable LDAP authentication".

The following entry fields are available to configure access to LDAP:

• Connection URL

• Connection principal

• Connection credentials

• Connection security level

• User distinguished name template

• User search template

• Base element for user searches

• Search entire subtree

20 System Administration

• User password attribute name

• Credentials digest algorithm

• User e-mail attribute name

• Adding first-time users to group

• Using LDAP to map names of version control users to e-mails

Meaning of each fields is discussed below. Connection URL

Connection URL defines Parabuild's connection to the directory. The format of the URL is defined by the JNDI provider. This URL specifies the DNS name or the IP address of the directory server. You may also specify server port number and distinguished name (DN) of the root naming context. The default port number is 389.

Example 4.3. LDAP Connection URL

ldap://ldapserver:389

Connection Principal And Connection Credentials

If necessary Parabuild authenticates itself to the directory with the user name and password specified by the Connection Principal and Connection Credentials. Often the anonymous connection is sufficient and these properties don't have to be set. Connection Security Level

This field specifies the security level to use. Its value is one of the following strings: "none", "simple", "strong". If this field is not set, the behaviour is determined by the directory service provider. The default value is "simple". Processing Referrals

This field that holds the value that specifies how referrals encountered by the service provider are to be processed. It can be one of the following strings: "follow" - follow referrals automatically; "ignore" - ignore referrals; "throw" - throw an exception when a referral is encountered. If this field is set to "De- fault", the default is determined by the provider. User Distinguished Name Template

Parabuild supports selecting user's entry in the directory by using a template for the distinguished name (DN) of the user's directory entry. This is a recommend approach. The ${user.id}template field should be used to mark where the actual user name should inserted. Multiple lookup locations can be entered by separating each location with parentheses. Use this setting when the DN contains the user name and is the same for all users.

21 System Administration

Example 4.4. LDAP User Distinguished Name Template

uid=${user.id},ou=Test Organizational Unit,dc=test,dc=com

User Search Template

As alternative to using a DN template, Parabuild supports searching unique user's entry in the directory by using a template for the LDAP search filter. The${user.id}template field should be used to mark where the actual user name should inserted. The following example shows an LDAP filter for the case when user should enter her e-mail address to be authenticated.

Example 4.5. LDAP User Search Template

(mail=${user.id})

Parabuild will not authenticate a user if the LDAP filter returns multiple entries.

Base Element for User Searches

The base element for user searches may be used if user search is selected. If not specified, the top level element in the directory context will be used. The following example requests Parabuild to limit search to the context "ou=Test Organizational Unit,dc=test,dc=com"

Example 4.6. LDAP User Search Template

ou=Test Organizational Unit,dc=test,dc=com

Parabuild will not authenticate a user if the LDAP filter returns multiple entries.

Search Entire Subtree

Setting "Search entire subtree" may be used if user search is selected. Check this box if you want Par- abuild to search the entire subtree of the element specified by the "Base Element For User Searches" field for the user's entry. If not checked (default) only the top level will be searched. User Password Attribute Name

22 System Administration

By default Parabuild authenticates a user by binding to the directory with the DN of the entry for the user and the password presented by the user. If binding succeeds the user is considered to be authenticated. The directory performs password digesting transparently. This mode is used if "User password attribute name" is not set. This is a recommended method.

If "User password attribute name" is set Parabuild will retrieve the stored password from the directory and compare it explicitly with the value provided by the user. This field should be set to the name of an attribute of the user's entry that contains the password. Credentials Digest Algorithm

The selected credentials digest algorithm is used to digest clear text passwords. This field may be used in conjunction with using the user password attribute name and should be set to the algorithm used by your LDAP server. The supported digest algorithms are MD5 and SHA-1. User E-Mail Attribute Name

This mandatory field should be set to the name of an attribute of the user's entry that contains user's e- mail address. Add First-Time Users To Group

Parabuild will add to the selected Parabuild group users if they log to Parabuild first time. Using LDAP to Map Names of Version Control Users to E-mails

Environments using LDAP both for Parabuild and version control authentication may prefer to use e- mails of users that are maintained by an LDAP server to send notifications about build results. This may be very convenient because e-mails are maintained in a single place. To enable using LDAP to map names of version control users to e-mails, check box "Use LDAP to look up VCS user e-mail". Testing LDAP Configuration

Parabuild allows you to test created LDAP configuration. Fill the entry field "Test user name" and "Test password" with valid values and click on "Test" button. Parabuild will display a success message if the configuration is correct Parabuild will display a error message if the configuration is invalid or provided combination of the test user name and password does not exist. Integrating With Active Directory

To successfully integrate with Active Directory please follow these instructions: Set the Connection Principal and Connection Credentials to a user and password in Active Directory. Set Processing Refer- rals to "follow". Set User Search Template to sAMAccountName=${user.id}. Select Search Entire Sub- tree.

23 Chapter 5. Configuring a Build Note

Subsequent chapters will use "build configuration" and "build" interchangeably. Overview

To add a new build configuration, follow these steps:

1. Open a web browser of your preference and enter URL of your Parabuild server. If Parabuild ran on a host named "build", the URL would be "http://build:8080.

2. Login in as "admin" user.

3. Go to the list of builds by clicking "Builds" menu item on the top navigation bar.

4. In the build list, select link "Add new build". A general build settings form will show up. Fill in general settings fields and click the "Continue" button.

5. Detailed build configuration form will show up. Complete build configuration and click the "Save" button. Parabuild will save new build configuration and redirect you to the build statuses page.

Following sections discuss the process of configuring a build in detail. General Settings Form

General build settings form is displayed when a new build added. It allows to set the general build configuration parameters. These parameters include:

1. Build name.

2. Build results access.

3. Build farm name.

4. Version control.

5. Runner type.

6. Build type.

Naming a Build

Parabuild requires each build configuration to have a name. A build name should be short, simple, and self-explanatory. We recommend to apply the following simple rules when naming a build:

• Initially, a build name should start with one of the following: a product name, a project code name or a project home directory name in a version control system.

24 Configuring a Build

• Add to the build name a product version if there is one.

• For scheduled builds use one of the following suffixes: "qa", "nightly" or "daily" to reflect the timed nature of the build.

Example 5.1. Composing Build Name

Consider a product named "MyProduct". The current version of the product is 2.3. Possible names for an automatic (integration) build for the product would be: "myprod_23", "myprd_23" and "myproduct_23". Name QA, nightly or daily builds accordingly: "myprod_23_qa" or "myprd_23_dayly".

Oftentimes, the name of a project or product is considerably long, so it may be rather convenient to shorten it when naming a build. For example, the project name "MyNewProject Version 2.0" could be shortened to "mnp_20".

We do not recommend using strictly generic names like "build", "qa", "nightly", etc. Even if you are currently developing a single product with no specific version, over time the product will have different versions, maintenance branches, and/or platforms. The build name will quickly become an internal brand, and therefore it is reasonable to name the build to reflect its association with a particular product or source line. Generic names are not suitable for this purpose. Selecting Build Type

Parabuild offers three types of build configurations: automatic continuous integration builds, scheduled builds and manual builds. Automatic builds are fired upon every check-in or a series of check-ins into the version control system. Scheduled builds are fired at a configured time. Manual build are fired per a build manager's request. Once the build type is selected, it cannot be changed. Automatic Builds

Automatic builds are also known as integration builds. Parabuild initiates an automatic build at every check-in (or a series of check-ins) into the version control system.

The main goal of an automatic build is to ensure that new changes to the project source line do not break it, and that the product can be built cleanly. If a product cannot be built cleanly, then the project source line is broken. In either case, Parabuild will send e-mail notifications about the results of each build.

Notifications about successful builds inform that the project source line is in a clean state and that the team members may perform the check-out to integrate into the new changes safely. Owners of changes that were built would know that their changes did not break the build.

Automatic builds are ideal for setting up Continuous Integration for your projects. Important

Notifications about failed builds inform the owners of the changes that their changes possibly have broken the project source line. This gives them an opportunity to check-in the changes that fix the build immediately. Other members of the team then know that the project source line is broken, and that it is better not to check it out until the build is fixed. Scheduled Builds

25 Configuring a Build

Parabuild runs scheduled builds at configured times. Scheduled builds can be used to run builds that are timed by their nature such as nightly, daily, or QA builds.

It is important that scheduled builds run cleanly. Stable QA builds allow for uninterrupted QA and testing process. Failed QA or nightly builds prevent the QA teams from doing their job. Parabuild ensures that scheduled builds run against the last known clean state of the product source line. An automatic integration build backs every scheduled build. Scheduled builds use source control settings of the referenced automatic builds. Important

In order for a scheduled build to be created, an automatic (integration) build that backs it should be already configured. Manual Builds

Manual builds do not have a schedule and run only when a build administrator requests it. Manual builds can be used to run builds to produce results from short-living patch branches. Parallel Builds

Parabuild runs parallel builds simultaneously with a leading build. Parallel builds can be used to run builds that require parallel execution of multiple build configurations. Good examples of such builds are those requiring building and testing on multiple platforms. Parallel builds can be also used to deliver build acceleration.

If any of parallel builds fail Parabuild will mark a leading build run as failed. If the leading build run has a finalizer step, Parabuild will execute dependent builds fully before executing the finalizer step. This allows gathering and processing results from parallel builds in the finalizer step.

Parallel builds use version control settings of the referenced leading build. Select "Build reference" as a version control system when creating a parallel build. Important

In order for a parallel build to be created, a leading build should be already configured. Selecting Build Results Access

Parabuild allows you to set two types of access to the build results:

• Public access - Build results are available for general access. Everybody will have access to the build results and will receive e-mail notifications according to security settings of the server.

• Private access - Only the build administrator will have access to the build results and will receive build results notifications. Private access may be used to test new builds or to set up system builds that are visible only to the build administrator.

Note

New builds are created with private access. Build administrator can change this setting to public at any time. We recommend to test a new build to make sure it runs cleanly before making it public.

26 Configuring a Build

Detailed Build Configuration

Detailed build configuration is performed through various tabs. "Version Control" and "Build configuration" tabs are used to configure mandatory build parameters including version control system, build steps, build schedule properties, and labeling. "Notification settings" tab is used to configure various notification policies, to map e-mails to version control users and to set up build watchers. Parabuild maintains an archive of logs available for viewing by the team, and an archive of build results, also known as build artifacts, that can be downloaded via Parabuild Web UI. "Build logs" and "Build results" tabs are used to configure locations of the logs and results accordingly. Adding Build Steps

A build configuration must have at least one build step. Build steps are configured by modifying a build sequence table that provides supports for multi-step builds. Build Sequence Table

The build sequence table holds definitions of build steps. To add a build step, click on the "Add row" link. Each row in the build sequence table consists of the following entry fields: "Step name", "Build commands", "Success patterns", "Failure patterns", "Respect error code" check box and "Step timeout":

Meaning of each field is discussed below. Step Name

Enter a name of the build step in this field. The step name should reflect nature of the build step. "BUILD", "TEST", "DEPLOY" are good examples. Each step name should be unique in the build configuration. "Step name" is a mandatory field. Shell Commands

Enter shell commands that are used to perform the build step in this field. Parabuild will generate and execute a wrapper shell script that contains all commands entered in this field.

For example, if your project is built using NAnt under Windows, the build commands may look as following: rem Display build environment variables set rem Run build nant all.clean

Tip

Though Parabuild supports ad-hock build scripting using the "Shell commands" field, we recommend placing build scripts under control of a version control system if they take more than one line. This will allow keeping track of changes made to you build scripts.

"Shell commands" is a mandatory field.

For convenient editing, it is possible to open the "Shell Commands", "Failure Patterns" and "Success Patterns" in an expanded modal form by clicking a small tag image: Success Patterns

27 Configuring a Build

Enter step success patterns, one per line, in this field. Parabuild will try to find one of entered success patterns in the main build log to decide if the build step was successful. For example, for a build configuration using ANT tool, a success pattern would be "BUILD SUCCESSFUL".

Success patterns should be entered if "Respect error code" check box is not checked.

Success patterns are case sensitive.

Success patterns can be regular expressions. A regular expression should begin with '^' and end with '$'. Failure Patterns

Enter step failure patterns, one per line, in this field. Parabuild will try to find one of entered failure patterns in the main build log to decide if the build step failed. For example, for a build configuration using ANT tool, a failure pattern would be "BUILD FAILED".

Failure patterns should be entered if "Respect error code" check box is not checked. Parabuild searches the build log for failure patterns before checking if success patterns are present. If neither failure nor success patterns are present, Parabuild considers the build step failed.

Failure patterns are case sensitive.

Failure patterns can be regular expressions. A regular expression should begin with '^' and end with '$'. Respecting Error Code

If "Respect error code" check box is checked, Parabuild considers a build step failed if the build step commands return non-zero error code. Checking error code and searching the build log for failure pat- ters have priority over searching for success patterns. Tip

Use error code respecting if a build scripting tool used by your project cannot provide stable success and failure patterns. Timeout

Enter a step timeout in minutes in this field. Parabuild will stop execution of the build step forcefully if elapsed build step time exceeds the timeout value.

"Timeout" is a mandatory field. Continue If Failed

Sometimes it is necessary to continue running the build if a particular build step has filed. For instance, you Quality Control team may still want build results even if a step that runs automated unit tests failed. Check "Continue if failed" box if you'd like to continue running the build if the selected step failed Disabled

Check "Disabled" box to temporarily disable this build step. Initializer Step

Check "Initializer step" box to make this step an initializer step. The initializer step runs before any dependent parallel build runs.

28 Configuring a Build

Finalizer Step

Check "Finalizer step" box to make this step a finalizer step. The finalizer step always runs. It allows performing work upon completion of a build run without regard to success or failure of previous build steps. The finalizer step of a leading parallel build runs after completion of dependent parallel builds. Inserting Build Step

Parabuild allows inserting a build step at arbitrary location. To insert a build step, check box for a step before that you'd like to insert a new step and click on "Insert Row" link. Common Version Control Settings

The following settings are available to all version systems:

• Custom checkout directory

• Ignore list

Custom Checkout Directory

Important

"Custom checkout directory" is an advanced setting. It should be used with caution and only if the default value is not suitable. This setting is available only when an advanced build configuration is enabled using the system settings page.

This setting allows changing the default checkout directory for the build. It can be either a fully qualified path such as /opt/build/my_build or a template. The template supports fields${build.id}and {build.name}. Template example is /opt/builds/build_${build.id}. Ignore List

Important

"Ignore list" is an advanced setting. This setting is available only when an advanced build configuration is enabled using the system settings page.

This setting may contain a list of paths for that changes in a version control system should be ignored. Changes in the files included into the ignore-list will not trigger the build. Parabuild compares this list against endings of fully qualified paths of changed files.

To use a regular expression, start the line with character "^" and end it with character "$". Regular expressions are applied to the whole change path.

Figure 5.1. Entering Regular Expressions in Ignore List

Configuring Accurev Access

29 Configuring a Build

In order to access Accurev version control system, Parabuild should be installed on a box that has a working Accurev client.

To configure access to Accurev, fill in the following fields:

• Path to accurev executable

• Host

• Port

• User

• Password

• Stream

Figure 5.2. Example: Configuring Accurev Access

The meaning of each field discussed below. Path To accurev Executable

Path to accurev executable is a mandatory field. This field should be set to a fully qualified path to accurev executable. The path should be wrapped in double quotes if it contains spaces.

Example 5.2. Path To cleartool Executable

Unix:

/opt/accurev/bin/accurev

Windows:

C:\Program Files\AccuRev\bin\accurev.exe

Host

Host is a mandatory field. It should be set to the name of Accurev server. Port

Port is a mandatory field. It should be set to the port on that Accurev server accepts requests. The default value is 5050. User

User is a mandatory field. It should be set to a registered Accurev user. Password

30 Configuring a Build

is a mandatory field. It should be set to a password of the Accurev user. Stream

Stream is a mandatory field. It should be set to a stream that Parabuild will access to perform a build Configuring Bazaar Access

To configure access to Bazaar version control system, fill in the following mandatory fields:

• Path to Bazaar client executable (bzr)

• Bazaar branch path

Meaning of each field is discussed below. Path To Bazaar Client Executable

Path to the Bazaar client executable is a mandatory field. This field should be set to a fully qualified path to a Bazaar client executable. The path should be wrapped in double quotes if it contains spaces.

Example 5.3. Path to Bazaar Executable Field

Unix:

/usr/bin/bzr

Windows:

C:\Bazaar\bzr.exe

Bazaar Branch Path

Bazaar Branch Path is a mandatory field. This file should contain a URL pointing to a Bazaar repository and should correspond with the URL notation. Parabuild supports BZR+SSH, HTTP, BZR and FILE protocols to access Bazaar servers. Configuring Access To Bazaar via SSH

Configuring access to Bazaar via SSH consists of generating public and private DSA keys and listing the generated public key at the Bazaar server. The following discussion assumes that Parabuild is installed on a Unix-like system and OpenSSH client is used. Please consult with the documentation for the corresponding SSH client if it is different from the above.

First, login to the server as user parabuild and ensure that the current directory is parabuild's home:

su - parabuild cd ~

31 Configuring a Build

Generate public and private keys. When asked for passphrase, hit Enter (no passphrase): ssh-keygen -t dsa

The typical console output produced by ssh-keygen is the following:

Generating public/private dsa key pair. Enter file in which to save the key (/home/parabuild/.ssh/id_dsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/parabuild/.ssh/id_dsa. Your public key has been saved in /home/username/.ssh/id_dsa.pub. The key fingerprint is: e2:eb:aa:23:0b:0f:15:6a:f6:39:eb:0f:3a:37:96:20 parabuild@hostname

Set the correct permissions for the generated keys: chmod 600 ~/.ssh/id_dsa chmod 644 ~/.ssh/id_dsa.pub

E-mail thepublic key, ~/.ssh/id_dsa.pub, to your Bazaar administrator.

If you are an administrator of the system where Bazaar is installed, add the public key to file ~/.ssh/authorized_keys for the user that parabuild will use to access Bazaar via SSH and make this file read-only: chmod go-w ~ ~/.ssh ~/.ssh/authorized_keys

Example 5.4. Bazaar Branch Path Field Using SSH Protocol

bzr+ssh://my-bazaar-server/project-v-2.0

Configuring ClearCase Access

In order to access ClearCase, Parabuild should be installed on a box that has a working ClearCase client. Under Unix and Linux systems user "parabuild" and group "parabuild" should be allowed access to VOB explicitly.

To configure access to ClearCase LT version control system, fill in the following fields:

• Path to cleartool executable

• Snapshot view config spec

• Branches

• Relative build dir

• Change window

32 Configuring a Build

The following fields are available only when advanced build settings are enabled via system settings:

• View storage location (-stgloc)

• View name template

• Ignore error lines

The meaning of each field discussed below. Path To cleartool Executable

Path to cleartool executable is a mandatory field. This field should be set to a fully qualified path to cleartool executable. The path should be wrapped in double quotes if it contains spaces.

Example 5.5. Path To cleartool Executable

Unix:

/opt/clearcase/bin/cleartool

Windows:

C:\Rational\ClearCase\bin\cleartool.exe

Snapshot View Config Spec

Snapshot view config spec is a mandatory field. Enter a config spec for a snapshot view that Parabuild will use to access your project code base. It should correspond the notation for ClearCase configuration specs for snapshot views. Please refer ClearCase documentation for detailed discussion of configuration specs.

Example 5.6. Snapshot View Config Spec

element * CHECKEDOUT element * /main/LATEST load \project_vob\3rdparties\lib load \ project_vob\version20\myproj

Branch

Branch is an optional field. If this field is set, Parabuild will limit watching for changes to the given branch. This field allows entering multiple branch names. Use the following characters: space, comma or semicolon to separate one branch name from another. Relative Build Dir

Parabuild should be provided a path to the build directory (project home). Parabuild will start build step scripts using this directory as a current directory. The relative build directory is a directory that is relative to a working directory provided by Parabuild. Using the example in the previous section, the relative build dir path could be project_vob\version20\myproj.

33 Configuring a Build

Change Window

Parabuild maintains synthetic change lists for ClearCase. The change list is a set of logically connected changes in multiple files. An example of a change list can be adding to ClearCase a C++ class and a sup- porting binary library that the class makes use of.

ClearCase itself does not support change lists. If a logically connected group of files is checked in, and the process takes longer than a minute, it is possible that Parabuild might detect the presence of changes before all files make it to the ClearCase repository and fire a build against an incomplete submission time stamp. To avoid this problem Parabuild uses "change window" for the advanced detection of the member files of a change list. The change window is the maximum time in seconds a check-in of a group of files may take.

Entering zero value in the change window field turns off the advanced detection of members of change lists that are taking a long time to process. View Name Template

An optional field "View name template" may contain a custom template that Parabuild will use to compose a ClearCase view tag name. The template may include alphanumeric characters, characters "-" and "_". The template must include a template parameter${build.id}and may include ${cc.user} parameter. ${build.id} parameter will be replaced with a unique build configuration ID during runtime.${cc.user}parameter will be replaced with the name of a user account that runs Parabuild server.

If "View name template" is not filled, Parabuild will use a default value. The default value is "par- abuild_${build.id}". Important

"View name template" is an advanced setting. It should be used with caution and only if the default value is not suitable. This setting is available only when an advanced build configuration is enabled using the system settings page. View Storage Location

An optional field "View Storage Location" may specify a name of a server storage location to hold the view storage directory or a path to the local view storage.

To enter server the name of the server storage location, select "-stgloc" from the view storage location drop down.

To enter the path to the local view storage, select "-vws" from the view storage location drop down list. Certain ClearCase configurations may require providing the path to the local view storage. Parabuild provides a template parameter ${build.id} that can be used as a path name space that uniquely defines the path to the local view storage for an integration build and for dependant scheduled builds. Example: \\ComputerName\ViewStorage\parabuild_${build.id}.vws

If not set, the server storage location is selected automatically by ClearCase. By default this field is not set. Important

"View Storage Location" is an advanced setting. It should be used with caution and only if the default value is not suitable. This setting is available only when an advanced build configuration is enabled using the system settings page.

34 Configuring a Build

Ignore Error Lines

An optional field "Ignore error lines" may specify a list of strings that define what lines in standard error output should be ignored if they contain one of the strings. Important

"Ignore error lines" is an advanced setting. This setting is available only when an advanced build configuration is enabled using the system settings page. It should be used with caution and only if the default value is not suitable. Configuring CVS Access

To configure access to CVS, fill the following mandatory fields:

• CVS Root

• CVS Repository path

• Path to CVS client executable

• Change window

The following fields are optional:

• CVS password

• Path to external rsh

• Branch name

• Change pre-check

• Fast change detection

• Compression level

• Repository browser

• Custom Relative Build Directory

Meaning of each field discussed below. CVS Root

CVS root is a mandatory field. The entry for this field should conform with the format for the CVS root.

Example 5.7. CVS root for pserver authentication

:pserver:[email protected]:/home/cvs/data/CVSroot

35 Configuring a Build

CVS Repository Path

Repository path is a mandatory field. It defines the location of the home of the project source line relative to the CVS root.

Example 5.8. Single line CVS repository path

mycompany/myproject20

Parabuild supports multiple path projects. For multiple path projects each path should be entered one per line.

Example 5.9. Multi-line CVS repository path

mycompany/myproject20/3rdparty/libs

All build scripts are executed with a project source line home as the current directory. The project source line home is the first line defined in the CVS repository path. For example, if the CVS repository path is mycompany/myproject20, and the build script is stored in mycompany/myproject20/make, the build command may look like make all.clean

Path To CVS Client Executable

Path to CVS client executable is a mandatory field. This field should be set to a fully qualified path to a CVS client executable. The path should be wrapped in double quotes if it contains spaces.

Example 5.10. Path to CVS executable field

Unix:

/usr/bin/cvs

Windows:

C:\cvs\cvs.exe

CVS Password

CVS password is an optional field. If needed, enter a password that will be required to access CVS in this field. Path To External rsh

This optional field defines a fully qualified path to a remote shell binary for usage. Usually this field is used to configure access to CVS via SSH.

36 Configuring a Build

Configuring Access To CVS Via SSH

Configuring access to CVS via SSH consists of generating public and private DSA keys and listing the generated public key at the CVS server. The following discussion assumes that Parabuild is installed on a Unix-like system and OpenSSH client is used. Please consult with the documentation for the corresponding SSH client if it is different from the above.

First, login to the server as user parabuild and ensure that the current directory is parabuild's home: su - parabuild cd ~

Generate public and private keys. When asked for passphrase, hit Enter (no passphrase): ssh-keygen -t dsa

The typical console output produced by ssh-keygen is the following: Generating public/private dsa key pair. Enter file in which to save the key (/home/parabuild/.ssh/id_dsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/parabuild/.ssh/id_dsa. Your public key has been saved in /home/username/.ssh/id_dsa.pub. The key fingerprint is: e2:eb:aa:23:0b:0f:15:6a:f6:39:eb:0f:3a:37:96:20 parabuild@hostname

Set the correct permissions for the generated keys: chmod 600 ~/.ssh/id_dsa chmod 644 ~/.ssh/id_dsa.pub

E-mail thepublic key, ~/.ssh/id_dsa.pub, to your CVS administrator.

If you are an administrator of the system where CVS is installed, add the public key to file ~/.ssh/authorized_keys for the user that parabuild will use to access CVS via SSH and make this file read-only: chmod go-w ~ ~/.ssh ~/.ssh/authorized_keys

Once the keys are installed, edit the build configuration in Parabuild and fill the fields "CVS root" and "Path to external rsh". See the example below.

Example 5.11. Connecting to CVS using SSH As Remote Shell Under Unix

CVS root:

:ext:[email protected]:/home/cvs/data/CVSroot

Path to external rsh:

37 Configuring a Build

/usr/bin/ssh

Change Window

Parabuild maintains synthetic change lists for CVS. The change list is a set of logically connected changes in multiple files. An example of a change list can be adding to CVS a C++ class and a support- ing binary library that the class makes use of.

CVS itself does not support change lists. If a logically connected group of files is checked in, and the process takes longer than a minute, it is possible that Parabuild might detect the presence of changes before all files make it to the CVS repository and fire a build against an incomplete submission time stamp. To avoid this problem Parabuild uses "change window" for the advanced detection of the member files of a change list. The change window is the maximum time in seconds a check-in of a group of files may take.

Entering zero value in the change window field turns off the advanced detection of members of change lists that are taking a long time to process. Change Pre-check

If Change Pre-check is on, Parabuild will issue a cvs history command for a quick detection of the presence of changes after periods of inactivity.

Using change pre-check may speed up the detection of changes that need to be built. It is beneficial pre- dominantly for CVS servers hosting large standalone source lines.

Change pre-check is not beneficial if a CVS server hosts multiple projects under active development.

A default setting is not to use change pre-check. Fast Change Detection

If Fast Change Detection is checked, Parabuild will use option "-S" when running cvs log command. This may reduce amount of information passed from CVS to Parabuild and speed up detecting of changes as a result. Using fast change detection requires CVS starting version 1.4 and on. This option should be disabled for prior versions of CVS. Compression Level

Compression level drop down allows to set a compression level used to transfer files over the network from CVS to Parabuild. The default setting for compression level is zero (no compression).

While higher compression levels may reduce network traffic between Parabuild and the CVS server, they are very likely to increase the CPU load on both servers. We recommend leaving the compression level set at zero if both Parabuild and CVS are connected over a high-speed intranet, which is usually the case. Branch Name

Branch name is an optional field. Use this field to enter a name of a branch if the build being configured will be performed against a branched source line. Repository Browser

Parabuild allows selecting ViewVC or Cenqua FishEye as a repository browser. Parabuild integrates

38 Configuring a Build

with repository browsers by providing direct links to repository browser pages when displaying changes participated in a given build run. Configuration for repository browsers in discussed in the following sections. Integration With ViewVC

ViewVC (formerly known as ViewCVS) is a browser interface for CVS and Subversion version control repositories. It generates HTML to present navigable directory, revision, and change log listings. To enable integration with ViewVC, fill ViewVC URL and ViewVC root fields. The meaning and use of each field is discussed below. ViewVC URL

ViewVC URL should contain a base part of the URL that would be used to access ViewVC. The content of this field depends on an how access to ViewVC is configured. The most common forms look like the following. The bold font marks the base part of the URL:

Example 5.12. The Most Commonly Used Forms of ViewVC URLs

http://mycvshost/viewcvs/ myproject / README?rev=6881&view=markup

http://mycvshost/cgi-bin/viewcvs.cgi/ myproject/tags?rev=1033&view=log

http://mycvshost/viewcvs.py/myprojectREADME?rev=6881&view=markup

Identify your base URL and enter in the ViewVC URL field. ViewVC Root

Enter ViewVC root in this field if applicable. Integration With FishEye

FishEye is a browser interface for CVS and Subversion version control repositories. It generates HTML to present navigable directory, revision, and change log listings. To enable integration with FishEye, fill FishEye URL and FishEye root fields. The meaning and use of each field is discussed below. FishEye URL

FishEye URL should contain a base part of the URL that would be used to access FishEye. The content of this field depends on an how access to FishEye is configured. The most common forms look like the following. The bold font marks the base part of the URL:

Example 5.13. The Most Commonly Used Forms of FishEye URLs

http://myfisheyehost/fisheye/ myproject / README?rev=6881&view=markup

Identify your base URL and enter in the FishEye URL field. FishEye Root

Enter FishEye root in this field if applicable.

39 Configuring a Build

Integration With WebSVN

WebSVN is a browser interface for the Subversion version control repository. It generates HTML to present navigable directory, revision, and change log listings. To enable integration with WebSVN, fill 'Base WebSVN URL' and 'Repository name' fields. Example:

The meaning and use of each field is discussed below. Base WebSVN URL

Base WebSVN URL should contain a base part of the URL that would be used to access WebSVN. The content of this field depends on an how access to WebSVN is configured. The most common forms look like the following. The bold font marks the base part of the URL:

Example 5.14. The Most Commonly Used Form of WebSVN URL

https://host.net/websvn/mycompany/filede- tails.php?repname=mycompany&path=/trunk/Fbuild.xml&rev=15717

Identify your base URL and enter in the WebSVN URL field. Repository name

Enter the repository name in this field if applicable. Custom Relative Build Directory

An optional field Custom relative build dir" may contain a custom relative path to a build directory. You will have to set this field if CVS repository path consists of CVS module names. Parabuild will start build step scripts using this directory as a current directory. The relative build directory is a directory that is relative to a working directory provided by Parabuild. For instance, if a module named "my_proj" consisted of a repository path projects/release/my_proj and a build script were stored under projects/release/my_proj/build directory, the relative build dir field would have to contain value "projects/release/my_proj/build". Important

"Custom relative build dir" is an advanced setting. It should be used with caution and only if the default value is not suitable. This setting is available only when an advanced build configuration is enabled using the system settings page. Configuring Watching for File System Changes

Parabuild provides an ability to configure a surrogate "File system" VCS to support watching file system for changes. This ability can be used to trigger builds when changes are detected. To configure watching for file system changes, fill in the following mandatory fields:

• User name

• Paths

40 Configuring a Build

The following fields are optional:

• Command to sync to change list

• Command to label/tag a build

• Command to remove a tabel/tag

The meaning of each field discussed below. User name

User name is a mandatory field. Parabuild will use this field to fill "user" part of detected change lists. Path

Path is a mandatory field. This field should contain a list of directories, files or URLs that Parabuild should watch for changes. Command To Sync To Change List

"File system" VCS allows running arbitrary shell scripts as a part of the change detection and build cycles. Such commands serve as points of extensibility. Field "Sync to change list" may contain a command that can be used to alter content of the file system. The content may represent certain state of the file system that is considered "in sync" with state of the file system or an external VCS at given time.

Parabuild supplies parameters of the build configuration to the shell scripts. The parameters are passed in form of shell variables. The following shell variables are available to the "Sync To Change List" shell script:

• PARABUILD_CHANGE_LIST_TIMESTAMP contains number of milliseconds passed since midnight, January 1, 1970 UTC.

• PARABUILD_CHANGE_LIST_DATETIME contains a string representation of the change list time stamp in "yyyyMMddHHmmss" format.

• PARABUILD_CONFIGURATION_IDcontains a unique system-wide identifier assigned to this build configuration.

• PARABUILD_BUILD_NAME contains a name assigned to this build configuration.

Command To Label Build

Field "Command To Label Build" may contain a command that can be used to label or to tag content of an external VCS at given time. This command may be called if a build run was successful and if labeling is enabled. The following shell variables are available to the "Command To Label Build" shell script:

• PARABUILD_LABEL_TO_CREATE contains the name of the label that should be applied to the state of an external VCS at the given time.

• PARABUILD_LABEL_TIMESTAMP contains number of milliseconds passed since midnight, Janu- ary 1, 1970 UTC.

41 Configuring a Build

• PPARABUILD_LABEL_DATETIME contains a string representation of the time stamp that a label should be applied to in "yyyyMMddHHmmss" format.

• PARABUILD_CONFIGURATION_IDcontains a unique system-wide identifier assigned to this build configuration.

• PARABUILD_BUILD_NAME contains a name assigned to this build configuration.

Command To Delete Label

Field "Command To Delete Label" may contain a command that can be used to delete a label or a tag that was previously created by Parabuild in the external VCS. This command may be called if label cleanup is configured. The following shell variables are available to the "Command To Delete Label" shell script:

• PARABUILD_LABEL_TO_DELETE contains the name of the label that should be deleted.

• PARABUILD_CONFIGURATION_IDcontains a unique system-wide identifier assigned to this build configuration.

• PARABUILD_BUILD_NAME contains a name assigned to this build configuration.

Error Handling

The shell command discussed in the previous sections should return a non-zero error code if something goes wrong. If a command returns a non-zero code, Parabuild will collect a limited number of lines from the tail of stderr output. The output will be sent to the build administrator to notify about the error condition. Configuring Generic Version Control System Access

Parabuild provides an ability to configure access to a generic version control system. A generic version control system can be used to integrate Parabuild with a version control system that Parabuild does not integrate with yet. Also, this feature can be used to deliver a custom integration if once included into Parabuild does not fit your needs. Using this feature requires extensive knowledge of other languages such as bash, Perl, Java and alike.

Parabuild integrates with a generic version control system by calling shell scripts according to a defined protocol of access to a version control system as it is seen by Parabuild.

Parabuild supplies parameters of the build configuration to the shell scripts. The parameters are passed in form of shell variables.

Shell command should be called according to the OS-specific rules: Example for bash call:bash / op/sripts/get_changes.sh. Example for cmd call: call C:\scripts\get_changes.bat

The protocol, commands and their parameters are discussed below. Command To Get Changes

Parabuild issues this command every time it has to poll a version control system for new changes according to build schedule. If changes are present this command should output a string-delimited set of change records tostdout. Parabuild will parse the output according to the parser parameters. The para-

42 Configuring a Build

meters are entered in the corresponding entry fields. The meaning of each field is discussed below. Parser Parameters

Column divider is a string that separates columns in a change record. The column divider should contain a set of characters that are unlikely to be present in the change record. Example:w0Fg9.

End of record marker is a string that marks end of a change record. The end of record marker should contain a set of characters that are unlikely to be present in the change record. Example:bH56d. End of the record token should be followed by a line break.

Change date formatdefines a template Parabuild will use to parse change dates. Change Record Format

The format of the change record is the following:

The change date column should follow the format defined in the "Change date format" field. Example of the format is yyyyMMdd.HHmmss.

The change type should contain one of the following sting literals:checkin, mkelem, add, delete or remove. Parameters

The following shell variables are available to the "Get Changes" shell script:

• PARABUILD_SINCE_TIMESTAMP contains a time stamp to start looking for changes from. This is a number of milliseconds passed since midnight, January 1, 1970 UTC.

• PARABUILD_SINCE_DATETIME contains a string representation of the time stamp in " yyyyMM- ddHHmmss " format.

• PARABUILD_CONFIGURATION_IDcontains a unique system-wide identifier assigned to this build configuration.

• PARABUILD_BUILD_NAME contains a name assigned to this build configuration.

Command To Sync To Change List

Field "Sync to change list" may contain a command that can be used to alter content of the file system. The content may represent certain state of the file system that is considered "in sync" with state of the file system or an external VCS at given time.

The following shell variables are available to the "Sync To Change List" shell script:

• PARABUILD_CHANGE_LIST_TIMESTAMP contains number of milliseconds passed since midnight, January 1, 1970 UTC.

• PARABUILD_CHANGE_LIST_DATETIME contains a string representation of the change list time stamp in "yyyyMMddHHmmss" format.

43 Configuring a Build

• PARABUILD_CONFIGURATION_IDcontains a unique system-wide identifier assigned to this build configuration.

• PARABUILD_BUILD_NAME contains a name assigned to this build configuration.

Command To Label Build

• PARABUILD_LABEL_TO_CREATE contains the name of the label that should be applied to the state of an external VCS at the given time.

• PARABUILD_LABEL_TIMESTAMP contains number of milliseconds passed since midnight, Janu- ary 1, 1970 UTC.

• PPARABUILD_LABEL_DATETIME contains a string representation of the time stamp that a label should be applied to in "yyyyMMddHHmmss" format.

• PARABUILD_CONFIGURATION_IDcontains a unique system-wide identifier assigned to this build configuration.

• PARABUILD_BUILD_NAME contains a name assigned to this build configuration.

Command To Delete Label

• PARABUILD_LABEL_TO_DELETE contains the name of the label that should be deleted.

• PARABUILD_CONFIGURATION_IDcontains a unique system-wide identifier assigned to this build configuration.

• PARABUILD_BUILD_NAME contains a name assigned to this build configuration.

Error Handling

To configure access to Git version control system, fill in the following mandatory fields:

• Path to Git client executable (git)

44 Configuring a Build

• Git repository

• Depot path

Meaning of each field is discussed below. Path To Git Client Executable

Path to the Git client executable is a mandatory field. This field should be set to a fully qualified path to a Git client executable. The path should be wrapped in double quotes if it contains spaces.

Example 5.15. Path to Git Executable Field

Unix:

/usr/bin/git

Windows:

C:\Git\git.exe

Git Repository

Git Repository is a mandatory field. This file should contain a URL pointing to a Git repository and should correspond with the URL notation. Parabuild supports SSH, HTTP, GIT and FILE protocols to access Git servers.

Example 5.16. Git Repository Field Using SSH Protocol

ssh://my-git-server/project.git

Git Repository Path

Repository path is a mandatory field. It defines the location of the home of the project source inside the Git repository. Parabuild will watch for changes only the paths defined in this field.

Example 5.17. Single Line Git Repository Path

projects/myproject_20

Parabuild supports multiple-path projects. For multiple path projects each path should be entered one per line.

Example 5.18. Multi-path Git Repository Path

projects/myproject_20

45 Configuring a Build

3rdparty

All build scripts are executed with a project source line home as the current directory. The project source line home is the first line defined in the Git repository path. For example, if Git repository path is/ projects/myproject_20, and the build script is stored in /projects/myproject_20/make file, the build command may look like make all.clean

Git repository path should be set to "/" if the project home is at the root of the Git repository. Configuring Mercurial Access

Parabuild provides extensive support for Continuous Integration and Release Management for Distrib- uted Version Control System (DVCS) Mercurial. To configure access to Mercurial, fill in the following mandatory fields:

• Path to hg executable

• Repository URL

The configuration screen for MKS also includes the following optional fields:

• Branch

• Custom checkout dir

• Ignore list

Figure 5.3. Mercurial Configuration Example

The meaning of each field discussed below. Path to hg Executable

Path to hg executable is a mandatory field. This field should be set to a fully qualified path to Mercuri- al's command line client hg. The path should be wrapped in double quotes if it contains spaces. Repository URL

Repository URL is a mandatory field. This field should contain a path to a Mercurial repository. Suppor- ted protocols are http://, https://, file:// and ssh://. Branch

Branch is an optional field. It may be set to a Mercurial branch. Configuring MKS Access

46 Configuring a Build

To configure access to MKS Source Integrity Enterprise version control system, fill in the following mandatory fields:

• Path to si executable

• MKS Host

• MKS Port

• MKS User

• MKS Password

• MKS Project path

• rlog date format

The configuration screen for MKS also includes optional field "co date format override".

The meaning of each field discussed below. Path to SI Executable

Path to si executable is a mandatory field. This field should be set to a fully qualified path to a MKS's command line client executable (si). The path should be wrapped in double quotes if it contains spaces. MKS Host

MKS host is a mandatory field. MKS host should be set to a valid MKS server IP address or a DNS name. MKS Port

MKS port is a mandatory field. MKS port should be set to a valid MKS server port number that the server is listening on. MKS User

MKS user is a mandatory field. It should contain a name of a valid MKS user that Parabuild will use to access the MKS server. The user should be allowed to access the MKS server beforehand. MKS Password

MKS password is an optional field. This field should be set if the user defined in the MKS user field requires a password to access the MKS server. MKS Project

MKS project is a mandatory field. Enter a fully qualified path to the project in this field.

If it is not entered explicitly, Parabuild provides a client part of the client view automatically by repla- cing the depot name with a template client name "parabuild". A client view rlog Date Format

47 Configuring a Build

This field should contain the format for the dates present in the output of "si rlog" command. If Par- abuild reports a problem executing command "si rlog", such as "Unparseable date" error, the format needs to be changed. For example, the date "Sep 11, 2008 10:15:38 AM" would require the format "MMM dd, yyyy hh:mm:ss a".

The default format is "MMM dd, yyyy - hh:mm a" that matches the most often used rlog date format, example: " Apr 29, 2006 - 6:29 PM". co Date Format Override

This field may contain the format for the dates expected by "si co" command. If Parabuild reports a problem executing command "si co", the format needs to be changed so that it matches the format expected by your Parabuild installation. For example, the date "Sep 11, 2008 10:15:38 AM" would require the format "MMM dd, yyyy hh:mm:ss a".

If not set, Parabuild will try to guess the format based on the locale of the system Parabuild is running on . Configuring Perforce Access

To configure access to Perforce version control system, fill in the following mandatory fields:

• Path to P4 executable

• P4 port

• P4 user

• P4 client view

The following fields are optional:

• P4 password

• Do not sync

• P4 counter

• Update have list

• P4 options

• P4Web URL

The following fields are available only when advanced build settings are enabled via system settings:

• Client name template

• P4 variables override

• UNC paths under Windows

The meaning of each field discussed below.

48 Configuring a Build

Path to P4 Executable

Path to P4 executable is a mandatory field. This field should be set to a fully qualified path to a Perforce client executable. The path should be wrapped in double quotes if it contains spaces.

Example 5.19. Path to P4 executable field

Unix:

/opt/perforce/bin/p4

Windows:

C:\perforce\p4.exe

P4 Port

P4 port is a mandatory field. P4 port should be set to a Perforce server address and port. It should correspond with the notation for P4PORT.

Example 5.20. P4 port field

perforce:1666

P4 User

P4 user is a mandatory field. It should contain a name of a valid Perforce user that Parabuild will use to access the Perforce server. The user should be allowed to access the Perforce server by calling p4 protect beforehand. P4 Client View

Client view is a mandatory field. It defines the location of a home of a project source line.

Example 5.21. Single-line P4 Client View

//depot/projects/myproject_20/...

Parabuild supports multiple path projects. For multiple path projects each path should be entered one per line.

Example 5.22. Multi-path P4 Client View

//depot/projects/myproject_20/...

//depot/3rdparty/...

49 Configuring a Build

Parabuild maintains its client specs automatically. Parabuild provides two modes of entering the client view: a simple mode and an advanced mode.

The simple mode should be used by projects that do not require complex depot mappings. In the simple mode Parabuild allows entering simple P4 mappings that allow only "..." wildcards. All build scripts are executed with a project source line home as the current directory. When in the simple mode, the project source line home is the first line defined in the P4 depot path. For example, if P4 client view is/ /depot/projects/myproject_20, and the build script is stored in / /depot/projects/myproject_20/make file, the build command may look like make all.clean

The resulting client view is formed by adding a part of the depot path following the depot name to a Par- abuild check-out directory. Considering the early example of a multi-path project, a directory structure after sync may look like /opt/parabuild/etc/build/b0co/ projects/myproject_20 /opt/parabuild/etc/build/b0co/ 3rdparty

When in the advanced mode, Parabuild allows entering client views of any complexity. To turn on the advanced mode, check the "Advanced view mode" check box and enter the relative build directory (project home). The client views must conform the P4 client view spec. In the advanced mode Parabuild should be provided a path to the build directory (project home) explicitly. The relative build directory is a directory that is relative to Parabuild's P4 client root. Parabuild always uses the checkout directory that created for every build configuration as a Parabuild's client root. The following example shows possible client and the choice of the build directory.

Example 5.23. Advanced Mode Client View And Relative Build Directory

P4 client view: -//depot/project/version20/src/release/* //depot/project/version20/3rdparty/... //depot/project/version20/src/...

Possible relative build directory assuming that it would exist after sync:

project/version20/src/test/build

If it is not entered explicitly, Parabuild provides a client part of the client view automatically by repla- cing the depot name with a template client name "parabuild". A client view

//depot/projects/myproject_20/... that does not have the client part will be internally translated to

50 Configuring a Build

//depot/projects/myproject_20/... //parabuild/projects/myproject_20/...

The actual client view that Parabuild used to access P4 is composed during the runtime. Parabuild re- places the template client name//parabuildwith the actual generated client name.

Parabuild also support explicit entering of the depot and client paths of the client view. The only require- ment is that the client part should always start with //parabuid/. Disabling Automatic Syncing

Before starting a build, Parabuild synchronizes the build workspace with Perforce in accordance with build's Perforce view using the last change list number detected for this build configuration. Some environments may prefer to disable the default behaviour and to synchronize the build workspace using their own scripts. Usually the custom synchronisation is done by adding a sync step to the normal sequence of build steps defined under that Build Configuration tab.

If you wish to be able to alter the default behaviour, go to Administration, then go to Stability Settings and check box "Enable no-checkout builds". Return to the build configuration. The version control tab on the build configuration screen will now display a check box "Do not sync". Check this box to disable automatic workspace synchronization.

If the workspace synchronization is disabled, it is responsibility of the build sequence to populate the build workspace. The custom sync scripts can use shell variable PAR- ABUILD_CHANGE_LIST_NUMBER to sync to the build change list number. Please check section Perforce Environment Variables for a more detailed discussion about the available shell variables related to Perforce. P4 Password

P4 password is an optional field. This field should be set if the user defined in the P4 user field requires a password to access the Perforce server. P4 Counter

P4 counter is an optional field. P4 counter may contain a name of a Perforce counter that contains the number of the latest change list for the configured depot path of the project.

By default Parabuild polls Perforce server for change lists. For an overloaded Perforce server this may present a concern. Using a counter that contains the latest change list number for the configured depot path of the project reduces the load of the Perforce server.

If the counter is used, a Perforce administrator needs to set up a trigger on the Perforce server. The trigger should update the counter to the latest change list for the build depot path. If the depot path is multi- line, the trigger should take this into account by monitoring all configured paths.

When deciding for using the counter, consider an additional administrative overhead that is associated with maintaining the trigger. If the build depot path is changed, such changes should be reflected in the code of the trigger. Update Have List

Parabuild populates a client workspace and updates the have list if box Update Have List is checked. If non checked, Parabuild populates a client workspace, but does not update the have list. Unchecking this box may increase concurrency Perforce server because a sync command will not lock the database.

51 Configuring a Build

P4 Options

Parabuild allows setting the following Perforce options:

• modtime - modification time for files that were edited in the build client workspace will be set to the time when the file is submitted to the depot.

• nomodtime - modification time for files that were edited in the build client workspace will be set to the time when the file is synced.

• clobber - syncing files will overwrite writable files on the build client workspace.

• noclobber - overwrite writable files on the build client workspace will be protected.

Client Name Template

An optional field "Client name template" may contain a custom template that Parabuild will use to compose a Perforce client name. The template may include alphanumeric characters, characters "-" and "_". The template must include a template parameter${build.id}and may include ${p4.user} parameter. ${build.id} parameter will be replaced with a unique build configuration ID during runtime.${p4.user}parameter will be replaced with the name of Perforce user entered in the "P4 User" field. If "Client name template" is not filled, Parabuild will use a default value. The default value is " parabuild_${build.id}". Important

"Client name template" is an advanced setting. It should be used with caution and only if the default value is not suitable. This setting is available only when an advanced build configuration is enabled using the system settings page. P4 Variables Override

If check box "P4 variables override" is checked, Parabuild will set and make available to the build scripts shell variables P4CLIENT, P4PASSWD, P4PORT and P4USER that were used to create a client spec for the build run. If these variable are already available in the environment used to start Parabuild, the variables will be overridden. By default the box is not checked and the variables are not set. Please check section Perforce Environment Variables for a more detailed discussion about the available shell variables related to Perforce. Important

"P4 Variables Override" is an advanced setting. This setting is available only when an advanced build configuration is enabled using the system settings page. P4Web URL

P4Web is a browser interface for Perforce version control. It generates HTML to present navigable directory, revision, and change log listings. Parabuild integrates with P4Web by providing direct links to P4Web pages. To enable integration with P4Web, fill P4Web URL field. P4Web URL should contain a

52 Configuring a Build

fully qualified path to P4Web server that includes a protocol, host name and port number, such as http://public.perforce.com:8080. Configuring Serena Version Manager (PVCS) Access

To configure access to PVCS version control system, fill in the following mandatory fields:

• Path to PVCS client (pcli)

• Repository

• Projects

• Password

• Branch label

• Promotion group

• Change window

The following fields are optional:

• User

• Password

• Branch label

• Promotion group

• Change window

The meaning of each field discussed below. Setting Parabuild Service User

All PVCS users must have the ability to read, write, create and erase files in the PVCS repository. Par- abuild runs as a service under Windows using LocalSystem user account, the same account that most other services use. This user may not have enough permissions to access PVCS repository on the network. You need to change the users that Parabuild service runs under to address the permission issue. To change the user, please follow the detailed description provided in the sectionChanging Parabuild service user. Path to PVCS client (pcli)

Path to pcli executable is a mandatory field. This field should be set to a fully qualified path to a PVCS command line client executable (pcli). The path should be wrapped in double quotes if it contains spaces.

Example 5.24. Path to sscm Executable

53 Configuring a Build

Unix:

/opt/pvcs/bin/pcli

Windows:

C:\pvcs\pcli.exe

Repository

Repository is a mandatory field and should contain a fully qualified path to PVCS repository. Projects

Projects is a mandatory field. It should be set to a fully qualified PVCS path to a project. Project path should conform notation for PVCS paths and begin with "/".

Example 5.25. PVCS Project

/projects/myproject_v_2_0

Parabuild supports multiple-path PVCS projects. For multiple path projects each path should be entered one per line.

Example 5.26. Multi-path PVCS Project

/projects/myproject_v_2_0

/projects/framework_v_1_1

All build scripts are executed with a project source line home as the current directory. The project source line home is the first line defined in the PVCS project path. For example, if PVCS project path is / projects/myproject_v_2_0 and the build script is stored in / projects/myproject_v_2_0/nmake file, the build command may look like NAnt all.clean

Considering the earlier example of a multi-path project, the Parabuild directory structure after receiving the project source lines may look like C:\parabuild\etc\build\b0co\ projects\myproject_v_2_0 C:\parabuild\etc\build\b0co\ projects\framework_v_1_1

User

PVCS user is an optional field. It may contain a name of a valid PVCS user that Parabuild will use to ac-

54 Configuring a Build

cess the PVC repository. The user should be allowed to access the PVCS repository beforehand. Password

PVCS password is an optional field. This field should be set if the user defined in the PVCS user field requires a password to access the PVCS repository. Branch Label

Branch label is an optional field. Use this field to enter a name of a branch label that Parabuild will use to access project code base. Promotion Group

Promotion group is an optional field. Use this field to enter a name of a promotion group that Parabuild will use to access project code base. Change Window

Parabuild maintains synthetic change lists for PVCS. The change list is a set of logically connected changes in multiple files. An example of a change list can be adding to PVCS a C++ class and a support- ing binary library that the class makes use of.

PVCS itself does not support change lists. If a logically connected group of files is checked in, and the process takes longer than a minute, it is possible that Parabuild might detect the presence of changes before all files make it to the PVCS repository and fire a build against an incomplete submission time stamp. To avoid this problem Parabuild uses "change window" for the advanced detection of the member files of a change list. The change window is the maximum time in seconds a check-in of a group of files may take.

Entering zero value in the change window field turns off the advanced detection of members of change lists that are taking a long time to process. Configuring StarTeam Access

To configure access to Borland StarTeam version control system, fill in the following mandatory fields:

• Path to stcmd executable

• Server address

• TCP/IP endpoint

• Encryption

• User

• Password

• End-of-line conversion

• Project path

The meaning of each field discussed below.

55 Configuring a Build

Path to stcmd Executable

Path to stcmd executable is a mandatory field. This field should be set to a fully qualified path to a StarTeam's command line client executable (stcmd). The path should be wrapped in double quotes if it contains spaces. StarTeam Server Address

StarTeam server address is a mandatory field. StarTeam server address should be set to a valid StarTeam server IP address or a DNS name. StarTeam TCP/IP Endpoint

StarTeam TCP/IP endpoint is a mandatory field. StarTeam TCP/IP endpoint should be set to a valid StarTeam server port number that the server is listening on. StarTeam User

StarTeam user is a mandatory field. It should contain a name of a valid StarTeam user that Parabuild will use to access the StarTeam server. The user should be allowed to access the StarTeam server beforehand. StarTeam Password

StarTeam password is an mandatory field. This field should be set to a valid password for the selected user. StarTeam End-of-line Conversion

StarTeam end-of-line conversion is a mandatory field. Select a desired end-of-line conversion for project's local copy. The default value is "On". StarTeam Project

StarTeam project is a mandatory field. Enter a fully qualified path to the project in this field. Configuring Subversion Access

To configure access to Subversion version control system, fill in the following mandatory fields:

• Path to Subversion client executable (svn)

• Subversion URL

• Subversion user

• Subversion password

• Depot path

• Repository browser

Meaning of each field discussed below.

56 Configuring a Build

Path To Subversion Client Executable

Path to the Subversion client executable is a mandatory field. This field should be set to a fully qualified path to a Subversion client executable. The path should be wrapped in double quotes if it contains spaces.

Example 5.27. Field Path to Subversion Executable

Unix:

/usr/bin/svn

Windows:

C:\Subversion\svn.exe

This field may contain a template with a parameter that is defined on a system, project, agent or build level.

Example 5.28. Path to Subversion Executable Using a Parameter

${SVN_EXE_PATH}

Subversion URL

Subversion URL is a mandatory field. This file should contain a URL pointing to a Subversion server and should correspond with the URL notation. Parabuild supports HTTP, HTTPS, SVN and FILE protocols to access Subversion servers.

Example 5.29. Subversion URL Field Using HTTP Protocol

http://subversion:3690

Example 5.30. Subversion URL Field using svn Protocol

svn://subversion:3690

Subversion User

Subversion user is a mandatory field. It should contain the name of a valid Subversion user that Par- abuild will use to access a Subversion server. Subversion Password

Subversion password is a mandatory field. It should contain a valid password of the Subversion user.

57 Configuring a Build

Subversion Repository Path

Repository path is a mandatory field. It defines the location of the home of the project source line and should begin with a slash.

Example 5.31. Single Line Subversion Repository Path

projects/myproject_20

Parabuild supports multiple-path projects. For multiple path projects each path should be entered one per line.

Example 5.32. Multi-path Subversion Repository Path

projects/myproject_20

3rdparty

All build scripts are executed with a project source line home as the current directory. The project source line home is the first line defined in the Subversion repository path. For example, if Subversion repository path is/projects/myproject_20, and the build script is stored in / projects/myproject_20/make file, the build command may look like make all.clean

Non-Recursive Repository Path

Parabuild supports non-recursive repository paths. To mark a path a non-recursive, add -N to the end of the Repository path.

Example 5.33. Non-Recursive Subversion Repository Path

projects/myproject_20 -N

projects/myproject_20/subpath

Watching Non-Recursive Repository Paths Recursively for Changes

By default, Parabuild ignores changes under a non-recursive repository path. Check box "Watch non- recursive paths recursively for changes" alters the default behaviour. When this box is checked, Par- abuild detects changes under the non-recursive paths. The check out is still performed non-recursively.

Repository Browser

Parabuild allows selecting ViewVC or Cenqua FishEye as a repository browser for Subversion. Par- abuild integrates with repository browsers by providing direct links to repository browser pages when displaying changes participated in a given build run. Configuration for repository browsers in discussed

58 Configuring a Build

in the following sections. Integration With ViewVC

Example 5.34. The Most Commonly Used Forms of ViewVC URLs

http://myviewvchost/viewcvs/ myproject / README?rev=6881&view=markup

http://myviewvchost/cgi-bin/viewcvs.cgi/ myproject/tags?rev=1033&view=log

http://myviewvchost/viewcvs.py/myprojectREADME?rev=6881&view=markup

Identify your base URL and enter in the ViewVC URL field. Integration With FishEye

Example 5.35. The Most Commonly Used Forms of FishEye URLs

http://myfisheyehost/fisheye/ myproject / README?rev=6881&view=markup

Identify your base URL and enter in the FishEye URL field. Configuring Surround Access

To configure access to Surround version control system, fill in the following mandatory fields:

• Path to sscm executable

• Surround server address

59 Configuring a Build

• Surround server port

• Surround user name

• Branch name

• Repository

The following fields are optional:

• Surround password

The meaning of each field discussed below. Path To sscm Executable

Path to sscm executable is a mandatory field. This field should be set to a fully qualified path to a Sur- round command line client executable. The path should be wrapped in double quotes if it contains spaces.

Example 5.36. Path to sscm Executable

Unix:

/opt/surround/bin/sscm

Windows:

C:\surround\sscm.exe

Surround Address

Surround address is a mandatory field. Surround address should be set to a Surround server address. Surround Port

Surround port is a mandatory field. Surround port should be set to a port a Surround server listens on. The default value is 4900. Surround User

Surround user is a mandatory field. It should contain a name of a valid Surround user that Parabuild will use to access the Surround server. The user should be allowed to access the Surround server beforehand. The user should be a part of a Surround group that has at least the following permission: Create Label, Generate Reports, View Repository List, View File History, View Branch History, Get File, Login Via CLI Client and View User. Surround Password

Surround password is an optional field. This field should be set if the user defined in the Surround user field requires a password to access the Surround server.

60 Configuring a Build

Branch Name

Branch name is an mandatory field. Use this field to enter a name of a branch that Parabuild will use to access project code base. Repository

Repository is an mandatory field. Use this field to enter a path the project home under Surround control. The repository should not have a leading slash character.

Example 5.37. Surround Repository

myproject/framewor/version2

Configuring Vault Access

To configure access to Vault version control system, fill in the following mandatory fields:

• Vault server

• Vault user name

• Vault password

• Vault repository

• Repository path

The following fields are optional:

• Connect using SSL

• Proxy server

• Proxy port

• Proxy user

• Proxy password

• Proxy domain

61 Configuring a Build

The meaning of each field discussed below. Vault Server

Entry type the name or the numeric IP address of the Vault server. This is not an URL. This is a mandatory field. Vault User name

Enter user name that will be used to access the server. This used must be an active vault user as defined in the Vault Admin tool. This is a mandatory field. Vault Password

Enter password of the user that will be used to access the server. Vault Repository

Enter vault repository. This is a mandatory field. Repository Path

Repository path is a mandatory field. It should be set to a fully qualified Vault path to a project home. Repository path should conform notation for Vault paths and begin with "$/".

Example 5.38. Vault Repository Path

$/projects/myproject_v_2_0

Parabuild supports multiple-path Vault projects. For multiple path projects each path should be entered one per line.

Example 5.39. Vault Repository Path for Multi-path Vault Project

$/projects/myproject_v_2_0

$/projects/framework_v_1_1

All build scripts are executed with a project source line home as the current directory. The project source line home is the first line defined in the Vault project path. For example, if Vault project path is $/projects/myproject_v_2_0 and the build script is stored in $/projects/myproject_v_2_0/nmake file, the build command may look like NAnt all.clean

Considering the earlier example of a multi-path project, the Parabuild directory structure after receiving the project source lines may look like C:\parabuild\etc\build\b0co\ projects\myproject_v_2_0

62 Configuring a Build

C:\parabuild\etc\build\b0co\ projects\framework_v_1_1

Proxy Server

Enter a name or a numerical IP address of a proxy server in this field. If Parabuild has to access Vault via proxy server. Proxy Port

Enter a port number of a proxy server if Parabuild has to access Vault via proxy server. Proxy User

Enter a user name that is going to be used to access proxy server in this field. Proxy Password

Enter a password of the user that is going to be used to access proxy server. Proxy Domain

Enter proxy domain name in this field. Configuring Visual SourceSafe Access

To configure access to Visual SourceSafe Access version control system, change the user that Parabuild service runs under, and fill in the following mandatory fields:

• VSS database path

• Project path

• User

• Password

• Path to VSS client (SS.EXE)

• Read-only checkout

Meaning of each field discussed below. Setting Parabuild Service User

All VSS users must have the ability to read, write, create and erase files in the VSS directory and all subdirectories. Parabuild runs as a service under Windows using LocalSystem user account, the same account that most other services use. This user may not have enough permissions to access VSS database on the network. You need to change the users that Parabuild service runs under to address the permission issue. To change the user, please follow the detailed description provided in the sectionChan- ging Parabuild service user. VSS Database Path

63 Configuring a Build

VSS database path is a mandatory field. VSS database path should be set to a fully qualified path to a directory containing VSS database.

Example 5.40. VSS database path

\\vss\database\data

Project Path

Project path is a mandatory field. It should be set to a fully qualified VSS path to a project home. Project path should conform notation for VSS paths and begin with "$" sign.

Example 5.41. VSS Project Path

$/projects/myproject_v_2_0

Parabuild supports multiple path VSS projects. For multiple path projects each path should be entered one per line.

Example 5.42. Multi-path VSS Project

$/projects/myproject_v_2_0

$/projects/framework_v_1_1

All build scripts are executed with a project source line home as the current directory. The project source line home is the first line defined in the VSS project path. For example, if VSS project path is $/projects/myproject_v_2_0 and the build script is stored in $/projects/myproject_v_2_0/nmake file, the build command may look like nmake all.clean

User

VSS user is a mandatory field. It should be set to a valid VSS user. Password

64 Configuring a Build

VSS password is a mandatory field. It should be set to a valid password for the user configured earlier. Path To VSS Client (SS.EXE)

Path to VSS client (SS.EXE) is a mandatory field. It should be set to a fully qualified path to the VSS command line client, SS.EXE. The path should be wrapped in double quotes if it contains spaces.

Example 5.43. Path to VSS Client

C:\VisualSourceSafe\SS.EXE

Example 5.44. Path to VSS Client With Spaces in It

"C:\Visual SourceSafe\SS.EXE"

Read-only Check Out

If box "Read-only checkout" is checked Parabuild will populate local copy with files having the read- only flag set. Limitations of Visual SourceSafe Labels

Though Parabuild supports labeling projects under VSS control, Parabuild generally cannot guarantee that a label placed on a source line will reflect the source line state at the build time. This limitation comes from the fact that Visual SourceSafe does not support multiple labels on the same revision of a file, though it is normal that a given revision needs to be labeled more than once (consider a nightly QA build that labels a project if the build run is successful).

Instead, Parabuild attempts to use the fact that VSS allows to create a "label" revision for a file. If labeling for a build that uses VSS is on, Parabuild will place a label immediately after the successful completion of a build run. Since there is a time window between start and finish of a build run, it is possible that there will be submissions within this window, and a label will be placed at the state of the source line which was not the one the build ran against in the first place.

We do not recommend enabling labeling with automatic (integration) builds for VSS projects. There is little point in that because of the issues discussed above. With scheduled builds that may need labeling, we recommend to set up schedules in which builds run at times when there is minimal or no VSS submission activity (night time may work well). Configuring Build Schedule

The build schedule is configured by modifying fields provided by the "Schedule Settings" panel. The content of the panel depends on the build type and is discussed in the following sections. Common Schedule Parameters

The following schedule parameters are present in both automatic and scheduled builds:

Clean checkout, builds Clean checkout if broken Clean checkout on agent change

65 Configuring a Build

Sticky agent

Meaning of each parameter is discussed below. Clean Checkout Counter

Field "Clean Checkout" defines the number of builds after that Parabuild will empty a directory that contains a build workspace and will perform a clean checkout. If "one" is entered in this field, Parabuild will perform the clean checkout before every build run. Set value of this field to zero to disable automatic emptying of the checkout directory. Performing Clean Checkout If Previous Build Was Broken

If the check box "Clean checkout if broken" is checked, Parabuild will perform a clean checkout if the previous build run failed. By default this check box is unchecked. Performing Clean Checkout on Agent Change

If the option "Clean checkout on agent change" is selected, Parabuild will perform a clean checkout every time an agent that the build is running on changes. To enable this option, check box "Clean checkout on agent change" under the build configuration tab. The check box is located on the schedule panel: Using Sticky Agents

If this option is selected, the build will try to keep running on the remote agent it has run initially. The build will move to another agent only if its current agent goes out of commission.

This option is especially useful for configurations where populating a build workspace takes significant time. Long-running incremental builds may also benefit from selecting this option because staying on the same agent allows to avoid running a full build.

To enable sticky build agents, check box "Sticky agent" under the build configuration tab. The check box is located on the schedule panel: Note

Selecting this option effectively disables load balancing for the build. Automatic Builds

Automatic builds are also known as integration builds. Parabuild initiates an automatic build at every check-in (or a series of check-ins) into the version control system. The following schedule configuration settings are available for automatic builds:

Field "Poll interval". Field "Cool-down interval". Field "Serialize this build".

Meaning of each settings is discussed below. Setting Poll Interval

Field "Poll interval" defines number of seconds Parabuild waits before repeating check for new changes in the version control system. Enabling Build Serialization

Checking box "Serialize this build" overrides a default system-wide setting for build serialization. If this

66 Configuring a Build

box is checked, this build will start on an agent that is not busy running other builds. Setting Cool-Down Interval

An optional field "Cool-down interval" may contain a time interval in seconds that Parabuild will use to issue additional requests for information about new changes from the version control system. A new build run will be fired only after there are no more changes detected within the given cool-down interval. If new changes are detected, Parabuild will wait for this interval again. To disable this feature set the cool-down interval to zero. The default value for this field is zero (cool-down is disabled).

The number of additional requests is limited to the value defined by the system-wide setting "Maximum cool-down attempts". This limit is used to avoid build not being fired continuously for active code bases. Important

"Cool-down interval" is an advanced setting. It should be used with caution and only if the default value is not suitable. This setting is available only when an advanced build configuration is enabled using the system settings page. We strongly recommend avoiding using this feature unless this is absolutely necessary and instead relying on atomic change lists provided by your version control system when supported. Perforce and Subversion support atomic changes lists out of the box. Parabuild provides synthetic atomic change lists for Surround SCM, Visual SourceSafe and CVS. Scheduled Builds

Parabuild runs scheduled builds at configured times. Scheduled builds can be used to run builds that are timed by their nature such as nightly, daily, or QA builds. The following schedule configuration settings are available for scheduled builds:

Check box "Run if there are no changes". Schedule table.

Meaning of each settings is discussed below. Running Build If No New Changes

If check box "Run if there are no changes" is checked, Parabuild run a build even if there are no new changes to the code base. Modifying Schedule Table

Schedule table defines when to run scheduled builds and may contain one or more rows. Each row consists of the following entry fields:

Hour - Enter an hour when to run a build in this field. The hour range is from 0 to 23. This is a mandatory field. Days of week- Enter days of week when to run a build in this field. This field may contain simple numbers ranging from 1 to 7 or may define a range. 1stands for Sunday, 2 stands for Monday, 3 stands for Tuesday, 4 stands for Wednesday, 5 stands for Thursday, 6 stands for Friday and 7 stands for Sat- urday. For instance, if this field contains "1-5" value, the build will run on 1,2,3,4 and 5 days of week. Alternatively, names of day of week can be used. The valid values areMON,TUE, WED,THU, FRI, SAT and SUN. Days of month - Enter days of month when to run a build in this field. This field may contain simple numbers ranging from 1 to 31 or may define a range or a list of days. For instance, if this field contains "5, 13, 20" value, the build will run on 5, 13, 20 days of a month. Leave this field blank if you don't want to limit running a build to particular days of month.

67 Configuring a Build

Configuring Build Labeling

If a build run was successful, Parabuild may label (tag) the code base defined by the version control settings for the build. To enable labeling (tagging), select "Custom" radio button in the "Build label" group and enter the label template in the custom template field. The custom label templates can contain alphanumeric characters and "_" (underscore). The templates should start with a word character. Currently the label templates support the following properties that are set accordingly during the build time:

build.name - will be replaced with the build name. build.number - will be replaced with the build number. build.date - will be replaced with the build date. build.timestamp - will be replaced with the build time stamp. changelist.number - will be replaced with the change list number the build run against. A synthetic change list number provided by Parabuild will be used if the build is configured with Surround, Visu- al SourceSave or CVS as version control systems. Build configurations backed by Perforce or Subver- sion will use native change list numbers.

The build.date property has "yyyyMMdd" format. The build.timestamp property has "yyyyMMddHHmmss" format.

Example 5.45. Composing Build Label Template

A label template using the properties may look like the following:

myproj_${build.name}_${build.number}_${build.timestamp}

The resulting label name created by Parabuild for a build named my_build and build number 154 may look like:

myproj_my_build_154_20040629124502

Configuring Dependent Build

If a build run was successful, Parabuild may start other build. To enable starting other build, select the build using selection list "Start build on success" in the "Dependent Build".

Figure 5.4. Configuring Dependent Build

Notification Settings Tab

When a build step finishes, Parabuild sends an e-mail notification about step results to users who performed check-ins into the version control system. Notification settings tab allows you to configure:

• Notification policy

• Mapping names of users of a version control system to e-mail.

• Setting default e-mail domain

• Notifying other users

68 Configuring a Build

Setting Notification Policy

Notifications policy settings control quantity of messages Parabuild sends to build run participants.

Check "Send failures only" box to limit sending messages regarding build failures only. If this box is not checked, Parabuild will send messages regarding starting build steps and build steps results, both successful and failed.

Check "Send failures only once" box to limit sending a message regarding a failed build step to new build run participants only. If the build is broken several times in a row, only new build participants will be receiving the failure message.

Check "Send start notice" box to allow Parabuild sending a message regarding starting a build step. If this box is not checked, the message regarding starting a build step will not be sent.

Check "Send start notice for first step only" to limit sending a message regarding starting a build step to the first step only.

Check "Send result for last step only" to limit sending a message regarding outcome of a build step to the last step only.

Check "Notify watchers only" box to limit sending messages to watchers and Parabuild administrator. Build run participants will not receive notification messages if this box is checked. Mapping Names of Users of a Version Control System to E-mail

Parabuild allows you to associate the name of a user in version control with an e-mail address. When a user submits changes to version control system, the user's name will be matched with the e-mail address. Parabuild will use this address to send a notification about build result. Use table "Version control user to e-mail map" to add e-mails associated with names of version control users. Using E-mails Provided by Version Control System

In addition to mapping names, Parabuild allows to use users' e-mail addresses directly from a version control system when available. Parabuild can retrieve e-mails of users from the following version control systems:

• Perforce

• CVS

To allow using e-mails from a version control system enter domain name and check " Use version control e-mails" check box.

Note: To use e-mails from CVS Parabuild, a user configured to access CVS should be allowed to readCVSROOT/users. Setting Default E-mail Domain

Setting default e-mail domain can be useful when names of users in a version control system mostly match the name part of their e-mail address and when they belong to the same company or domain -

69 Configuring a Build

then all you need to set up the notification part of the build configuration is to enter the default e-mail domain. Names of users that do not fit this can be explicitly mapped by filling the "version control user to e-mail map" table.

If names of users of a version control system are not explicitly mapped to e-mail addresses, Parabuild will use default e-mail domain to compose e-mail addresses. Parabuild will make a fully qualified address by appending "@" and the default e-mail domain to the user name of the user.

Example 5.46. Composing an e-mail address from user name and default e-mail domain

If the name of the version control user were "john", and the default domain were mycompany.com, the resulting e-mail would be [email protected].

Notifying Other Users

Adding Users to Build Watchers Table

Parabuild allows you to send the build results notifications to users other than those whose changes triggered a build. Users interested in receiving notifications may include:

• Members of an e-mail list that includes all members of engineering and/or QA teams.

• Build administrators

• Project mangers.

Use "Build watchers" table to add e-mail addresses of users to be notified about build results. Notifica- tion level defines content of the e-mail that will be sent.

Notification Levels

If "Build results only" level is set, Parabuild will send notification messages about successful and failed builds. This level is good for keeping engineers notified about current build statuses.

A broken build is always an emergency. "Broken builds only" level can be used to notify team leaders, project managers, and other interested parties about broken builds.

The "All" level suits the best needs of build administrators and release engineers who may need to react to the infrastructure problems and may want to be notified immediately if such problems occur. Such problems may include: unavailability of the version control or issue tracking systems, build configuration problems, etc. E-mail addresses that have the "All" level set will receive all messages sent by Par- abuild, including notifications about successful and failed builds, and e-mails about infrastructure problems or system errors.

Parabuild allows using names of Parabuild security groups as receivers of notifications messages. Understanding Relative Paths

Most of the custom log and build result configurations discussed in the following chapters use a notion of a relative path to describe location of a log file or a directory. A relative path is a path that is relative

70 Configuring a Build

to a build directory. A build directory is a directory that used by Parabuild as a current directory to execute the shell commands from the build configuration.

To find what an absolute path of the build directory is, add the command

echo %PARABUILD_BUILD_DIR%

for Windows or

echo $PARABUILD_BUILD_DIR

for Unix or Linux as the fist command in a build step field in the build sequence table. It will print the absolute path of the build directory in the main build step log. Build Logs Tab

Parabuild automatically stores console output of each build run in a log archive. The Build Logs Tab allows configuring compression of archived logs and adding custom build logs so that they are available for future browsing. Setting Up Build Logs Compression

To save disk space, Parabuild allows to set the number of days after that archived logs will be compressed. Log compression is a seamless operation. Compressed logs are available for browsing and searching. Access to logs that are not compressed can be faster.

The number of days mostly depends on concerns regarding the amount of free space on the disk drive. If the size of logs produced by each build run is small, we recommend using the default value of 30 days. If the size reaches megabytes, set the number to a lower value. The minimum value is one day.

Use "Compress build logs older than" field to set a number of days after that archived build logs should be compressed. Adding Custom Logs

Parabuild allows you to configure additional build logs so that they are available for future browsing. Parabuild supports standard log types and a number of tool-specific log types, including:

• Single text file logs

• Directories with text files

• Single HTML file logs

• Directories with HTML files

• JUnit XML reports

71 Configuring a Build

• Boost Unit Test Framework XML reports

• GoogleTest XML reports

• PMD XML reports

• Squish test XML reports

Use table "Custom logs" to configure additional build logs. Adding Single Text File Log

To configure a single text file log, select "Single text file" in the log type drop down and click on the "Add" button. Fill in the "Description" and "Log path" entry fields. The "Description" field should contain some text describing the log. "Log path" should contain a path to the log file in text format. The path should be relative to the project home. If the log file is found, Parabuild will store the log file in the archive and will make it available for browsing. Adding Directory with Text File Logs

To add a directory that contains logs in text format, select "Directory with text files" in the log type drop down and click on the "Add" button. Fill in the "Description", "Log path", and "Log file extensions" entry fields. The "Description" field should contain some text describing the log. "Log path" should contain a path to the directory that contains log files. The path should be relative to the project home. If the directory is found, Parabuild will store log files from this directory in the archive and will make the files available for browsing. Adding Directory with Boost Unit Test Framework Logs

To add a directory that contains logs in Boost Unit Test Framework XML format, select "Boost Test" in the log type drop down and click on the "Add" button. Fill in the entry fields "Description" and "Log path". The "Description" field should contain some text describing the log. "Log path" should contain a path to the directory that contains XML log files. The path should be relative to the project home. If the directory is found, Parabuild will store log files from this directory in its internal archive and will make the formatted log and test statistics available for browsing: Adding GoogleTest XML Log

To add a path to a log in GoogleTest XML format, select "GoogleTest" in the log type drop down and click on the "Add" button. Fill in the entry fields "Description" and "Log path". The "Description" field should contain some text describing the log. "Log path" should contain a path to the GoogleTest log file. The path should be relative to the project home. If the file is found, Parabuild will store the log file in its internal archive and will make the formatted log and test statistics available for browsing: Adding Single HTML File Log

To configure a single HTML file log, select "Single HTML file" in a log type drop down and click on "Add" button. Fill in the "Description" and "Log path" entry fields. The "Description" field should contain some text describing the log. "Log path" should contain a path to a log file in HTML format. The path should be a path relative to the project home. If the file is found, Parabuild will store the log file in the archive and will make it available for browsing. Adding HTML Directory Log

72 Configuring a Build

To add a directory that contains a set of HTML files that can be seen as a single log, select "Directory with HTML files" in the log type drop down and click on the "Add" button. Fill in the "Description", "Log path", and "Index file" entry fields. The "Description" field should contain some text describing the log. "Log path" should contain a path to the directory that contains log files. The path should be relative to the project home. The "Index file" should point to a "home" index file. The path to the index file is relative to the "home" log directory. If the directory and the index file are found, Parabuild will store the directory in the archive and will make the files available for browsing.

To understand the use of the "Log Path" and "Index file", consider this example of a file tree of a C++ project named "myproj20" after the completion of a build step. This project uses a tool that generates information about project test coverage in HTML format.

./myproj20/lib ./myproj20/src/startup.cpp ./myproj20/src/threadmon.cpp ./myproj20/src/util.cpp ...... /myproj20/temp/logs/test_coverage/coverage.html ./myproj20/temp/logs/test_coverage/src/startup.html ./myproj20/temp/logs/test_coverage/src/threadmon.html ./myproj20/temp/logs/test_coverage/src/util.html

In this case the HTML directory log path would be " temp/logs/test_coverage" and the index file path would be " coverage.html" Adding Generic Test Results

In addition to integrating with specialized testing tools such as JUnit, NUnit, Boost, CppUnit and others, Parabuild provides an ability to gather and report arbitrary test statistics. This ability is facilitated by the log type "Generic test result". To configure the generic test result, select "Generic test result" in a log type drop down and click on "Add" button. Fill in the "Description" and "Log path" entry fields. The "Description" field should contain some text describing the log. "Log path" should contain a path to a log file in the generic test result format. The path should be a path relative to the project home. If the file is found, Parabuild will record the test statistics in the archive and will make it available for browsing:

Example of the content of a file with the generic test result:

test.errors=50 test.failures=7 test.skips=0 test.successes=2034

In this example the log path would betemp/test/test-result.properties. Adding Squish XML Log

To add a path to a log in Squish XML format, select "Squish XML log" in the log type drop down and click on the "Add" button. Fill in the entry fields "Description" and "Log path". The "Description" field should contain some text describing the log. "Log path" should contain a path to the Squish log file in XML format. The path should be relative to the project home. If the file is found, Parabuild will store the log file in its internal archive and will make the formatted log and test statistics available for browsing:

73 Configuring a Build

Using Template Parameters in Log Path

Each log configuration allows using the following predefined, optional, template parameters in a path to the log. This allows accessing paths produced by the build that are dynamically created using build information such as a build number or a build date:

Table 5.1. Template Parameters for Log Path

Parameter Name Parameter Value build.date The date the build started, in YYYYMMDD format. build.id A unique build configuration ID. build.name The name of the build. build.number The number of the build. build.run.id The unique ID of the build. build.timestamp The date the build started, in yyyyMMddHHmmss format. changelist.number The number of the change list the build run against. step.name The name of the build step.

Example 5.47. Using Predefined Template Parameters in Log Path

test_logs_${build.timestamp}/junit_logs

In addition to the predefined parameters above, Parabuild allows using global, system-wide, parameters and parameters defined by the project, agent and build configurations.

Example 5.48. Using Global Template Parameters in Log Path

test_logs_${MY_LOG_PATH}/junit_logs

Build Results Tab

Parabuild allows to collect and archive results of a build run (build artifacts) for future download. "Build results" tab allows to configure various types of build results, including single files and directories. Con- figuring build results is optional.

If the configured results are found, Parabuild will put the results into the internal archive and display "Results" link both on the build list and on the detailed build view. Setting Up Automatic Deleting of Old Build Results

To save disk space, Parabuild allows to set the number of days after that archived build results will be deleted.

74 Configuring a Build

The number of days depends on balance of concerns regarding the amount of free space on the disk drive and need to access to past build results.

Use "Delete build results older than" field to set a number of days after that archived build results should be deleted.

Pinned builds results are not deleted.

Figure 5.5. Setting Cut-off Time for Old Build Results

Preventing Deleting of Too Many Results

Setting the cut off time in the form above to an accidentally small value could cause deleting of too many result from the build archive. To prevent this from happening, Parabuild provides a stability setting under the Administration menu that sets a global minimum result retention time:

Figure 5.6. Setting Global Minimum Result Retention Time

If the value entered in the build configuration cut off time is too low, Parabuild won't allow to save the changes to the build confirmation and issue a error message. Parabuild will also ignore already existing settings if they are lower than the global minimum. Configuring Single File Result

To configure a single file build result, select "Single file" in a result type drop down list and click on the "Add" button. Fill in the "Description" and "Result path" entry fields. The "Description" field should contain some text describing the result. "Result path" should contain a path to a result file. The path should be relative to the project home. If the file is found upon completing of the build run, Parabuild will store the file in the archive and will make it available for downloading. Configuring Directory Result

To add files in a directory, select "Directory" in the result type drop down list and click on the "Add" button. Fill in the "Description", "Result path" and "Result file extensions" fields. The "Description" field should contain a text describing the result. "Result path" should contain a path to the directory that contains result files. The path should be relative to the project home. File extensions should be separated by a comma or a space. If the directory is found, Parabuild will store files with given extensions from this directory in the archive and will make the files available for downloading. Configuring An External URL Result

Parabuild allows configuring a result that will be presented as a URL link on the build result pages. To add an external URL result, select "External URL" in the result type drop down list and click on the "Add" button. Fill in the "Description" and "URL template" fields. The "Description" field should contain a text describing the result. "URL template" should contain a template for the resulting URL. Ex- ample: http://myhost:8080/build_results/${build.name}_${changelist.number}. Parabuild will replace the template parameters with actual values at build time. Check "Test URL for availability" box if you want Parabuild to verify availability of the build result defined by the URL by establishing a connection to it.

75 Configuring a Build

Accessing Externally Stored Build Results

You may need to store and to provide access to, build results outside of archive of build results managed by Parabuild. We recommend the following approach to providing access to externally stored results from Parabuild:

1. Create and store build results on network-accessible media as a part of your build script;

2. Create and store a temporarily HTML file containing links to the build results;

3. Create a configuration for a HTML file log as described in section Adding a Single HTML File Log that points to the generated HTML file with the build results links. These links will be available for access on build logs pages provided by Parabuild;

4. Inform members of your team about availability of and location of the links to the externally stored build results on the Parabuild build logs pages.

These steps will allow you to maintain external build results storage of any complexity. Using Template Parameters in Result Path

Each result configuration allows using the following predefined, optional, template parameters in a path to the result. This allows accessing paths produced by the build that are dynamically created using build information such as a build number or a build date:

Table 5.2. Template Parameters for Result Path

Example 5.49. Using Template Parameter in Result Path

test_logs_${build.timestamp}/junit_logs

In addition to the predefined parameters above, Parabuild allows using global, system-wide, parameters and parameters defined by the project, agent and build configurations.

76 Configuring a Build

Example 5.50. Using Global Template Parameters in Log Path

test_logs_${MY_LOG_PATH}/junit_logs

Publishing Build Results Automatically

Parabuild provides a configuration parameter to publish a build result automatically to a previously created result group.

Figure 5.7. Selecting Result Group for Automatic Build Result Publishing

Ignoring Result Time Stamp

By default, Parabuild will not archive results produced by previous build runs. Parabuild identifies such results by comparing a time stamp of a result path to the current system time. Sometimes it is necessary to archive the result produced by the previous build runs as a result produced by the current build run. Check box "Ignore time stamp" to enable archiving the results produced by the previous build runs.

Figure 5.8. Ignoring Result Time Stamp

Reporting Results of Parallel Builds On Leader Result Page

Parabuild has an option to report to report results of a parallel build on build leader's result page. This allows for quick access to results of the parallel build without switching between builds.

Figure 5.9. Reporting Results of Parallel Builds On Leader Result Page

Debugging Build Result Path

The only challenge when configuring results is providing a correct path to build results. The simplest way to find out if the path is correct is to add a command that lists content of a directory containing results as the last build step command:

Windows: dir ./path/used/to/configure/results *nix: ls -al .\path\used\to\configure\results

77 Configuring a Build

Release Notes Tab

Release notes is a list of fixed or closed issues, bugs and implemented requirements that are included in a build run. Parabuild supports collecting release notes from the following issue tracking systems:

• Perforce jobs

• Bugzilla

• Jira

Release notes are available for scheduled builds only. Release notes are configured by selecting "Re- lease notes" tab and adding a corresponding configuration for a selected issue tracking system. Linking Release Notes And Changes

Parabuild supports linking release notes and change lists to allow for tracking of what changes are made as a part of work on an issue. After Parabuild links change lists to issues, the linked change lists number are shown on the build run's "Release notes" page. Details of each issue and associated change lists are also available. Linking Perforce Jobs And Change Lists

Linking of Perforce jobs and change lists is performed automatically when "Perforce jobs" release notes handler is configured.

Figure 5.10. Configuring Perforce Jobs

Linking Using Change List Description Content

Linking of change lists and release notes collected from Bugzilla and JIRA is done by extracting issue keys from change list descriptors by using regular expressions. To be able to configure linking you should understand regular expressions in general and capturing groups in particular. Detailed discussion on regular expressions is outside of the scope of this manual. If needed, please refer extensive regular expressions resources available on the Internet.

To enable linking for JIRA and Bugzilla configurations, fill the multi-line entry filed "Change to issue link patterns". This field should contain a single regular expression per line. These regular expressions will be used to find and to extract issue keys from change lists descriptions. Each regular expression should contain one or more capturing group. Each capturing group should capture an issue key in a format that exactly corresponds the format used by the issue tracker that linking is configured for. Tip

For linking to be effective, your team should develop and agree on a simple, unambiguous standard of a format of how issue keys are mentioned in change list descriptors. Having this standard in place will allow capturing issue keys using regular expressions entered in the "Change to issue link patterns" field. Examples of such a standard can be statements such as these: "Change list containing a fix to a Bugzilla bug should contain a line "Fixed Bugzilla bug #" or "Change list implementing a change request should contain a line "Implemen- ted JIRA -".

78 Configuring a Build

Below you can find examples of regular expression that you can use in configuring linking based on change list descriptions:

Bugzilla[a-zA-Z\s]*#([0-9]+) will extract Bugzilla bug identifiers "5555" and "7777" from change list descriptions such as "Starting working on Bugzilla #5555" and "Refactoring: moved method; fixed bugzilla bug #7777", accordingly. JIRA[a-zA-Z\s]* ([a-zA-Z]-[0-9]+) will extract Jira issue keys "MYPROJ-5555", "MYPROJ-7777" and "MYPROJ-1234" from change list descriptions such as "Closed JIRA MYPROJ-5555", "Fixed JIRA MYPROJ-7777 and started working on JIRA MYPROJ-1234", accordingly. Retrieving Release Notes From Bugzilla

Parabuild retrieves release notes from Bugzilla using direct access to a Bugzilla database hosted by a MySQL server.

A MySQL driver has to be installed before configuring Bugzilla as a source of release notes. To install the driver please follow these steps:

1. Go to http://dev.mysql.com/downloads/connector/j/3.1.html

2. Download a binary distribution for MySQL Connector/J. Versions available as of this writing are mysql-connector-java-3.1.13.tar.gz andmysql-connect- or-java-3.1.13.zip.

3. Untar/unzip file mysql-connector-java-3.1.13-bin.jar to /lib/common/lib

4. Restart your Parabuild instance

To add Bugzilla as a source of release notes, select "Bugzilla - direct connection" using a drop-down list of available issue tackers and click on "Add" button. A Bugzilla configuration panel will be added to the "Release notes" tab. Fill required and optional entry fields to complete configuration. Meaning of each entry field on the panel is discussed below.

Figure 5.11. Configuring Bugzilla Integration

Bugzilla MySQL Host

"Bugzilla MySQL host" entry field contains a DNS name or an IP address of a MySQL server hosting the Bugzilla database. This is a mandatory field. Bugzilla MySQL Port

"Bugzilla MySQL port" entry field contains a port number of a MySQL server hosting the Bugzilla database. This is a mandatory field. Bugzilla MySQL Database

"Bugzilla MySQL database" entry field contains a name of the Bugzilla database. This is a mandatory field. Bugzilla MySQL User

79 Configuring a Build

"Bugzilla MySQL user" entry field contains a name of a user authorised to access the Bugzilla database. This is a mandatory field. Bugzilla MySQL Password

"Bugzilla MySQL password" entry field contains a password of a user authorised to access the Bugzilla database. This is a mandatory field. Bugzilla Product

"Bugzilla product" entry field contains a name of a product that release noted will be collected for. This is a mandatory field. Version

"Version" entry field contains a version a product that release noted will be collected for. This is an optional field. If the version is not set, release notes will be requested for all versions of the product. Issue Filter

"Issue filter" entry field contains a string that is used to decide if a bug should be included into release notes. Parabuild will search a summary of a bug for this string and will include the bug into release notes if the string is found. This is an optional field. Filtering is not performed if the filter is not set. Bug URL Template

"Bug URL template" entry field may contain an optional URL template that Parabuild will use to create HTML links on its release notes pages to point to Bugzilla Web UI for quick access to bug details. The template can use a single ${bug.id} template parameter.

Example 5.51. Bugzilla Bug URL Template

http://bugzilla/track/show_bug.cgi?id=${bug.id}

Parameters Tab

"Parameters" tab allows you to configure parameters that will be passed to your build scripts as shell variables. It is also possible to define a counter and a template that may be used to generate a string containing product version. Version Counter

Parabuild can keep track of a counter that may be used to form a string containing a product version. Version strings generated by Parabuild the are unique for the given build configuration. Parallel builds use product version generated by a leading build. The following entry fields and controls are available to support the version counter:

• Check box "Enable version counter"

• Entry field "Version template"

80 Configuring a Build

• Drop down "Version counter increment"

• Check box "Increment if broken"

Meaning of each input control is discussed below. Enable Version Counter

Check the box "Enable version counter" to enable support for a version counter for this build configuration. If the version counter is enabled Parabuild will increment version counter automatically or using input when a build is started. Version Template

Entry field "Version template" allows you entering a template that Parabuild will use to form a version string. The following template parameters are supported:

• build.name - contains build name.

• version.counter - contains value of the version counter.

• build.number- contains build number.

Example: MyProduct 2.5.${version.counter}.${build.number} Version Counter Increment

Use drop down "Version counter increment" to select either a manual or automatic increment mode for the version counter. If the manual mode is selected Parabuild will not increment the counter. You will have to enter the counter value manually when a build start is requested. If the automatic mode is selected Parabuild will increment the version counter automatically or will use a value that was entered manually when a build start is requested. Increment If Broken

By default Parabuild will not store the incremented version counter if a build run was broken. Check this box to enable storing the incremented version counter without regard to outcome of the build run. Showing Perforce Parameters

A build of a manual schedule type that has Perforce as a version control system can be set up to show Perforce change list number and Perforce client view on a build start page. To enable showing Perforce parameters check box "Show Perforce Parameters". If enabled, it allows to set Perforce change list number and Perforce client view at build start. If these parameter are not set explicitly, a manual build will run again the latest change for the Perforce client view that is configured for the build. Build Instructions

This feature provides an ability to enter detailed instructions for a particular build on the launch screen for users to read before kicking off a build. Text box "Build Instructions" can be configured to display information related to how a particular build should be run. Entry filed "Build Instructions URL" may contain a link from the launch screen to information that can be provided via a pop-up window or to a screen from an internal wiki page. This makes it easier for developers to understand how each build

81 Configuring a Build

should be run. Displaying build instructions section is enabled on the User Interface Settings by checking box "Show build instructions":

When the build instructions section is enabled, Parabuild will show the entry field on under the Build Parameters tab that can be user to enter the build instructions:

The build instructions will appear on the manual start page: Parameters

Table "Parameters" contains a list of definitions of parameters that will be passed to your build scripts when a build is started manually. Each table row contains the following entry fields and controls:

• Entry field "Variable name" should contain a name of a shell variable that will be passed to the build script.

• Entry field "Description" should contain a free-form description of the parameter.

• Drop down "Type" contains a list of possible ways of how a variable is presented to a user requesting a manual build start. This list includes the following options: "Check list", "Radio list", "Drop down list" and "Single value".

• Entry field "Values" contains a list of allowed values for the given parameter.

• Check box "Required" marks a required parameter.

If box "Use first value as default" is checked, a parameter is passed to a build that is started automatically, too. The value of the parameter will be the first value from the list of allowed values. Default Parameter Value

A parameter can have a default value. If box "Use first value as default" is checked, the default values are be passed to the build script. This allows passing parameters to a build that is started either manually or automatically. Parameters are not passed to automatic builds if using the first value as default is not enabled.

Figure 5.12. Enabling Using First Parameter Value as Default

82 Chapter 6. Managing Build Results

Parabuild allows publishing build results so that they are available to users according to their access right. Published build results are accessible through the short-cut link "Results" on the top navigation bar on Web UI.

This feature is useful when a build administrator wants to make build results easily accessible so that users don't have to go through the list of past build runs to find a particular build result. Members of the Quality Control group are often users of this feature. Managing Build Result Groups

Published build results are organized into build result groups. To access the list of build result groups click on link "Results". The page with a list of build result groups will appear. Managing build result groups is described in the following sections. Adding A Build Result Group

To add a build result group click on link "Add new result group". An entry form for a new build result group will appear. Fill mandatory fields "Result group name" and "Description" and click on button "Save". Editing A Build Result Group

To edit a build result group click on link "Edit" that corresponds the build result group you would like to change. An entry form for the existing build result group will appear. Modify fields "Result group name" and "Description" and click on button "Save". Deleting A Build Result Group

To delete a build result group click on link "Delete" that corresponds the build result group you would like to delete. Parabuild will delete this result group after receiving a confirmation. Publishing Build Results

Once build result groups are created it is possible to publish build results. Go to a page containing build results for a particular build run and click on "Edit results". Check boxes for results that you would like to publish, select the build result group that selected results should be published to, fill an optional field "Comment" and click on button "Save".

83 Chapter 7. Managing Users And Groups

Parabuild offers group-based security for restricted access to build statuses and results. Each user may belong to zero or more groups. Each group may have zero or more builds. A user has a read access to status and results of a particular build if the user belongs to a group that has the given build associated with the group.

Only the build administrator has the right to create, read, update and delete system settings and build configurations, manage users, and perform other administrative tasks as forceful stopping and starting builds. Simplified Security Mode

If a software organization is not interested in restricting read access to build statuses and results, which is usually the case, Parabuild will provide a built-in "Anonymous" group to allow for a simplified security mode. The simplified security mode helps avoid administration overhead associated with user management. If a build belongs to the "Anonymous" group, users may access build status and build results without logging in into Parabuild by providing a user name and a password.

The "Anonymous" group should be enabled explicitly. To enable the "Anonymous" group, go to System Settings page and check the "Enable Anonymous group" box. Note

When the "Anonymous" group is enabled, new build configurations are automatically added to the group. Adding a User

To add a user, click on the "Administration" menu link on the Parabuild top navigation bar. Click on the "Users" link under the "User Management" section to display a table containing a user list. Click on link "Add User". A new user form will be displayed. Fill in the required fields and click the "Save" button. To cancel the modifications click the "Cancel" button. The meaning of each field in the form is described below. Login Name

User's full name may include first and last names. This is a mandatory field. Login Password

Enter in this field a password that you will use to log into Parabuild. This is a mandatory field when creating a new user. Retype Password

84 Managing Users And Groups

Enter the same password that was entered in the "Login password" field. E-Mail

User's e-mail address is a mandatory field. It should contain a valid e-mail address of the user. Admin User

Checking this flag gives a user administrator privileges. A user with administrator privileges can do everything the admin user can do except deleting the admin user.

Figure 7.1. Enabling Using Change List Numbers as Build Numbers

Instant Messaging

If the user would like to receive instant messaging notifications about build events, select the corresponding instant messenger type. Instant Messaging Address

Enter user's instant messaging address in this field. The address should correspond with the selected messenger type. Notify About

Use the corresponding check boxes to select the types of notification to be sent to the user's instant messaging address. Accessibility Setting Build Status Refresh Rate

Build status refresh rate defines how often the build status page is refreshed. The refresh rate is measured in seconds. Setting Successful Build Color

Entry field "Successful build color" allows setting a color that Parabuild uses to mark successful builds. This field accepts a six-digit hexadecimal number in RGB format. The default value is 006400 (dark green). Setting Failed Build Color

Entry field "Failed build color" allows setting a color that Parabuild uses to mark failed builds. This field accepts a six-digit hexadecimal number in RGB format. The default value is 8b0000 (dark red). Selecting Default Display Group

Drop down list "Default display group" allows selecting a display group that Parabuild will take a user to upon user log in. By default Parabuild will show all build statuses.

85 Managing Users And Groups

Figure 7.2. Selecting Default Display Group

User Belongs to Group(s)

Select corresponding check boxes to add the user to a group. Modifying a User

To modify a user, click on the "Administration" menu link on the Parabuild top navigation bar. Click on the "Users" link under "Security" section to display a table containing the user list. Click on the "Edit" link located in the row that corresponds to the user you intend to edit. A user edit form will be displayed. Fill in the required fields and click the "Save" button. To cancel the modifications click on the "Cancel" button. The meaning of each field in the form is described in the Adding a User section. Deleting a User

To delete a user, click on "Administration" menu link on the Parabuild top navigation bar. Click on the "Users" link under the "Security" section to display a table containing user list. Click on the "Delete" link located in the row that corresponds to the user you intend to delete. The user will be deleted after the confirmation of the delete request. Adding a Group

To add a group, click on the "Administration" menu link on the Parabuild top navigation bar. Click on the "Groups" link under the "Security" section to display a table containing a list of groups. Click on the link "Add Group" link. A new group form will be displayed. Fill in the required fields and click the "Save" button. To cancel the modifications click the "Cancel" button. The meaning of each field in the form is described below. Group Name

Enter a short group name. This is a mandatory field Group Description

Enter an extended group description. This is a mandatory field. Allowed to Access Builds

This fields presents a list of builds that members of this group may access. Select the corresponding check boxes to add the build to the group. Rights

This fields presents a list of permissions that members of this group have. The permissions are "Activate build", "Edit build", "Start build" and "Stop build". Use this permissions to allow members of the group to edit configurations of build included into the groups, activate and deactivate builds, and start or stop builds. Select the corresponding check boxes to add the rights to the group.

86 Managing Users And Groups

Note

"Activate build" right implies a right to deactivate a build. "Start build" right implies a right to request Parabuild to do a clean checkout for the next build run. "Stop build" implies a right to resume a stopped build. Modifying a Group

To modify a group, click on "Administration" menu link on Parabuild top navigation bar. Click on the "Groups" link under the "Security" section to display a table containing a list of groups. Click on the "Edit" link located in a row that corresponds to the group you intend to edit. A group edit form will be displayed. Fill in the required fields and click the "Save" button. To cancel the modifications click on the "Cancel" button. The meaning of each field in the form is described in the Adding a Group section. Deleting a Group

To delete a group, click on "Administration" menu link on Parabuild top navigation bar. Click on the "Groups" link under the "Security" section to display a table containing a list of groups. Click on the "De- lete" link located in a row that corresponds to the group you intend to delete. The group will be deleted after the confirmation of the delete request.

87 Chapter 8. Managing Builds

Parabuild provides an extensive set of commands to manage configured builds. The command list is accessible to a build administrator from build status pages and from build result pages. Each command is presented as a link on the command list page. To execute a command click on the corresponding link. The meaning of each command is discussed in the following sections. Runtime Commands

Runtime commands control build behaviour at run time. The following commands are available:

• Stop

• Stop a group

• Resume

• Resume a group

• Start

• Deactivate

• Activate

• Clean checkout

• Re-run

Stopping Build

"Stop" command will stop the build if it is running. The build will enter a paused state. In the paused state an automatic build is not watching a version control for changes and a scheduled build does not start according to its schedule. The build still can be requested to start using "Start" command. A build in the paused state will not automatically resume its operation after server re-start. Paused build are visible to users who are not build administrators. Stopping Group

"Stop a group" command allows to stop a group of builds at once: The stopped builds will enter a paused state. In the paused state an automatic build is not watching a version control for changes and a scheduled build does not start according to its schedule. The build still can be request to start using "Start" command. A build in the paused state will automatically resume its operation after server re-start. Paused build are visible to users who are not build administrators. Resuming Build

"Resume" command will resume a previously paused build. After being resumed an automatic build is watching a version control for changes and a scheduled build starts according to its schedule. Resuming Group

88 Managing Builds

"Resume a group" command will resume a group previously paused builds. After being resumed an automatic build is watching a version control for changes and a scheduled build starts according to its schedule. Stopping and resuming a group of builds is also available from that page that displays statuses of builds attached to a particular build agent: Starting Build

"Start" command requests a build to start without regard to the presence of new changes or a build schedule.

After clicking in the "Start" link Parabuild will present a page with a build start form. The build start form allows entering manual configuration parameters according to the build configuration. It also allows entering a note for this build run, entering a optional label (tag) to apply to the code base and select if the build results should be pinned. Pinned build results are preserved when a clean up of the build archive is performed. If generating of product version is configured, Parabuild will allow entering or adjusting the version counter. After entering the build run parameters click on "Start" button to start the build.

A user that started a build will receive a notification about build results even if her changes are not present in this build. Running Build Against Perforce Change List Number Or Label

Fill field "Change list number or label" to run a manual build against an arbitrary Perforce change list number or a label:

Figure 8.1. Entering Perforce Change List Number for Manual Build

Starting Build Immediately After Saving Build Configuration

Often changes to a build configuration require starting the build to make use of the changes. Now it is possible to start the build immediately after saving it:

Figure 8.2. Starting Build Immediately After Saving Build Configuration

Deactivating Build

"Deactivate" command will move the build into an inactive state. It will stop the build if it is running. The build will enter an inactive state. In the inactive state an automatic build is not watching a version control for changes and a scheduled build does not start according to its schedule. The build still can be requested to start using "Start" command. A build in the inactive state will not automatically resume its operation after restarting Parabuild. Inactive builds are not visible to users who are not build administrators. Activating Build

"Activate" command will resume a previously de-activated build. After being resumed an automatic build is watching a version control for changes and a scheduled build starts according to its schedule.

89 Managing Builds

Requesting Clean Checkout

"Clean checkout" command request Parabuild to delete and to re-populate the current working copy when the build starts next time. Re-Running Build

"Re-run" command allows re-running an arbitrary build. After clicking on the "Re-run" link Parabuild will present a page with a form requesting to enter the build number that should be re-run. Fill the build number and click on "Load parameters" button. Modify or fill the build run parameters as described in section Start Command and click on "Start" button to start the build. Configuration Commands

Configuration commands are used to for managing build configurations. The following commands are available:

• Edit

• Copy

• Delete

• Change schedule type

The meaning of each command is decided in the following sections. Editing Build Configuration

Clicking on "Edit" link will open an entry form with this build configuration. Configuring a build is discussed in sectionDetailed Build Configuration. Copying Build Configuration

"Copy" command provides a convenient way to quickly create a build configuration that closely re- sembles the current build configuration. You may find this command very useful when setting up build management for existing and new branches of your product code line.

After clicking on the "Copy" link Parabuild will create an inactive copy of this build configuration and assign it an arbitrary name. After creating the copy Parabuild will show a page with options to edit or to active the new created build configuration. Viewtier recommends proceeding to editing the configuration and adjusting the build name and other parameter that are different from the original build configuration. Deleting Build Configuration

"Delete" command will stop the build and delete this build configuration. Build logs an results are still accessible through the search function. Changing Schedule Type

"Change schedule type" command allows to change the build schedule from manual to automatic and from automatic to manual. To change the schedule, visit build's link "Commands". Parabuild will show a

90 Managing Builds

page with a list of commands. Click on the link "Change schedule type":

Parabuild will show a form for requesting the schedule change. Click on "Convert" button. Parabuild will change the schedule type and return to the list of build's commands: Miscellaneous Commands

Section "Miscellaneous commands" provides a list of commands that don't fit into any other category. This list includes "Diff" command. Diff Command

"Diff" command allows to enumerate changes between to arbitrary build numbers. Clicking on "Diff" link will open an entry form. Fill fields "From build" and "To build" and click in "OK" button to what changes have been recorded by Parabuild between these two build runs. Maintenance Commands

Maintenance commands are used for management of the build archive. The following command are available:

• Cleanup logs

• Cleanup results

Cleanup Logs Command

Over time various build logs that Parabuild stored in its log archive may occupy significant disk space. "Cleanup up logs" command allows deleting logs that are older then a given number of days from the archive permanently. Fill field "Permanently delete build logs older than, days" and click on "Delete" button. After confirming the deletion Parabuild will delete the logs. Note

Build logs may contain valuable information about past builds. Viewtier recommends using high-volume hard drives to host Parabuild instead of deleting build logs. Cleanup Results Command

Over time build results that Parabuild stored in its results archive may occupy significant disk space. "Cleanup up results" command allows deletions results that are older then a given number of days from the archive permanently. Fill field "Permanently delete build results older than, days" and click on "De- lete" button. After confirming the deletion Parabuild will delete the results. Parabuild will not delete pinned build results. Pinning build results is performed at build start time as described in sectionStart Command. Note

Build results stored in Parabuild archive may contain valuable product information. Viewtier recommends using high-volume hard drives to host Parabuild instead of deleting build results.

91 Managing Builds

Maintenance Commands

Maintenance commands are used for management of the build archive. The following command are available:

• Cleanup logs

• Cleanup results

Cleanup Logs Command

Build logs may contain valuable information about past builds. Viewtier recommends using high-volume hard drives to host Parabuild instead of deleting build logs. Cleanup Results Command

Build results stored in Parabuild archive may contain valuable product information. Viewtier recommends using high-volume hard drives to host Parabuild instead of deleting build results.

92 Chapter 9. Managing Build Results

Parabuild collects build results according to the build configuration. Build results can be published to a result group. Publishing Build Results

An administrator may make results of a build run to be downloadable through the top navigation menu. Access to the published build results is controlled by server's security:

Figure 9.1. Accessing Published Build Results

Once a result group is defined, it is possible to publish build results right off the build results page. Also, new build results page allows deleting selected build results. To publish a build result, check a box corresponding the selected result, select the result group and click on "Save" button. Provide an optional comment for this action by filling "Comment" field:

Figure 9.2. Publishing Build Results

Pinning Build Results At Publish Time

It is possible to pin a build result at the time the result is published. A pinned build result is protected from being deleted as a part of a clean up operation. To pin the build result check box "Pin result":

Figure 9.3. Pinning Build Result At Publish Time

93 Chapter 10. Configuring Remote Builds

A build can be run by a Parabuild server itself or by a build farm that consists of a cluster of Parabuild instances running in a remote agent mode. Parabuild allows to change the build farm that a build is assingned to with a single click of a mouse. Parabuild running in the remote agent mode should be installed on the new agent host beforehand. Please refer to Installation Guide for details on installing Par- abuild in the remote agent mode.

In order to change the build farm a build is attached to, login to Parabuild as admin and select "Edit" command for the build you would like to modify. The build configuration screen will appear. The drop down field "Build farm" defines what build farm the build is assigned to. Change "Build farm" field to the desired build farm and click on the "Save" button. Parabuild will run the build in the new build farm. The change is effective immediately: Startup Procedure for Build Manager and Re- mote Agents

To start up the whole build infrastructure that uses remote agents, first start the remote agents and then start the build manager. Shutdown Procedure for Build Manager and Remote Agents

To shutdown the whole build infrastructure that uses remote agents, first shutdown the build manager and then shutdown the remote agents.

94 Chapter 11. Viewing System Errors

To see a log of system errors, click on the "Errors" link on the top navigation bar. This link is visible to administrators and users for that an option "View system errors" is turned on. The log consists of a table that shows time an error occurred, error severity, an optional build name and an agent and a brief error description:

To see error details click on the link for error time or the error description.

95 Chapter 12. Build Script Environment Variables

Parabuild provides a set of environment variables available to build scripts. Build scripts may use the environment variables for many purposes. For instance, build scripts can use environment variable PAR- ABUILD_BUILD_NUMBER to compose a name of resulting build package. Note

Parabuild may add shell variables that are not documented in the following sections. Presence and content of such variables are not guaranteed. Your build scripts should not rely on the undocumented shell variables. PARABUILD_BUILD_DATE

Environment variable PARABUILD_BUILD_DATE holds value of a date a build run started on. PAR- ABUILD_BUILD_DATE has "yyyyMMdd" format. PARABUILD_BUILD_DIR

Environment variable PARABUILD_BUILD_DIR holds a full path to the directory where build step commands are called in. PARABUILD_BUILD_NAME

Environment variable PARABUILD_BUILD_NAME holds a name of a build running. PARABUILD_BUILD_ID

Environment variable PARABUILD_BUILD_ID holds a unique ID of the configuration of the running build. PARABUILD_BUILD_NUMBER

Environment variable PARABUILD_BUILD_NUMBER holds value of a sequential build run number. PARABUILD_BUILD_RUN_ID

Environment variable PARABUILD_BUILD_RUN_ID holds a unique system-wide ID assigned to this build run. PARABUILD_BUILD_STARTED_BY_USER

Environment variable PARABUILD_BUILD_STARTED_BY_USER holds value of a name of a user who stated this build. If the build was started automatically this variable will contain value "system". PARABUILD_BUILD_TIMESTAMP

96 Build Script Environment Variables

Environment variable PARABUILD_BUILD_TIMESTAMP holds value of a date and time a build run started at. PARABUILD_BUILD_TIMESTAMP has "yyyyMMddHHmmss" format. PARABUILD_CHANGE_LIST_NUMBER

Environment variable PARABUILD_CHANGE_LIST_NUMBER holds value of a last change list that made to this build run. PARABUILD_CLEAN_CHECKOUT

Environment variable PARABUILD_CLEAN_CHECKOUT holds value "true" if a clean checkout was performed before starting this build. This environment variable is available to all steps of the build. This environment variable is not set if a clean check out was not performed PARABUILD_CHECKOUT_DIR

Environment variable PARABUILD_CHECKOUT_DIR holds a name of a working directory that parabuild uses to check out the code base. Each build configuration uses its own checkout directory. PARABUILD_LAST_GOOD_BUILD_NUMBER

If a last successful build is present, the environment variable PAR- ABUILD_LAST_GOOD_BUILD_NUMBER holds the number of the last successful build. PARABUILD_LAST_GOOD_BUILD_DATETIME

If a last successful build is present, the environment variable PAR- ABUILD_LAST_GOOD_BUILD_DATETIME contains a string representation of the time that the last successful build started at in "yyyyMMddHHmmss" format. PAR- ABUILD_LAST_GOOD_CHANGE_LIST_NUMBE R

If a last successful build is present, the environment variable PAR- ABUILD_LAST_GOOD_CHANGE_LIST_NUMBER holds a number of a last change list that made to the last successful build run PAR- ABUILD_LAST_GOOD_CHANGE_LIST_DATETI ME

If a last successful build is present, the environment variable PAR- ABUILD_LAST_GOOD_CHANGE_LIST_DATETIME contains a string representation of a last change list that made to the last successful build run in "yyyyMMddHHmmss" format.

97 Build Script Environment Variables

PAR- ABUILD_PREVIOUS_CHANGE_LIST_NUMBER

If a previous build is present, the environment variable PAR- ABUILD_PREVIOUS_CHANGE_LIST_NUMBER holds value of a last change list that made to the previous build run. This variable can be used to calculate changes between the current and the previous builds. PAR- ABUILD_PREVIOUS_CHANGE_LIST_DATETIM E

If a previous build is present, the environment variable PAR- ABUILD_PREVIOUS_CHANGE_LIST_DATETIME contains a string representation of the change list time stamp in "yyyyMMddHHmmss" format. PARABUILD_PROJECT_ID

The environment variable PARABUILD_PROJECT_ID contains a unique ID of a project that the build belongs to. PARABUILD_PROJECT_NAME

The environment variable PARABUILD_PROJECT_NAME contains a unique name of a project that the build belongs to. PARABUILD_STEP_NAME

Environment variable PARABUILD_STEP_NAME holds a name of a step running. PARABUILD_PREVIOUS_STEPS

Environment variable PARABUILD_PREVIOUS_STEPS holds a list of names of previous steps and their results.

Example 12.1. Example of PARABUILD_PREVIOUS_STEPS Value

BUILD:SUCCESSFUL;TEST:BROKEN

PARABUILD_VERSION

Optional environment variable PARABUILD_VERSION holds value of version if it was generated.

98 Build Script Environment Variables

PARABUILD_SEQUENCE_NUMBER

This environment variable holds an unique, low-value number. The number can be used by build configurations that are used to run server-side tests to generate non-conflicting port numbers for test services. Environment Variables for Perforce Builds

The following environment variables are always available to build scripts running as a part of build configurations using Perforce as a version control system: PARABUILD_P4CLIENT, PAR- ABUILD_P4PASSWD, PARABUILD_P4PORT and PARABUILD_P4USER. These variables can be used by build scripts to perform read-only operations using the client spec that Parabuild created for the build run.

Parabuild may also set and make available to the build scripts shell variables P4CLIENT, P4PASSWD, P4PORT and P4USER if explicitly asked to do so. If these variable are already available to the environment used to start Parabuild, the variables will be overridden. To make P4CLIENT, P4PASSWD, P4PORT and P4USER available to your build scripts, check the "P4 variables override" box in the "P4 Settings" panel under the "Build configuration" tab. By default the box is not checked and the variables are not set. Variable P4PASSWD is not set if authentication mode p4 login is used.

Please refer to Perforce documentation for detailed discussion of the shell variables P4CLIENT, P4PASSWD, P4PORT and P4USER. PARABUILD_P4CLIENT

Environment variable PARABUILD_P4CLIENT holds the same value as P4CLIENT that Parabuild used to access the code base being built. PARABUILD_P4PASSWD

Environment variable PARABUILD_P4PASSWD holds the same value as P4PASSWD that Parabuild used to access the code base being built. This variable is not set if authentication mode p4 login is used. PARABUILD_P4PORT

Environment variable PARABUILD_P4PORT holds the same value as P4PORT that Parabuild used to access the code base being built. PARABUILD_P4USER

Environment variable PARABUILD_P4USER holds the same value as P4USER that Parabuild used to access the code base being built. Environment Variables for CVS Builds

The following environment variables are available to build scripts running as a part of build configurations using CVS as a version control system: PARABUILD_CVS_ROOT and PAR- ABUILD_CVS_BRANCH. PARABUILD_CVS_ROOT

Environment variable PARABUILD_CVS_ROOT holds the same value as CVS_ROOT that Parabuild used to access the code base being built.

99 Build Script Environment Variables

PARABUILD_CVS_BRANCH

Environment variable PARABUILD_CVS_BRANCH holds the name of the CVS branch that Parabuild used to access the code base being built. Environment Variables for Git Builds

The following environment variables are available to build scripts running as a part of build configurations using Git as a version control system: PARABUILD_GIT_BRANCH. PARABUILD_GIT_BRANCH

Optional environment variable PARABUILD_GIT_BRANCH holds a name of a Git branch that Par- abuild used to access the code base being built. Environment Variables for Parallel Builds

The following environment variables are always available to build scripts running in parallel with a leading build: PARABUILD_LEADING_BUILD_ID, PARABUILD_LEADING_BUILD_NAME, PARABUILD_LEADING_BUILD_RUN_ID. These variables can be used by build scripts to create and to access a file storage that is shared between a parallel build and the leading build. PARABUILD_LEADING_BUILD_ID

Environment variable PARABUILD_LEADING_BUILD_ID holds a leading build ID. PARABUILD_LEADING_BUILD_NAME

Environment variable PARABUILD_LEADING_BUILD_NAME holds a name of the leading build. PARABUILD_LEADING_BUILD_RUN_ID

Environment variable PARABUILD_LEADING_BUILD_RUN_ID holds a leading build run ID. Environment Variables for Dependent Builds

The following environment variables are always available to build scripts running in builds that are started as a result of build dependency definition. These variables can be used by build scripts to create and to access a file storage that is shared between a dependent build and the build that started the dependent build. PARABUILD_UPSTREAM_BUILD_ID

Environment variable PARABUILD_UPSTREAM_BUILD_ID holds an ID of the build that started the dependent build. PARABUILD_UPSTREAM_BUILD_NAME

Environment variable PARABUILD_UPSTREAM_BUILD_NAME holds a name of the build that started the dependent build.

100 Build Script Environment Variables

PARABUILD_UPSTREAM_BUILD_RUN_ID

Environment variable PARABUILD_UPSTREAM_BUILD_RUN_ID holds a build run ID of the build that started the dependent build.

101 Chapter 13. Starting And Stopping Parabuild Service Under Windows Starting Parabuild Service

Parabuild is installed as a Windows service and is started automatically when the installation is complete. Parabuild service starts automatically when the Windows system is re-started.

It is possible to start Parabuild service manually if it is not running, for example because it was stopped before. To start Parabuild from the command line, follow the steps below:

1. Press the "Start" button;

2. Click on "Run" menu item;

3. Type "cmd" in the "Open" field, a command shell will open;

4. Type "net start parabuild". This command will start Parabuild service.

It is also possible to start Parabuild service using administrative interface:

1. Press the "Start" button;

2. Click on "Settings" menu item, Windows control panel will open;

3. Click on "Administrative Tools" icon;

4. Click on "Services" icon, Services management window will open;

5. Find Parabuild in the list of services, right click on it, select "Start". Parabuild service will start.

Stopping Parabuild Service

It is possible to stop Parabuild service manually, for example to perform an upgrade. To stop Parabuild from the command line, follow the steps below:

1. Press the "Start" button;

2. Click on "Run" menu item;

3. Type "cmd" in the "Open" field, a command shell will open;

4. Type "net stop Parabuild". This command will stop Parabuild service.

It is also possible to stop Parabuild service using administrative interface:

1. Press the "Start" button;

102 Starting And Stopping Parabuild Service Un- der Windows

2. Click on "Settings" menu item, Windows control panel will open;

3. Click on "Administrative Tools" icon;

4. Click on "Services" icon, Services management window will open;

5. Find Parabuild in the list of services, right click on it, select "Stop". Parabuild service will stop.

Changing Parabuild Service User Under Win- dows

By default, Parabuild service runs as a user with name "LocalSystem". Certain version control systems, such as ClearCase, require their clients to run as a user other than "LocalSystem". To change a user Par- abuild service runs as, follow the steps below:

1. Press the "Start" button;

2. Click on "Settings" menu item, Windows control panel will open;

3. Click on "Administrative Tools" icon;

4. Click on "Services" icon, Services management window will open;

5. Find Parabuild in the list of services, right click on it, select "Properties" menu item;

6. Select "Log On" tab;

7. Select "This account" radio button.

8. Enter user name and password.

9. Press "OK" button.

For changes to take effect, restart Parabuild service by stopping and starting it. Embedding Build Status Into Web Pages

Parabuild allows embedding information about statuses of its builds into arbitrary web pages. Pages where such status can be used may include a front page of your project, online release notes e.t.c. To embed information about status of a particular build, add a the following single-line call to Javascript available from your Parabuild server. The example below shows an HTML fragment making a call to embeddable Javascript. Parabuild will show a small rectangular box with an icon and a link to the online build status. Color of the icon and a link depends on last build result:

Example 13.1. Embedding Build Status Into Web Pages