2.2. Configuration

% mkdir /var/www/codestriker
% cd /var/www/codestriker
% tar zxvf /from/installed/location/codestriker-X.Y.Z.tar.gz
% chown -R apache.apache /var/www/codestriker/codestriker-X.Y.Z
	

2.2.1. Codestriker Database

The $db variable should be set to a DBI URL representing the Codestriker database that was created, as specified in Section 2.1. Basically, if you are using PostgreSQL, this should be:

$db = 'DBI:Pg:dbname=codestrikerdb';

For MySQL, this would be:

$db = 'DBI:mysql:dbname=codestrikerdb';

If your database is situated on a different host, for example "dbhost", this could be modified to:

$db = 'DBI:mysql:dbname=codestrikerdb;host=dbhost';

The database user and password also need to be specified. If your username was "codestriker", and the password was "cspasswd", the settings would be just:

# Database user.
$dbuser = 'codestriker';

# Database password.
$dbpasswd = 'cspasswd';

2.2.2. Email

When a code review topic is created, or a comment against a review is made, an email is sent out as a notification mechanism. Codestriker needs to know what mail host it can use for sending email messages. The configuration file default is "localhost":

# Location of the mailing host.  This is used when sending out codestriker
# comments.
$mailhost = 'localhost';
           

2.2.3. Compression

Some of the HTML pages generated by Codestriker can be quite large, depending on the review size. If your deployment is operating to users outside an intranet, it may be worth enabling this option to enable compression. Note, IE doesn't support receiving compressed HTML, so setting this option will have no effect. Initially, it is best to leave this option turned off (the default), and only to enable it if there is a significant performance problem.

# Indicate whether to try and compress output if the client browser
# supports it.  This can make a tremendous difference in bandwidth,
# especially over slow links.
$use_compression = 0;
	  

2.2.4. Source Code Management Systems

This part of the configuration deals with informing Codestriker what source code control systems you use. By doing this, Codestriker can then display reviews with revision information, and then allow the reviewer to view the entire contents of a file before a change, and with a change applied. When a review is created, the user specifies which source control system it is applied against (there may not be any, if it is just a simple patch or text file). For many Codestriker deployments, there may only be a single SCM system. There is currently support for CVS, Subversion, Perforce, Visual Source Safe, and ClearCase. An example setting could be the following:

@valid_repositories =
    (
     '/home/sits/cvs',
     'http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi /cvsroot',
     'svn:http://svn.collab.net/repos/svn/trunk',
     ':pserver:anonymous:password@cvs.sourceforge.net:/cvsroot',
     'c:/cvsrep',
     'perforce:sits:client@localhost:1666',
     'clearcase:h:\\my_stuff\\view_name\\vob_name'
    );
	  

This is Perl syntax for a list of string values. The first value indicates a CVS repository on the same machine as Codestriker, which has a CVSROOT of /home/sits/cvs.

If you have ViewCVS installed on your site, Codestriker can use it directly for CVS information, if CVS is not installed on the same machine. The second value http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi /cvsroot contain the base URL for accessing ViewCVS, and the second part contains the CVSROOT value of this repository, which is /cvsroot.

