diff --git a/docs/hackinghowto.rst b/docs/hackinghowto.rst index 40d14e24..a2a153aa 100644 --- a/docs/hackinghowto.rst +++ b/docs/hackinghowto.rst @@ -23,13 +23,21 @@ Second thing to do is take a look at :ref:`codebase-chapter` where we've started documenting how GNU MediaGoblin is built and how to add new things. +Third you'll need to :ref:`get the requirements +`. -How to set up and maintain an environment for hacking -===================================================== +Fourth, you'll need to build a development environment. For this step, there are two options: +1. :ref:`virtualenv ` OR +2. :ref:`buildout and bootstrap ` + +Pick one---don't do both! + + +.. _get-requirements-section: Getting requirements --------------------- +==================== First, you need to have the following installed before you can build an environment for hacking on GNU MediaGoblin: @@ -49,13 +57,94 @@ requirements:: sudo apt-get install mongodb git-core python python-dev \ python-lxml -After getting the requirements, there are two ways to build a development environment: +.. YouCanHelp:: -1. Running bootstrap and buildout, OR -2. Creating a virtual environment + If you have instructions for other GNU/Linux distributions to set + up requirements, let us know! -Pick one---don't do both! +.. _hacking-with-virtualenv: + +How to set up and maintain an environment for hacking with virtualenv +===================================================================== + +.. Note:: + + Either follow the instructions in this section OR follow the ones + in :ref:`hacking-with-buildout`. But don't do both! + + +**Requirements** + +* virtualenv: http://pypi.python.org/pypi/virtualenv +* virtualenv wrapper: http://www.doughellmann.com/projects/virtualenvwrapper/ +* git: http://git-scm.com/ + + +**Create a development environment** + +1. Clone the repository:: + + git clone http://git.gitorious.org/mediagoblin/mediagoblin.git + +2. Create a virtual environment:: + + mkvirtualenv --no-site-packages mediagoblin + +3. If that doesn't put you in the virutal environment you just + created, then do:: + + workon mediagoblin + +4. Run:: + + python setup.py develop + +That's it! + + +**Activating a virtual environment** + +When you want to work on GNU MediaGoblin, you need to activate the +virtual environment like this:: + + workon mediagoblin + + +**Deactivating a virtual environment** + +If you want to deactivate it, you can do this:: + + deactivate + + +**Updating a virtual environment with dependency changes** + +1. Enter the virtual environment. + +2. Run:: + + python setup.py develop + + +**Updating a virtual environment with code changes** + +You don't need to do anything---code changes are automatically +available. + + +**Deleting a virtual environment** + +At some point you may want to delete your virtual environment. +Perhaps it's to start over. Perhaps it's so you can test building +development environments with virtualenv. + +To do this, do:: + + rmvirtualenv mediagoblin + + +.. _hacking-with-buildout: Creating a dev environment with bootstrap and buildout ------------------------------------------------------ @@ -63,9 +152,16 @@ Creating a dev environment with bootstrap and buildout .. Note:: Either follow the instructions in this section OR follow the ones - in the next one---don't do both! + in :ref:`hacking-with-virtualenv`. But don't do both! +**Requirements** + +No additional requirements. + + +**Create a development environment** + After installing the requirements, follow these steps: 1. Clone the repository:: @@ -84,13 +180,7 @@ session stuff, etc). You can change this, but for development purposes this default should be fine. -.. Note:: - - We used `zc.buildout `_ because it - involves fewer steps to get things running and less knowledge of - Python packaging. However, if you prefer to use `virtualenv - `_, that should work just - fine. +**Updating for dependency changes** While hacking on GNU MediaGoblin over time, you'll eventually have to update your development environment because the dependencies have @@ -98,76 +188,38 @@ changed. To do that, run:: ./bin/buildout -.. Note:: - You only need to do this when dependencies are updated. You don't - need to do this when you've made code changes. +**Updating for code changes** +You don't need to do anything---code changes are automatically +available. + + +**Deleting your buildout** + +At some point, you may want to delete your buildout. Perhaps it's to +start over. Perhaps it's to test building development environments +with buildout. + +To do this, do:: + + rm -rf bin develop-eggs eggs mediagoblin.egg-info parts user_dev + + +.. _env_with_virtualenv: Creating a dev environment with virtualenv ------------------------------------------ -.. Note:: - - Either follow the instructions in this section OR follow the ones - in the previous one---don't do both! - -The following assumes you have these things installed: - -1. virtualenv: - - http://pypi.python.org/pypi/virtualenv - -2. virtualenv wrapper: - - http://www.doughellmann.com/projects/virtualenvwrapper/ - -3. git: - - http://git-scm.com/ - - -Follow these steps: - -1. Clone the repository:: - - git clone http://git.gitorious.org/mediagoblin/mediagoblin.git - -2. Create a virtual environment:: - - mkvirtualenv --no-site-packages mediagoblin - -3. If that doesn't put you in the virutal environment you just created, then do:: - - workon mediagoblin - -4. Run:: - - python setup.py develop - - -That's it! - -When you want to work on GNU MediaGoblin, you need to activate the -virtual environment like this:: - - workon mediagoblin - -If you want to deactivate it, you can do this:: - - deactivate - -.. Note:: - - You don't have to do anything additional to move changes you're - making to your virtual environment because the virtual environment - is pointing at the actual code files. - Running the server ================== -Run:: +If you did virtualenv, run:: + + paster serve mediagoblin.ini --reload + +If you did buildout, run:: ./bin/paster serve mediagoblin.ini --reload @@ -179,7 +231,11 @@ You need to do this if you want your media to process and actually show up. It's probably a good idea in development to have the web server (above) running in one terminal and celeryd in another window. -Run:: +If you did virtualenv, run:: + + CELERY_CONFIG_MODULE=mediagoblin.celery_setup.from_celery celeryd + +If you did buildout, run:: CELERY_CONFIG_MODULE=mediagoblin.celery_setup.from_celery ./bin/celeryd @@ -187,13 +243,30 @@ Run:: Running the test suite ====================== -Run:: +If you did virtualenv, run:: + + nosetests + +If you did buildout, run:: ./bin/nosetests -Wiping your environment for a clean-slate ------------------------------------------ +Troubleshooting +=============== + +pymongo.errors.AutoReconnect: could not find master/primary +----------------------------------------------------------- + +If you see this:: + + pymongo.errors.AutoReconnect: could not find master/primary + +then make sure mongodb is installed and running. + + +Wiping your user data +===================== .. Note:: @@ -201,17 +274,6 @@ Wiping your environment for a clean-slate a new instance, you will probably never have to do this. Will plans to do this work and thus he documented it. - -Delete the following directories: - -* bin/ -* develop-eggs/ -* eggs/ -* mediagoblin.egg-info/ -* parts/ -* user_dev/ - - .. YouCanHelp:: If you're familiar with MongoDB, we'd love to get a `script that