 ------
 SCM Implementation: ClearCase
 ------
 Wim Deblauwe, Arne Degenring
 ------
 2008-09-02
 ------

~~ 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.

    []

    <<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 {{{./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.