Announcement: first release for Berkeley DB driver for R8

[Scott Lystig Fritchie]

I'll be sending an announcement to the User Contributions editor
shortly.  For those of you who just can't wait for the editor to
create a link at http://www.erlang.org/user.html, the source
distribution can be found at http://www.snookles.com/erlang/.

I'm happy to announce the first public release of an Erlang R8 driver
for Berkeley DB 4.0.  It works quite well, and there aren't any major
bugs or memory leaks that I'm aware of.  Well, that's not quite
true. I don't know if the implementation of the cursor portion of the
DB API is 100% solid when run on a VM with threads support and enabled
(via "erl +A5" or whatever)....  I'll include the README file below,
rearranged slightly for the imaptient reader:

-Scott

--- snip ---

Limitations
===========

See the comments at the top of ../src/berkeley_db.erl for details on
the limitations on this release.  The most noteworthy limitation is
that the transaction subsystem is not yet supported.  I'd started this
project thinking I knew how I'd do it ... but an assumption turned out
to be incorrect.  I'm releasing this now without supporting
transactions so that I have a release "out there" while I work on
getting the transaction subsystem to play nicely with Pthreads
separate from the one running the Erlang VM.


Usage
=====

With few differences, this implementation exposes the Berkeley DB API
as a C programmer sees it.  Users should be familiar with DB's C API
before attempting to use this driver.  The API is documented in the
"docs" subdirectory of the source distribution; it is also available
at http://www.sleepycat.com/docs/index.html.

The regression test functions provide the most concrete examples of
how to write Erlang code to use the driver.


License
=======

I'm going to use the Berkeley BSD license.  See the file "LICENSE" at
the top of the source distribution directory.

I am not an attorney.  As far as I know, the BSD license I'm applying
to the C protion of the driver does not conflict with the Berkeley DB
code's license.  If it turns out that my assumption is incorrect, I
will reissue this distribution with two different licenses: one
compatible with the Berkeley DB license for those files that require
it, and the BSD license for everything else.


Compilation instructions
========================

0. You must have Erlang R8 installed on your system.  I haven't tried
   this driver with R7; I don't know if it would work.

   This driver ought to work on any platform supported both by DB and
   Erlang.  I have only tried it under FreeBSD 4.5, Linux RedHat 6.1,
   and Solaris 8 for Intel/x86.  There shouldn't be any problem with
   FreeBSD 4.x, more recent Linux distributions, or older Solaris
   releases.  I'd appreciate reports on other UNIX platforms....

   This ought to work on Win32 platforms, too, but I haven't tried
   it.  at the very least, the makefile `i have included will not
   work.  Sorry.

1. You must have Berkeley DB version 4.0.14 installed on your system
   before proceeding any further.  Earlier releases of 4.0.x may work,
   but you are on your own if you try it.  Later releases should be
   fine, but since there aren't any newer releases yet, it's tough to
   test.  :-)  The source code can be downloaded at
   http://www.sleepycat.com/download.html.

   Follow the installation docs in the DB distribution.  Shared
   library support is included by default, so you don't need to do
   anything special for it.  If you want to try using the RPC server
   code, add "--enable-rpc" to the arguments you give to "configure".

   I have several different versions of DB installed on my development
   machine, so I added "--prefix=/usr/local/DB4.0" to "configure"'s
   arguments in order to avoid clobbering the other versions.  Note
   that that directory also appears in ../src/Makefile.

   Linux users (and perhaps other platforms) may have to do some
   additional work in order to tell "ldconfig" (or whatever manages
   your shared libraries) where the DB 4.0 shared library is stored.
   In my case, that meant adding a "/usr/local/DB4.0/lib" line to
   /etc/ld.so.conf and then running "ldconfig".  FreeBSD 4.5 didn't
   require any such special magic.  For Solaris 8, you can use "crle"
   to add /usr/local/DB4.0 (or whatever you call it) to the library
   search path, or simply create a couple of symlinks in /usr/lib: "ln
   -s /usr/local/DB4.0/libdb-4.0.so /usr/lib" and "ln -s
   /usr/local/DB4.0/libdb-4.so /usr/lib"

2. Edit ../src/Makefile as appropriate.  All the items that likely
   require changes are near the top.

3. Change directory to ../src if you haven't already.

4. Run "make"

5. Run the following command:

  erl -pz ../ebin -pz ../priv -run berkeley_db regression_test -run erlang halt

You should see the following output:

  Erlang (BEAM) emulator version 5.1.1 [source] [threads:0]
  
  Eshell V5.1.1  (abort with ^G)
  1>              Turning off debugging to insert 25000 records
                  Returning driver debugging to status 0
  
  If you made it this far, the regression test passed.

If Erlang exits with any kind of error (most likely a 'badmatch'
error), then the not-very-complete regression test failed.

6. Copy ../ebin/*.beam and ../priv/*.so to whereever you wish to
   install them.  There doesn't seem to be much tradition or custom
   where dynamic driver files ought to be installed.  (TODO: Figure
   out what better to do here.)  So, for now, copy those files where
   you think is appropriate, and always start "erl" with either "-pa"
   or "-pz" flags specifying the directory(ies) where you installed
   those files.

7. As a former colleague of mine would always say: "Have fun!"