.. include:: ../links.txt

.. _install:

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

Rum uses `setuptools`_ for its packaging needs so it can be installed, along
with all dependencies, using the ``easy_install`` command::

    $ easy_install rum

However, it is not recommended to install Rum in the system's site-packages
directory due to the potential of a conflict caused by a version mismatch
between the libraries Rum needs and those already present in the system.
This same logic applies to any Python library distributed as a setuptools EGG in
particular and to any Python library in general.

The recommended way to install Rum is in a *virtual* Python environment along
with the rest of packages that are needed by your application and the
application itself. Several tools exist to create these isolated and
reproducible environments, the most popular ones seem to be `zc.buildout`_ and
`virtualenv`_. In this document we will cover how to use ``virtualenv`` for
this purpose.

Create a ``virtualenv``
-----------------------

If you already have ``setuptools`` installed in your system you can use it to
download and install ``virtualenv``::

    $ easy_install virtualenv

Once you have the ``virtualenv`` script installed in your system you can create
the virtual environment like this::

    $ virtualenv /path/where/you/want/the/virtualenv/installed/in

If you don't have ``setuptools`` installed I would recommend **not** to install
it but download a `standalone version of virtualenv`_ which doesn't need
``setuptools`` to be installed and used. This script
will download ``setuptools`` for you and install it **inside** the virtual
environment so your system's Python install is not modified in any way.


Once you have downloaded the standalone version, you can create the virtual
environment with the following command::

    $ python virtualenv.py /path/where/you/want/the/virtualenv/installed/in

.. note::

    You might want to create the virtual environment with the
    ``--no-site-packages`` option to really isolate the environment since that
    will prevent the system-wide installed packages to be used. Use this
    option if ``easy_install`` complains when installing Rum about a version
    mis-match of any dependency. 

Activate the ``virtualenv``
---------------------------

Once the virtualenv directory structure has been created you must *activate* it
in order for the commands we'll be executing next use the executables which live
inside the environment (including ``python``). First of all, change directories
so the directory where the you installed the virtualenv becomes the current
one::

    $ cd /path/where/you/want/the/virtualenv/installed/in

Then, on a \*nix system (linux, macosx, ...) ::

    $ source bin/activate

Or, in a Windows shell::

    $ Scripts/activate.bat

virtualenv will change your shell's prompt with the name of the virtual
environment. To deactivate the virtual environment execute the ``deactivate``
command

Install Rum inside the ``virtualenv``
-------------------------------------

Now you can execute ``easy_install`` to install Rum inside the virtual
environment (make sure it has been activated first!)::

    $ easy_install rum RumAlchemy tw.rum

Note that we also installed two other packages we haven't mentioned, ``tw.rum``
and ``RumAlchemy``. Since Rum is a modular system we'll need some plugins to
do something useful.
    
``RumAlchemy`` is a plugin that enables Rum to be able to introspect and handle
CRUD operations on `SQLAlchemy`_ mapped classes. It is the only data backend
implemented at the moment so we'll install that one.

``tw.rum`` is a plugin that uses `tw.forms`_ to generate views. These views
include forms, tabular grids and other widgets. Again, it is the only
implementation available at the moment so we'll use it.

.. note::
    If you want to implement a plugin to handle other data
    backends or generate views/forms in another way, please consult the
    :ref:`developer_docs`.

Summary
-------

At this point we should have a functional Rum installation inside the virtual
Python environment we created.

If any of the steps above went wrong and cannot figure out how to solve it on
your own you can ask the :ref:`community` for help.