Constructing a Release Build Using Base ClearCase

Chapter 3 discussed the concepts of a Release-Prep Line. This section illustrates how to create this environment using Base ClearCase, as well as how to implement a Staging VOB.

Create the Release Build Environment

If you are using Base ClearCase, you can create a Release-Prep Line (or branch in Base ClearCase terms) by creating a child branch off the project's integration branch. You can do this using the ClearCase Type Explorer GUI. Select the appropriate ClearCase VOB (for example, \RatlBankSources), open the branch types folder, and select Type, Create. This displays the window shown in Figure 10.6, in which you can enter the branch type's name and details.

Figure 10.6. Base ClearCase Release-Prep branch

Alternatively, you can execute the following from the command line:

>cleartool mkbrtype -nc RatlBankModel_Rel@\RatlBankSources >cleartool mkview -tag RatlBankModel_rel -stgloc ccstg_d_views

This creates a new branch called RatlBankModel_Rel in the ClearCase VOB RatlBankSources. It also creates a dynamic Release Build view called RatlBankModel_rel.

Building Releases in Dynamic Views

Although it is not a requirement, I recommend that you create your Release Build using a dynamic view so that you can take advantage of the ClearCase build auditing capabilities described in Chapter 9.

To configure this view to use the Release-Prep branch, you would then amend the view's config spec so that it was similar to the following:

element * CHECKEDOUT element * /main/RatlBankModel_Rel/LATEST element * RATLBANKMODEL_02_INT -mkbranch RatlBankModel_Rel element * /main/0 -mkbranch RatlBankModel_Rel

This config spec selects the Integration Build baseline RATLBANKMODEL_02_INT as the candidate baseline for the Release Build. Note that this config spec also allows elements to be checked out. However, if they are, they are checked out to the Release-Prep branch.

Implement Critical Changes and Fixes

In an ideal world, you would never need to change the elements in your release environment, simply building the current content. However, the real world has two scenarios in which you might want to make a change:

• Making a minor change because of a build failure

• Backing out some functionality not required for the release

If the Release Build fails because of a minor defect, it should be acceptable to make the change on the Release-Prep Line. You can then apply a label to the changed files and make a release. However, you should always ensure that you deliver the changes back for the next Integration Build. If you find that at Release Build time you are asked to actively take out some functionality, you can use the Release-Prep branch and execute a Base ClearCase subtractive merge to take out the functionality. For more information on subtractive merges, refer to the cleartool merge manual page or the product manuals.

Execute the Release Build

Irrespective of whether you use Base ClearCase or UCM, your Release Build should be executed via a single Ant target, such as release. For all Release Builds you need to decide whether you will always create a new label or whether you will simply promote the status of the Integration Build label to indicate that it has now been released. For me, the decision hinges on whether you have made any changes to your Release Build. If you have, you should put down a new label to indicate this fact. With this in mind, the Ant target for a Release Build would look similar to Listing 10.2.

Listing 10.2. Base ClearCase Release Target

<?xml version="1.0"?> <project name="RatlBankModel" default="help" basedir="."> ... <!-- update the buildinfo.properties file --> <target name="update-buildinfo">     <propertyfile file="${name.build.info}"      comment="Build Information File - DO NOT CHANGE">         <entry key="build.num"          type="int" default="0000"          operation="+" pattern="0000"/>         <entry key="build.date"          type="date"          value="now"          pattern="dd.MM.yyyy HH:mm"/>     </propertyfile> </target> <!-- Release Build --> <target name="release" description="execute Release Build">     depends="compile, junit-all, javadoc, update-buildinfo">     <cc-apply-label label="${name.build.prefix}-${build.num}" plevel="BUILT"/> </target> </project>

To create your Release Build, you could then execute the following from the command line:

>ant release

This example uses the macro cc-apply-label and the automated baseline numbering capability from Chapter 5, "Apache Ant Best Practices," to generate and apply a unique ClearCase label. Note that this target does not currently carry out any staging of the built objects. I will discuss how to implement an environment in Base ClearCase to achieve this next.

