README

= RDBXML -- XML Databases for Ruby

This package provides wrapper functions to the C++ APIS for BDB XML (Dbxml) and
BDB (Db) as well as pure-Ruby convenience functions (RDBXML).  While the wrapper
layer should be more or less complete, the Ruby interface is still a work in
progress.

== Requirements
* Rake[http://rake.rubyforge.org] >= 7.0
* Oracle BDB XML[http://www.oracle.com/technology/products/berkeley-db/xml/index.html]

== Installation

=== The Easy Way

RDBXML is distributed as a Ruby Gem for easy installation, e.g.
  sudo gem install rdbxml

This will attempt to find the DBXML libaries/headers in the standard paths (plus
/usr/local/) and will use the interface files taken from the dbxml-2.4.13
distribution (the latest version, at the time of this writing).

=== The Right Way

Due to tight dependencies, it's recommended that you obtain, build, and install
the latest version of the DBXML distribution from
Oracle[http://www.oracle.com/technology/software/products/berkeley-db/xml/index.html].

This will ensure that you have the correct versions of the various BDB and
BDBXML libraries, as well as the current SWIG Interface definitions included in
the DBXML distribution.

You then pass the install location of the DBXML distribution to the RDBXML build
system, e.g. (this worked on Mac OS X):

  sudo env DBXML_DIST=/opt/dbxml-2.4.13 gem install rdbxml

You might want to pass extra flags to the compiler/linker (this worked on Linux):

  sudo env CXXFLAGS=-fPIC LDFLAGS=-Wl,-rpath\ /opt/dbxml-2.4.13/lib \
    DBXML_DIST=/opt/dbxml-2.4.13 gem install ./pkg/rdbxml-2.4.13.gem

This will build, test, and install the RDBXML gem.

== Example Usage
  require 'rubygems'
  require 'rdbxml'

  # create database directory
  env_dir = './db-env'
  Dir.mkdir env_dir  unless File.exists? env_dir

  # create environment, database, and container
  env = RDBXML::env env_dir
  db = RDBXML::XmlManager.new env, 0
  docs = db['documents']

  # Create document
  docs['Document Name'] = '<doc>Documet XML</doc>'

  # Read document
  puts docs['Document Name'].to_s

== Disclaimer

This release is still far from feature completeness, and is primarily
intended to test the build system and the BDBXML API wrappers.  Please report
any issues on the RDBXML Website[http://rubyforge.org/projects/rdbxml].

Author::    Steve Sloan (mailto:steve@finagle.org)
Website::   http://rdbxml.rubyforge.org
Rubyforge:: http://rubyforge.org/projects/rdbxml
Copyright:: Copyright (c) 2007 Steve Sloan
License::   MIT