Download the latest version of the ClearCase connector here.
This is the README for the Krugle reference implementation of a ClearCase Source Control Management Interface
(SCMI).
Requirements:
* Windows, *nix or OS X
* Java 1.5 or greater
* 100 megabytes of free RAM, for most regular sized repositories. The SCMI may use as much as 512
megabytes on larger repositories. If an 'out of memory' condition occurs, the maximum java memory
argument (-Xmx) can be adjusted in scmi-env.bat (windows) and run.sh (*nix).
* ClearCase command line client (cleartool)
* 1 gigabyte of working space.
* 128 megabytes of free RAM, by default. This can be adjusted
in scmi-env.bat (windows) and run.sh (*nix).
Features and Limitations:
* Works on Rational ClearCase 6 and 7
* Dynamic UCM and snapshot views are support. Snapshot views are not yet supported.
* The user which runs the SCMI process must have proper clearcase credentials to access
the views which the SCMI will access.
Known Issues:
* The console output of the SCMI application may include NullPointerExceptions from the ProcessInputStream class.
WINDOWS INSTALLATION
1. Prepare the windows host
* It is recommended that you create a new user specifically for this SCMI application. "clearcasescmi"
is a good choice. This is not necessary, especially if this is not a long term install.
* Verify you have java 1.5 or greater.
* Ensure the user has sufficient privledges to access the views that must be crawled.
* Install the ClearCase command line client.
2. Decompress the contents of the ClearCase SCMI distribution. The path "C:\SCMI\clearcase-scmi\"
is suggested.
3. Edit the settings in <installed location>\clearcase.properties
* It is likely that this file will have unix newlines, so use an editor more advanced than notepad.
Wordpad is sufficient. You must be sure to use "\\" when a "\" character is needed, because java
will assume these strings use character escapes.
* Set toolPath to a valid path to cleartool. "cleartool" will work if cleartool is on your PATH
* Set the view root. On windows this should be \\view\ and so the config file should be set to: "\\\\view\\"
To set it to a drive letter such as M:\, use "M:\\". Note, do not set this to an individual view mount point. It must
be the general view root that all views mount beneath. (usually \\view\ or M:\)
* By default, all state files (including checked out working copies) will be placed in the
stateDir subdirectory of the SCMI install path. This can be changed by setting:
scmi.stateDir=C:\\path\\to\\custom\\stateDir
You might want to change this if you're running out of space where the SCMI is installed,
or if the stateDir directory structure is creating filepaths with too many characters for
Windows to support.
4. Edit the settings in <installed location>\run.bat
* Set JAVA to a command which will invoke java 1.5 or greater. "java" will probably work, and you can
test this by running "java -version" from the command line.
* Set SCMI_HOME to the <installed location> where you unzipped the scripts. If you followed the
suggestion from (2) above, this would be "C:\\SCMI\\clearcase-scmi\\"
5. Execute run.bat as the appropriate user.
6. Validate that the SCMI is running correctly by pointing your browser to the following URL:
http://<hostname of SCMI>:<port of SCMI>/status
The port usually is 8765 (or what you set in clearcase.properties).
If this doesn't return a status page the SCMI didn't start up properly. Check the activity log for
details in this case: logs/scmi-activity.log
7. Continue to USAGE instructions below.
*NIX INSTALLATION
1. Prepare the *nix server where the client will be installed
* Verify you have java 1.5 or greater.
* Create a user (e.g. "clearcasescmi") that will be used to run the client. Not necessary but suggested.
* Install and configure a ClearCase command line client (cleartool)
2. Copy and unpack the contents of the ClearCase SCMI distribution on your server.
Ideally these files should go into /home/<user>, where <user> is the user you created in step 1 above.
For example, if the SCMI archive name is clearcase-scmi-1.0.0-release.zip
and you wanted to have the resulting files located at /home/clearcasescmi/, you would execute:
unzip clearcase-scmi-1.0.0-release.zip
mv clearcase-scmi-1.0.0 /home/clearcasescmi/
3. Change settings in the clearcase.properties file according to your needs.
* If your ClearCase server uses a character encoding other than ISO-8859-1 for responses,
you will need to edit the scmi.clearcase.charset property in this file.
* By default, all state files (including checked out working copies) will be placed in the
stateDir subdirectory of the SCMI install path. This can be changed by setting:
scmi.stateDir=/path/to/custom/stateDir
You might want to change this if you're running out of space on the mount where the
SCMI is installed.
4. Change settings in the <installed location>/init.d/clearcasescmi.sh file to match your server setup.
* Note that you can start right away by executing bin/run.sh from the scmi folder, but to kill that process
you will need to kill its PID by hand. It is suggested you follow the steps below to properly
install the SCMI application.
* Uncomment and set the USER= parameter at the top of /init.d/clearcasescmi.sh. For the example above, the value
for USER should be set to clearcasescmi.
* Edit the SCMIDIR= parameter, also at the top of the file. This must match the location where
you unpacked the files, for example /home/clearcasescmi/clearcase-scmi-1.0.0
* Make sure MYNAME is unique for every scmi script you may have installed. This will be used
by clearcasescmi.sh to store the pid of the running process.
5. Set the owner for all the installed files to be the user specified above. For example
chown -R clearcasescmi /home/clearcasescmi/clearcase-scmi-1.0.0
6. Create a symlink from /etc/init.d/clearcasescmi to <installed location>/init.d/clearcasescmi.sh
cd /etc/init.d
ln -s /home/clearcasescmi/clearcase-scmi-1.0.0/init.d/clearcasescmi.sh clearcasescmi
Then set this script to be started at the correct runlevels. The exact method for this will depend on your
flavor of *nix. If your system supports chkconfig (try 'which chkconfig' to test this):
chkconfig --levels 35 clearcasescmi on
If you have an Ubuntu system you will need to use update-rc.d:
update-rc.d clearcasescmi defaults
If you do not have chkconfig of update-rc.d commands available, you will need to determine the appropriate
substitute for your OS in order to enable automatic startup.
7. Start the ClearCase SCMI by running the service after installation, for example
service clearcasescmi start
If you experience problems with 'service':
a) Run as root, and if you su to root, make sure you run 'su -' so that paths are setup correctly.
b) If you cannot get the 'service' command to work as intended, you can directly execute 'run.sh'
but this must be done as the SCMI user, and not as root. The process will have to be killed with
the 'kill' command.
Then you should watch the log file located at <installed location>/logs/scmi-activity.log to
ensure the service has started up properly.
8. Validate that the SCMI is running correctly by pointing your browser to the following URL:
http://<hostname of SCMI>:<port of SCMI>/status
The port usually is 8765 (or what you set in clearcase.properties).
If this doesn't return a status page the SCMI didn't start up properly. Check the activity log for
details in this case: logs/scmi-activity.log
USAGE
1. Once the SCMI script is setup correctly, navigate to your Krugle Enterprise Search
Appliance (KE) admin page. Typically this is http://<hostname>:8080/projects/project_listing.html
2. Create a new Data repository of the SCMI type.
* The Data Repository Host Location should be set the hostname or IP address of the machine hosting this SCMI.
* The Data Repository name can be anything, "ClearCase scmi" is a good start.
* The username and password are blank.
* The port should be set to 8765 (or what you set in clearcase.properties), and the protocol set
to HTTP.
* The path should be set to /repository
* The Project definition box should be unchecked for most cases. It should only be set if you are sure
this SCMI is source of project definitions.
3. Create a new project or edit an existing one.
* Add a location for the Data repository you just created in step 2.
* The location should be set to the name of the view.
* The parameters field can be left empty. Optionally you can provide a "vobs" parameter
which will filter the vobs indexed for the project. The "vobs" parameter should be a command separated list
of terms. If the "vobs" parameter is given, only vobtags in the view which contain at least one of the vob
strings will be indexed. For example:
If the vobtags in this view are: /vob/project1 /vob/project2 /vob/documentation /vob/qa
And the parameters field is set to: vobs=project,qa
Then /vob/project1 /vob/project2 and /vob/qa will all be indexed, while /vob/documentation will be omitted
because it did not match any of the terms in "vobs". Note that UCM ClearCase activities may still contain
references to vobs otherwise omitted by this method.
For more information on setting up Krugle Enterprise with these SCMI clients, please see
the Krugle Enterprise Administration Guide and the SCMI SDK documentation.
PLUGINS
Plugins allow functionality of the SCMI application to be added or modified. A plugin is installed
if it is placed in the /plugins directory. Every plugin has a properties file in the /plugins directory
as well, and this properties file controls various configuration values as well as whether or not the
plugin is enabled.
All SCMIs which crawl source code should include the file-filter plugin. It will be enabled by default
but it will only filter out known binary file types. To modify the list of files and directories filtered
out, edit /plugins/filter.properties
LOGGING
If you wish you may change log settings by editing the log4j.properties file. The first line currently looks like:
log4j.rootLogger = info, ActivityRFA, ErrorRFA
You can increase the amount of information being logged by changing "info" to "debug". Note that this
change must be made before the SCMI client is started.