FAM-Ruby 0.2.0 README
=====================

This document was last updated on Tue Dec 05 00:45:30 2006.
Please see the file COPYING for licensing and warranty information.  The
latest version of this library is available at the following URL:
http://www.pablotron.org/software/fam-ruby/.

Introduction
============
FAM-Ruby is a Ruby interface to SGI's File Alteration Monitor
(http://oss.sgi.com/projects/fam/).  FAM allows you to monitor files and
directories for changes (file modification, creation, and removal) -- in
an event-driven manner.  FAM is available on a variety of platforms,
including Irix, Linux, and BSD variants (a patch for systems that use
dnotify is also available).  As of version 0.2.0, FAM-Ruby can also be
used with Gamin (http://www.gnome.org/~veillard/gamin/), a GNOME
library that is compatible with a subset of FAM.  An RDoc-generated API
reference is available in doc/, and a brief description of each event
code is available in event_codes.txt.

System Requirements
===================
- FAM, version 2.6.6.1 (or newer):
  http://oss.sgi.com/projects/fam/
- Ruby, version 1.6.7 (or newer):
  http://www.ruby-lang.org/

If you don't have FAM installed, you can use Gamin instead.  Note that
the FAM-Ruby API changes slightly under Gamin; see "Using FAM-Ruby With
Gamin" below for additional information.

Installation
============
ruby ./extconf.rb            # generate Makefile
make && su -c "make install" # compile and install library

Using FAM-Ruby With Gamin
=========================
Gamin supports a subset of the FAM API, and it adds an additional
method.  The API differences under Gamin are as follows:

  * Fam::Connection#debug_level= is not defined.
  * Fam::Connection#suspend_monitor exists, but doesn't work
  * Fam::Connection#resume_monitor exists, but doesn't work
  * Fam::Connection#monitor_collection exists, but doesn't work
  * Fam::Connection##no_exists is defined (as of Gamin 0.0.23).

Comparing error values between FAM and Gamin will probably fail, since
Gamin defines the same error values (as FamErrlist), but as different
values.

A detailed list of differences between FAM and Gamin is available on the
Gamin page at http://www.gnome.org/~veillard/gamin/differences.html.

About the Author
================
Paul Duncan <pabs@pablotron.org>
http://www.pablotron.org/

See the file AUTHORS for additional contributions.