Bloof Script - interactive analysis of software project data

Preface

What is Bloof?

Bloof Script is a user application that provides a script for analysing the evolution of software projects and exporting the results for further processing.

It is build upon the Bloof infrastructure for analytical processing of version control data.

Bloof operates on the version control data of a software project and stores its data in a SQL92-compliant database. Bloof is designed to be open for different version control systems. It also is open for different database products. At the moment Bloof supports the following version control systems:

cvs - concurrent versionng system

Bloof supports the following databaes:

McKoi Database
PostgreSQL Database

Getting started

Before you begin

To use Bloof Script, you will need a Java ^TM runtime environment version 1.4 or greater. Sun provides Java runtimes for Win32, Solaris and Linux from their website at http://www.javasoft.com/j2se/ . IBM also provides various Java runtimes for a number of platforms at http://www.ibm.com/java/jdk/download/ .

When Java has been installed on your system, unpack the Bloof Script distribution file to a directory in your file system. Then you are ready to analyse the software project of your choise. Simply run the script script that is shipped with Bloof Script.

Project sources

CVS controlled Project

Bloof is able to process all sorts of software projects that use CVS as version control system. The input data for processing is the cvs logfile for a module of your repository. This can be the main module or any other submodule.

The following input methos are supported

online access to your cvs repository via pserver
online access to your cvs repository via ssh, rsh
reading cvs log file from your local disk. Read the How to generate cvs log file section for details

How to generate cvs log file

Using the command line cvs tool you can either:

run cvs log > logfile.log in any subtree of the checked-out sources. This command will get the logfile and store it in a file named logfile.log
run cvs rlog modulename > logfile.log This command will get the logfile for the specified module and store it in a file named logfile.log

Note, that you have to be able to access your repository. So be shure, that your CVSROOT variable and CVS_RSH are set correctly. For more details about CVS have a loot at http://www.cvshome.org .

Data storage

Bloof processes the version control data and stores it in database tables. It accesses a database via JDBC . Any DBMS with a JDBC driver and SQL92-compliance can be used. At the moment, Bloof supports the following DBMS.

Internal McKoi Database

Mckoi SQL Database is an SQL (Structured Query Language) Database management system written for the JavaTM platform. Mckoi SQL Database is optimized to run as a client/server database server for multiple clients, however it can also be embedded in an application as a stand-alone database. It is highly multi-threaded and features an extendable object-oriented engine.

How to use McKoi with Bloof?

Bloor is shipped together with the McKoi database. If the user specifies the Default Internal Database connection method, Bloof will run McKoi as embedded database, using the ./bloofd subdirectory of the Bloof application for file storage.

You can also specify another connection to a McKoi database in the Bloof application.

PostgreSQL Database

PostgreSQL is an object-relational database management system (ORDBMS) based on POSTGRES, Version 4.2, developed at the University of California at Berkeley Computer Science Department.

PostgreSQL is an open-source descendant of this original Berkeley code. It provides SQL92/SQL99 language support and other modern features.

How to use Postgres with Bloof?

Bloor originally assumes:

PostgreSQL Database Server is running on localhost on the default Postgres Port
on this Server a user named bloof with password bloof and a database named bloof to which the user has full access exist.

If you have your Postgres Database running on a different machine with different access methods, you can specify your own Database access method in the Bloof application.

Reference to Bloof Script commands

Command	Arguments	Description	Examples
exit
help \| ?		Prints information about the valid commands
import	<project name>< scm parameter >< db parameter >	Imports the specified SCM source into the specified database location	import bloof cvsroot=:pserver:anonymous@cvs.sourceforge.net:/cvsroot/bloof cvspassword= cvsmodule=bloof db=internal
open	< db parameter >	Opens a project from the specified database location	open db=internal
run	< metric parameter >[ file filter ] [ developer filter ] [ time filter ]	Runs the specified metric with the specified filters.	run loc files=/cvsroot/bloof/src/db developers=pekacki time=2003-01-01,2003-05-01
results		Lists the available results of already run metrics
metrics		Lists the available metrics
export	<result=> <file=>	Exports a result into a XML File or to the console	file=export.xml
update		Updates a already opened or imported project	update
exit		Exits the session

Parameters

Id	Parameter	Description	Examples
<project name parameter>	<project=>	Specify the of the project	project=bloof
<scm parameter>	<cvsroot=> <cvspassword=> <cvsmodule=> [cvslogin=][sshserver=<true\|false>]	Specify the CVSROOT according to CVS specification , password, module name and optional login. If external connection mode is SSH, sshserver=true must be specified.	cvsroot=:pserver:anonymous@cvs.sourceforge.net:/cvsroot/bloof cvspassword= cvsmodule=bloof
<db parameter>	<db=<INTERNAL\|MCKOI\|POSTGRES>> [dburl=] [dbuser=] [dbpassword=]	Specify the data for accessing the database. The parameters dburl, dbuser and dbpassword are obligatory if db is not INTERNAL. dburl is the JDBC Url for the database	db=POSTGRES dburl=jdbc:postgresql:// bloofhost:port/bloofdb dbuser=bloof dbpassword=bloof
<metric parameter>	<type=<SQL\|METRIC_NAME>> [sql_query=]	Specify the type of metric. In case of the SQL type, a SQL String must be specified. Otherwise, the name of the metric. The names of all available metrics can be queried with the metrics command.	SQL
<file filter>	<files=file1[,file2,...]>	Specify a file filter consiting of a list of filenames or directorynames.	files=/cvsroot/bloof/src/db/DbAccess.java
<developer filter>	<developers=name1[,name2,...]>	Specify a developer filter consiting of a list of developer names.	developers=rudy,gamma
<time filter>	<time=FROM[,TO]>	Specify a time filter beginning with the data specified in FROM, ending with the optional date specified in TO	time=2001-01-01

