The CVS Server sensor requires Java 1.5.0 or later and Ant 1.6.5 or later. Since the sensor works by parsing the RCS data files managed by CVS, it should be compatible with any recent version of CVS. However, our only experience with this sensor to date is with CVSNT 2.0 on Windows.

Download CVS 1.11 or later and install as instructed.

Follow the instructions in Chapter 2, Client-side configuration: Tool sensor installation to set your Hackystat host and user key.

In the HackyInstaller main window, select the CVS sensor and press "Configure Selected Sensor". Figure 26.14, “ CVS sensor installer configuration window ” shows what the configuration window should look like after the path to Ant is set, the sensor is enabled, and the "Install" button has been pressed to install the sensor.

Figure 26.14.  CVS sensor installer configuration window

This sensor supports the following properties and paths:

Create a file called usermaps.xml in the .hackystat directory of the account that will run the CVS sensor. This file contains the set of all CVS user accounts with a corresponding Hackystat account, as documented in Section 2.7, “Sensors for multi-user tools and the usermaps.xml file”.

Define a target in a build.xml file to invoke the CVS Server sensor on your CVS data from the previous day. Example 26.23, “An example CVS Server target for daily use” illustrates one possible definition of such a target. When the target does not specify a date range explicitly, then by default only commit data from the previous day is processed by the sensor.

<target name="CvsServerDailySensor"
        description="Sends CVS commit information from the previous day to Hackystat.">
  <taskdef name="hacky-cvs" classname="org.hackystat.sensor.cvs.CvsSensorAntTask" />
  <hacky-cvs repositoryName="HackyDev" 
             fromEmail="HackystatAdmin@my.org" toEmail="CvsSensorAdmin@my.org" smtpServer="mail.my.org"> 
    <fileset dir="C:\cvs-repository\cvsnt"> 
      <include name="**/*.*,v"/>
      <exclude name="**/*.jar,v"/>
      <exclude name="**/*.class,v"/>
      <exclude name="**/*.gif,v"/>
      <exclude name="**/*.zip,v"/>
      <exclude name="**/*.jpg,v"/>
      <exclude name="**/*.png,v"/>
      <exclude name="**/*.bmp,v"/>
      <exclude name="**/*.ico,v"/>
      <exclude name="**/*.doc,v"/>
      <exclude name="**/*.xls,v"/>
      <exclude name="**/*.ppt,v"/>
      <exclude name="**/*.mdb,v"/>
      <exclude name="**/*.exe,v"/>
      <exclude name="**/*.dll,v"/>
    </fileset>
  </hacky-cvs>
</target>

Please note the following regarding Example 26.23, “An example CVS Server target for daily use”:

	The hacky-cvs target requires a "repositoryName" argument specifying the CVS repository associated with this commit data. This is an arbitrary string for potential use by Hackystat analyses.
	The sensor can be optionally configured to send out alert email when it is unable to send data to Hackystat server. The arguements "fromEmail", "toEmail" and "smtpServer" are used for this purposes. They are optional. However, if you use them, they must appear together.
	The fileset attribute specifies the set of files in the repository for which commit data should be extracted. In this example, we include all files that end with ",v", because those files (i.e. RCS files) are the only ones for which we can extract commit information. On the other hand, we exclude binary files, since no embedded commit information is available for those files.

In some circumstances, such as when installing the server for the first time, you may wish to collect data over a different period of time than just the previous day. To enable this, you can supply the optional fromDate and toDate attributes along with dates in YYYY-MM-DD format. When the sensor is invoked with these attributes, it will send commit data regarding all commits that occurred during that interval that can be recovered from the CVS repository files. Example 26.24, “An example CVS Server target recovering commits from an arbitrary date range” illustrates an example target that recovers commit data for all of 2004 by default. (Use the -D option to Ant to override the default cvsserver.fromDate and cvsserver.toDate property settings.)

<target name="CvsServerIntervalSensor"
        description="Sends CVS commit information over a time interval to Hackystat. Interval defaults to all of 2004.
                     Set properties cvsserver.fromDate and cvsserver.toDate to adjust interval. ">
  <taskdef name="hacky-cvs" classname="org.hackystat.sensor.cvs.CvsSensorAntTask" />
  <property name="cvsserver.fromDate" value="2004-01-01"/>
  <property name="cvsserver.toDate" value="2004-12-31"/>
  <hacky-cvs repositoryName="HackyDev"
             fromDate="${cvsserver.fromDate}" 
             toDate="${cvsserver.toDate}"> 
    <fileset dir="C:\cvs-repository\cvsnt"> 
      <include name="**/*.*,v"/>
      <exclude name="**/*.jar,v"/>
      <exclude name="**/*.class,v"/>
      <exclude name="**/*.gif,v"/>
      <exclude name="**/*.zip,v"/>
      <exclude name="**/*.jpg,v"/>
      <exclude name="**/*.png,v"/>
      <exclude name="**/*.bmp,v"/>
      <exclude name="**/*.ico,v"/>
      <exclude name="**/*.doc,v"/>
      <exclude name="**/*.xls,v"/>
      <exclude name="**/*.ppt,v"/>
      <exclude name="**/*.mdb,v"/>
      <exclude name="**/*.exe,v"/>
      <exclude name="**/*.dll,v"/>
    </fileset>
  </hacky-cvs>
