ClearCase Plugin

Integrates Hudson with ClearCase.
With this plugin you can base ClearCase and UCM ClearCase. The plugin uses the cleartool executable to work with a Clear case server which requires that the cleartool command is installed on master and all slaves. The SCM also supports polling so it can start a build if any changes in the repository.

Usage

1. Main configuration
   1. Set up the cleartool executable in the Hudson configuration. To verify that the executable can be used by Hudson press the "Check cleartool version"

1. Per job configuration
   1. Select Base Clear Case
      1. Set the name of the view that will be used by Clear case. The view name has to be unique on the computer.
      2. Set the configspec that should be used
      3. Check the "Use update" if you want a quicker build.
         "Use update" will not remove and create the view for every build but it has a side effect that build artifacts in the view can be left between builds.
      4. Enter the branch for the branch.
         The name of the branch is needed to get the correct change log for the view path.
         
         
          
         
   2. Select UCM Clear Case
      1. Set the name of the view that will be used by Clear case. The view name has to be unique on the computer.
      2. Set the stream that should be used
      3. Set the load rules that should be used in the stream.

This plugin is not feature complete, but it is being used in a live environment. If you have any clear case experience please join us in developing this plugin.

Frequently asked questions

Is the view name available in the build scripts?

Yes, the view name can be accessed through the environment variable CLEARCASE_VIEWNAME, which contains the name of the view. The environment variable CLEARCASE_VIEWPATH contains the absolute path to the view folder.

Can the view name be updated with the name of the job.

Yes, from version 0.6 it is possible to add ${USER_NAME} and ${JOB_NAME} in a view name which are replaced with the name of the user and job.

Error when creating view (storage directory must be in UNC style)

Jamie Burrell solved it by doing the following at the command line of the machine on which Hudson runs. Note that the view name need not be the one you are using for Hudson. It needn't ever be used. I also had trouble using localhost, and needed to use my machine name.:

cleartool mkstgloc -view mystgloc \\<host>\<shared folder>\<view name>.vws

Error when retrieving history (Error: Not an object in a vob: "vobs")

On Linux and Solaris there are sometimes problems retrieving the ClearCase history using lshistory. In the Advanced section in the configuration it is possible to specify one or several paths in the VOB path(s) field that will be used when retrieving the history. If the config spec contains "vobs/gtx2" then the VOB path(s) field should be set to gtx2. (Mail thread, issue #1053)

Current state of the plugin

The plugin is being used in a large corporate environment for more than 2 months. For simple SCM usage, create a snapshot view, check out and build the code, it will function well.

Existing issues with the plugin:

• The plugin will not clean its Clear case usage, which means that the snapshot view created by the plugin is not removed. The Clear case administrator must manually remove the view when a Hudson job has been deleted. As long as jobs/views are used for a long period of time this should not be a problem.

Todo list

• Add tagging support that would set a build label on a successful build.
• Add feature that verifies that the view name is unique.
• Add documentation on how to install a build trigger on a Clear case server
• Add clean up feature when jobs are deleted.
• UCM: Add ability to perform difference report between any two builds using baseline

Roadmap idea

 0.7

• Tagging (baseline) support
• Ability to compare any two builds (both with ClearCase as SCM) uaing tagging/baselines.
• Simple file filtering in SCM polling

0.8

•  Ability to run history command inside load rule (Issue 1713)
•  Better default viewname (Issue 1715)

0.9

• Refactoring and bugfixes 

Changelog

Upcoming version (features in snapshot)

0.6 branch

• Added activity based UCM changelog.
• Added option to not trigger build on downstream branch destroys (issue #1470, discussion)
• Fixed problem with too many open files (issue #1921)
• Fixed problem with Priocess leaked file descriptors (issue #1946)
• The view-extended pathname is removed from file paths in dynamic view events (issue #1885)
• The view name can now contain properties which are replaced before usage. ${USER_NAME} and ${JOB_NAME} (issue #1715)
• Implemented SCM methods getModuleRoot() so the SCM can work better with builders. (issue #1848)

Version 0.5.2

• UCM Load rules begining with double "\" or "/" no longer throws an exception when retrieving the history (issue #1706)
• UCM Load rules no longer loses single "\" (issue #1707)

Version 0.5.1

• Replaced setview call with startview when checking out dynamic views.(issue #1631)

Version 0.5

• Initial support for ClearCase UCM. It can now use UCM streams and apply load rules to them. The plugin has now two SCM configuration points, Base ClearCase and UCM ClearCase. (issue #1580)
• Changeset items are now listed in XML API (issue #1325)
• File element changes with version 0 is now also ignored on linux/solaris (issue #1465)
• Added CLEARCASE_VIEWPATH environment variable that contains the absolute path to the ClearCase view (issue #1480)
• Changeset items are now marked with an icon depicting if the item was added, removed or checked in. (issue #1068)
• Fixed so "setview" will be called on all dynamic views in every build (issue #1484)

Version 0.4

• Added option to set additional arguments when creating the snapshot view using 'mkview'.
• Fixed problem with merged entries so the oldest date/time is used for the merged entry.
• Sorts the list so the latest entry is placed at top.

Version 0.3.3

• Time window for merging commits can now grow to include all entries in one commit. (issue #1079)
• Rephrased all "Clear case" to "ClearCase" and "clear tool" to "cleartool"

Version 0.3.2

• Fixed issue with '^M' characters in the config spec when running on unix/linux.
• Improved help section about view root (thanks to Jason Messmer)
• Better error handling when the cleartool command is not set (issue #1086)

Version 0.3.1

• Fixed a problem when the SCM object was serialized and not created through the constructor.

Version 0.3

• Added option to use multiple branches when polling for changes (issue #1028).
• Added functionality that checks if the config spec needs to be updated (both dynamic and snapshot) (issue #1027).
• Added support of using existing dynamic views. The plugin will not create dynamic views.
• Added option to use multiple VOB paths when polling for changes (issue #1053)
• Added feature that merges change log entries that have the same user, comment and time (issue #924)
• Fixed so the plugin will not start a "cleartool update" after the view has been updated with the "cleartool setcs" command.
• Fixed a poll changes bug when the plugin is used by a maven job (issue #1029).
• Fixed so plugin works with JDK1.5 (issue #1053)
• Fixed a bug that occurred when the user removed the view, then the poll changes would throw an exception. (issue #923).

Version 0.2.1

• Fixed a unicode problem with the change log xml file

Version 0.2

• Reworked the plugin so it will use a config spec to retrieve files from the Clear case repository. The files are retrieved into the workspace as other SCMs.
• Fixed so the annotation plugins works as they should
• Added the environment variable CLEARCASE_VIEWNAME that contains the view name
• Rewrote the history parsing to fix a NPE.
• Added option to see the cleartool version and verify that Hudson can use it

Version 0.1

• First version