Installation
============

At the time of writing, this package requires a patch for pyodbc
to support the Virtuoso extensions for SPARQL. You only need this
if you want to use the RDFLib store. It is not required for 
SQLAlchemy. The patch is documented at:
http://river.styx.org/ww/2010/10/pyodbc-spasql/index

**NOTE** there has been a backwards-incompatible change with version
0.11 of this package and it requires the newest pyodbc patches from
the above link.

For straightforward usage, it should be sufficient to simply install
the package using *easy_install* or *pip*::

    pip install virtuoso

this should fetch and install the prerequisites. This may fail if you
do not already have *iODBC* or *unixODBC* installed on your system. If 
it succeeded you are now hopefully ready to go!

If you would like to use this with SQLAlchemy you will need to install
it in the usual way::

    pip install sqlalchemy

And likewise for rdflib::

    pip install rdflib

ODBC
----

Connecting to Virtuoso requires *pyodbc*. A simple
configuration is to have an *odbc.ini* containing something 
like::

    [VOS]
    Description     = Virtuoso
    Driver          = /usr/local/lib/virtodbc.so
    Servername      = localhost
    Port            = 1111
    UserName        = dba

If you are installing this package and intend to run the unit
tests, you must have a *DSN* with the name *VOS* configured.

If you use *unixODBC* instead of *iODBC* installed, your ODBC
configuration files might need to be slightly different and in 
any case the location is system dependent and configurable via
environment variables. A complete guide to setting up and 
configuring ODBC is beyond the scope of this document, please
refer to your vendor's documentation for additional guidance.

Development
-----------

This is a general guide, not a set of hard and fast rules. It assumes
that you have *virtualenv* and *pip* installed on the development
system.::

    # create a working environment
    virtualenv vdev

    # activate the environment
    . ./vdev/bin/activate

    # install some useful modules
    pip install mercurial
    pip install nose
    # for working with the documentation
    pip install sphinx
    pip install Sphinx-PyPi-upload

    # install from the mercurial respository
    pip install -e hg+http://bitbucket.org/ww/virtuoso#egg=virtuoso

Once installed you can run the unit tests by changing into the
*vdev/src/virtuoso* directory and running::

    % nosetests -v -s
    test_sqlalchemy.Test01Basic.test_01_table ... ok
    test_sqlalchemy.Test01Basic.test_02_fkey ... ok
    test_sqlalchemy.Test02Object.test_01_insert ... ok
    test_sqlalchemy.Test02Object.test_02_update ... ok
    test_sqlalchemy.Test02Object.test_03_delete ... ok
    test_sqlalchemy.Test03Relation.test_01_create ... ok
    test_sqlalchemy.Test03Relation.test_02_update ... ok
    test_sqlalchemy.Test03Relation.test_03_fkey_violation ... ok
    test_sqlalchemy.Test03Relation.test_04_delete ... ok

    ----------------------------------------------------------------------
    Ran 9 tests in 0.356s

    OK