pkgme 0.4.3

=====
pkgme
=====

The ``pkgme`` program is a framework for generating Debian packaging artifacts
from information gleaned from inspecting the code. The framework takes care
of the common tasks, and knows about packaging in general. It is extensible
so that programming language-specific conventions and rules can be supported.


Project information
===================

``pkgme`` development is `hosted on Launchpad`_. Please see the project page
for downloads, bug reports, and accessing the latest code (available in the
Bazaar_ version control system). You can also subscribe to the `pkgme mailing
list`_ for discussions on using and extending ``pkgme``. The archives_ are
also available on-line.


.. _`hosted on Launchpad`: http://launchpad.net/pkgme
.. _Bazaar: http://bazaar.canonical.com
.. _`pkgme mailing list`: https://launchpad.net/~pkgme-devs
.. _archives: https://lists.launchpad.net/pkgme-devs/


Dependencies
============

In addition to the various Python modules documented in ``setup.py``,
``pkgme`` depends on ``devscripts`` and ``debhelper``.


Developers
==========

To get a development environment set up (using ``buildout``) run::

$ make bootstrap

You can then run the tests with

$ make check

The bootstrap will fail if you have a system-wide install of buildout that
is the same version as the one in use by this project. (You will see
``DistributionNotFound: zc.buildout==<version>``). If you encounter
that then you can either remove the site-wide install, or use a virtualenv
to run the bootstrap step.

You can get a shell to try code interactively by running ``./bin/py``.

Buildout uses two directories as caches that can be shared between branches.
The first is the ``download-cache`` directory. This contains all of the
distributions of the Python dependencies. You can get this from
``lp:ca-download-cache``, but the Makefile will grab it for you.

The other directory is the ``eggs`` directory that holds built versions
of the dependencies.

The default for both of these is to symlink them from the parent directory,
but if you wish to put them somewhere else you can set the locations with
the ``CA_DOWNLOAD_CACHE_DIR`` and ``CA_EGGS_DIR`` environment variables.


If you want to override the default location of the backends, set the
environment variable ``$PKGME_BACKEND_PATHS``. This is a colon-separated list
of directories, for example:

% export PKGME_BACKEND_PATHS=/pkgme/foo-backends:/pkgme/bar-backends
% cd my-about-to-be-packaged-code
% ~/path/to/branch/bin/pkgme


Building the documentation
--------------------------

If you have the Sphinx toolchain installed (on Debian/Ubuntu, the
python-sphinx package), you can build the documentation like so::

% make html

You'll need to be in your virtualenv, and you should have installed ``pkgme``
in that virtualenv before trying to build the documentation.


.. _virtualenv: http://virtualenv.openplans.org/


Table of Contents
=================

.. toctree::
:glob:

*
..
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.



==============
NEWS for pkgme
==============

0.4.3 (2012-09-27)
==================

Improvements
------------

* all_info is only called once, rather than three times. The three calls were
the same, so all it was doing was wasting time. (Jonathan Lange)

* Be more careful in how the .orig.tar.gz is constructed when building a source
package. Some overly general transformations were being applied, that changed
the content of some packages, and so caused the package to fail to build.
(James Westby)


0.4.2 (2012-09-25)
==================

Improvements
------------

* Distribution defaults to "UNRELEASED" if there is no ``/etc/lsb-release``
file, rather than erroring out. (Natalia)

* More logging on how long various steps take. (Jonathan Lange)


0.4.1 (2012-09-12)
==================

Changes
-------

* ``query_backends`` raises a ``NoEligibleBackend`` error if there are no
eligible backends. (Jonathan Lange).

Improvements
------------

* Backends can now specify extra fields to be added to the binary package
stanza in debian/control. (James Westby)


0.4.0 (2012-09-06)
==================

Changes
-------

* ``BackendSelector.get_eligible_backends`` returns a list of dicts, rather
than a list of ``(score, backend)`` 2-tuples. (Jonathan Lange)

* New module ``pkgme.api`` that has the useful stuff from the pkgme script.
(Jonathan Lange)

* ``pkgme.bin.main.get_all_info`` has been removed. Use
``packaging_info_as_data(get_all_info(...))`` instead. Both are in
``pkgme.api``. (Jonathan Lange)


Deprecations
------------

* ``pkgme.write_packaging``. Instead use ``pkgme.api.get_all_info`` to get
packaging information, and ``pkgme.api.write_packaging_info`` to write it
out to disk. (Jonathan Lange)

* From ``pkgme.testing``, ``TempdirFixture``, ``FileFixture`` and
``ExecutableFileFixture``. Use ``treeshape.FileTree`` instead.


0.3.1 (2012-08-28)
==================

Improvements
------------

* Backends can now signal that their errors are intended for end-user
consumption by exiting with return code, ``ScriptUserError.RETURN_CODE``.

Changes
-------

* Many matchers were removed from ``pkgme.testing``. These matchers are now
available in `testtools <http://pypi.python.org/pypi/testtools>`_ 0.9.13 or
later.

* Switched to buildout for handling dependencies.


0.3 (2012-08-03)
================

* New release, lots of new features.

0.2 (201X-XX-XX)
================

0.1 (201X-XX-XX)
================
* Initial release.



-*- rst -*-