SCM Implementation: ClearCase
SCM URL
For all URLs below, use a colon (:) as the separator. In case of a colon being used within one of the parameters (e.g. a Windows path), then use a pipe (|) as the separator.
scm:clearcase<delimiter>[view_name]<delimiter>config_spec
view_name: Name of the view that is created on a 'checkout' of the code. This parameter is optional.
config_spec: Either
- a user-supplied config spec file, or
- one load rule that is used by the ClearCase SCM provider to automatically generate a config spec when creating a view.
Note: Since 1.1.1, you could also use:
scm:clearcase<delimiter>[loadCommand]<delimiter>[VOBName]<delimiter>[streamName]<delimiter>/main/fooBar/LATEST
OR
scm:clearcase<delimiter>[viewName]<delimiter>[loadCommand]<delimiter>[VOBName]<delimiter>[streamName]<delimiter>/main/fooBar/LATEST
ClearCase UCM
If you are using ClearCase UCM, the URL format is the following
scm:clearcase<delimiter>[view_name]<delimiter>config_spec<delimiter>vob_name<delimiter>stream_name
vob_name: Identifier of the ClearCase VOB
stream_name: Name of the project's Stream
User-supplied config spec
If you specify the location of an user-supplied config spec file in the SCM URL, this config spec is used each time a view is created. SCM URL samples:
scm:clearcase:\\myserver\clearcase\configspecs\my_module.txt scm:clearcase:my_module_view:\\myserver\clearcase\configspecs\my_module.txt
To make sure all the correct elements are loaded in the view, the config spec must have "load" rules specified. You can also include other config specs into your own config spec, as in the following example:
include \\myserver\clearcase\configspecs\my_dynamic_configspec.txt load /myvob/modules/my_module
Notice that checking out from a tag (which is used by the maven-release-plugin) is currently not supported for user-supplied config specs. Another point to remember is that ClearCase does not check out projects directly into the checkout directory, but instead a sub-directory of the checkout directory (e.g. /checkoutdir/myvob/modules/my_module instead of just /checkoutdir). This is unexpected by the scm:bootstrap command, Continuum, the Maven-Release-Plugin and other users of the ClearCase SCM provider. Adjust the build working directory after the checkout (in Continuum, for example, by adjusting the POM file location within the Build definition).
Auto-generated config spec
For many users of a base ClearCase SCM installation, auto-generated config specs are more convenient than user-supplied config specs. Instead of being forced to provide a config spec file at an external location, the SCM URL contains all information that is needed to check out the code. Specify one load rule for the project you want to check out within the SCM URL, as in the following examples:
scm:clearcase:load /MY_VOB/my/project/dir scm:clearcase:my_module_view:load /MY_VOB/my/project/dir
This information is used by the ClearCase SCM provider to automatically generate the following config spec:
element * CHECKEDOUT element * /main/LATEST load <load_directory>
When working with auto-generated config specs, checking out from version tags (= ClearCase label types) is supported as well. (Notice that checking out from a branch tag (= ClearCase branch type) is currently not supported.) In case a tag has been specified, the following config spec is created:
element * CHECKEDOUT element * <tag> element -directory * /main/LATEST load <load_directory>
Notice that ClearCase does not check out projects directly into the checkout directory, but instead a sub-directory of the checkout directory (e.g. /checkoutdir/myvob/modules/my_module instead of just /checkoutdir). When using auto-generated config specs, the correct location of the project directory is provided to other modules that use the ClearCase SCM provider, such as the scm:bootstrap command. As a consequence, the build can automatically be run from the correct working directory.
Creating and removing views
Each time a 'checkout' of code is performed (e.g. when adding a project to Continuum), the ClearCase SCM provider creates a new snapshot view using the cleartool mkview command. As the view name, the view_name parameter is used if it has been specified. Many users prefer to leave the view_name parameter out, as the ClearCase SCM provider automatically chooses a view name according to the following pattern: username-hostname-maven-checkoutdir, e.g. johndoe-mymachine-maven-myproject.
Notice that the ClearCase SCM provider does not remove views once they have been created. When you don't need the view any longer, remember to explicitly remove it using ClearCase HomeBase or cleartool, e.g. using one of the following commands:
cleartool rmview /views/myproject cleartool rmview -tag johndoe-mymachine-maven-myproject
In case a view name already exists when checking out, ClearCase reports an error like the following:
cleartool: Error: A registry entry already exists for "johndoe-mymachine-maven-myproject".
ClearCase settings file
You can configure the behaviour of the ClearCase SCM provider by providing a clearcase-settings.xml file, either at ${user.home}/.scm/clearcase-settings.xml or at ${maven.home}/conf/clearcase-settings.xml. Notice: If the file is present at both locations, the settings from the .scm subdirectory of the user's home directory is used; the settings are not merged.
-vws parameter on mkview command
By default, when creating a view, the -vws parameter of the mkview command is used to specify the location of the view store. In many environments, however, the -vws parameter can be omitted, and ClearCase uses appropriate defaults. To turn off the usage of the -vws parameter, configure it in the clearcase-settings.xml file:
<clearcase-settings>
<useVWSParameter>false</useVWSParameter>
</clearcase-settings>Viewstore location
This setting is only relevant if and when useVWSParameter has been left or set to the default value of true. By default the viewstore location \\${hostname}\viewstore is used. To define another viewstore location, use the following setting:
<clearcase-settings>
<viewstore>\\mymachine\myvwstore</viewstore>
</clearcase-settings>ClearCase Type
By default, the ClearCase SCM provider uses commands appropriate for the full ClearCase version. If you are using ClearCase LT or ClearCase UCM instead, you must specify this fact in the clearcase-settings.xml file.
<clearcase-settings>
<clearcaseType>UCM</clearcaseType>
</clearcase-settings>As ClearCase LT uses a predefined and unchangeable folder as the viewstore directory, you should also specify the viewstore root location in the clearcase-settings.xml file:
<clearcase-settings>
<clearcaseType>LT</clearcaseType>
<viewstore>\\mymachine\myvwstore</viewstore>
</clearcase-settings>ClearCase dynamic views
The ClearCase SCM provider uses snapshot views. In case you are forced to use ClearCase dynamic views, one option is to use the SCM local file system provider instead. Within the SCM URL, you could specify the view name that the Continous Integration Server is using, for example:
scm:local|\\view\continuum_view\MY_VOB\my\project|module1
Notice that this option provides only very limited integration of Maven into the configuration management system. As no SCM metadata can be accessed, it is not possible to use SCM plugin features like creating tags (applying labels), creating changelogs, and so on.