ClearCase Plugin

Integrates Hudson with ClearCase.

Plugin Information

1.0 Configuration Incompatible With Earlier Versions Please note that version 1.0 of the ClearCase plugin is not configuration-compatible with earlier versions. Projects using base ClearCase will need to be reconfigured, with load rules removed from the config spec and specified separately in the new Load Rules field. This needs to be done for all base ClearCase projects, including those using dynamic views.

With this plugin you can use either base ClearCase and UCM ClearCase as the SCM for Hudson projects. The plugin uses the cleartool executable to work with a ClearCase server - this requires that the cleartool command (and therefore the full ClearCase client) be installed on master and all slaves on which you wish to run ClearCase jobs. The SCM also supports polling, so it can start a build when changes are detected on the branch or stream specified in the job configuration.

Usage

Global configuration

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

Base ClearCase

Basic configuration

• Set the name of the view that will be used by ClearCase. The view name has to be unique in the ClearCase region the master/slaves are using.
• Set the config spec that should be used. This should not contain any load rules.
• Specify one or more load rules - this is required, even with a dynamic view. The load rules are used both for determining the contents of snapshot views and for constructing the "cleartool lshistory" command used for polling and generating changelogs.
  • Load rules should be separated by newlines.
  • Load rules should be a path to a file or directory within the view, i.e., "vob/some_vob" or "\some_other_vob\directory". The path can have a leading file separator, or not. You can also have load rules starting with "load", as you would in a snapshot config spec outside of Hudson - the "load " will be removed and the path will be processed as normal.
• Check "Use update" if you wish to use the same view for every build - this will greatly speed up your builds, since the view won't be recreated and repopulated every build, but build output will be left in the view.
  • This option is only applicable to snapshot views. Dynamic views are not removed and recreated.
• Specify one or more branches - these branches will be used for polling for changes and assembling changelogs.

Advanced configuration

• Click the "Advanced" button to reveal the advanced options, including the dynamic view options.
• Excluded regions
  • Optionally, specify one or more regular expressions representing files or directories which you wish to ignore when polling and generating changelogs. In this example, any changes to a file named "version.properties" or "Version.properties" anywhere in the source tree will be ignored.
• Additional mkview arguments
  • If you need to pass additional arguments to "cleartool mkview", such as -gpath, -hpath, -server, etc, do that here. You can refer to the workspace the view will be under as $WORKSPACE, and the view name as $CLEARCASE_VIEWNAME. These will be replaced before being passed to "cleartool mkview".
• Filter destroy sub-branch events
  • If selected, "destroy sub-branch" events, which are generally the result of removing a version 0 of a file, will be ignored in polling.
• Remove ClearCase view on rename
  • If selected, the view will be removed, via "cleartool rmview", if the job is renamed, since the workspace directory will change and the existing view will no longer be valid.
• Multi-site poll buffer
  • Optionally, if you wish to have polling check for changes since the last build plus an additional period of time, in case of changes made at another site before the build which had not yet been synced to the build site by build time, enter that buffer period here, in minutes.

Dynamic view configuration

• Optionally, you can use an existing dynamic view, rather than a new snapshot view. To do so, check "Use dynamic view" under the advanced options.
• View root
  • Required for dynamic view use - this is the directory or drive under which dynamic views live. On Unix, this is generally "/view", while on Windows, it's generally "M:\".
• Do Not Reset Config Spec
  • If selected, the dynamic view's config spec won't be changed, regardless of whether it matches the config spec specified in the job configuration.

UCM ClearCase

• To be documented

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

The above solution did work but it sets the view storage location globally for everyone in the same region. A better solution may be:
(under the "Advanced" button in the "Additional mkview arguments" field):

-vws \\<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)

Todo list

• Add feature that verifies that the view name is unique.
• Add documentation on how to install a build trigger on a Clear case server
• UCM: Add ability to perform difference report between any two builds using baseline

Roadmap

Next major release in developmment

• Tentative: Planning to move UCM Make Baseline functionality out of main ClearCase plugin and into new "ClearCase Tag" plugin, along with new label functionality.

Changelog

Version 1.1 (in trunk)

