Tutorial¶
This tutorial will guide you through setting up your first project using dh-virtualenv. Having some knowledge on how Debian packages work won’t hurt, but it is not necessary a mandatory requirement. You also need some basic build tools, so it is recommended to install build-essential and devscripts packages.
Step 1: Install dh-virtualenv¶
In order to use it, you need to install the dh-virtualenv. If you run Debian Jessie (testing), Debian Sid (unstable) or Ubuntu 14.04 LTS (Trusty), you can install dh-virtualenv simply with apt-get:
sudo apt-get install dh-virtualenv
For more recent packages there is [an unofficial PPA maintained](https://launchpad.net/~spotify-jyrki/+archive/ubuntu/dh-virtualenv) by the author.
For other systems the only way is to build and install it yourself. Steps to do that, after you have cloned the repository are:
sudo apt-get install devscripts python-virtualenv git equivs # Install needed packages
git clone https://github.com/spotify/dh-virtualenv.git # Clone Git repository
cd dh-virtualenv # Move into the repository
sudo mk-build-deps -ri # This will install build dependencies
dpkg-buildpackage -us -uc -b # Build the *dh-virtualenv* package
# and finally, install it (you might have to solve some
# dependencies when doing this):
sudo dpkg -i ../dh-virtualenv_<version>.deb
Step 2: Setup the Debian packaging¶
Grab your favourite Python project you want to use dh-virtualenv
with and set it up. Only requirement is that your project has a
somewhat sane setup.py
and requirements listed in a
requirements.txt
file. Note however that defining any requirements
is not mandatory.
Next you need to define the Debian packaging for your software. To do
this, create a directory called debian
in the project root.
To be able to build a debian package, a few files are needed. First, we need to define the compatibility level of the project. For this, do:
echo "9" > debian/compat
The 9 is a magic number for latest compatibility level, but we don’t
need to worry about that. Next we need a file that tells what our
project is about, a file called control
. Enter a following
debian/control
file:
Source: my-awesome-python-software
Section: python
Priority: extra
Maintainer: Matt Maintainer <matt@example.com>
Build-Depends: debhelper (>= 9), python, dh-virtualenv (>= 0.8)
Standards-Version: 3.9.5
Package: my-awesome-python-software
Architecture: any
Pre-Depends: dpkg (>= 1.16.1), python2.7 | python2.6, ${misc:Pre-Depends}
Depends: ${python:Depends}, ${misc:Depends}
Description: really neat package!
second line can contain extra information about it.
The control
file is used to define the build dependencies, so if you
are building a package that requires for example lxml
, make sure
you define libxml2-dev
in Build-Depends etc.
Depends in the lower section is used to define run-time dependencies.
Following the example above, in case of lxml you would add libxml2
in to the Depends field.
To help keeping your installed virtualenv in sync with the host’s Python
interpreter in case of updates, create a file named
debian/«pkgname».triggers
, where «pkgname»
is what you
named your package in the control
file. It triggers a special script
whenever the Python binary changes; don’t worry, that script is provided
by dh-virtualenv
automatically.
# Register interest in Python interpreter changes (Python 2 for now); and
# don't make the Python package dependent on the virtualenv package
# processing (noawait)
interest-noawait /usr/bin/python2.6
interest-noawait /usr/bin/python2.7
# Also provide a symbolic trigger for all dh-virtualenv packages
interest dh-virtualenv-interpreter-update
Note that if you provide a custom postinst
script with your package,
then don’t forget to put the #DEBHELPER#
marker into it, else the trigger
script will be missing.
Next, we need a changelog file. It is basically a documentation of
changes in your package plus the source for version number for Debian
package builder. Here’s a short sample changelog to be entered in
debian/changelog
:
my-awesome-python-software (0.1-1) unstable; urgency=low
* Initial public release
-- Matt Maintainer <matt@example.com> Fri, 01 Nov 2013 17:00:00 +0200
You don’t need to create this file by hand, a handy tool called
dch
exists for entering new changelog entries.
Now, last bit is left, which is the debian/rules
file. This file
is basically a Makefile that Debian uses to build the package. Content
for that is fairly straightforward:
#!/usr/bin/make -f
%:
dh $@ --with python-virtualenv
And there we go, debianization of your new package is ready!
Step 3: Build your project¶
Now you can just build your project by running dpkg-buildpackage -us
-uc
. Enjoy your newly baked dh-virtualenv backed project! :)