Bug Reporting Guidelines

When you find a bug in Bloof we want to hear about it. Your bug reports play an important part in making Bloof more reliable.

The following suggestions are intended to assist you in forming bug reports that can be handled in an effective fashion. No one is required to follow them but it tends to be to everyone's advantage.

We cannot promise to fix every bug right away. If the bug is obvious, critical, or affects a lot of users, chances are good that someone will look into it. It could also happen that we tell you to update to a newer version to see if the bug happens there. Or we might decide that the bug cannot be fixed before some major rewrite we might be planning is done. Or perhaps it is simply too hard and there are more important things on the agenda.

Identifying Bugs

Before you report a bug, please read and re-read the documentation to verify that you can really do whatever it is you are trying. If it is not clear from the documentation whether you can do something or not, please report that too; it is a bug in the documentation. If it turns out that the program does something different from what the documentation says, that is a bug. That might include, but is not limited to, the following circumstances:

A program terminates with a fatal signal or an operating system error message that would point to a problem in the program. (A counterexample might be a "disk full" message, since you have to fix that yourself.)
A program produces the wrong output for any given input.
A program refuses to accept valid input (as defined in the documentation).
A program accepts invalid input without a notice or error message. But keep in mind that your idea of invalid input might be our idea of an extension or compatibility with traditional practice.
Bloof fails to compile, build, or install according to the instructions on supported platforms.

Here "program" refers to any executable, not only the application.

Being slow or resource-hogging is not necessarily a bug. Read the documentation or ask on one of the mailing lists for help in tuning your applications.

Before you continue, check on the TODO list and in the FAQ to see if your bug is already known. If you cannot decode the information on the TODO list, report your problem. The least we can do is make the TODO list clearer.

What to report

The most important thing to remember about bug reporting is to state all the facts and only facts. Do not speculate what you think went wrong, what "it seemed to do" or which part of the program has a fault. If you are not familiar with the implementation you would probably guess wrong and not help us a bit. And even if you are, educated explanations are a great supplement to but no substitute for facts. If we are going to fix the bug we still have to see it happen for ourselves first. Reporting the bare facts is relatively straightforward (you can probably copy and paste them from the screen) but all too often important details are left out because someone thought it does not matter or the report would be understood anyway.

The following items should be contained in every bug report:

The exact sequence of steps from program start-up necessary to reproduce the problem. This should be self-contained; it is not enough to send in a bare error message without the affected logfile. We do not have the time to reverse-engineer your input data, and if we are supposed to make up our own data we would probably miss the problem.
The output you got. Please do not say that it "didn't work" or "crashed". If there is an error message, show it, even if you do not understand it. If the program terminates with an operating system error, say which. If nothing at all happens, say so. Even if the result of your test case is a program crash or otherwise obvious it might not happen on our platform. The easiest thing is to copy the output from the terminal, if possible.
Anything you did at all differently from the installation instructions.
The Bloof version. It is diplayed on application start up in the command line.
Informatin about the Runtime Enviroment. This includes the platform name and version, and Java VM Name an Version.

Do not be afraid if your bug report becomes rather lengthy. That is a fact of life. It is better to report everything the first time than us having to squeeze the facts out of you. On the other hand, if your input files are huge, it is fair to ask first whether somebody is interested in looking into it.

Do not spend all your time to figure out which changes in the input make the problem go away. This will probably not help solving it. If it turns out that the bug cannot be fixed right away, you will still have time to find and share your work-around. Also, once again, do not waste your time guessing why the bug exists. We will find that out soon enough.

When writing a bug report, please choose non-confusing terminology. The software package in total is called Bloof.

Where to report bugs

In general, announce bug reports to the bug report tracker at http://sourceforge.net/tracker/?group_id=71700

Do not send bug reports to any of the user mailing lists, such as bloof-users@sourceforge.net These mailing lists are for answering user questions and their subscribers normally do not wish to receive bug reports. More importantly, they are unlikely to fix them.

Also, please do not send reports to the developers' mailing list bloof-developers@sourceforge.net This list is for discussing the development of Bloof and it would be nice if we could keep the bug reports separate.

If you have a problem with the documentation, the best place to report it is the bug tracker . Please be specific about what part of the documentation you are unhappy with.