Python-support is a tool to handle byte-compilation of python modules 
when there are several python versions installed on the system.


How does it work?
=================
Python-support looks for modules in /usr/share/python-support.
 * Private modules (.py files that shouldn't be installed in the default 
   sys.path) are handled through a foo.dirs file, which contains a list 
   of directories in which to find modules. If the directory contains a 
   .pyversion file, they will be bytecompiled with the python version 
   described inside, otherwise the current python version will be used.
 * Public modules (.py files that should be installed in the default 
   sys.path) are handled through a foo/ subdirectory, containing a 
   hierarchy as normally found in /usr/lib/pythonX.Y/site-packages/. 
   They will be installed and bytecompiled in each python specific 
   directory: /var/lib/python-support/pythonX.Y/. If a .version file is
   found in /usr/share/python-support/foo/, it will be parsed for the 
   list of python versions the module supports. It should look like 
   e.g.:
	2.2,2.4-
   for a package supporting python2.2, and all versions starting from 
   python2.4.
 * Public extensions (.so files) are handled just like public modules, 
   but extensions for each pythonX.Y version will be searched in
   /usr/lib/python-support/foo/pythonX.Y/ and installed in 
   /var/lib/python-support/pythonX.Y/ together with the corresponding 
   modules. No .version file is needed in this case, and the modules 
   will be installed only for the python versions supported by the 
   extensions.
   ** Note that even if a package only ships extensions, it MUST **
   ** still ship the /usr/share/python-support/foo directory.    **

How to make a package using it?
===============================
All the work is done using dh_pysupport. Most packages built for the 
"old" policy can just be changed to use dh_pysupport instead of 
dh_python, and this should work. Packages building binary extensions 
should also be changed to build the extensions for all python versions 
in a single package.

*** You don't need X[BS]-Python-Version fields. You don't need ***
*** debian/pycompat. You don't need to call dh_python after    ***
*** dh_pysupport. Just remove all of these.                    ***

Of course, don't forget the dependency fields:
	Build-Depends: python-support (>= 0.6), debhelper(>= 5)
	Depends: ${python:Depends}

If you're including public modules or extensions, you should also add
the field:
	Provides: ${python:Provides}

If you're depending on another python module, you should not declare
it in the Depends field, but like this:
	Python-Depends: python-bar (>= some.version)
The appropriate dependencies on python2.X-bar will automatically be
added.

 For a package with only private modules
 ---------------------------------------
In this case, the rules file will probably look like this:

build:
	make ...

install:
	make install DESTDIR=debian/foo/

binary-indep:
	...
	dh_pysupport
	dh_installdeb
	...

If the private modules are not in a default directory (like 
/usr/share/$package or /usr/lib/$package) you should pass the directory 
to dh_pysupport:
	dh_pysupport /usr/share/someframework/foo

If the modules need a specific python version, you can pass the -V 
argument to dh_pysupport; it works exactly like for the old dh_python.
	dh_pysupport -V2.4

 For a package with public modules
 ---------------------------------
If the module doesn't work with all python versions, you should setup a
debian/pyversions file. If the package needs python >= 2.3, it will look
like :
	2.3-
This file will be installed in /usr/share/python-support/foo/.version.

The rules file will look like this:

build:
	...
	python setup.py build

install:
	...
	python setup.py install --root=$(CURDIR)/debian/python-foo

binary-indep:
	...
	dh_pysupport
	dh_installdeb
	...

 For a package with public C extensions:
 ---------------------------------------
First of all, you should build-depend on python-all-dev.

If you want to build the extension only for some python versions, you 
should create a debian/pyversions file as described earlier, and set in 
the rules file:
PYVERS=$(shell pyversions -vr)
You need to build-depend on python (>= 2.3.5-11) for this to work.

Otherwise, you can just build the extensions for all supported python 
versions:
PYVERS=$(shell pyversions -vs)

The rest of the rules file will look like:

build: $(PYVERS:%=build-python%)
	touch $@
build-python%:
	python$* setup.py build
	touch $@

install: build $(PYVERS:%=install-python%)
install-python%:
	python$* setup.py install --root $(CURDIR)/debian/python-foo

binary-arch:
	...
	dh_pysupport
	dh_installdeb
	...

Specific cases
==============
 Packages hardcoding the path to their modules
 ---------------------------------------------
Some packages installing their modules in /usr/lib/python2.X expect
to find them explicitly at that place at runtime. Fortunately this is
uncommon as distutils doesn't allow that, but in this case the module
will stop functioning with python-support. The solution is to install
the files explicitly to /var/lib/python-support. Python-support will
then automatically move them to the appropriate place.

build-%/configure-stamp:
	mkdir build-$*
	cd build-$* && PYTHON=/usr/bin/python$* ../configure --prefix=/usr
	touch $@

build: $(PYVERS:%=build-%/build-stamp)
build-%/build-stamp: build-%/configure-stamp
	$(MAKE) -C build-$* pyexecdir=/var/lib/python-support/python$*
	touch $@

install: build $(PYVERS:%=install-%)
install-%: build-%/build-stamp
	$(MAKE) -C build-$* install pyexecdir=/var/lib/python-support/python$* DESTDIR=$(CURDIR)/debian/tmp

binary-arch:
	...
	dh_pysupport
	dh_installdeb

 Namespace packages
 ------------------
Namespace packages are empty __init__.py files that are necessary for 
other .py files to be considered as Python modules by the interpreter. 
Since version 0.7.1, python-support will add them automatically as 
needed. However, this will be done later than the update-python-modules 
call when dpkg installs the package.

What this means is, if you need a namespace package or depend on a 
package that needs it, *and* that you need to use it during the 
postinst phase (e.g. for a daemon), you will have to add the following 
command before starting your daemon:
	update-python-modules -p