| ------ |
| SCM Implementation: ClearCase |
| ------ |
| Wim Deblauwe, Arne Degenring |
| ------ |
| 2007-03-22 |
| ------ |
| |
| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ~~ NOTE: For help with the syntax of this file, see: |
| ~~ http://maven.apache.org/doxia/references/apt-format.html |
| |
| SCM Implementation: ClearCase |
| |
| * General Info |
| |
| Link: {{http://www-306.ibm.com/software/awdtools/clearcase/}} |
| |
| License: Commercial |
| |
| * 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. |
| |
| ** 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 {{{local.html}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. |