path: root/docs
diff options
authorDamien Lespiau <>2014-09-05 00:46:37 +0100
committerJeremy Kerr <>2014-09-07 20:07:40 +0800
commitc3f6f34ad0b60b812d1b0fd33b5f758f52697f0c (patch)
tree8d6aba3e9930c52641c1d518848c5574c9de90b2 /docs
parente4f09a3605ea8f1efeeb6cae1fdf3bba9dbd412c (diff)
HACKING: Add some documentation about using virtualenv with patchwork
virtualenv is super nice to isolate devevelopment from the python packages installed in the sytem. It also allows to have parallel configurations to run tests againsts. Signed-off-by: Damien Lespiau <> Signed-off-by: Jeremy Kerr <>
Diffstat (limited to 'docs')
1 files changed, 52 insertions, 0 deletions
diff --git a/docs/HACKING b/docs/HACKING
new file mode 100644
index 0000000..b5785bf
--- /dev/null
+++ b/docs/HACKING
@@ -0,0 +1,52 @@
+== Using virtualenv
+It's always a good idea to use virtualenv to develop python software.
+1. Install pip, virtualenv (python-pip, python-virtualenv packages)
+ Because we're going to recompile our dependencies, we'll also need
+ development headers:
+ - For the MySQL/MariaDB setups: mariadb-devel (Fedora)
+2. Create a new virtual environement. Virtual environments are "instances" of
+ your system python, without any of the extra python packages installed.
+ Inside a virtual env, we'll just install the dependencies needed for
+ patchwork and run it from there.
+ Virtual envs are useful to develop and deploy patchwork against a "well
+ known" set of dependencies. They can also be used to test patchwork against
+ several versions of django, creating a separate virtual env per version.
+ $ virtualenv django-1.7
+ will create a virtual env called 'django-1.7' in eponymous directory.
+3. Activate a virtual environment
+ $ sources django-1.7/bin/activate
+ (django-1.7)$
+ The shell prompt is preprended with the virtual env name.
+4. Install the required dependencies
+ To ease this task, it's customary to maintain a list of dependencies in a
+ text file and install them in one go. One can maintain such a list of
+ dependencies per interesting configuration.
+ (django-1.7)$ pip install -r docs/requirements-django-1.7-mysql.txt
+ Of course, this is a one-time step, once installed in the virtual
+ environment, no need to to install the requirements everytime.
+5. Now one can run patchwork within that environment
+ (django-1.7)$ ./apps/ --version
+ 1.7
+ (django-1.7)$ ./apps/ runserver
+6. To exit the virtual environment
+ (django-1.7)$ deactivate
+ $