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.

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 and dh_python:
	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