#summary Guidelines for setting up a virtual environment for use with Melange.
#labels Importance-Useful,Phase-Guidelines,Contents-Draft

= Overview =

Project configuration management, particularly with Python, is often the source of lots of frustration and leads to cases of the infamous "it works on my machine" syndrome. Thankfully tools exist to help ease the process; in this case, [https://pypi.python.org/pypi/virtualenv]Virtualenv and [https://pypi.python.org/pypi/pip]Pip can be used in conjunction with Melange (and others) to keep the project isolated from your machine's dependencies and configuration while making it easier for others to duplicate your workflow and environment.

= Setup =

If you don't already have pip installed, go ahead and visit the above link to download the setup package and run the setup script. If you've never installed a system-wide Python package before, simply _cd_ into the  project directory (from Terminal) and run the following line to get going:
{{{
sudo python setup.py install
}}}

Now that you have pip, we're going to use it to install Virtualenv. Briefly, Virtualenv is a Python tool that can be used to create an isolated, virtual environment containing a Python interpreter with packages independent of your system. This is invaluable to simulating a "from scratch" configuration that relieves you of having to deal with dependency issues relating to versioning, compatibility, and other headaches. Back in Terminal, enter the following to install the Virtualenv package:
{{{
sudo pip install virtualenv
}}}

Easy, right? At this point, if you already have a version of Melange checked out then you can ignore this next line. Otherwise, step into that Terminal window and _cd_ to your Projects folder or wherever you are going to store the project folder. Clone the repository: 
{{{
git clone http://code.google.com/p/soc/
}}}
Note: cloning in without your username or password in the URL means that you'll have to enter your username and password every time. However if you look under the Source tab above you'll see instructions to add your Google Code password to your _.netrc_ file that will use those credentials for future git actions.

Now, to actually set up the virtual environment. _cd_ yet again into your new project directory and enter the following:
{{{
virtualenv venv --no-site-packages venv
source venv/bin/activate
pip install django
}}}
_--no-site-packages_ - Prevent virtualenv from including any global package dependencies in your virtual instance.

At this point, you're all set. Before you run Melange or perform any build actions, just type 
{{{
source venv/bin/activate
}}}
to launch virtualenv and use your isolated environment. For example, to build Melange just run the following:
{{{
source venv/bin/activate
python bootstrap.py 
bin/buildout
bin/gen-app-yaml local-devel
bin/paver build --skip-pylint
}}}

Later if you want to do a clean build of Melange, just _rm -rf venv_ and _rm -rf build_ and then repeat the above steps. No need to delete the entire repository!

= Additional Info =

Just a couple of quick tips relating to Git. You'll probably want to do the following:
{{{
# Tell Git to ignore your virtualenv instance
echo "venv" >> .gitignore
}}}
And, if you're feeling sneaky, the following command will allow you to type _git run_ to activate your environment and run a local instance.
{{{
git config alias.run '!source venv/bin/activate; thirdparty/google_appengine/dev_appserver.py build'
}}}

Happy coding!