README

   1 Python-support is a tool to handle byte-compilation of python modules
   2 when there are several python versions installed on the system.
   3
   4 QUICK GUIDE FOR MAINTAINERS
   5 ===========================
   6
   7  * If necessary, describe the supported versions in debian/pyversions.
   8  * If your package is arch-all:
   9    - Build it using its standard build system.
  10    - Build-depend on python and python-support.
  11  * If your package is arch-any:
  12    - Build it once for every supported Python version (loop over
  13      `pyversions -vr`).
  14    - Build-depend on python-all-dev and python-support.
  15  * Install files to the *standard* locations.
  16  * Call dh_pysupport in the binary-* target.
  17  * Add ${python:Depends} to the dependencies.
  18
  19 And that’s all. Anything else is likely superfluous. If your package
  20 works correctly by doing that (and this is the case of 99% packages),
  21 you can stop reading this file here.
  22
  23
  24 How does it work?
  25 =================
  26 Python-support looks for modules in /usr/share/python-support.
  27  * Private modules (.py files that shouldn't be installed in the default
  28    sys.path) are handled through a foo.private file, which contains a list
  29    of files to bytecompile. If the header of the foo.private file contains
  30    a "pyversion=..." field, they will be bytecompiled with the Python
  31    version described here, otherwise the current Python version will be
  32    used.
  33  * Public modules (.py files that should be installed in the default
  34    sys.path) are handled through a foo.public file, which contains a
  35    list of files to install. The files are normally installed in
  36    /usr/share/pyshared/. They will be installed and bytecompiled in each
  37    Python specific directory: /usr/lib/pymodules/pythonX.Y/. If the header
  38    of the foo.public file contains a "pyversions=..." field, it will be
  39    parsed for the list of python versions the module supports. It should
  40    look like e.g.:
  41         2.2,2.4-
  42    for a package supporting python2.2, and all versions starting from
  43    python2.4.
  44  * Public extensions (.so files) are handled just like public modules:
  45    they are listed in the foo.public file. However, extensions for each
  46    pythonX.Y will be located in /usr/lib/pyshared/pythonX.Y/, while they
  47    are installed in /usr/lib/pymodules/pythonX.Y together with the
  48    corresponding modules.
  49
  50 How to make a package using it?
  51 ===============================
  52 All the work is done using dh_pysupport. For most packages, using the
  53 standard build system then calling dh_pysupport should be enough.
  54 However, if the package builds binary extensions, it should be changed
  55 to build the extensions for all python versions in a single package.
  56 While not mandatory, it is highly recommended.
  57
  58 *** You don't need X[BS]-Python-Version fields. You don't need ***
  59 *** debian/pycompat. You don't need to call dh_python after    ***
  60 *** dh_pysupport. Just remove all of these.                    ***
  61
  62 Of course, don't forget the dependency fields:
  63         Build-Depends: python-support (>= 0.90), debhelper(>= 5)
  64         Depends: ${python:Depends}
  65
  66 If you're including public modules or extensions *and* if some other
  67 packages are expected to need them for a specific (non-default) Python
  68 version, you can also add the field:
  69         Provides: ${python:Provides}
  70
  71 However, if you do that, you need to be very careful. Especially, if
  72 you're depending on another python module, you should not declare it in
  73 the Depends field, but like this:
  74         Python-Depends: python-bar (>= some.version)
  75 The appropriate dependencies on python2.X-bar will automatically be
  76 added.
  77
  78  For a package with only private modules
  79  ---------------------------------------
  80 In this case, the rules file will probably look like this:
  81
  82 build:
  83         make ...
  84
  85 install:
  86         make install DESTDIR=debian/foo/
  87
  88 binary-indep:
  89         ...
  90         dh_pysupport
  91         dh_installdeb
  92         ...
  93
  94 If the private modules are not in a default directory (like
  95 /usr/share/$package or /usr/lib/$package) you should pass the directory
  96 to dh_pysupport:
  97         dh_pysupport /usr/share/someframework/foo
  98
  99 If the modules need a specific python version (like e.g. for Zope), you can
 100 pass the -V argument to dh_pysupport.
 101         dh_pysupport -V2.4
 102
 103  For a package with public modules
 104  ---------------------------------
 105 If the module doesn't work with all python versions, you should setup a
 106 debian/pyversions file. If the package needs python >= 2.3, it will look
 107 like :
 108         2.3-
 109
 110 The rules file will look like this:
 111
 112 build:
 113         ...
 114         python setup.py build
 115
 116 install:
 117         ...
 118         python setup.py install --root=$(CURDIR)/debian/python-foo
 119
 120 binary-indep:
 121         ...
 122         dh_pysupport
 123         dh_installdeb
 124         ...
 125
 126  For a package with public C extensions:
 127  ---------------------------------------
 128 First of all, you should build-depend on python-all-dev.
 129
 130 If you want to build the extension only for some python versions, you
 131 should create a debian/pyversions file as described earlier, and set in
 132 the rules file:
 133 PYVERS=$(shell pyversions -vr)
 134 You need to build-depend on python (>= 2.3.5-11) for this to work.
 135
 136 Otherwise, you can just build the extensions for all supported python
 137 versions:
 138 PYVERS=$(shell pyversions -vs)
 139
 140 The rest of the rules file will look like:
 141
 142 build: $(PYVERS:%=build-python%)
 143         touch $@
 144 build-python%:
 145         python$* setup.py build
 146         touch $@
 147
 148 install: build $(PYVERS:%=install-python%)
 149 install-python%:
 150         python$* setup.py install --root $(CURDIR)/debian/python-foo
 151
 152 binary-arch:
 153         ...
 154         dh_pysupport
 155         dh_installdeb
 156         ...
 157
 158 Specific cases
 159 ==============
 160  Packages hardcoding the path to their modules
 161  ---------------------------------------------
 162 Some packages installing their modules in /usr/lib/python2.X expect
 163 to find them explicitly at that place at runtime. Fortunately this is
 164 uncommon as distutils doesn't allow that, but in this case the module
 165 will stop functioning with python-support. The solution is to install
 166 the files explicitly to /usr/lib/pymodules. Python-support will then
 167 automatically move them to the appropriate place.
 168
 169 build-%/configure-stamp:
 170         mkdir build-$*
 171         cd build-$* && PYTHON=/usr/bin/python$* ../configure --prefix=/usr
 172         touch $@
 173
 174 build: $(PYVERS:%=build-%/build-stamp)
 175 build-%/build-stamp: build-%/configure-stamp
 176         $(MAKE) -C build-$* pyexecdir=/usr/lib/pymodules/python$*
 177         touch $@
 178
 179 install: build $(PYVERS:%=install-%)
 180 install-%: build-%/build-stamp
 181         $(MAKE) -C build-$* install pyexecdir=/usr/lib/pymodules/python$* DESTDIR=$(CURDIR)/debian/tmp
 182
 183 binary-arch:
 184         ...
 185         dh_pysupport
 186         dh_installdeb
 187
 188  Namespace packages
 189  ------------------
 190 Namespace packages are empty __init__.py files that are necessary for
 191 other .py files to be considered as Python modules by the interpreter.
 192 To avoid this being a problem, python-support will add them automatically
 193 as needed. However, this will be done later than the update-python-modules
 194 call when dpkg installs the package, because this is, like
 195 byte-compilation, a time-consuming operation.
 196
 197 What this means is, if you need a namespace package or depend on a
 198 package that needs it, *and* that you need to use it during the
 199 postinst phase (e.g. for a daemon), you will have to add the following
 200 command in the postinst before starting your daemon:
 201         update-python-modules -p
 202
 203  Namespace packages and broken modules
 204  -------------------------------------
 205 Some Python modules like Twisted rely on the fact that there is no
 206 __init__.py file in some directories. THESE PACKAGES ARE BROKEN. You
 207 should try to fix the package first to not rely on such implementation
 208 details.
 209
 210 However, if it turns out not to be possible, you can, as a workaround,
 211 create a file named ".noinit" in the directories where you don't want
 212 __init__.py to be created. In this case, update-python-modules will not
 213 create the namespace package.
 214
 215
 216 Note : Legacy locations
 217 =======================
 218 Packages used to ship files in the following way:
 219  * /usr/share/python-support/$package contained the public modules.
 220  * /usr/lib/python-support/pythonX.Y/$package contained the public
 221    extensions.
 222  * /usr/share/python-support/$package.dirs contained a list of directories
 223    to handle for byte-compilation (for private modules).
 224 These locations are still supported, but deprecated. New packages should
 225 not be using them.