Differences between revisions 12 and 50 (spanning 38 versions)
Revision 12 as of 2006-05-02 07:59:52
Size: 7299
Editor: ?Duck
Comment: Removed clean rule in cdbs eg (no bytecompilation for p-s + #252134 closed)
Revision 50 as of 2017-12-11 07:38:11
Size: 6441
Editor: ?chrysn
Comment: the naming of source packages is a difficult matter (as has shown #debian-python)
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
## page was renamed from DebianPythonFAQ
#language en
#pragma section-numbers 2
Line 3: Line 7:
This is the FAQ of the debian-python@l.d.o mailing list. It is of particular interest to members of the [http://python-modules.alioth.debian.org/ Debian Python Modules Team]. This is the FAQ of the debian-python@l.d.o mailing list. It is of particular interest to members of the [[Teams/PythonModulesTeam| Debian Python Modules Team]]. Please also look at [[Python]] for introductory info.

<<TableOfContents(3)>>
Line 7: Line 13:
If you're interested in help packaging Python itself, there's [http://alioth.debian.org/projects/pkg-python pkg-python] but if you want to help with the Python modules or packaging a new one, you should look at [http://python-modules.alioth.debian.org Debian Python Modules Team] project. Both groups discuss its activities in the same mailing list. If you're interested in help packaging Python itself, there's [[http://alioth.debian.org/projects/pkg-python|pkg-python]] but if you want to help with the Python modules or packaging a new one, you should look at [[Teams/PythonModulesTeam| Debian Python Modules Team]] project. Both groups discuss its activities in the same debian-python@l.d.o mailing list.
Line 11: Line 17:
The Debian Python Modules Team has its own [http://python-modules.alioth.debian.org/python-modules-policy.html policy], but keep in mind that they follow [http://www.debian.org/doc/packaging-manuals/python-policy/ Debian Python Policy] and of course [http://www.debian.org/doc/debian-policy/ Debian Policy] too. The Debian Python Modules Team has its own [[http://python-modules.alioth.debian.org/python-modules-policy.html|policy]], but keep in mind that they follow [[http://www.debian.org/doc/packaging-manuals/python-policy/|Debian Python Policy]] and of course [[http://www.debian.org/doc/debian-policy/|Debian Policy]] too.
Line 13: Line 19:
== Supporting multiple python versions == == Multiple python versions support ==
Line 15: Line 21:
We always have several versions of Python in Debian. Some packages provide modules only for the default version, and other provide modules for all available versions. Some sources packages do that by providing several binary packages while other do that with a single one. Debian supports several versions of Python simultaneously. Some packages include modules only for the default version, while others provide modules for all available. These are generally all provided within a single binary package, although in the past multiple packages were sometimes used.
Line 17: Line 23:
We should reduce that diversity and if possible provide the modules for all python version available within Debian. The following guidelines should help you. The general trend is to reduce that diversity and provide modules for all Python versions available within Debian using the following guidelines.
Line 20: Line 26:
Traditionally, Python extension modules list the development packages of all Python version they are built for in their build dependencies. For compiled modules you still have to specify each dependencies, this may be improved later. For Python-only modules, build depending on python-dev is sufficient for buildsystems made in Python (like the very used distutils), python-support will manage late-bytecompilation automagically. For compiled modules you need to depend on python-all-dev, and python-all-dbg.
For Python-only modules the sole python-all is sufficient if they use Python-based build system (like the very used distutils).
A helper such as dh_python2 (or the deprecated python-support and python-central) will automagically manage bytecompilation.
Line 22: Line 30:
=== Note on bytecompilation for Python-only modules === == Note on bytecompilation for pure Python modules ==
Line 24: Line 32:
As python-support introduce late-bytecompilation, no '.py[co]' files shall be shipped in your package. You can then avoid generating such files and gain some build time. With distutils use the "--no-compile -O0" options ; if you are using the CDBS class, everything is already done for you. Beware some upstream sources contain a setup.cfg which override your build options (see #360848), then you will have to patch it. As the helpers manage late-bytecompilation, no .pyc/.pyo files shall be shipped in your package. You do no need to spend build time for generating them. With distutils use the "--no-compile -O0" options; dh and the python CDBS classes know how to handle this. Beware some upstream sources that contain a setup.cfg which override your build options (see DebianBug:360848), then you will have to patch it. In all cases, dh_python2 or python-support will remove those files if they are generated.
Line 26: Line 34:
=== Using python-support === === What are dh_python2 and dh_python3? ===
Line 28: Line 36:
A non-binary module (i.e. package with architecture: all) can use python-support to make the module available to all available Python versions. For this you need to install the module in a sub-directory of /usr/share/python-support and then you need to register that directory with update-python-modules in the postint (and unregister accordingly in prerm). Of course you need to add "python-support" as a dependency. Please note that the default Depends field generated by dh_python is wrong since the package now supports multiple versions. Until this is fixed you need to manually define the dependency (like "python (>=2.3), python (<< 2.5)", if you say that you support python 2.3 and python2.4). dh_python{2,3} are the python helpers included in the python package since 2.6.6-3.
Line 30: Line 38:
Example of postinst: dh_python2 differs from python-support, in including the per-python-version symlink farm within the binary package, only requiring byte-compilation at install time. Packages using dh_python2 with public modules must be rebuilt when Debian changes the supported Python versions (this should never happen after 2.7).

They can also guess dependencies from requires.txt, for setuptools/distutils packages.

Instructions for transitioning to dh_python2 from [[Python/PythonSupportToDHPython2|python-support]] and [[Python/PyCentral2DhPython2|python-central]].

See [[DebianMan:1/dh_python2|dh_python2(1)]] ([[http://alioth.debian.org/scm/loggerhead/pkg-python/python-defaults-debian/annotate/head:/dh_python2.rst|bzr HEAD]]) or [[DebianMan:1/dh_python3|dh_python3(1)]] for more details.

=== What is python-support? ===

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

See /usr/share/doc/python-support/README.gz or [[http://svn.debian.org/viewsvn/collab-maint/deb-maint/python-support/trunk/README|SVN README]] for up-to-date information.

=== What is python-central? ===

Python-central is a (now deprecated) package that contains some helper scripts for building and installing python modules independent of the current installed Python version.

=== Should I use dh_pythonX, python-support or python-central? ===

dh_python2 is recommended for new Python 2 packages.
dh_python3 is the only helper for Python3.
python-support and python-central are deprecated.

Some statistics (the number of packages using each method - lower number is contrib), as of 2014-04-22:
Line 32: Line 64:
#!/bin/sh

set -e

#DEBHELPER#

if [ "$1" = "configure" ] && which update-python-modules >/dev/null 2>&1; then
        update-python-modules -i /usr/share/python-support/kid
fi
~$ build-rdeps dh-python | grep total
Found a total of 283 reverse build-depend(s) for dh-python.
Found a total of 2 reverse build-depend(s) for dh-python.
~$ build-rdeps python-support | grep total
Found a total of 4 reverse build-depend(s) for python-support.
Found a total of 585 reverse build-depend(s) for python-support.
Line 43: Line 72:
Example of prerm:
{{{
#!/bin/sh

set -e

#DEBHELPER#

if which update-python-modules >/dev/null 2>&1; then
        update-python-modules -c -i /usr/share/python-support/kid
fi
}}}

If you are using CDBS, a sample debian/rules file looks like this:

{{{
#!/usr/bin/make -f
# -*- mode: makefile; coding: utf-8 -*-

# python-distutils before debhelper to avoid it calling dh_python by itself
include /usr/share/cdbs/1/class/python-distutils.mk
include /usr/share/cdbs/1/rules/debhelper.mk

DEB_PYTHON_INSTALL_ARGS_ALL += --install-lib usr/share/python-support/$your-package

# If you have an additional documentation package, you have to remove *.py files
# from this package, otherwise the following target isn't needed at all
common-binary-post-install-indep::
        rm -rf debian/$your-package-doc/usr/share/python-support
}}}

A sample debian/control.in file :

{{{
Source: $your-source-package
Section: python
Priority: optional
Maintainer: Maintainer name and email
Uploaders: Debian Python Modules Team <python-modules-team@lists.alioth.debian.org>
Standards-Version: 3.6.2
Build-Depends: @cdbs@, python-dev

Package: $your-package
Architecture: all
Depends: python (>= 2.3), python-support
Description: your description
}}}

If you are using this sample, you have to generate the debian/control file (otherwise you should replace @cdbs@ by cdbs and debhelper depends) using the following command line :
{{{
$ DEB_AUTO_UPDATE_DEBIAN_CONTROL=yes fakeroot debian/rules clean
}}}

Concerning CDBS, there is an interesting documentation :
[https://perso.duckcorp.org/duck/cdbs-doc/cdbs-doc.xhtml]

(TODO: extend sample for egg support)

=== Converting to python-support ===
If your package python-foo previously provided packages for several Python versions (python2.3-foo, python2.4-foo), you should do the following:
 * check if any other packages depend on something else than python-foo. If any package does
   * add python2.3-foo, python2.4-foo to the "Provides" field of your package
   * file bugs for these packages, mentioning the transition
   * drop them after the other packages have been fixed
 * add python2.3-foo and python2.4-foo to the "Conflicts" and "Replaces" field. This will force their uninstallation if python-foo is upgraded to the new version.
NB! Only python-support numbers are accurate, as other packages may build-depend indirectly on dh-python (for python3) or not use it at all (for python2)
Line 117: Line 82:
We don't want to provide ".egg" files within the .deb. However we want to make the "egg meta-information" available so that users can use eggs if they so wish. For that you need to pass the option "--single-version-externally-managed" to the "setup.py install" call. We don't want to provide ".egg" files within the .deb. However we want to make the "egg meta-information" available so that users can use eggs if they so wish. Python >= 2.5 does that by default in distutils. For setuptools based setup.py you need to pass the option "--single-version-externally-managed" to the "setup.py install" call.
Line 119: Line 84:
Packages relying on CDBS can do that this way: ==== with dh_python2 ====
This [[http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652617|bug report]] provides relevant information:

 * Add {{{*.egg-info/*}}} to {{{debian/clean}}}. (This requires Debhelper compatibility >= 7, declared in {{{debian/compat}}}.)
 * Add {{{extend-diff-ignore="^[^/]+\.egg-info/"}}} to debian/source/options. (This requires Debian source package format 3.0, declared in {{{debian/source/format}}}.)

==== with CDBS and setuptools ====
Packages relying on CDBS and setuptools can do that this way:
Line 125: Line 97:
=== How do we add Egg support to a package that doesnt support it yet? === == Package naming ==
Line 127: Line 99:
Basicly, you should modify setup.py to use the setup function of "setuptools" instead of "distutils". Of course, you must then Build-Depends on "python-setuptools (>= 0.6a9)" which is the first version supporting the egg-info directories. For binary packages of Python libraries, the [[Python/LibraryStyleGuide#debian.2Fcontrol|Python Library Style Guide]] has some answers. For source package names, there is no consensus on whether they should be "foo" for a package named "foo" on the Python package index, or "python-foo".
Line 129: Line 101:
Check the following links for documentation about setuptools and creation of Eggs:
 * http://peak.telecommunity.com/DevCenter/setuptools
 * http://peak.telecommunity.com/DevCenter/PythonEggs#building-eggs
Line 133: Line 102:
Example of minimal patch:
{{{
--- elementtree-1.2.6.old/setup.py 2006-04-18 12:25:33.000000000 +0000
+++ elementtree-1.2.6/setup.py 2006-04-18 12:26:30.000000000 +0000
@@ -7,6 +7,7 @@
 #

 from distutils.core import setup
+from setuptools import setup

 try:
     # add download_url syntax to distutils
}}}

Adding "egg support" is only required in some specific cases: when another software uses the python module via an egg and when this egg support is not yet integrated upstream.
----
## This page is referenced from : /usr/share/cdbs/1/class/python-distutils.mk in package "cdbs"
CategoryPermalink

Debian Python FAQ

This is the FAQ of the debian-python@l.d.o mailing list. It is of particular interest to members of the Debian Python Modules Team. Please also look at Python for introductory info.

1. What are the projects and documentation available ?

If you're interested in help packaging Python itself, there's pkg-python but if you want to help with the Python modules or packaging a new one, you should look at Debian Python Modules Team project. Both groups discuss its activities in the same debian-python@l.d.o mailing list.

1.1. python-modules

The Debian Python Modules Team has its own policy, but keep in mind that they follow Debian Python Policy and of course Debian Policy too.

2. Multiple python versions support

Debian supports several versions of Python simultaneously. Some packages include modules only for the default version, while others provide modules for all available. These are generally all provided within a single binary package, although in the past multiple packages were sometimes used.

The general trend is to reduce that diversity and provide modules for all Python versions available within Debian using the following guidelines.

2.1. Build dependencies

For compiled modules you need to depend on python-all-dev, and python-all-dbg. For Python-only modules the sole python-all is sufficient if they use Python-based build system (like the very used distutils). A helper such as dh_python2 (or the deprecated python-support and python-central) will automagically manage bytecompilation.

3. Note on bytecompilation for pure Python modules

As the helpers manage late-bytecompilation, no .pyc/.pyo files shall be shipped in your package. You do no need to spend build time for generating them. With distutils use the "--no-compile -O0" options; dh and the python CDBS classes know how to handle this. Beware some upstream sources that contain a setup.cfg which override your build options (see 360848), then you will have to patch it. In all cases, dh_python2 or python-support will remove those files if they are generated.

3.1. What are dh_python2 and dh_python3?

dh_python{2,3} are the python helpers included in the python package since 2.6.6-3.

dh_python2 differs from python-support, in including the per-python-version symlink farm within the binary package, only requiring byte-compilation at install time. Packages using dh_python2 with public modules must be rebuilt when Debian changes the supported Python versions (this should never happen after 2.7).

They can also guess dependencies from requires.txt, for setuptools/distutils packages.

Instructions for transitioning to dh_python2 from python-support and python-central.

See dh_python2(1) (bzr HEAD) or dh_python3(1) for more details.

3.2. What is python-support?

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

See /usr/share/doc/python-support/README.gz or SVN README for up-to-date information.

3.3. What is python-central?

Python-central is a (now deprecated) package that contains some helper scripts for building and installing python modules independent of the current installed Python version.

3.4. Should I use dh_pythonX, python-support or python-central?

dh_python2 is recommended for new Python 2 packages. dh_python3 is the only helper for Python3. python-support and python-central are deprecated.

Some statistics (the number of packages using each method - lower number is contrib), as of 2014-04-22:

~$ build-rdeps dh-python | grep total
Found a total of 283 reverse build-depend(s) for dh-python.
Found a total of 2 reverse build-depend(s) for dh-python.
~$ build-rdeps python-support | grep total
Found a total of 4 reverse build-depend(s) for python-support.
Found a total of 585 reverse build-depend(s) for python-support.

NB! Only python-support numbers are accurate, as other packages may build-depend indirectly on dh-python (for python3) or not use it at all (for python2)

4. Python eggs

4.1. What are Python eggs?

http://peak.telecommunity.com/DevCenter/PythonEggs

4.2. How should we package Python eggs?

We don't want to provide ".egg" files within the .deb. However we want to make the "egg meta-information" available so that users can use eggs if they so wish. Python >= 2.5 does that by default in distutils. For setuptools based setup.py you need to pass the option "--single-version-externally-managed" to the "setup.py install" call.

4.2.1. with dh_python2

This bug report provides relevant information:

  • Add *.egg-info/* to debian/clean. (This requires Debhelper compatibility >= 7, declared in debian/compat.)

  • Add extend-diff-ignore="^[^/]+\.egg-info/" to debian/source/options. (This requires Debian source package format 3.0, declared in debian/source/format.)

4.2.2. with CDBS and setuptools

Packages relying on CDBS and setuptools can do that this way:

# Install egg-info directories
DEB_PYTHON_INSTALL_ARGS_ALL += --single-version-externally-managed

5. Package naming

For binary packages of Python libraries, the Python Library Style Guide has some answers. For source package names, there is no consensus on whether they should be "foo" for a package named "foo" on the Python package index, or "python-foo".


CategoryPermalink