• Bug fix: Load rules containing spaces are now handled properly in cleartool calls. (issue #4443)
• Bug fix: Use cases where the slave is run in a setview shell (so that the dynamic view is already started and source is accessed directly through, say, "/vobs/foo") are handled properly for polling and determining changelogs.
• RFE: Changing from using "cleartool update" to "cleartool setcs -current" for base snapshot views (and calling "cleartool setcs -current" for base dynamic views without changes in the config spec) to handle included config specs, etc. (issue #4569)
• RFE: Added optional, advanced option for UCM jobs for branch name - by default, stream is used, but if the override branch name is specified, it will be used for polling/changelog instead. (issue #4575)
• Bug fix: Discovered that views were still not being properly deregistered when processWorkspaceBeforeDeletion gets called - changed that to remove view tag instead, just to be safe.
• Bug fix: Use of "/" in load rules for Windows jobs no longer causes all lshistory entries to be ignored. (issue #4781)
• RFE: New option for base dynamic views to freeze config spec at build start time, using time rule. (issue #4652)
• RFE: When checking out for a snapshot view, before creating a new view, Hudson now checks to see if the given view tag already exists. If so, the checkout fails and an appropriate error message is logged. (issue #4653)
• RFE: Added advanced global option for standard view name pattern - when given, all jobs will use that for their view name, replacing variables as normal. (issue #4675)
• RFE: Added "$
  Unknown macro: {OS}
  " as variable which can be replaced in view names with the "os.name" Java system property.
• RFE: Added call to "startview" and "mount -avob" before lshistory is run on dynamic views. (issue #4676)
• RFE: Advanced option for having dynamic views created, rather than solely using existing views. Still very much raw functionality - optional mkview parameters need to be specified, but there is currently no check for them. (issue #4674)
• Also cleaned up code a lot, and got rid of deprecated calls whenever possible.

Version 1.0.2

• Bug fix: Case sensitivity problems in extended view path comparison were introduced by the change to "lshistory -all" - they should all be cleared up now. (issue #3666, issue #4330)
• RFE: New option to specify a polling buffer in minutes - will be subtracted from previous build's start time to determine when to poll against. (issue #3454)

Version 1.0.1

• Bug fix: Macros in view name weren't being processed in createHistoryAction, before running cleartool pwv. (issue #4385)
• Bug fix: Load rules in configuration can handle "load " in them properly now. (issue #4396)

Version 1.0

• Behavior change: Requiring "load rules" to be specified (separately from config spec) for base ClearCase, and all dynamic views. This provides support for lshistory -all, and future extensions such as labeling.
• Behavior change: Use of "lshistory -all" rather than "lshistory -recurse" - dramatic performance improvements, better change detection. Requires reconfiguration of existing jobs. This provides an enormous performance improvement in polling for jobs with large source trees.

Version 0.9.1

• RFE: Dynamic UCM views no longer call "chstream -generate", based on this discussion.
• Bug fix: UCM config spec wasn't using proper line endings. (issue #4027)
• Bug fix: Forcing US locale for lshistory timestamp format, since that's what ClearCase expects. (issue #3994)

Version 0.9

• Bug fix/behavior change: Change to config spec (for base ClearCase jobs) or load rules (for UCM ClearCase jobs) when "Use Update" is selected will no longer lead to view removal and recreation. Instead, config spec of existing view will be changed. (issue #3672)
• Bug fix: View is properly deleted when job is deleted, workspace is deleted by automatic workspace cleanup, workspace is wiped out manually with "Wipe Out Workspace", or job is renamed, if "Remove view on rename" is selected. Also, "Remove view on rename" setting now sticks properly. (issue #2209, issue #3095, issue #3508)
• Bug fix: Handling of line endings improved in general - modified splits, comparisons, etc to properly handle both Windows and Unix line endings. (issue #3694)
• Behavior change: When using existing dynamic views, the ClearCase plugin will now report to the Hudson project that the "module root" is /view/view_name (or m:\view_name, or whatever is specified as the view drive), allowing for the M2 project type and the like to run from within the dynamic view.

Version 0.8.4

• Bug fix: properly ignoring empty-string excluded regions now (issue #3622)
• Added LICENSE.txt to src/main/resources, which will now be bundled in the hpi.

Version 0.8.3

• Bug fixes: issue #3263, issue #3359, issue #3545, issue #3556
• MIT license header added to all source files

Version 0.8.2

• New feature: support for excludedRegions, patterns in filenames/paths to be ignored when polling for changes.
• New feature: support $CLEARCASE_VIEWNAME and other environment variables in mkview optional parameters (issue #2994)
• New feature: option to remove view when job name is changed (issue #3095)
• Bug fix: fixed lshistory timing issues when master and slave are in different timezones (issue #2493)
• Bug fix: extra newline characters in lshistory removed (issue #2801)
• Bug fix: loading remove/create UCM snapshot view fixed (issue #2846)
• Bug fix: no longer attempts to remove non-existent view when update only is not selected for UCM (issue #2902)
• Bug fix: better multiplatform support (issue #2939)
• Bug fix: better handling of multiple VOBs with UCM (issue #3097)
• Bug fix: UCM update-only snapshot views no longer always removed/recreated (issue #3184)
• Bug fix: support UCM dynamic view baseline creation (issue #3186)
• Bug fix: issue with createdBaselines variable in UcmMakeBaseline (issue #3304)
• Bug fix: if excludedRegions were not given, all changes were rejected - fixed (issue #3325)

Version 0.8.1

• Macros supported in 'additional arguments for mkview' (issue #2490) 
• Support for 'forced' re-creation of view (issue #2737)
• Dynamic UCM support (issue #1970)
• Node name is now resolved when using slaves (issue #2606)
• Environment variables resolved for mkview (issue #2470)
• Composite baseline support (issue #2518, issue #2426)
• Other bug fixes (issue #2740)

Version 0.7.1

• Added Tagging support for UCM clearcase (Baselines) (issue #1649)
• Removing jobs will now remove view from Clearcase server (issue #1050)
• Check that config rules contains load (issue #1062)
• All views can be listed from the configuration page (issue #1067)

Version 0.6

• 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!base_standard_config.png|align=right!