we've started documenting how GNU MediaGoblin is built and how to add
new things.
+Third you'll need to :ref:`get the requirements
+<get-requirements-section>`.
-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 <hacking-with-virtualenv>` OR
+2. :ref:`buildout and bootstrap <hacking-with-buildout>`
+
+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:
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:
-Creating a dev environment with bootstrap and buildout
-------------------------------------------------------
+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 the next one---don't do both!
+ in :ref:`hacking-with-buildout`. But don't do both!
-After installing the requirements, follow these steps:
+**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. Bootstrap and run buildout::
+2. Create a virtual environment::
- cd mediagoblin
- python bootstrap.py && ./bin/buildout
+ mkvirtualenv --no-site-packages mediagoblin
+3. If that doesn't put you in the virutal environment you just
+ created, then do::
-That's it! Using this method, buildout should create a ``user_dev``
-directory, in which certain things will be stored (media, beaker
-session stuff, etc). You can change this, but for development
-purposes this default should be fine.
+ workon mediagoblin
+4. Run::
-.. Note::
+ python setup.py develop
- We used `zc.buildout <http://www.buildout.org/>`_ because it
- involves fewer steps to get things running and less knowledge of
- Python packaging. However, if you prefer to use `virtualenv
- <http://pypi.python.org/pypi/virtualenv>`_, that should work just
- fine.
+That's it!
-While hacking on GNU MediaGoblin over time, you'll eventually have to
-update your development environment because the dependencies have
-changed. To do that, run::
- ./bin/buildout
+**Activating a virtual environment**
-.. Note::
+When you want to work on GNU MediaGoblin, you need to activate the
+virtual environment like this::
+
+ workon mediagoblin
- You only need to do this when dependencies are updated. You don't
- need to do this when you've made code changes.
+**Deactivating a virtual environment**
-Creating a dev environment with virtualenv
-------------------------------------------
+If you want to deactivate it, you can do this::
-.. Note::
+ deactivate
- 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:
+**Updating a virtual environment with dependency changes**
-1. virtualenv:
+1. Enter the virtual environment.
- http://pypi.python.org/pypi/virtualenv
+2. Run::
-2. virtualenv wrapper:
+ python setup.py develop
- http://www.doughellmann.com/projects/virtualenvwrapper/
-3. git:
+**Updating a virtual environment with code changes**
- http://git-scm.com/
+You don't need to do anything---code changes are automatically
+available.
-Follow these steps:
+**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
+------------------------------------------------------
+
+.. Note::
+
+ Either follow the instructions in this section OR follow the ones
+ 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::
git clone http://git.gitorious.org/mediagoblin/mediagoblin.git
-2. Create a virtual environment::
+2. Bootstrap and run buildout::
- mkvirtualenv --no-site-packages mediagoblin
+ cd mediagoblin
+ python bootstrap.py && ./bin/buildout
-3. If that doesn't put you in the virutal environment you just created, then do::
- workon mediagoblin
+That's it! Using this method, buildout should create a ``user_dev``
+directory, in which certain things will be stored (media, beaker
+session stuff, etc). You can change this, but for development
+purposes this default should be fine.
-4. Run::
- python setup.py develop
+**Updating for dependency changes**
+While hacking on GNU MediaGoblin over time, you'll eventually have to
+update your development environment because the dependencies have
+changed. To do that, run::
-That's it!
+ ./bin/buildout
-When you want to work on GNU MediaGoblin, you need to activate the
-virtual environment like this::
- workon mediagoblin
+**Updating for code changes**
-If you want to deactivate it, you can do this::
+You don't need to do anything---code changes are automatically
+available.
- deactivate
-.. Note::
+**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::
- 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.
+ rm -rf bin develop-eggs eggs mediagoblin.egg-info parts user_dev
+
+
+.. _env_with_virtualenv:
+
+Creating a dev environment with virtualenv
+------------------------------------------
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
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
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
+===============
-.. Note::
+pymongo.errors.AutoReconnect: could not find master/primary
+-----------------------------------------------------------
- Unless you're doing development and working on and testing creating
- a new instance, you will probably never have to do this. Will
- plans to do this work and thus he documented it.
+If you see this::
+ pymongo.errors.AutoReconnect: could not find master/primary
-Delete the following directories:
+then make sure mongodb is installed and running.
-* bin/
-* develop-eggs/
-* eggs/
-* mediagoblin.egg-info/
-* parts/
-* user_dev/
+Wiping your user data
+=====================
+
+.. Note::
+
+ Unless you're doing development and working on and testing creating
+ a new instance, you will probably never have to do this. Will
+ plans to do this work and thus he documented it.
.. YouCanHelp::
projects / mediagoblin.git / commitdiff