Stage the Release Build Outputs

With Base ClearCase you can use directory permissions to enforce which project is allowed to write to which staging directory. To do this you need to create a new Windows or Linux/UNIX user group for each project. For example, the RatlBankModel project could have a group called RatlBankModel_Users. You would then change the ownership of the project's staging directory as follows:

[View full width]
>cleartool protectvob -add_group RatlBankModel_users D:\ClearCase_Storage\VOBs \RatlBankReleases.vbs >cleartool protect -recurse -chgrp RatlBankModel_Users -chmod 775 M:\RatlBankModel_rel \RatlBankReleases\model

The first command adds the new group to the Staging VOB. You would need to run this as a ClearCase privileged userthat is, as a member of the ClearCase group (normally called clearcase on Windows) or as root on Linux/UNIX. The next command then changes the ownership of all files in the project's staging directory. Note that this command refers to a ClearCase VOB called RatlBankReleases that has been created specifically for staging build objects. The physical staging directory for this project inside the RatlBankReleases Staging VOB is called model. To ensure that all other projects can still access the staging directory, while ensuring that they cannot write to it, directory permissions of 775 are applied.

After you have created this environment, you place labels to indicate which collective group of staged objects should be consumed by different projects. This can be carried out automatically as part of the build process, as shown in Listing 10.3.

Listing 10.3. Ant Release Build Target and Staging

[View full width]

<?xml version="1.0"?> <project name="RatlBankModel" default="help" basedir="."     xmlns:ca="antlib:net.sourceforge.clearantlib">     <property name="dir.dist"  value="dist"/>     <property name="dir.stage" value="../../RatlBankReleases/model"/> ... <!-- Release Build --> <target name="release" description="execute Release Build">     depends="compile, junit-all, javadoc, update-buildinfo">     <ca:ccstage todir="${dir.stage}" outfile="ccstage.xml">         <fileset dir="${dir.dist}">             <include name="**/*.jar"/>         </fileset>     </ca:ccstage>     <cc-apply-label label="${name.build.prefix}-${build.num}" plevel="BUILT"/>     <cc-apply-label label="${name.build.prefix}-${build.num}" plevel="BUILT"  startloc="${dir.stage}"/> </target> </project>

In this example the <ccstage> task is used to automatically stage the build's derived objects. Then the cc-apply-label macro is called twicefirst to label all the input (source) files used during the build, and then to label all the staged objects. This is an example of how to achieve a complete build, stage, and label; you might want to implement more or less automation, depending on your requirements.

Reusing Staged Objects

Of course, there is little point in staging objects if you don't use them somehow. For example, assume that the label RATLBANKMODEL_01_REL has been applied to the RatlBankModel project's staging directory. To reuse these staged objects in another project, such as RatlBankWeb, you would change a RatlBankWeb user's config spec to look similar to the following:

element * CHECKEDOUT element * /main/RatlBankWeb_Int/LATEST element * /main/LATEST -mkbranch RatlBankWeb_Int element * /main/0 -mkbranch RatlBankWeb_int element \RatlBankReleases\model\... RATLBANKMODEL_01_REL ...

In this example, the config spec contains a line for the label for each project's staged objects (as in the last line). The other lines simply match the particular project's own source code. In this case the config spec ensures that all modifications for the RatlBankWeb project are made on its integration branch.

If you have a large number of staging directories, one best practice is to maintain a separate config spec file that lists a set of compatible labels and then reference it by including it in each user's own config spec. For example, you could create a file called ratlbank_rel1.cspec that contains the lines for each of the staging directories:

element \RatlBankReleases\model\... RATLBANKMODEL_01_REL element \RatlBankReleases\db\... RATLBANKDB_01_REL ...

Then amend each user's config spec to reference this file:

element * CHECKEDOUT element * /main/RatlBankWeb_Int/LATEST element * /main/LATEST -mkbranch RatlBankWeb_Int element * /main/0 -mkbranch RatlBankWt_int include ratlbank_rel1.cspec

Note that this file should be added to version control and maintained as part of the build and release process.