------------------------------------------------------------------------------

	        Copyright (c) 2000-2006 All rights reserved
	        Alberto Reggiori <areggiori@webweaving.org>
		Dirk-Willem van Gulik <dirkx@webweaving.org>

	           RDFStore - Perl API for RDF Storage

		             Version 0.50

------------------------------------------------------------------------------

DESCRIPTION
-----------

RDFStore is a perl extension to manage RDF [1] data and information directly inside
the perl environment.

PREREQUISITES
-------------

To run RDFStore you need Perl and the following modules properly installed:

    URI (which requires MIME::Base64)
    DBI
    XML::Parser (which requires expat)

The package also need a BerkeleyDB installation, which generally comes with your default OS distribution and the
build script should be able to identify and use. Differently you can download, compile and install a redent version
of the BerkeleyDB software from the SleepyCat Web site http://www.sleepycat.com/ .

INSTALLATION
------------

Try first the following steps:

perl Makefile.PL
make
make test
make install

If it does not work, do not disperate and try the following two alternatives - generally 
compilation errors are due to mis-configuartion of the BerkleyDB parameters (include files, libraries
and library name).

a) Manual configuration
-----------------------

1) Edit the configuration file in this directory named 'arch_conf.in' and change the settings to point to your
   local BDB installation (or the one you want to compile in)
2) Run the 'perl Makefile.PL -v' command
3) Check that the compile paramters you inserted are actually seen by the system
4) Run the usal make sequence of commands as above

b) Interactive configuration
----------------------------

1) Run the 'perl Makefile.PL -i -v' command

   Then you will get prompted to interactively insert the BDB parameters yourself, without requiring to edit the 
   above file by hand. Some basic checking is done on the values you insert.
2) Check that the compile paramters you inserted are actually seen by the system
3) Run the usal make sequence of commands as above

Build the DBMS TCP/IP deamon
----------------------------

To build and install (optional) DBMS support:
 
cd dbms
make
make test
make install
 
(by default the dbmsd get installed under the /RDFStore branch)

Note that the DBMS configuration file dbms/arch.conf is autogenerated by the standard installation procedure above.
If you decide to skip that and change directory directly to the dbms/ directory you might want to edit by hand the
file dbms/arch.conf with your editor and changes the settings (read the comments in the makefile itself for help).

Examples
--------

First have a look to utils/ directory which contains to very basic and useful programs:

utils/rdf.pl

	You can use it to parse, store and serialize your RDF data (see -h option about how to use it)

utils/rdfquery.pl

	You can use it to run general RDQL/Squish queries, either on existing databases (e.g. created with rdf.pl) or
        query public URLs containing RDF/XML. It is also possible to run "remote" RDQL queries on a remote DBMS server
	with a syntax simalr to the following:

		SELECT
			?title, ?link
		FROM
			<rdfstore://rss_database@myserver.mydomain.org:1234>
		WHERE
        		(?item, <rdf:type>, <rss:item>),
        		(?item, <rss::title>, ?title),
        		(?item, <rss::link>, ?link)
		USING
        		rdf for <http://www.w3.org/1999/02/22-rdf-syntax-ns#>,
        		rss for <http://purl.org/rss/1.0/>

utils/rdfdump.pl

	Allows to dump the content of a given RDFStore as RDF/XML or N-Triples syntax. The output by default is sent to
	the STDOUT - the total number of statements is also printed if the '-v' option is specified.

		rdfdump.pl -syntax RDF/XML -storename test -dbms_host localhost

	to dump the content of the 'test' database on the local dbmsd host (generally put under /RDFStore/dbms/te - to create
	a new database see rdf.pl utility above)

For more API specific examples look at the t/*.t perl scripts coming with the distribution and the samples/ directory.

SEEK HELP
---------

Email <areggiori@webweaving.org> or <dirkx@webweaving.org> or emial/subscribe to rdfstore mailing list on yahoo groups 
rdfstore@yahoogroups.com and archived at http://groups.yahoo.com/group/rdfstore

REFERENCES
----------

[1] http://www.w3.org/RDF
[2] http://www.w3.org/TR/rdf-primer/
[3] http://www.w3.org/TR/rdf-mt/
[4] http://www.w3.org/TR/rdf-syntax-grammar/
[5] http://www.w3.org/TR/rdf-schema/
[6] http://www.w3.org/TR/rdf-testcases/
[7] http://www.w3.org/TR/1999/REC-rdf-syntax-19990222/ (obsolete)
[8] http://robustai.net/sailor/grammar/Quads.html

That's all folks!

$Id: INSTALL,v 1.8 2006/06/19 10:10:21 areggiori Exp $
