#acl: All:read

= Building a Simple Python Package =

<<TableOfContents>>

Given a simple, i.e. no extra data or extensions, debian package with sub-packages this section explains how to make a Debian Python2 and Python3 package from it.

Assume that an example, top-level package `math3d` has an `__init__.py`, some modules, and a hierarchy of sub-packages with their own `__init__.py` and modules. The example here has the tree layout as follows:
~-{{{
math3d/
├── interpolation
│   ├── __init__.py
│   ├── r3interpolation.py
│   ├── se3interpolation.py
│   └── so3interpolation.py
├── reference_system
│   ├── frame.py
│   └── __init__.py
├── __init__.py
├── orientation.py
├── quaternion.py
├── transform.py
├── utils.py
└── vector.py
}}}-~

At the level of the folder `math3d` put a `debian` folder with the files described in the following sections. A directory view of the `debian` folder reads as follows:
~-{{{
debian/
├── changelog
├── compat
├── control
├── python3-math3d.install
├── python-math3d.pyinstall
└── rules
}}}-~ 

== Debian Policy Files ==

The following files are requred by the [[http://www.debian.org/doc/manuals/maint-guide/dreq.en.html|Chapter 4. Required files under the debian directory]] in the [[http://www.debian.org/doc/manuals/maint-guide/index.en.html|Debian New Maintainers' Guide]].

=== changelog ===

Following the debian changelog format described by [[http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog|4.4 Debian changelog: debian/changelog]] of the [[http://www.debian.org/doc/debian-policy/index.html|Debian Policy Manual]]. E.g.
~-{{{
math3d (2.0.0) unstable; urgency=low

  * Major upgrade.
  * Rudimentary reference system feature.
  * Much PEP8 update.
  * Prepared for Python3.
  * Header string replaces by __ variables.
  * Local imports by leading "." or "..".
  * Partly converted to np.float64 as basic type.
  * Use of properties, partially replacing __getattr__ and __setattr__.
  * Revised constructors for some classes.
  * New build system with debhelper, for both Python2 and Python3 packages.

 -- Morten Lind <morten@lind.dyndns.dk>  Thu, 26 Dec 2012 00:45:00 +0100

math3d (1.3.1) unstable; urgency=low

  * Bugfix: Use of _eps imported from utils.

 -- Morten Lind <morten@lind.dyndns.dk>  Thu, 20 Dec 2012 21:46:43 +0100

...
}}}-~

=== control ===

Specifies name, description, Python versions, etc. Source stanza and stancas for Python2 and Python3 must be given separately. E.g.
~-{{{
Source: math3d
Section: python
Priority: extra
Maintainer: Morten Lind <morten@lind.dyndns.dk>
Build-Depends: debhelper (>= 8.0.0)
Standards-Version: 3.9.3
Homepage: http://launchpad.net/pymath3d
X-Python-Version: >= 2.6
X-Python3-Version: >= 3.1

Package: python-math3d
Architecture: all
Depends: ${python:Depends}, python-numpy, ${misc:Depends}
Description: 3D Special Euclidean mathematics package for Python.

Package: python3-math3d
Architecture: all
Depends: ${python3:Depends}, python3-numpy, ${misc:Depends}
Description: 3D Special Euclidean mathematics package for Python.
}}}-~

=== rules ===

This file can be immensly complex, and describes how dpkg-buildpackage is to build the package. It should be as simple as 
~-{{{
%:
   dh $@ --with python2,python3
}}}-~

== Files for DebHelper ==

For package building with debhelper, some  the following files should also be found

=== compat ===

Contains a single number which determines the compatibility mode for debhelper. This should be 7 or higher. Currently it is 9 since the debhelper used is on version 9. 

=== python-math3d.pyinstall ===

This file describes the packages and modules to be picked up by `dh_python2` for installment into the deb. It must list all packages and modules can be matched by wildcards. E.g.:
~-{{{
math3d/*.py
math3d/interpolation/*.py
math3d/reference_system/*.py
}}}-~

=== python3-math3d.install ===

A simple map for the top-level package to be picked up, possibly by `dh_install`, and put into the deb. It maps the top-level package for the Python3 deb and where it should reside in the target system. E.g.:
~-{{{
math3d /usr/lib/python3/dist-packages
}}}-~

== Build Command ==

When all have been setup, in the folder containing `debian` and `math3d`, issue the following on the commandline:
~-{{{
$ fakeroot dh binary  --with python2,python3
}}}-~

This will create deb packages `python-math3d_<version>.deb` and `python3-math3d_<version>.deb` in the parent folder. The version will be taken from the top most entry in the `changelog` file.

Once built, the build command, i.e. `dh binary`, can not be run again; it will do nothing. Before building again it is necessary to clean the generated build environment by issuing:
~-{{{
$ dh clean 
}}}-~