Getting started
===============

As a metaframework TurboGears has a lot of dependencies. As version numbers tend to change quickly, manageing packages is crucial, especially when working withs multiple projects.

Installing TurboGears on Linux
------------------------------

Requirements
............

Installing TurboGears needs basic support by the underlaying python installation.
You should have at least setuptools_ installed. 
If you do not have setuptools installed, you will have to do a custom python installation.
Additionally you will need the virtualenv_ script.
You can install it via your distribution's package manager or, if you do not have appropriate rights, invoke the script directly.

Installation
............

.. highlight:: bash

Tip
  You should never run any of the following commands as root. This protects your default python installation.

First you have create a new virtualenv to house your Turbogears installation::

 $ virtualenv --no-site-packages tg2env

Virtualenv_ creates a custom python installation in the directory tg2env. The additional parameter "--no-site-packages" means, that the environment will not use any extensions installed in your operating system's python installation.

To activate the virtualenv type::

 $ source tg2env/bin/activate

Your command prompt should now include "(tg2env)", which means you are using your custom environment.

Now install TurboGears using::

 (tg2env)$ easy_install -i http://www.turbogears.org/2.0/downloads/current/index tg.devtools

This will download all necessary packages and install them into your virtual environment.
Virtualenv_ allows you to have multiple TurboGears versions with different sets of dependencies installed at the same time.
If one of your environments breaks, you can delete the directory and start over easily.

You can leave the virtualenv at any time using::

 (tg2env)$ deactivate

.. _setuptools: http://pypi.python.org/pypi/setuptools
.. _virtualenv: http://pypi.python.org/pypi/virtualenv

Creating a new TurboGears project
---------------------------------

Tip
  Everything will now happen inside a virtualenv, if not stated otherwise.

The easiest way to start a new project is to use the quickstart command::

 $ paster quickstart

Answer the questions to your likeing.