</target>

The next step in setting up your CVS server sensor is to create shell script to simplify invocation of the sensor. Example 26.25, “An example CVS Server shell script” illustrates one possible shell script which is implemented as a batch file for the Windows platform. It invokes the CVS server sensor daily Ant task.

del cvssensor.output.txt 
ant CvsServerDailySensor > cvssensor.output.txt 

Please note the following regarding Example 26.25, “An example CVS Server shell script”:

	Deletes the file "cvssensor.output.txt" if present, which contains the output from each run of the CVS sensor via this script.
	This line runs ant and invokes the target CvsServerDailySensor, placing the output from the execution of the sensor into the file cvssensor.output.txt.

The typical way to invoke the CVS server sensor is to use an operating system facility to run your script once a day at a convenient time. In Unix, the facility is called "cron", in Windows, the facility is called "Scheduled Tasks" and is found in the Control Panel. Each day when it runs, it will process all commit data from the previous day. Thus, you will need to wait a day to see commit data show up in your Hackystat analyses.

To verify your CVS Server sensor installation, commit a file to your CVS server, and then run the CVS server sensor using the fromDate and toDate attributes to specify that commits from today should be processed. The sensor will generate a line of output for each file that it processes, as illustrated in Example 26.26, “Example CVS server sensor verification invocation”. In this example, the fileset was modified so that only one file (README.html,v) in the hackyDocBook module was processed.

C:\CruiseControls\cvs-sensor>ant -DfromDate=2004-12-31 -DtoDate=2005-01-01 interval
Buildfile: build.xml

interval:
[cvs-sensor] Processing commits between Fri Dec 31 00:00:00 HST 2004 to Sat Jan 01 00:00:00 HST 2005
[cvs-sensor] Start Processing: C:\cvs-repository\cvsnt\hackyDocBook\README.html,v

BUILD SUCCESSFUL
Total time: 5 seconds

After invoking the CVS Server sensor on files with commit data, login to your account on your Hackystat server, and use the "List Sensor Data" command on the Extras page to verify that Commit data for the specified file was received by the server, as illustrated in Figure 26.15, “ List Sensor Data with CVS Server data ”.

Figure 26.15.  List Sensor Data with CVS Server data

The first step in troubleshooting your sensor installation is to verify that your Hackystat host and key settings are valid and that you can contact the Hackystat server, as described in Section 2.4, “HackyInstaller GUI: Setting and verifying the Hackystat host and user key”

The CVS Server sensor writes out a file called cvsserver.0.log to the .hackystat/logs directory that can be useful in debugging your installation. Under normal conditions, this file should look similar to Example 26.27, “Log file for CVS Server sensor”.

Hackystat Version: 6.3.1206 (December 6 2004 12:12:57)
SensorShell started at: 12/31/2004 11:34:32
Type 'help' for a list of commands.
Host: http://hackystat.ics.hawaii.edu/ is available and key is valid.
Defined shell command: Activity
Defined shell command: Coverage
Defined shell command: UnitTest
Defined shell command: Commit
Defined shell command: BuffTrans
Defined shell command: Build
Defined shell command: FileMetric
AutoSend not enabled.
Checking for offline data to recover.
No offline data found.
#> Commit [setTool, CvsSensor]
setTool OK
#> Commit [add, 1104528281000, C:\cvs-repository\cvsnt\hackyDocBook\README.html, johnson, HackyDev, 1, 1.11, 300, 2, 2, Updates to hackyDocBook]
Commit add OK (1 total)
#> send
Sending sensor data (12/31 11:34:34)
  Activity: Send OK (No entries to send.)
  Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
  Coverage: Send OK (No entries to send.)
  AutoSend: AutoSend OK ('send' command ignored)
  BuffTrans: Send OK (No entries to send.)
  Commit: Send OK (1 entries)
  UnitTest: Send OK (No entries to send.)
  Build: Send OK (No entries to send.)
  FileMetric: Send OK (No entries to send.)
>> 

You may find that the CVS reports an exception similar to the following while processing certain files:

[cvs-sensor] Start Processing: C:\cvs-repository\cvsnt\cedric-test\mysql\columns_priv.frm,v
[cvs-sensor] Error processing C:\cvs-repository\cvsnt\cedric-test\mysql\columns_priv.frm,v. Error message is Lexical error at line 35, column 36.  Encountered: "\u017d" (381), after : "@\u0003\u20ac~\u0001\u0010\u0004\u20ac". Error type is class org.apache.commons.jrcs.rcs.TokenMgrError
[cvs-sensor] org.apache.commons.jrcs.rcs.TokenMgrError: Lexical error at line 35, column 36.  Encountered: "\u017d" (381), after : "@\u0003\u20ac~\u0001\u0010\u0004\u20ac"

This error typically occurs when the CVS sensor encounters a binary file. The sensor will continue to process additional files, so there is no functional harm in this error message. To prevent it, refine your fileset specification to avoid files of the offending type. In this case, for example, the fileset should be augmented to exclude files with the suffix ".frm,v".

If none of the above troubleshooting activities solves your problem, then you should send an email to your Hackystat Administrator to request help. Please include in your email the following information: