stdeb - Python to Debian source package conversion utility
==========================================================

stdeb_ ("setuptools debian") produces Debian source packages from
Python packages via a new distutils command, ``sdist_dsc``. Automatic
defaults are provided for the Debian package, but many aspects of the
resulting package can be customized via a configuration file.

.. _stdeb: http://stdeb.python-hosting.com/

News
----

 * 2008-04-26: Version 0.2 Released. See the `download page`_. See the `Changelog for 0.2`_
 * 2007-04-02: Version 0.2.a1 Released. See the `download page`_.
 * 2006-06-19: Version 0.1 Released. See the `download page`_.

.. _Changelog for 0.2: http://stdeb.python-hosting.com/file/tags/release-0.2/CHANGELOG.txt

Invocation
----------

All methods eventually result in a call to the ``sdist_dsc`` distutils
command. You may prefer to do so directly::

  python -c "import stdeb; execfile('setup.py')" sdist_dsc

Alternatively, two scripts are provided::

  stdeb_run_setup [options] # calls "python setup.py sdist_dsc [options]"

  py2dsc [options] mypackage-0.1.tar.gz # uses pre-built Python source package

In all cases, a Debian source package is produced from unmodified
Python packages. The following files are produced in a newly created
subdirectory ``deb_dist``:

 * ``packagename_versionname.orig.tar.gz``
 * ``packagename_versionname-debianversion.dsc``
 * ``packagename_versionname-debianversion.diff.gz``

These can then be compiled into binary packages using the standard
Debian machinery (e.g. dpkg-buildpackage).

Quickstart example
------------------

This generates a source package::

  wget http://pypi.python.org/packages/source/R/Reindent/Reindent-0.1.0.tar.gz
  py2dsc Reindent-0.1.0.tar.gz

This turns it into a .deb::

  cd deb_dist/reindent-0.1.0/
  dpkg-buildpackage -rfakeroot -uc -us

This installs it::
  cd ..
  sudo dpkg -i python-reindent_0.1.0-1_all.deb

Another example, with more explanation
--------------------------------------

This example is more useful if you don't have a Python source package
(.tar.gz file generated by ``python setup.py sdist``). For the sake of
illustration, we do download such a tarball, but immediately unpack it
(alternatively, use a version control system to grab the unpacked
source of a package)::

  wget http://pypi.python.org/packages/source/R/Reindent/Reindent-0.1.0.tar.gz
  tar xzf Reindent-0.1.0.tar.gz
  cd Reindent-0.1.0

The following will generate a directory ``deb_dist`` containing the
files ``reindent_0.1.0-1.dsc``, ``reindent_0.1.0.orig.tar.gz`` and
``reindent_0.1.0-1.diff.gz``, which, together, are a debian source
package::

  python setup.py sdist_dsc

(For packages that don't use setuptools, you need to get the stdeb
monkeypatch for the sdist_dsc distutils command. So, do this: ``python
-c "import stdeb; execfile('setup.py')" sdist_dsc``, or use the
command ``stdeb_run_setup``, which does just this.)

The source generated in the above way is also extracted (using
``dpkg-source -x``) and placed in the ``deb_dist`` subdirectory. To
continue the example above::

  cd deb_dist/reindent-0.1.0
  dpkg-buildpackage -rfakeroot -uc -us

Finally, the generated package can be installed::

  cd ..
  sudo dpkg -i python-reindent_0.1.0-1_all.deb

Download
--------

Files are available at the `download page`_.

.. _download page: http://stdeb.python-hosting.com/wiki/Download

The subversion repository is available at
https://svn.stdeb.python-hosting.com/trunk

Background
----------

For the average Python package, its source distribution
(python_package.tar.gz created with ``python setup.py sdist``)
contains nearly everything necessary to make a Debian source
package. This near-equivalence encouraged me to write this distutils
extension, which executes the setup.py file to extract relevant
information. This process is made significantly easier through the use
of setuptools_.

.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools

setuptools is used because of some nice features.  For example,
setuptools makes the job of "Debianizing" python console and gui
scripts much easier.

I wrote this initially to Debianize several Python packages of my own,
but I have the feeling it could be generally useful. It appears
similar, at least in theory, to easydeb_, `Logilab's Devtools`_, and
bdist_dpkg_.

.. _easydeb: http://easy-deb.sourceforge.net/
.. _Logilab's DevTools: http://www.logilab.org/projects/devtools
.. _bdist_dpkg: http://svn.python.org/view/sandbox/trunk/Lib/bdist_dpkg.py

Prerequisites
-------------

 * Python_ 2.3 or greater
 * setuptools_
 * subprocess.py_ (included with Python 2.4, backwards compatible with Python 2.3)

.. _Python: http://www.python.org/
.. _subprocess.py: http://svn.python.org/view/python/trunk/Lib/subprocess.py?rev=46651&view=log

Customizing the produced Debian source package
----------------------------------------------

stdeb will attempt to provide reasonable defaults, but these are only
guesses.

To customize the Debian source package produced, you may write config
files of the format understood by ConfigParser_. When building each
package, stdeb looks for the existance of a ``stdeb.cfg`` file in the
``.egg-info`` directory. You may specify an additional config file
with the command-line option --extra-cfg-file.

.. _ConfigParser: http://docs.python.org/lib/module-ConfigParser.html

For an example configuration file I use to build several packages,
please see http://stdeb.python-hosting.com/wiki/stdeb_all.cfg

Using stdeb on stdeb
--------------------

There is a chicken-and-egg problem when trying to make a Debian
package of stdeb with stdeb. Here's a recipe to avoid it::

 # in the stdeb distribution directory (with setup.py)
 python setup.py sdist
 python setup.py build
 PYTHONPATH="build/lib" python stdeb/py2dsc.py dist/stdeb-VERSION.tar.gz

TODO
----

* Make output meet `Debian Python Policy`_ specifications or the `new
  python policy`_. This will include several things, among which are:

  - the ability to make custom changelogs
  - the ability to include project-supplied documentation as a -doc package
  - include license information in debian/copyright
  - the ability to include project-supplied examples, tests, and data
    as a separate package
  - much more not listed

* Create (better) documentation

* Log output using standard distutils mechanisms

* Refactor the source code to have a simpler, more sane design

.. _debian python policy: http://www.debian.org/doc/packaging-manuals/python-policy/
.. _new python policy: http://wiki.debian.org/DebianPython/NewPolicy
.. _python-central: http://python-modules.alioth.debian.org/python-central_howto.txt

Call for volunteers
-------------------

I don't have a lot of time for this. This project stands a very real
chance of being only a shadow of its potential self unless people step
up and contribute. There are numerous ways in which people could
help. In particular, I'd be interested in finding a co-maintainer or
maintainer if the project generates any interest. Secondarily, I would
appreciate advice from Debian developers or Ubuntu MOTUs about the
arcane details of Python packaging.

Features
--------

* Install .desktop files. (``MIME-Desktop-Files`` config option.)

* Install .mime and .sharedmimeinfo files. (``MIME-File`` and
  ``Shared-MIME-File`` config options.)

* Install copyright files. (``Copyright-File`` config option.)

* Automatic conversion of Python package names into valid Debian
  package names.

* Apply patches to upstream sources. (``Stdeb-Patch-File`` config
  option.)

* Pass environment variables to setup.py script. (``Setup-Env-Vars``
  config option.)

Mailing list
------------

Please address all questions to the distutils-SIG_

.. _distutils-SIG: http://mail.python.org/mailman/listinfo/distutils-sig

License
-------

MIT-style license. Copyright (c) 2006-2008 stdeb authors.

See the LICENSE.txt file provided with the source distribution for
full details.

Authors
-------

Andrew Straw <strawman@astraw.com>
Pedro Algarvio, aka, s0undt3ch <ufs@ufsoft.org>

Additional Credits
------------------

* WebFaction_ (aka `python-hosting`_) for hosting services.

.. _WebFaction: http://webfaction.com/
.. _python-hosting: http://python-hosting.com/
