             FRAMEWORK FOR PORTABLE DATABASE APPLICATIONS
----------------------------------------------------------------------

by Darren Duncan <perl@DarrenDuncan.net>

CONTENTS

* Preface
* Keeping Up To Date
* Requirements
* Installation
* Support
* To Do
* Author

PREFACE

The "Rosetta" distribution features mainly the Perl 5 modules named "Rosetta",
"Rosetta::Schema/::*", "Rosetta::Engine/::*", and "Rosetta::Locale/::*", but
also some related modules like "Rosetta::Driver" and "Rosetta::Driver::Native".
 These constitute the "core" of the Rosetta framework, for RDBMS-generic apps
and schemas.  In addition, there are several documentation-only files.

To get the most out of Rosetta, please also install the "Rosetta-Drivers"
distribution, which includes RDBMS-specific glue that adapts Rosetta to work
with various database products.  Alternately, third parties may have released
Rosetta drivers (subclasses of Rosetta::Driver) in other distributions.

An optional addition is the "Rosetta-Emulators" distribution, which is an extra
layer on top of the Rosetta core that emulates the APIs of other database
accessor modules so that existing apps can use Rosetta as a drop-in replacement
for them.  Another option is "Rosetta-Applications", which constitutes
stand-alone "example" or "utility" applications built on Rosetta.

(Note that the previous two paragraphs are notes for the future; the other
distributions don't exist yet.)

All of my modules have complete POD inside of them, so please refer to that for
a description of module-specific details such as their method APIs.  The file
"lib/Rosetta/Framework.pod" contains the main POD documentation for the Rosetta
framework taken as a whole, including the purpose and overall design structure
of the distribution; it should be read first.  There is also the file 
"lib/Rosetta/SimilarModules.pod" which compares Rosetta to other modules.

This Read Me document concerns itself mainly with installation and support
issues, and also includes any "To Do" lists.

KEEPING UP TO DATE

My module set is constantly under development.  You should be able to find the
newest versions at my website, "http://www.DarrenDuncan.net", on the page called
"Perl Libraries I Made" (name subject to change).  They can also be found on CPAN
under the author name of "DUNCAND".  

I am inclined to update the copies on my web site more often, but those
intermediate versions are more likely to have been tested less, and the modules
may be updated day by day without increasing the version numbers.  However, the
copies on CPAN are guaranteed to have unique version numbers when the module has
changed.

REQUIREMENTS

All of my modules require Perl 5.004 or newer, even though only some of them need
it, in the interest of consistency.  That said, Perl 5.004 is already 3 years 
old, is available as a binary on practically every OS that supports Perl at all, 
and is a very solid release, so I see no reason to support anything older.

The Rosetta core modules don't require anything else.

INSTALLATION

To install these modules, cd to the directory that contains all of the extracted 
distribution files, including this ReadMe file, and type the following:

        perl Makefile.PL
        make
        make test
        make install

The last step probably won't work if you are not the administrator of your 
machine; in that case you either need to get your administrator to install this 
for you, or put it in a your own local directory instead.

The Makefile.PL can do this for you if you substitute something like the 
following for the first line above:

        perl Makefile.PL PREFIX=/tmp/myperl5
        
or:

        perl Makefile.PL PREFIX=/home/me/myperl5

If you are on a Mac system that is older than Mac OS X (Mac OS 9 or earlier)
and/or you are otherwise having problems with the Makefile, you can still
install this module the old fashioned way, by copying.

Every file in the "lib" folder of this distribution goes in its corresponding 
location within the "lib" folder that came with your Perl 5 distribution.

Or alternately, put them anywhere you want, but you will need to have that 
location added to your include path by your main program using something like 
this:

        use lib '/home/me/myperl5/lib';

Then you would want to run the included test programs to make sure the modules
are installed correctly.  Call them like this:

        perl -w t/Rosetta.t
        perl -w t/Rosetta-Schema-DataType.t
        perl -w t/Rosetta-Schema-Table.t
        perl -w t/Rosetta-Schema-View.t

Any existing POD is embedded in the module itself.  The Makefile probably 
extracted it for you in the usual manner, or you can run a POD extractor on it 
yourself to the same effect.  You can also find an HTMLized copy of the POD on 
CPAN and other public source archives; I link to one copy of it on my web site.

SUPPORT

Currently I don't have any support arranged with other people, lists, newsgroups,
or otherwise.  Feel free to ask me if you can't figure things out on your own, or
another person whom you know has used this.  I may start a mailing list for 
support issues later, so that users of my modules can help each other with them.

TO DO

	* Everything, more or less.
	* See the file lib/Rosetta/Framework.pod for the planned time table; it is 
	in the section "SCHEDULE FOR DEVELOPMENT".

AUTHOR

Copyright (c) 1999-2003, Darren R. Duncan.  All rights reserved.  This module
is free software; you can redistribute it and/or modify it under the same terms
as Perl itself.  However, I do request that this copyright information and
credits remain attached to the file.  If you modify this module and
redistribute a changed version then please attach a note listing the
modifications.  This module is available "as-is" and the author can not be held
accountable for any problems resulting from its use.

I am always interested in knowing how my work helps others, so if you put this
module to use in any of your own products or services then I would appreciate
(but not require) it if you send me the website url for said product or
service, so I know who you are.  Also, if you make non-proprietary changes to
the module because it doesn't work the way you need, and you are willing to
make these freely available, then please send me a copy so that I can roll
desirable changes into the main release.

Address comments, suggestions, and bug reports to perl@DarrenDuncan.net.

Share and Enjoy!