Codestriker can also work with other source control systems. There is currently support for CVS, Subversion (http://subversion.tigris.org), Perforce (http://www.perforce.com/), Visual Source Safe (msdn.microsoft.com/ssafe/) and ClearCase. In the future other SCM systems will become available depending on demand and contributions. The third string svn:http://svn.collab.net/repos/svn/trunk is a Subversion repository URL prefixed by "svn:". Codestriker works with both http style repositories, and the stand alone Subversion server. The Subversion repository can be located on another computer than the one running Codestriker.

The next value which is likely to be common for many deployments is an anonymous CVS pserver specification. The string is actually in the same form as a CVS pserver URL. Note you can also use the :ext method with SSH, if the user running the Codestriker application has the ability to connect to the CVS server via SSH (see the configuration file for an example). For more information of setting up anonymous pserver access, please consult the CVS manual. Note if your anonymous account does not have a password, the setting would be (note the colons):

     ':pserver:anonymous:@cvs.sourceforge.net:/cvsroot'
          

The next value is an example of a CVS repository located on a Win32 system. Note that forward slashes are still used as a directory separator.

The next value is a Perforce repository specification, where after the "perforce:" keyword, there is the Perforce user and client, followed by the hostname and port of the Perforce server.

The final value is a ClearCase repository specification, where after the "clearcase:" keyword, is the pathname to a shared snapshot view, where a file of any version can be retrieved from the vob using the "cleartool get" command. It is important that this snapshot view is accessible with the same path specification for all developers. This is because a diff file created by a developer will refer to the snapshot view, and will allow Codestriker to retrieve specific files and versions mentioned in the review text, when necessary. It is also important that the user account running the webserver process has permission to access to the snapshot view.

During a review, it is sometimes beneficial to see the revision history of a file, such as information provided by CVSweb or ViewCVS. You can specify a mapping of repository names to URLs for this purpose, for example:

$file_viewer =
{
    '/home/sits/cvs' => 'http://localhost/cgi-bin/cvsweb.cgi'
};
	  

This indicates that for any review made against the /home/sits/cvs repository, file revision information can be found using the URL specified.

Finally, if you are using CVS, please make sure the $cvs setting is set to the correct path. For UNIX, this is likely to be something like:

# Location of the cvs binary.
$cvs = '/usr/bin/cvs';
	  

For Windows, this could be something like:

# Location of the cvs binary.
$cvs = 'c:/gnu/bin/cvs';
	  

Note the use of '/' (forward-slash) characters, rather than '\' (back-slash). Even under Windows, when setting filenames, you should always use forward slashes.

2.2.5. Bug-Tracking Integration

It is often useful to link the creation of code review topics with the associated bug records that the code is fixing. That way, it is possible to read a bug record, and apart from reading the textual description as to how it has been resolved, Codestriker can add in a link to the code review topic, which shows the actual code which fixed the bug (and any important decisions made in the Codestriker comments). Currently, there is only support for Bugzilla, but it is not difficult to add in support for other systems.

If you don't use Bugzilla (http://bugzilla.mozilla.org), you can skip this section, as by default, there is no linking to a bug tracking system. An example configuration could be as follows:

# Bug tracking type.
$bug_db = 'bugzilla';

# Bug database connection details.
$bug_db_host = 'localhost';
$bug_db_name = 'bugs';
$bug_db_password = 'bugs_password';
$bug_db_dbname = 'bugs';

# Bugzilla codestriker user id.
$bug_db_user_id = '2';
	  

The $bug_db setting indicates to use Bugzilla. If this value is set to '', then no linkage to a bug tracking system is performed (the default).

The $bug_db_host setting indicates the hostname that holds the bugzilla database, while $bug_db_name and $bug_db_password contain the database username and password to connect to the Bugzilla database. The $bug_db_dbname setting contains the Bugzilla database name, which by default is "bugs". You can verify these settings by using mysql to connect to the Bugzilla database interactively.

Codestriker adds "comments" to the appropriate bug record whenever a code review topic has been created against it, or the review's state has changed. To do this, a special Bugzilla user needs to be created which the comments will be created against. Create the user using the Bugzilla interface, and call it "codestriker@yourhost.yourdomain". Then connect to the Bugzilla database using mysql, and execute the following command to determine the userid of the user just created:

SELECT userid FROM profiles WHERE
login_name = 'codestriker@yourhost.yourdomain';
	  

This value should be set into the $bug_db_user_id setting.

# Bugzilla codestriker user id.
$bug_db_user_id = '2';
	  

2.2.6. LXR Integration

Codestriker has been integrated with LXR, so that when performing a review, those identifiers known to LXR will be automatically hyperlinked. This is an enormous aid to the code reviewing process, as you can quickly determine where a variable/function/method/class is defined and where it is used quickly, while studying the proposed changes.

The LXR home page is located at http://lxr.sourceforge.net. The integration has been tested with LXR version 0.9.2.

Its possible that each source code repository is associated with a different LXR deployment. The default configuration file shows an example:

$lxr_map = 
{
    '/home/sits/cvs' => { db => 'DBI:Pg:dbname=lxr',
			  user => 'lxr',
			  password => '',
			  url => 'http://localhost.localdomain/lxr/ident?i='
			},

     'svn:http://svn.collab.net/repos/svn/trunk' =>
                        { db => 'DBI:Pg:dbname=lxr2',
			  user => 'lxr',
			  password => '',
			  url => 'http://localhost.localdomain/lxr2/ident?i='
			}
			  
};
	  

This is basically fancy Perl syntax for a map. In this instance, there are two keys, /home/sits/cvs and 'svn:http://svn.collab.net/repos/svn/trunk, which represent the source control repositories specified above within the @valid_repositories setting.

Each key is mapped to an object containing four attributes. The db attribute is a DBI URL of the LXR database, user is the database username, password is the database password, and url is the URL of the LXR deployment for the identifier search page.

If you don't have LXR installed, you can simply set this variable as follows:

$lxr_map = 
{
};
	  

Also note, LXR at present doesn't seem to work with Taint checking. To avoid warning messages, you'll need to comment out the "PerlTaintCheck On" line in your Apache httpd.conf file, and remove the -T switch at the top of the bin/codestriker.pl.base file.

2.2.7. Deployment Options

There are a number of other options which affect how Codestriker runs. The most important ones are shown below. Unless you have specific reasons to, most intranet deployments of Codestriker can leave these options as is.

# Indicate if topics can be deleted.  Turning this to false can be useful for
# "anonymous" installations of codestriker.
$allow_delete = 1;

# Indicate if topics can be listed/searched.  Turning this to false can be
# useful for "anonymous" installations of Codestriker.
$allow_searchlist = 1;

# Indicate if the repository attribute can be set to a topic.  If this
# is disabled, it won't be possible to view the entire contents of a
# file before the proposed change and/or after.  On some servers (such
# as sourceforge), the firewall doesn't allow CGI scripts to make
# remote connections.
$allow_repositories = 1;

# The following controls project configuration.  Each Codestriker topic is
# a member of a specific project.  Uncomment the option you want
# below.  Note the textual state names below cannot be changed.

# Default option, projects are enabled, but they have no state
# changing operations (ie, projects are always in state 'Open').
@project_states = ('Open');

# Don't use projects at all.  Effectively, an implicit "default
# project" is created and associated with all topics behind the scenes.
# @project_states = ();
#
# Allow for projects to be closed.  Closing a project will
# not allow new topics to be created in that project.
# @project_states = ('Open', 'Closed');
#
# Allow for projects to be deleted.  This is potentially a dangerous
# option to allow, as deleting a project will delete all of its member
# topics as well.  Use with caution.
# @project_states = ('Open', 'Deleted');
#
# Allow for projects to be closed and deleted.  Use with caution.
# @project_states = ('Open', 'Closed', 'Deleted');

# If true, don't display any email addresses in their true form, but
# truncate them, to beat SPAM harvesters.
$antispam_email = 0;
	  

2.2.8. Topic Length Restrictions

As explained by the comments in the configuration file, it is possible to limit the size of code review topics that will be accepted by the system:

# The number of problems found per line drops if the size of the 
# topic is too large. A common inspection pitfall is for authors to 
# attempt to review too much material and then miss problems. 
# These two options allow the Codestriker administrator to limit 
# the length of the topics. Topics that have more lines than 
# $maximum_topic_size_lines are rejected when they are created. 
# Topics that are larger than $suggested_topic_size_lines generate 
# a warning displayed in the topic page, but are accepted into the 
# system. Codestriker measures that length of the topic by counting 
# the number of lines in the topic text.
#
# The Codestriker default of not enforcing any limits is specified by
# settings either option to an empty string. If you are not sure 
# what a reasonable limit would be, start with a suggested_topic_size_lines
# set to 350, and adjust with experience.
$maximum_topic_size_lines = '';
$suggested_topic_size_lines = '';
	  

2.2.9. Comment Email Configuration

By default, whenever a comment it submitted, an email will be sent to the author of the comment, the author of the review, and anyone else who has submitted a comment on the line of code in question. This may not be appropriate for some team processes, and can be changed by setting $allow_comment_email to 0.

# If true, Codestriker will send out emails to the topic owner and
# comment submitter when a comment is added. If this option is false,
# no email will be sent to either the topic owner or the comment
# submitter. Emails about each comment may not be needed if a meeting
# is planned to discuss the topic. If the comment submitter specifies
# a cc user, an email is always sent out, regardless of this setting.
$allow_comment_email = 1;
	   

2.2.10. Default View Topic Line Break Mode

As explained by the comments in the configuration file, it is possible to set the default view topic line break mode, by setting the $default_topic_br_mode variable. There is usually no need to change the default setting unless you regularly review code with very long lines.

# The default line break viewing mode to use in the URL when viewing a
# topic.  Can be either $LINE_BREAK_NORMAL_MODE or $LINE_BREAK_ASSIST_MODE.
# Using $LINE_BREAK_ASSIST_MODE indicates that extra line breaks may be
# used in the topic display if the review has very long code lines.  Using
# $LINE_BREAK_NORMAL_MODE will ensure that the display matches the line
# breaks present in the code.  The line break mode can also be changed
# dynamically in the view topic screen.  There is usually no need to
# change this setting unless you regularly review code with very long
# lines.
$LINE_BREAK_NORMAL_MODE = 1;
$LINE_BREAK_ASSIST_MODE = 2;

$default_topic_br_mode = $LINE_BREAK_NORMAL_MODE;
	  

2.2.11. Default View Topic File View Mode

As explained by the comments in the configuration file, it it possible to specify by default, whether topics display the deltas for all files in the review, or just a single file at a time by default. The viewing mode can be changed dynamically on the view topic screen.

# When displaying a topic, if this value is -1, then all files in the
# topic are displayed in the one page (default old Codestriker
# behaviour).  If the value is 0, then only the first file is shown,
# with links to display the other files.  This is useful for those
# deployments that review a large amount of code.
$default_file_to_view = -1;
	  

2.2.12. Comment Thread Metrics

As explained by the comments in the configuration file, it is possible to defined a number of metrics associated with each comment thread (issue) created in the review.

# Each comment thread (or issue) that is created against a specific
# code line in Codestriker can have a configurable number of
# user-defined metrics recorded against it.
#
# Every site has their own requirements, below are a number of example
# configurations.  The "name" attribute refers to the name of the
# metric being recorded.  The "values" attribute is a list of values
# that this metric can be assigned to.  The "default_value" attribute
# is optional, and indicates what the default value of the metric is
# assigned to.  If this attribute is not specified, then the user will
# be required to specify a value for a metric when creating a new
# comment thread.  This is recommended, so that users think about what
# these values should be, rather than blindly accepting default
# values.  For the "Status" metric below however, it is recording the
# "state" of the thread, so an initial state of "Submitted" is reasonable.
# For the other metrics below, an initial value makes no sense.
# Metric items can have an optional show_on_main_page list that will
# force the numbers of comments with the metric settings to be reported
# on the main page of codestriker. 
$comment_state_metrics =
    [ 
      { name             => 'Status', 
	values           => ['Submitted', 'Invalid', 'Completed'],
	default_value    => 'Submitted',
	show_on_mainpage => ['Submitted' ] 
      }
    ];

# Two metrics defined: Status and Type.
#$comment_state_metrics =
#    [
#      { name=>'Status', values=>['Submitted', 'Invalid', 'Completed'],
#	                default_value=>'Submitted' },
#      { name=>'Type', values=>['Style', 'Minor', 'Major', 'Severe'] }
#    ];
#
# Four metrics defined: Status, Level, Mode and Type.
#$comment_state_metrics =
#    [
#      { name=>'Status', values=>['Submitted', 'Invalid', 'Completed'],
#	                default_value=>'Submitted' },
#      { name=>'Level', values=>['Major', 'Minor'] },
#      { name=>'Mode', values=>['Missing', 'Wrong', 'Unclear', 'Suggestion'] },
#      { name=>'Type', values=>['Logic', 'Data Handling', 'Interface',
#			       'Error Handling', 'Performance', 'Comments',
#			       'Standards'] }
#    ];
#
# Case where no comment thread metrics are to be used.
#$comment_state_metrics = [];
	  

2.2.13. Metrics Support

As explained by the comments in the configuration file, it is possible to maintain software metrics obtained from the code reviewing process. There is also scope for customising Codestriker to track your own software metrics.

# This options configures the metric support in codestriker. You have
# the following options:
#
# $metric_config = "none", "basic", "all", "metric name, metric name, etc"
#
# "none" - turns off all extra metric support in the application. The
# metric page will only display and manage data that is strictly
# required to perform the review.  Codestriker will not require any
# addition data input from the reviewers and authors.  This is the
# default. However, you still get basic data like how many topics are
# being created and how problems are being found.
#
# "basic" - Turns on the metrics that are considered to be essential
# for a metric program. It will require that reviewers and authors
# enter the time spent reviewing the topic, the time spent in the
# review meeting, and the time spent preparing for the review. The
# metric selection assumes that you are following a formal review
# process with a preparation meeting, and a defect review meeting.
#   
#   kickoff time - time spent preparing for the review
#   checking time - time spent actually reviewing the topic.
#   logging meeting duration - the time spent in the logging meeting.
#
# "all" - Turns on all of the metrics that one could possibly want to
# track. The list of metrics is from the book "Software Inspection" by
# Gilb and Graham.  You should probably not use this unless you are
# using a formal process that is well established. You may want to
# enable this temporally to get a idea of the types of metrics that
# are supported.
#
# "name,name" - Lastly, you can pick and chose what metrics you would
# like to enable.  just list the metric names in a comma separated
# list. You can see all of the build in metrics in the
# lib/Codestriker.pm file. For example, if you don't hold a kick off
# meeting, and but do hold a logging meeting, the basic option will not
# quit fit. You should set the $metric_config as:
# $metric_config = "checking time,logging meeting duration".
#
# If you don't like our choices of metrics, the names, descriptions,
# etc feel free to edit the lib/Codestriker.pm. It contains
# documentations on how to add your own metrics into codestriker. It
# is easy to do, and does not require any coding.

$metric_config = "none";