Table of Contents
List of Examples
Table of Contents
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. Parabuild 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.
This guide is intended for anyone who is responsible for administration of a Parabuild server or a remote builder 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.
If you have any problems with the software or documentation, please contact Viewtier Technical Support 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 at www.viewtier.com.
650-240-4455
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 two view modes: list view and detailed view. To switch between the two modes click "List view" or "Detailed view" links, respectively. The differences between the modes are described below.
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 two view modes: list view and detailed view. To switch between the two modes click "List view" or "Detailed view" links, respectively. The differences between the modes are described below.
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.
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).
If a user logged in as an administrator, the build statuses page shows a list of build control commands. The following commands are available:
This command starts the build if the build is idle.
This command forcefully stops the build if the build is running.
All builds are originally inactive. Use this command to activate a new build.
This command opens the build configuration page.
This command opens a new build configuration page.
Table of Contents
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.
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.
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.
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 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 john@mycompany.com. Default e-mail domain is an optional setting.
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 port allows to set a port number the SMTP server listens on. This is a mandatory setting. A default value is port number 25.
Enter an SMTP server password if your SMTP server requires explicit login.
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.
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.
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.
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 and build.step. The default template is ${build.step} for ${build.name} (#${build.number}) started on ${build.host}.
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}.
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.
Parabuild uses value entered in the "Generated URL protocol" to form the protocol part of a URL used in e-mail and instant messages.
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
dd MMM yyyy format will render to 24 Dec 2003
MMM dd yyyy format will render to Dec 24 2003
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
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 personal preferences.
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.
This field contains maximum length of a change list description that will be used in notification messages sent by Parabuild.
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.
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.
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 "MyCompany," you may want to change the branding setting to "MyCompany Build Server". If not set, "Viewtier Parabuild 2.0" will be displayed. This is an optional parameter.
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.
Check this box to enable displaying links to RSS feeds containing information about build status changes.
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.
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.
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.
Check this box to allow anonymous users accessing build statuses through web user interface. Built-in security group "Anonymous" allows to configure what builds can be accessed by anonymous users.
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.
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.
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.
Parabuild uses default build step timeout when you create new build steps through the user interface.
Maximum change list size defines how many files per change list will be recorded. The default value is 500 files per change list.
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.
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.
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.
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.
Check this box to enable debug logging. Parabuild will send debug output to a file named parabuid_debug.log under logs directory if debug logging is enabled. Debug logs may be useful when communicating with Viewtier support. During normal operation debug logging should be disabled.
To manage projects select link "Projects" in "System settings" section of the system configuration. Parabuild will display a list of projects and corresponding controls.
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.
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.
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.
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.
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.
To delete a display group click on link "Delete" for the selected display group. After receiving a confirmation Parabuild will delete the display group.
Parabuild provides built-in display groups.
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.
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 "Administration" 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.
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.
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.
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.
You receive a license file after ordering Parabuild. In order to install your Parabuild license login to Parabuild 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.
To obtain an evaluation license, please visit http://www.viewtier.com/downloads.htm.
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
User password attribute name
Credentials digest algorithm
User e-mail attribute name
Add first-time users to group
Meaning of each fields is discussed below.
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.
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.
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".
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 "Default", the default is determined by the provider.
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.
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.
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"
Setting "Search entire subtree" may be used if user search is selected. Check this box if you want Parabuild 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.
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.
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.
This mandatory field should be set to the name of an attribute of the user's entry that contains user's e-mail address.
Parabuild will add to the selected Parabuild group users if they log to Parabuild first time.
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.
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 Referrals to "follow". Set User Search Template to sAMAccountName=${user.id}. Select Search Entire Subtree.
Table of Contents
Subsequent chapters will use "build configuration" and "build" interchangeably.
To add a new build configuration, follow these steps:
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.
Login in as "admin" user.
Go to the list of builds by clicking "Builds" menu item on the top navigation bar.
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.
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 build settings form is displayed when a new build added. It allows to set the general build configuration parameters. These parameters include:
Build name.
Build results access.
Builder host name (optional).
Version control.
Runner type.
Build type.
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.
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 3.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.
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 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.
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.
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.
In order for a scheduled build to be created, an automatic (integration) build that backs it should be already configured.
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.
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.
In order for a parallel build to be created, a leading build should be already configured.
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.
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.
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.
A build configuration must have at least one build step. Build steps are configured by modifying a build sequence table. Parabuild supports multi-step builds.
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.
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.
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
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.
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 '$'.
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 '$'.
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 patters have priority over searching for success patterns.
Use error code respecting if a build scripting tool used by your project cannot provide stable success and failure patterns.
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.
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
Check "Initializer step" box to make this step an initializer step. The initializer step runs before any dependent parallel build runs.
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.
The following settings are available to all version systems:
Custom checkout directory
Ignore list
This setting allows to overwrite 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}.
"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 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.
"Ignore list" is an advanced setting. This setting is available only when an advanced build configuration is enabled using the system settings page.
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
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 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.
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.
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.
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.
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 supporting 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.
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 "parabuild_${build.id}".
"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.
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.
"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.
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.
"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.
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 is a mandatory field. The entry for this field should conform with the format for the CVS root.
Repository path is a mandatory field. It defines the location of the home of the project source line relative to the CVS root.
Parabuild supports multiple path projects. For multiple path projects each path should be entered one per line.
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 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.
CVS password is an optional field. If needed, enter a password that will be required to access CVS in this field.
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.
Configuring access to CVS via SSH includes 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 the public 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.
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 supporting 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.
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 predominantly 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.
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 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 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.
Parabuild allows selecting ViewVC or Cenqua FishEye as a repository browser. Parabuild 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 in the following sections.
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 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 3.9. 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.
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 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 3.10. 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.
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".
"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.
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
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 is a mandatory field. Parabuild will use this field to fill "user" part of detected change lists.
Path is a mandatory field. This field should contain a list of directories, files or URLs that Parabuild should watch for changes.
"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_ID contains a unique system-wide identifier assigned to this build configuration.
PARABUILD_BUILD_NAME contains a name assigned to this build configuration.
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, January 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_ID contains a unique system-wide identifier assigned to this build configuration.
PARABUILD_BUILD_NAME contains a name assigned to this build configuration.
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_ID contains a unique system-wide identifier assigned to this build configuration.
PARABUILD_BUILD_NAME contains a name assigned to this build configuration.
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.
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.
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 to stdout. Parabuild will parse the output according to the parser parameters. The parameters are entered in the corresponding entry fields. The meaning of each field is discussed below.