/[collab-maint]/deb-maint/python-support/trunk/README
ViewVC logotype

Contents of /deb-maint/python-support/trunk/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 15642 - (show annotations) (download)
Thu Mar 11 22:42:02 2010 UTC (4 years, 5 months ago) by joss
File size: 8115 byte(s)
* dh_pysupport: fix syntax errors in previous patch.
* README: document that only python is required for arch: all 
  packages, not python-dev. Also talk about python-support itself.
  Closes: #563749.
* dh_pysupport: print an error if the default Python version cannot be 
  found. Closes: #572155.
* parseversions: I hate regexes.
* dh_pysupport: ensure there is a Python dependency even when no 
  specific versions are required. Closes: #568811.
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.

  ViewVC Help
Powered by ViewVC 1.1.5