RP1 Readme File

Owner: penny
$Date: 2002/05/07 21:41:36 $
$Revision: 1.8 $
Javadoc for RP1 API

Introduction

Release Planner is a research project being conducted by Prof., David A. Penny at the University of Toronto, Department of Computer Science. It is supported by BUL, CITO, NSERC, and in-kind support from Sitraka.

The goal is to discover better ways of planning and managing software projects. Further conceptual information is available by reading about the general approach.

This file is top-level documentation for the rp1 file repository. RP1 is a software development project aimed at building tools to support the release planning methodology. This CVS repository stores all information pertinent to the RP1 project, including design documentaion, source code, build environment, and testing environment.

Repository Structure

The rp repository is structured as follows.

Operating Environemnt

The code, source control system, and build environment must be cross-platform capable. To assist in this, GNU tools are used. On Windows platforms, Cygwin is used to provide a UNIX environment for these tools.

For design documentation, we use Microsoft Visio 2002 with Microsoft Word 2000.

For database development and prototyping, we use MS Access 2000.

Source Control

All code and associated documents and files are kept under source control using the CVS system. The root of the CVS repository is on the CSLab UNIX machines, in the directory "/u/penny/.cvsroot", in the repository 'rp'. This repository is owned by user id 'penny' and group 'relplan', and is group writeable. In order to work in the repository, you must have a CSLab acocunt, and you must belong to the group 'relplan'. One possible server machine for accessing this repository is "qew.cs.toronto.edu".

Following is an example of how to check out the rp repository from a CSLab machine.

% export CVSROOT=/u/penny/.cvsroot
% mkdir repo
% cd repo
% cvs checkout rp

Working From Home

CVS can be setup to use an 'rsh' type command for working from non-CSLab machines. CSLab provides secure shell 'ssh' access from remote machines which is 'rsh' compatible. Developers wishing to work from home must first setup SSH (secure remote shell) to be able to securely issue commands from home to their CSLab accounts. Test this independently before attempting a CVS access. The CVS client must then be configuired to use ssh. This is accomplished by setting an environment variable read by CVS appropriately, and then specifying a username and server name as well as a directory for the location of the repository. Once this is done, a separate mirror of the repository can be seamlessly maintained at home. Local ssh resources are available at the CSLAB SSH Resource Page.

Following is an example of how to check out the rp repository from a non-CSLab machine (e.g., at home).

% export CVS_RSH=/usr/local/bin/ssh2
% export CVSROOT=myusername@qew.cs.toronto.edu:/u/penny/.cvsroot
% mkdir repo
% cd repo
% cvs checkout rp

Build Environment

Once the repository has been checked out, a build can be initiated by issuing the command ant in your repository's rp/src directory.

Pre-requisite to a build is installation of the appropriate Java JDK and buildtool, Jakarta Ant. The installed locations of these tools are specified using environment variables. The ant command must be on your path.

% cd rp/src
% export JAVA_HOME=/java/jdk1.3
% export ANT_HOME=/usr/local/ant
% export PATH=${PATH}:${ANT_HOME}/bin
% ant compile
% ant run

Additional tools that may be used in the build are

Build Targets

The project buildfile is rp/src/build.xml. To get an up-to-date list and a brief description of available targets, run
% ant -projecthelp
The buildfile has the following major targets:

Programming Language

100% pure Java will be used throughout this project. The release of Java being used is Java 2 Platform, Standard Edition, Version 1.4. Any and all libraries that come standard with this release, and or any standard, downloadable extension packages may be used. The separately donwloadable extension packages in current use are:

Coding Conventions

Coding conventions follow the standards document written by Sun, "Code Conventions for the Java Programming Language" revised and updated as of April 20, 1999, with the following specializations, modifications, and imperatives.

There is a class rp.util.Debug that should be used for printing out debugging information (which may be at various levels and enabled/disabled using command line arguments), and making various types of boolean assertions about the code. Liberal use of these features is encouraged.

Code Documentation

All packages, interfaces, classes, data members, methods and method parameters will be documented using Javadoc conventions. The following references should be used.

Javadoc is built by the buildfile all at once. Note that there is no incremental build of Javadoc. The root of the generated Javadoc is here.

Libraries

The following Java libraries may be used.

Simple Tasks With CVS

Checking out the Repository

% export CVSROOT=/u/penny/.cvsroot
% mkdir repo
% cd repo
% cvs checkout rp

Bringing a Repo Up-to-Date

% cd repo/rp
% cvs -d -P update
The -d option creates new directories if present.
The -P removes empty directories.

Removing a Repo

% cd repo
% cvs release rp
% rm -rf rp

Adding a Directory

% cd repo/rp/src/rp
% mkdir foo
% cvs add foo
% cvs commit

Adding a File

% cd repo/rp/src/rp/foo
% touch File.java
% cvs add File.java
% cvs commit

Removing a File

% cd repo/rp/src/rp/foo
% rm File.java
% cvs remove File.java
% cvs commit

Removing a Directory

No such notion. Remove all the files from it, and the directory will get removed on the next update (see above).

Renaming a File

% mv old new
% cvs remove old
% cvs add new
% cvs commit

Checking Version History of a File

% cvs log file

Viewing an Older Version of a File

% cvs update -r 1.1 -p file > fileR1.1