= debug-commons


== TOC
- Overview
- History, Future, Aims
- Requirements
- Install
- Related (sub)projects [intermediate libraries]
- License


== Overview

----
Note: this document is currently being more-or-less duplicate of the
debug-commons homepage. So for the up-to-date information look rather at the
site directly and follow the links there:

http://debug-commons.rubyforge.org/
----

debug-commons currently consist of wrappers around various Ruby debugging
backends. 'Wrapping' in this case means that backends are enriched by
producing/consuming a unified XML-based protocol. Currently there are two
wrappers, one for Ruby "classic debugger" (debug.rb) and another for Kent
Sibilev's ruby-debug gem implementation. Both protocols have a lot in common,
however differ slightly due to the nature of their implementation and
behaviour. Take a look at classic-debug.txt and ruby-debug.txt files for more
detailed information about individual protocols.


== History, Future, Aims

The project was originally developed as part of Ruby Development Tools[1]. The
debugger plugin was mainly developed by Markus Barchfeld with the help of
Christopher Williams, Werner Schuster (murphee), Mirko Stocker (and others) who
work on other parts of RDT. Later Martin Krauskopf, implementing NetBeans
debugger module, wrote to RDT people about possible cooperation on the backend
they had. First official email here:

http://sourceforge.net/mailarchive/forum.php?thread_id=31511654&forum_id=9198

(MK: RDT folks have invested and brought a nice bunch of work. I believe
both sides (and hopefully others) will gain a lot in the end).


This project was founded because there doesn't seem to be a general open source
solution in the Ruby world for debugger-frontend implementers. The aim is to
provide such a solution for anyone who wants to start (or is already working)
on a debugger frontend (standalone GUI debugger, an IDE or editor plugin,
remote CLI-based one, ...). You might take a look at from-time-to-time evolving
Ruby Debugging document:

http://debug-commons.rubyforge.org/misc/ruby-debugging.html

Hopefully, in the future, we will have something similar as e.g. Java has with
its JPDA.

Currently there are RDT and NetBeans contributors working on this common
project - and anyone is very welcome to join.

There are some consideration to be done like joining/supporting a Common
Debugger Protocol (http://www.xdebug.org/docs-dbgp.php), better support for
JRuby, ... [TBD - probably separate TODO] so feel free to join the mailing
list(s) for a discussion about current and feature plans [TBD - link to MLs]


== Requirements
Currently tests fully pass with Ruby 1.8.6. Latest official build of 1.8.5
(p35) seems to end with Segmentation fault on some machines. So better to use
1.8.6 for non-problematic run. JRuby has some problems which are being
subsequently filed (and fixed) into their Tracker. See status on the project's
official website for more details.


== Install
Project is distributed as tarball containing classic-debug backend. Soon there
should be also ruby-debug extension.


== Related (sub)projects [intermediate libraries]
Together with the backends project there are also subprojects containing
libraries intermediating socket communication between backends and a frontend.
Currently only library for Java is there. Hopefully more will come.


== License

See MIT-LICENSE file.

