Get Gentoo!
gentoo.org sites
gentoo.org Wiki Bugs Forums Packages
Planet Archives Sources
Infra Status

Gentoo Archives: gentoo-commits

From: "Arfrever Frehtes Taifersar Arahesis (arfrever)" <arfrever@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] gentoo commit in xml/htdocs/proj/en/Python: developersguide.xml
Date: Sun, 28 Feb 2010 16:47:20
Message-Id: E1NlmIN-0002N7-U4@stork.gentoo.org
1 arfrever 10/02/28 16:47:07
2
3 Modified: developersguide.xml
4 Log:
5 Update documentation.
6
7 Revision Changes Path
8 1.12 xml/htdocs/proj/en/Python/developersguide.xml
9
10 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/Python/developersguide.xml?rev=1.12&view=markup
11 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/Python/developersguide.xml?rev=1.12&content-type=text/plain
12 diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/Python/developersguide.xml?r1=1.11&r2=1.12
13
14 Index: developersguide.xml
15 ===================================================================
16 RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/Python/developersguide.xml,v
17 retrieving revision 1.11
18 retrieving revision 1.12
19 diff -u -r1.11 -r1.12
20 --- developersguide.xml 3 Oct 2009 17:22:17 -0000 1.11
21 +++ developersguide.xml 28 Feb 2010 16:47:07 -0000 1.12
22 @@ -1,13 +1,13 @@
23 <?xml version="1.0" encoding="UTF-8"?>
24 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
25
26 -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/Python/developersguide.xml,v 1.11 2009/10/03 17:22:17 sping Exp $ -->
27 +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/Python/developersguide.xml,v 1.12 2010/02/28 16:47:07 arfrever Exp $ -->
28
29 <guide link="/proj/en/Python/developersguide.xml" lang="en">
30 <title>Gentoo Python Developers Guide</title>
31
32 <author title="Author">
33 - <mail link="dev-zero@g.o">Tiziano Müller</mail>
34 + <mail link="dev-zero@g.o">Tiziano Müller</mail>
35 </author>
36 <author title="Author">
37 <mail link="hawking@g.o">Ali Polatel</mail>
38 @@ -15,21 +15,24 @@
39 <author title="Author">
40 <mail link="pythonhead@g.o">Rob Cakebread</mail>
41 </author>
42 +<author title="Author">
43 + <mail link="arfrever@g.o">Arfrever Frehtes Taifersar Arahesis</mail>
44 +</author>
45
46 <abstract>
47 -This guide is supposed to be a help for (new) Python developers. Besides
48 -valuable hints and tricks, there are guidelines for version bumps and drops,
49 -stabilization, correct eclass usage, correct dependencies and tests.
50 +This guide is supposed to be a help for (new) maintainers of Python packages.
51 +Besides valuable hints and tricks, there are guidelines for version bumps and
52 +drops, stabilization, correct eclass usage, correct dependencies and tests.
53 </abstract>
54
55 <!-- The content of this document is licensed under the CC-BY-SA license -->
56 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
57 <license/>
58
59 -<version>0.3</version>
60 -<date>2008-06-20</date>
61 +<version>0.4</version>
62 +<date>2010-02-28</date>
63
64 -<chapter>
65 +<chapter id="Bumps_Drops_Stabilization">
66 <title>Bumps, Drops, Stabilization</title>
67 <section>
68 <title>Version Bumps and Fixing Bugs</title>
69 @@ -42,7 +45,7 @@
70
71 <ul>
72 <li>dev-lang/python</li>
73 - <li>dev-python/pycrypto</li>
74 + <li>app-admin/eselect-python</li>
75 </ul>
76
77 <p>
78 @@ -79,7 +82,7 @@
79 <body>
80
81 <p>
82 -Every team member should try to keep the package folders clean and uncluttered.
83 +Every team member should try to keep the package directories clean and uncluttered.
84 Besides the obvious checks (last stable for an arch, last not p.masked, other
85 packages depend on an exact version of this package), there are some other
86 things which you should consider before dropping an old version:
87 @@ -109,188 +112,564 @@
88 </section>
89 </chapter>
90
91 -<chapter>
92 -<title>Correct eclass usage</title>
93 +<chapter id="Writing_of_ebuilds">
94 +<title>Writing of ebuilds</title>
95 +<section>
96 +<title>Types of packages</title>
97 +<body>
98 +
99 +<p>
100 +There are 2 types of packages handled by python.eclass:
101 +</p>
102 +
103 +<ul>
104 + <li>Packages supporting installation for multiple versions of Python</li>
105 + <li>Packages not supporting installation for multiple versions of Python</li>
106 +</ul>
107 +
108 +<p>
109 +Packages supporting installation for multiple versions of Python install some files
110 +(usually <path>.py</path> or <path>.so</path>) into directories specific to given
111 +versions of Python.
112 +</p>
113 +
114 +<p>
115 +Packages not supporting installation for multiple versions of Python usually
116 +exhibit at least one of the following properties:
117 +</p>
118 +
119 +<ul>
120 + <li>
121 + They install Python modules outside of site-packages directories.
122 + </li>
123 + <li>
124 + They do not install any files into directories specific to given versions of Python.
125 + </li>
126 + <li>
127 + They install libraries linked against Python library (e.g. <path>libpython2.7.so</path>)
128 + outside of directories specific to given versions of Python (e.g. in <path>/usr/lib</path>)
129 + and filenames of these libraries do not contain Python version.
130 + </li>
131 + <li>
132 + They import Python modules installed by packages not supporting installation for
133 + multiple versions of Python.
134 + </li>
135 +</ul>
136 +
137 +</body>
138 +</section>
139 <section>
140 +<title>Specification of dependency on Python</title>
141 <body>
142
143 <p>
144 -There are currently 3 python related eclasses: <b>python</b>, <b>distutils</b>
145 -and <b>twisted</b>.
146 +Ebuilds should properly specify dependency on supported version(s) of Python.
147 +python.eclass supports <c>PYTHON_DEPEND</c> helper variable, which allows
148 +to specify minimal and maximal version of Python. <c>PYTHON_DEPEND</c>
149 +variable should be set before 'inherit'. <c>PYTHON_DEPEND</c> variable
150 +should contain 1 or 2 groups of version components and can optionally begin with
151 +USE flag conditional in the form of "flag? " or "!flag? ". Each group of version
152 +components should contain major version ("2", "3" or "*") and can optionally contain
153 +minimal version (e.g. "2.6") and maximal version (e.g. "3.1"). Version components
154 +should be separated by colons. Colons followed only by empty components can be
155 +ommitted. "*" major version means that versions of both Python 2 and Python 3 are
156 +accepted. Minimal and maximal versions should contain major and minor versions.
157 </p>
158
159 +<pre caption="Examples of PYTHON_DEPEND">
160 +# Dependency on any version of Python.
161 +<ident>PYTHON_DEPEND</ident>="*"
162 +
163 +# Dependency on any version of Python 2.
164 +<ident>PYTHON_DEPEND</ident>="2"
165 +
166 +# Dependency on any version of Python 3.
167 +<ident>PYTHON_DEPEND</ident>="3"
168 +
169 +# Dependency on any version of Python 2, which is at least 2.6.*.
170 +<ident>PYTHON_DEPEND</ident>="2:2.6"
171 +
172 +# Dependency on any version of Python 3, which is at least 3.2.*.
173 +<ident>PYTHON_DEPEND</ident>="3:3.2"
174 +
175 +# Dependency on any version of Python 2 or 3, which is at least 2.6.*.
176 +<ident>PYTHON_DEPEND</ident>="*:2.6"
177 +
178 +# Dependency on any version of Python 2, which is at least 2.7.*, or a version of Python 3, which is at least 3.2.*.
179 +<ident>PYTHON_DEPEND</ident>="2:2.7 3:3.2"
180 +
181 +# Dependency on any version of Python 2, which is at most 2.6.*.
182 +<ident>PYTHON_DEPEND</ident>="2::2.6"
183 +
184 +# Dependency on any version of Python 3, which is at most 3.2.*.
185 +<ident>PYTHON_DEPEND</ident>="3::3.2"
186 +
187 +# Dependency on any version of Python 2 or 3, which is at most 3.2.*.
188 +<ident>PYTHON_DEPEND</ident>="*::3.2"
189 +
190 +# Dependency on any version of Python 2, which is at least 2.5.* and at most 2.6.*.
191 +<ident>PYTHON_DEPEND</ident>="2:2.5:2.6"
192 +
193 +# Dependency on any version of Python 3, which is at least 3.1.* and at most 3.2.*.
194 +<ident>PYTHON_DEPEND</ident>="3:3.1:3.2"
195 +
196 +# Dependency on any version of Python 2 or 3, which is at least 2.6.* and at most 3.1.*.
197 +<ident>PYTHON_DEPEND</ident>="*:2.6:3.1"
198 +
199 +# Dependency on any version of Python 2, which is at least 2.5.* and at most 2.6.*, or a version of Python 3, which is at least 3.1.* and at most 3.2.*.
200 +<ident>PYTHON_DEPEND</ident>="2:2.5:2.6 3:3.1:3.2"
201 +
202 +# Dependency on any version of Python 2, when "python" USE flag is enabled.
203 +<ident>PYTHON_DEPEND</ident>="python? 2"
204 +
205 +# Dependency on any version of Python 2, which is at least 2.5.*, when "python" USE flag is enabled.
206 +<ident>PYTHON_DEPEND</ident>="python? 2:2.5"
207 +
208 +# Dependency on any version of Python 3, when "minimal" USE flag is disabled.
209 +<ident>PYTHON_DEPEND</ident>="!minimal? 3"
210 +</pre>
211 +
212 </body>
213 </section>
214 <section>
215 -<title>python.eclass</title>
216 +<title>Checking of USE flags of Python</title>
217 <body>
218
219 <p>
220 -Here are some important things to remember when using this eclass:
221 +Ebuilds can set <c>PYTHON_USE_WITH</c> or <c>PYTHON_USE_WITH_OR</c>
222 +before 'inherit' and call <b>python_pkg_setup()</b> to check if Python has been
223 +installed with specific USE flags. All USE flags specified in PYTHON_USE_WITH
224 +must be enabled, but at least one USE flag specified in PYTHON_USE_WITH_OR must
225 +be enabled. <c>PYTHON_USE_WITH_OPT</c> can specify a name of a USE flag,
226 +which conditionalizes PYTHON_USE_WITH and PYTHON_USE_WITH_OR.
227 +If python_set_active_version() (described below) is used, then it must be called
228 +before python_pkg_setup().
229 +</p>
230 +
231 +<pre caption="Example of PYTHON_USE_WITH (check for Tkinter)">
232 +<ident>PYTHON_USE_WITH</ident>="tk"
233 +
234 +<keyword>inherit</keyword> python
235 +
236 +...
237 +
238 +<stmt>pkg_setup</stmt>() {
239 + <keyword>python_set_active_version</keyword> 2
240 + <keyword>python_pkg_setup</keyword>
241 +}
242 +</pre>
243 +
244 +</body>
245 +</section>
246 +<section>
247 +<title>Supporting of installation for multiple versions of Python</title>
248 +<body>
249 +
250 +<p>
251 +Ebuilds should set <c>SUPPORT_PYTHON_ABIS</c>="1" before 'inherit'.
252 +</p>
253 +
254 +<p>
255 +Ebuilds not working with some versions of Python should set <c>RESTRICT_PYTHON_ABIS</c>
256 +variable (e.g. after DEPEND/RDEPEND), which should contain list of space-separated
257 +fnmatch patterns. Such patterns can contain '*' character.
258 +</p>
259 +
260 +<pre caption="Examples of RESTRICT_PYTHON_ABIS">
261 +# Package not supporting Python 2.4.
262 +<ident>RESTRICT_PYTHON_ABIS</ident>="2.4"
263 +
264 +# Package not supporting Python 3.
265 +<ident>RESTRICT_PYTHON_ABIS</ident>="3.*"
266 +
267 +# Package not supporting Python 2.4 and 2.5.
268 +<ident>RESTRICT_PYTHON_ABIS</ident>="2.[45]"
269 +
270 +# Package not supporting Python 2.4 and 3.
271 +<ident>RESTRICT_PYTHON_ABIS</ident>="2.4 3.*"
272 +
273 +# Package not supporting Python 2.4, 2.6, 2.7 and 3.
274 +<ident>RESTRICT_PYTHON_ABIS</ident>="2.4 2.[67] 3.*"
275 +</pre>
276 +
277 +<p>
278 +Separate build directories must be used for different Python versions. Distutils
279 +by default uses "build" directory, which can be changed by "-b" option of "build"
280 +command of setup.py. Packages, which do not use Distutils, and very small number
281 +of packages, which use Distutils, usually need to use build directories outside
282 +of "${S}". Functions from distutils.eclass by default use "<c>${S}/build-${PYTHON_ABI}</c>"
283 +build directories. Packages, which do not use "${S}/build-${PYTHON_ABI}" build
284 +directories, need to call <b>python_copy_sources()</b> function, which copies
285 +sources to separate build directories.
286 +</p>
287 +
288 +<pre caption="Example of python_copy_sources()">
289 +<stmt>src_prepare</stmt>() {
290 + <keyword>epatch</keyword> "<var>${FILESDIR}</var>/<var>${P}</var>-fix_build.patch"
291 + <keyword>python_copy_sources</keyword>
292 +}
293 +</pre>
294 +
295 +<p>
296 +python_copy_sources() can be also used to copy a subdirectory of "${S}" to separate
297 +build directories. It can be useful in ebuilds of packages, which optionally build
298 +Python bindings.
299 +</p>
300 +
301 +<pre caption="Example of python_copy_sources() with a subdirectory of &quot;${S}&quot;">
302 +<stmt>src_prepare</stmt>() {
303 + <keyword>default</keyword>
304 +
305 + if <keyword>use</keyword> python; then
306 + <keyword>python_copy_sources</keyword> bindings/python
307 + fi
308 +}
309 +</pre>
310 +
311 +<p>
312 +<b>python_execute_function()</b> is used to perform appropriate actions with all enabled
313 +Python versions. This function requires one argument, which is name of function
314 +or -d / --default-function option. This function accepts some optional arguments.
315 +python_execute_function() executes a function, which needs to be defined earlier.
316 +To improve readability, it's recommended to define functions, which are used only
317 +in 1 place in ebuilds, directly before passing their names to python_execute_function().
318 +</p>
319 +
320 +<pre caption="Example of python_execute_function()">
321 +<stmt>src_test</stmt>() {
322 + <stmt>testing</stmt>() {
323 + <ident>PYTHONPATH</ident>="build-<var>${PYTHON_ABI}</var>/lib" "<keyword>$(PYTHON)</keyword>" runtests.py
324 + }
325 + <keyword>python_execute_function</keyword> testing
326 +}
327 +</pre>
328 +
329 +<p>
330 +When given actions should be executed in separate build directories created by
331 +python_copy_sources(), then <b>-s</b> / <b>--separate-build-dirs</b> option must be
332 +passed to python_execute_function().
333 +</p>
334 +
335 +<pre caption="Example of python_execute_function() with -s option">
336 +<stmt>src_prepare</stmt>() {
337 + <keyword>epatch</keyword> "<var>${FILESDIR}</var>/<var>${P}</var>-fix_syntax.patch"
338 + <keyword>python_copy_sources</keyword>
339 +}
340 +<stmt>src_configure</stmt>() {
341 + <stmt>configuration</stmt>() {
342 + "<keyword>$(PYTHON)</keyword>" configure.py \
343 + --bindir="<var>${EPREFIX}</var>/usr/bin" \
344 + --destdir="<var>${EPREFIX}</var>$(python_get_sitedir)"
345 + }
346 + <keyword>python_execute_function</keyword> -s configuration
347 +}
348 +</pre>
349 +
350 +<p>If build directories are subdirectories of "${S}", then additionally <b>--source-dir</b>
351 +option and path to source directory must be passed to python_execute_function().
352 +</p>
353 +
354 +<pre caption="Example of python_execute_function() with -s and --source-dir options">
355 +<stmt>src_configure</stmt>() {
356 + <keyword>econf</keyword> \
357 + $(use_with java) \
358 + $(use_with python) \
359 + $(use_with ruby)
360 +
361 + <comment># Python bindings are built/tested/installed manually.</comment>
362 + <keyword>sed</keyword> -e "/SUBDIRS =/s/ python//" -i bindings/Makefile || <keyword>die</keyword> "sed failed"
363 +}
364 +
365 +<stmt>src_compile</stmt>() {
366 + <keyword>default</keyword>
367 +
368 + if <keyword>use</keyword> python; then
369 + <keyword>python_copy_sources</keyword> bindings/python
370 + <stmt>building</stmt>() {
371 + <comment># Override paths stored in bindings/python-${PYTHON_ABI}/Makefile files by 'configure'.</comment>
372 + <keyword>emake</keyword> PYTHON="$(PYTHON)" PYTHON_INCLUDEDIR="$(python_get_includedir)" PYTHON_LIBDIR="$(python_get_libdir)"
373 + }
374 + <keyword>python_execute_function</keyword> -s --source-dir bindings/python building
375 + fi
376 +}
377 +</pre>
378 +
379 +<p>
380 +<b>-d</b> / <b>--default-function</b> option is useful in cases, when the same
381 +actions, which are executed in default phase functions (e.g. emake in src_compile()),
382 +need to be executed. This option can be used only in a subset of ebuild phases.
383 +</p>
384 +
385 +<pre caption="Example of python_execute_function() with -d option">
386 +<stmt>src_compile</stmt>() {
387 + <keyword>python_execute_function</keyword> -d -s
388 +}
389 +</pre>
390 +
391 +<p>
392 +python.eclass defines the following phase functions, which can be used to simplify
393 +some ebuilds:
394 </p>
395
396 <ul>
397 - <li>Call python_version before using PYVER, PYVER_MINOR or PYVER_MAJOR.</li>
398 - <li>
399 - Insert a line "NEED_PYTHON=MY_VERSION" before the inherit to depend on
400 - python. If you don't need a specific version, put <c>virtual/python</c> in
401 - DEPEND/RDEPEND.
402 - </li>
403 - <li>
404 - If you don't use <b>distutils</b> (and/or your package installs
405 - <path>.py</path> files somewhere else than site-packages), you have to call
406 - python_mod_optimize and python_mod_cleanup yourself. If your package doesn't
407 - install itself into a subdir, omit "/YOURPACKAGE". You can pass any path you
408 - want to python_mod_optimize/cleanup. python_mod_cleanup will also remove
409 - empty directories after the cleanup. If you call python as root,
410 - <path>.py</path> files will get byte-compiled to <path>.pyc</path> but not
411 - recorded in the package's CONTENTS. They therefore won't get removed on
412 - update/removal of the package.
413 - </li>
414 + <li>python_src_prepare</li>
415 + <li>python_src_configure</li>
416 + <li>python_src_compile</li>
417 + <li>python_src_test</li>
418 + <li>python_src_install</li>
419 </ul>
420
421 -<pre caption="Optimize/cleanup idiom">
422 -<keyword>inherit</keyword> python multilib
423 +<p>python_src_prepare() calls 'python_copy_sources', while other phase functions call
424 +'python_execute_function -d -s'. If <c>PYTHON_EXPORT_PHASE_FUNCTIONS</c>="1"
425 +variable has been set before 'inherit', then these phase functions are exported.
426 +</p>
427
428 -[...]
429 +<p>
430 +<c>PYTHON_ABI</c> variable can be checked inside function executed by python_execute_function().
431 +</p>
432
433 -<stmt>pkg_postinst()</stmt> {
434 - <keyword>python_mod_optimize</keyword> $(python_get_sitedir)/YOURPACKAGE
435 -}
436 +<pre caption="Example of python_execute_function() with a function checking PYTHON_ABI variable">
437 +<stmt>src_prepare</stmt>() {
438 + <keyword>python_copy_sources</keyword>
439
440 -<stmt>pkg_postrm()</stmt> {
441 - <keyword>python_mod_cleanup</keyword>
442 + patching() {
443 + [[ "<var>${PYTHON_ABI}</var>" == 3.* ]] &amp;&amp; return
444 + <keyword>epatch</keyword> "<var>${FILESDIR}</var>/<var>${P}</var>-python-3.patch"
445 + }
446 + <keyword>python_execute_function</keyword> --action-message 'Applying patches with $(python_get_implementation) $(python_get_version)' -s patching
447 }
448 </pre>
449
450 <impo>
451 -If the package's setup byte-compiles installed <path>.py</path> files, it's a
452 -good idea to disable this and use python_mod_optimize to prevent unexpected
453 -problems.
454 +<b>--action-message</b> and <b>--failure-message</b> options of python_execute_function()
455 +accept arguments, which are internally evaluated, so single quotes might be useful.
456 </impo>
457
458 +<p>
459 +Sometimes another eclass defines a specialized function, which performs building,
460 +installation etc., but is designed for non-Python packages. In such cases, it's
461 +possible to call python_execute_function() with name of such a function.
462 +</p>
463 +
464 +<pre caption="Example of python_execute_function() with a function from another eclass">
465 +<stmt>src_configure</stmt>() {
466 + <keyword>python_execute_function</keyword> -s gnome2_src_configure
467 +}
468 +</pre>
469 +
470 </body>
471 </section>
472 <section>
473 -<title>distutils.eclass</title>
474 +<title>Setting of active version of Python in packages not supporting installation for multiple versions of Python</title>
475 +<body>
476 +
477 +<p>
478 +If given package supports only Python 2 or only Python 3, then <b>python_set_active_version()</b>
479 +function should be called to set active version of Python. Usually major version
480 +of Python should be passed to this function.
481 +</p>
482 +
483 +<pre caption="Example of python_set_active_version() with major version of Python">
484 +<stmt>pkg_setup</stmt>() {
485 + <keyword>python_set_active_version</keyword> 2
486 +}
487 +</pre>
488 +
489 +<p>
490 +If given package supports only 1 version of Python, then Python ABI (in the form
491 +of ${major_version}.${minor_version}) can be passed to python_set_active_version().
492 +It will cause that python-updater will ignore this package.
493 +</p>
494 +
495 +<pre caption="Example of python_set_active_version() with Python ABI">
496 +<stmt>pkg_setup</stmt>() {
497 + <keyword>python_set_active_version</keyword> 3.1
498 +}
499 +</pre>
500 +
501 +</body>
502 +</section>
503 +<section>
504 +<title>Getter functions</title>
505 <body>
506
507 <ul>
508 <li>
509 - To depend on a specific version of python, put NEED_PYTHON=MY_VERSION before
510 - the inherit (rather than DEPEND/RDEPEND on
511 - <c>dev-lang/python-MY_VERSION</c>) or leave it away to implicitly depend on
512 - <c>virtual/python</c> through the <b>distutils</b> eclass.
513 + <b>PYTHON</b> prints filename of Python interpreter (e.g. <path>python3.2</path>).
514 + </li>
515 + <li>
516 + <b>PYTHON</b> with <b>-a</b> / <b>--absolute-path</b> option prints absolute path to Python interpreter (e.g. <path>/usr/bin/python3.2</path>).
517 + </li>
518 + <li>
519 + <b>python_get_implementation</b> prints name of Python implementation (e.g. CPython).
520 + </li>
521 + <li>
522 + <b>python_get_implementational_package</b> prints category, name and slot of package providing Python implementation (e.g. dev-lang/python:3.2).
523 + </li>
524 + <li>
525 + <b>python_get_includedir</b> prints path to Python include directory (e.g. <path>/usr/include/python3.2</path>).
526 + </li>
527 + <li>
528 + <b>python_get_libdir</b> prints path to Python library directory (e.g. <path>/usr/lib64/python3.2</path>).
529 + </li>
530 + <li>
531 + <b>python_get_sitedir</b> prints path to Python site-packages directory (e.g. <path>/usr/lib64/python3.2/site-packages</path>).
532 + </li>
533 + <li>
534 + <b>python_get_library</b> prints path to Python library (e.g. <path>/usr/lib64/libpython3.2.so</path>).
535 + </li>
536 + <li>
537 + <b>python_get_library</b> with <b>-l</b> / <b>--linker-option</b> option prints Python library in the form of -l${library} linker option (e.g. -lpython3.2).
538 + </li>
539 + <li>
540 + <b>python_get_version</b> prints major and minor version of Python (e.g. 3.2).
541 + </li>
542 + <li>
543 + <b>python_get_version</b> with <b>--major</b> option prints major version of Python (e.g. 3).
544 </li>
545 <li>
546 - If the ebuild name (in ${PN}) differs from the folder created by the package
547 - in <path>site-packages/</path>, you have to define a variable PYTHON_MODNAME
548 - to tell <b>distutils</b> where to look for the module.
549 + <b>python_get_version</b> with <b>--minor</b> option prints minor version of Python (e.g. 2).
550 </li>
551 <li>
552 - Set the DOCS variable to install additional (pure-text) docs. If you write
553 - the src_install-function, you can put the definition of the DOCS var in the
554 - function but before calling distutils_src_install.
555 + <b>python_get_version</b> with <b>--micro</b> option prints micro version of Python (e.g. 0).
556 </li>
557 </ul>
558
559 -<pre caption="PYTHON_MODNAME usage (example from ipython-0.7.3.ebuild)">
560 -<comment># Copyright 1999-2007 Gentoo Foundation</comment>
561 -<comment># Distributed under the terms of the GNU General Public License v2</comment>
562 -<comment># $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/Python/developersguide.xml,v 1.11 2009/10/03 17:22:17 sping Exp $</comment>
563 -
564 -<ident>NEED_PYTHON</ident>=2.3
565 -
566 -<keyword>inherit</keyword> distutils
567 -
568 -<ident>DESCRIPTION</ident>="An advanced interactive shell for Python."
569 -<ident>HOMEPAGE</ident>="http://ipython.scipy.org/"
570 -<ident>SRC_URI</ident>="http://ipython.scipy.org/dist/${P}.tar.gz"
571 -
572 -<ident>LICENSE</ident>="BSD"
573 -<ident>SLOT</ident>="0"
574 -<ident>KEYWORDS</ident>="~amd64 ~ia64 ~ppc ~s390 ~x86"
575 -<ident>IUSE</ident>="doc examples emacs gnuplot test"
576 -
577 -<ident>DEPEND</ident>="test? ( dev-python/pexpect )"
578 -<ident>RDEPEND</ident>="gnuplot? ( dev-python/gnuplot-py )"
579 -
580 -<ident>PYTHON_MODNAME</ident>="IPython"
581 -
582 -[...]
583 -</pre>
584 -
585 -<pre caption="DOCS idiom">
586 -<stmt>src_install()</stmt> {
587 - <ident>DOCS</ident>="foo.txt bar.txt"
588 - <keyword>distutils_src_install</keyword>
589 - <keyword>dohtml</keyword> foo.html bar.png
590 +<pre caption="Example of python_get_includedir()">
591 +<stmt>src_install</stmt>() {
592 + ...
593 +
594 + <stmt>install_headers</stmt>() {
595 + <keyword>insinto</keyword> "$(python_get_includedir)"
596 + <keyword>doins</keyword> include/*.h
597 + }
598 + <keyword>python_execute_function</keyword> -q install_headers
599 }
600 </pre>
601
602 -<note>
603 -distutils.eclass defines the DDOCS variable with common doc file names and they
604 -are installed by default as docs. If the name of the doc file you want to
605 -install is there you don't have to specify a DOCS variable.
606 -</note>
607 +<impo>
608 +To call Python interpreter in ebuilds, "<b>$(PYTHON)</b>" should be used.
609 +</impo>
610 +
611 +<p>
612 +In ebuilds supporting installation for multiple versions of Python, sometimes
613 +given action needs to be executed only once (e.g. generation of documentation).
614 +In such cases it should be executed with the final Python ABI from the list of
615 +enabled ABI, which is performed by passing <b>-f</b> / <b>--final-ABI</b> option
616 +to appropriate getter functions.
617 +</p>
618
619 -<pre caption="DDOCS variable in distutils.eclass">
620 -<ident>DDOCS</ident>="CHANGELOG KNOWN_BUGS MAINTAINERS PKG-INFO CONTRIBUTORS TODO NEWS"
621 -<ident>DDOCS</ident>="<var>${DDOCS}</var> Change* MANIFEST* README*"
622 +<pre caption="Example of PYTHON() with -f option">
623 +<stmt>src_compile</stmt>() {
624 + <keyword>distutils_src_compile</keyword>
625 +
626 + if <keyword>use</keyword> doc; then
627 + "<keyword>$(PYTHON -f)</keyword>" setup.py pudge
628 + fi
629 +}
630 </pre>
631
632 </body>
633 </section>
634 <section>
635 -<title>twisted.eclass</title>
636 +<title>Shebangs in installed scripts</title>
637 <body>
638
639 <p>
640 -TBD
641 +Shebangs in installed scripts should be correct to avoid problems when a different
642 +version of Python is set as main active version of Python. If given package does
643 +not support some versions of Python and build system installs scripts with too
644 +generic shebangs, then <b>python_convert_shebangs()</b> should be called to convert
645 +shebangs. This function requires Python version and files / directories. Directories
646 +can be passed only with <b>-r</b> / <b>--recursive</b> option.
647 </p>
648
649 +<pre caption="Example of python_convert_shebangs()">
650 +<stmt>src_prepare</stmt>() {
651 + <keyword>python_convert_shebangs</keyword> -r 2 .
652 +}
653 +</pre>
654 +
655 </body>
656 </section>
657 -</chapter>
658 -
659 -<chapter>
660 -<title>Ebuild writing</title>
661 <section>
662 +<title>Handling of byte-compiled modules</title>
663 <body>
664
665 <p>
666 -Here are some important things to keep in mind when writing ebuilds for python
667 -packages.
668 +Byte-compilation of Python modules is usually disabled. <b>python_enable_pyc()</b> enables
669 +it, while <b>python_disable_pyc()</b> disables it.
670 </p>
671
672 -</body>
673 -</section>
674 -<section>
675 -<title>Calling python in ebuilds</title>
676 -<body>
677 -
678 <p>
679 -To call python in one of your ebuilds, use "${python}" to do it (defined in
680 -distutils.eclass).
681 +<b>python_mod_optimize()</b> is used to compile and optimize Python modules in
682 +pkg_postinst() phase. <b>python_mod_cleanup()</b> is used to remove compiled and
683 +optimized Python modules in pkg_postrm(). Ebuilds, which use distutils.eclass and
684 +install Python modules into site-packages directories, usually do not need to
685 +directly call python_mod_optimize() or python_mod_cleanup(). Paths of modules
686 +installed into site-packages directories should be relative to site-packages
687 +directories. Other paths should be relative to ${ROOT}. python_mod_cleanup()
688 +removes empty directories after cleaning up <path>.py</path> files.
689 </p>
690
691 +<pre caption="Example of python_mod_optimize() and python_mod_cleanup()">
692 +<stmt>pkg_postinst()</stmt> {
693 + <keyword>python_mod_optimize</keyword> PyQt4
694 +}
695 +
696 +<stmt>pkg_postrm()</stmt> {
697 + <keyword>python_mod_cleanup</keyword> PyQt4
698 +}
699 +</pre>
700 +
701 +<impo>
702 +If the package's build system byte-compiles installed <path>.py</path> files, it's
703 +a good idea to disable this and use python_mod_optimize() to prevent unexpected
704 +problems.
705 +</impo>
706 +
707 </body>
708 </section>
709 <section>
710 -<title>Checking for tkinter support</title>
711 +<title>Usage of distutils.eclass</title>
712 <body>
713
714 -<p>
715 -To check whether python has tkinter support you can use one of
716 -python_tkinter_exists (from python.eclass) or distutils_python_tkinter (from
717 -distutils.eclass) in pkg_setup. These two functions are identical.
718 -</p>
719 +<ul>
720 + <li>
721 + <b>distutils_src_compile()</b>, <b>distutils_src_test()</b> and
722 + <b>distutils_src_install()</b> internally perform actions appropriate for given
723 + type of package. In ebuilds supporting installation for multiple versions of Python,
724 + they define some functions and pass their names to python_execute_function().
725 + </li>
726 + <li>
727 + If the ebuild name (in ${PN}) differs from the directory created by the package
728 + in <path>site-packages/</path>, then ebuild should define a variable
729 + <c>PYTHON_MODNAME</c> variable to tell <b>distutils_pkg_postinst()</b>
730 + and <b>distutils_pkg_postrm()</b> paths of Python modules.
731 + </li>
732 + <li>
733 + Ebuilds can set <c>DOCS</c> variable to tell <b>distutils_src_install()</b>
734 + to install additional (pure-text) documentation files.
735 + </li>
736 +</ul>
737 +
738 +<pre caption="Example of PYTHON_MODNAME (from dev-python/ipython)">
739 +<ident>PYTHON_MODNAME</ident>="IPython"
740 +</pre>
741 +
742 +<note>
743 +distutils_src_install() installs some documentation files by default.
744 +</note>
745 +
746 +<pre caption="Documentation files installed by default">
747 +<ident>default_docs</ident>="AUTHORS Change* CHANGELOG CONTRIBUTORS KNOWN_BUGS MAINTAINERS MANIFEST* NEWS PKG-INFO README* TODO"
748 +</pre>
749
750 </body>
751 </section>
752 </chapter>
753
754 -<chapter>
755 +<chapter id="Common_Problems_and_Mistakes">
756 <title>Common Problems and Mistakes</title>
757 <section>
758 <body>
759 @@ -394,15 +773,21 @@
760 the default search path for module files. Here are two examples:
761 </p>
762
763 -<pre caption="src_test of dev-python/mechanize-0.1.7b -- a pure python module">
764 +<pre caption="Example of src_test() from a pure-Python module">
765 <stmt>src_test()</stmt> {
766 - <ident>PYTHONPATH</ident>=build/lib/ "<var>${python}</var>" test.py || <keyword>die</keyword> "tests failed"
767 + <stmt>testing</stmt>() {
768 + <ident>PYTHONPATH</ident>="build-<var>${PYTHON_ABI}</var>/lib" "<keyword>$(PYTHON)</keyword>" test.py
769 + }
770 + <keyword>python_execute_function</keyword> testing
771 }
772 </pre>
773
774 -<pre caption="src_test of dev-python/pyme-0.6.0-r1 -- a python module written in C">
775 +<pre caption="Example of src_test() from a Python module written in C">
776 <stmt>src_test()</stmt> {
777 - <ident>PYTHONPATH</ident>="<var>$(ls -d build/lib.*)</var>" "<var>${python}</var>" examples/genkey.py || <keyword>die</keyword> "genkey test failed"
778 + <stmt>testing</stmt>() {
779 + <ident>PYTHONPATH</ident>="$(ls -d build-<var>${PYTHON_ABI}</var>/lib.*)" "<keyword>$(PYTHON)</keyword>" test.py
780 + }
781 + <keyword>python_execute_function</keyword> testing
782 }
783 </pre>
Report Message
Find on MARC Find on Google Groups