Chapter 7. Integration Tools

7.1. Glue Installer

The command scmbug_install_glue.pl is used to install the integration glue in an SCM repository. Existing hooks used in the SCM system are not overwritten.

The --binary-paths configuration option should be set to a list of paths that include all binaries needed by the integration tools and the SCM system. This includes the tools diff, xsltproc, docbook2pdf, docbook2html and the SCM system's binaries. The --bug configuration option should be set to the id of a bug in the bug-tracker against which the integration glue installation will be documented.

Tip

It is preferable to set in --binary-paths the path to the directory that contains a binary, instead of the path to the binary itself. Using Subversion in Windows for example, the binaries require additional libraries (e.g. .dll files) that are contained in the directory that holds the binary.

An example installing the glue in a Subversion repository under UNIX is shown in Figure 7-1.

Figure 7-1. Glue Installation in a Subversion repository under UNIX.

$ scmbug_install_glue.pl --scm=Subversion --product=TestProduct \
  --repository=file:///tmp/testrepository --bug=770 --binary-paths=/bin,/usr/bin \
  --daemon=127.0.0.1
 This is the installation script of the Scmbug glue.
 The glue will be installed in repository: file:///tmp/testrepository.
 This is a repository for the Subversion SCM tool.
 The product name in the bug tracking system is TestProduct.
 The integration glue will be committed against bug 770.
 The IP address of the Scmbug integration daemon to contact is 127.0.0.1.
 The binary paths used are: /bin,/usr/bin
 -------------
 Press Enter to continue or Ctrl-C to cancel

Glue processing has been prepared in /tmp/Scmbug.30670
Installing part1
Check everything there before I commit or hit Ctrl-C to exit

Glue processing has been prepared in /tmp/Scmbug.30670
Installing part2
Check everything there before I commit or hit Ctrl-C to exit
        

Note

Under Windows, the paths supplied to the installer should have directories separated with a forward (/) slash. Figure 7-2 shows an example running the installer under Windows.

Figure 7-2. Glue Installation in a CVSNT repository under Windows.

C:\Program Files\Scmbug\bin> scmbug_install_glue.pl --scm=CVS --product=sdvel \
--repository=c:/cvsroot --bug=22 --daemon=192.168.136.140 \
--binary-paths="C:/Program Files/CVSNT"
          

7.1.1. CVS

Integration glue can be installed in both local and remote CVS repositories.

After installation, the file <CVS_REPOSITORY_PATH>/CVSROOT/etc/scmbug/glue.conf holds the configuration of the glue.

Warning

CVSNT integration has only been verified to work with a :pserver: configuration. A CVSROOT starting with :local: does not work. This is because of the presumptious way CVSNT handles the CVSROOT variable. Apparently for some configurations it expands it to include the configuration type. The integration hooks use this expanded variable and as a result are pointed to incorrect paths.

Warning

CVSNT uses the two variables Name and Root when configuring a repository, instead of only the CVSROOT variable. When hooks execute, CVSNT sets CVSROOT to be equal to Name. By default, CVSNT sets Name omitting the drive letter. The hooks will not execute if Name is not set to the full path of the repository since $CVSROOT will be referring to a path that does not exist. An example invalid Name/Root configuration is shown in Figure 7-3. An example valid Name/Root configuration is shown in Figure 7-4.

Figure 7-3. Example invalid Name/Root for CVSNT.

Name: /Projects
Root: C:/cvsrepos/Projects
	  

Figure 7-4. Example valid Name/Root for CVSNT.

Name: C:/cvsrepos/Projects
Root: C:/cvsrepos/Projects
	  

Setting Name to be equal to Root produces the warning shown in Figure 7-5. The compatibility problems seem to refer to some clients simply not parsing a CVSROOT with a drive letter in it. If your development environment includes UNIX clients, and problems do occur, one alternative is to let Name lack a drive letter and manually edit the hook files to include the full repository path.

Figure 7-5. CVSNT warning when Name is set to Root.

Using drive letters in repository names can create compatibility problems with
Unix clients and is not recommended. Are you sure you want to continue ?
	  

A major drawback of CVS is it's lack of atomic transactions. As a side-effect, when the same log message is used to commit files in two separate directories, two integration activities are issued using the same log message. Duplicate log messages are then entered in the bug-tracking system. Scmbug solves this problem by using the commitinfo and loginfo hooks to detect commits in separate directories and consolidate the log messages entered in the bug-tracking system as one log message (one integration activity). This behavior is optional and can be configured in the glue configuration file using the consolidate_cvs_messages variable, as shown in Figure 7-6. However, ActiveState ActivePerl does not yet implement the getppid() function. Windows systems running Scmbug need to disable consolidate_cvs_messages.

Figure 7-6. Configuration option that consolidates CVS messages.

# This applies only to CVS. When a commit affects more than
# one directory, multiple duplicate log comments are inserted,
# one-per-directory. Enabling this option would consolidate
# the commits to all use the first log message.
consolidate_cvs_messages => 1
        

7.1.2. Subversion

Subversion repositories do not support installation of the integration glue remotely. Local repository access is required.

After installation, the file <SVN_REPOSITORY_PATH>/hooks/etc/scmbug/glue.conf holds the configuration of the glue.

Subversion does not distinguish between commit activities and creation of tags or branches. It recommends that the user manually creates top-level directories named /trunk, /tags and /branches. When it's time to create a tag or branch, Subversion proposes following the convention of creating a copy of the main trunk using 'svn copy' in the /tags or /branches directories. As a result, the glue must manually detect if an activity_verify issued by Subversion also implies an activity_tag. To do so, it checks for addition of new subdirectories in the directories /tags or /branches. This behavior is defined in the glue configuration file using the label_directories variable, as shown in Figure 7-7.

Figure 7-7. Defining the Subversion labeling directories.

# This applies only to Subversion. It is recommended that tags
# are stored in the 'tags' directory, and branches in the
# 'branches' directory.
label_directories => [
		      'tags',
		      'branches'
		      ]
	

Similarly, Subversion does not distinguish between the main development line and other branches. The glue must manually detect if a changeset is committed under /trunk. This behavior is defined in the glue configuration file using the main_trunk_directories variable, as shown in Figure 7-8.

Figure 7-8. Defining the Subversion main trunk directories.

# This applies only to Subversion. It is recommended that the
# main trunk work is stored in the 'trunk' directory.
main_trunk_directories => [
			   'trunk'
			   ]
	

Note

It is not mandatory that trunk, tags, and branches are created in the root of the repository. A more flexible directory structure can be defined using the product_name_definition variable as shown in Figure 4-17.

7.1.3. Git

Git repositories do not support installation of the integration glue remotely. Local repository access is required.

After installation, the file <GIT_REPOSITORY_PATH>/.git/hooks/etc/scmbug/glue.conf holds the configuration of the glue.