dbus-deviation
==============

dbus-deviation is a project for parsing D-Bus introspection XML and processing
it in various ways. Its main tool is dbus-interface-diff, which calculates the
difference between two D-Bus APIs for the purpose of checking for API breaks.
This functionality is also available as a Python module, dbusdeviation.

A second Python module, dbusapi, is provided for parsing D-Bus introspection
XML to produce an AST representing a D-Bus interface.

dbus-deviation’s API is currently unstable and is likely to change wildly.

Using dbus-deviation
====================

dbus-deviation can be used as a utility program or as a Python library.

The utility programs:
 • dbus-interface-diff:
     Check for differences between two versions of the same D-Bus API and
     print details of each difference. It can check for problems with forwards
     and backwards compatibility, as well as general informational
     differences.

     Example:
       dbus-interface-diff \
           com.example.Interface1.xml \  # old version of the interface
           com.example.Interface2.xml    # new version of the interface

 • dbus-interface-vcs-helper:
     This is a helper program designed to be used by dbus-deviation.mk.

As a library, the core object is an InterfaceParser, allowing a D-Bus API to
be parsed and represented as an AST. See the API documentation for more
explanation and examples.

dbus-deviation.mk
-----------------

This is a Makefile snippet which should be copied into your project, added to
git, and the following two lines included in your top-level Makefile.am:
   dbus_api_xml_files = list of D-Bus interface XML files
   -include $(top_srcdir)/dbus-deviation.mk

Do not add it to EXTRA_DIST. It is designed to work from git checkouts only.

Then run:
   make dbus-deviation-mk-install
to set up the API signature database. This assumes that your project defines
D-Bus interfaces in XML files, and does not generate them at runtime.

Finally, copy pre-push.hook to .git/hooks/pre-push and ensure it’s executable.
This script will automatically update the API signature database when a new
release tag is pushed to the git remote.

There is currently no streamlined support for projects which generate D-Bus
interfaces at runtime.

dbus-deviation.mk defines the following rules:
 • dist-dbus-api-compatibility (a dependency of dist-hook)
 • check-dbus-api-compatibility (a dependency of check-local)
 • dbus-deviation-mk-install (never triggered automatically)

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

 • argparse
 • xml.etree

Licensing
=========

dbus-deviation is licensed under the choice of the Academic Free License
version 2.1, or the GNU General Public License version 2 (or, at your option,
any later version). This is the same license as D-Bus itself. See COPYING for
more details.

Bugs
====

Bug reports and (git formatted) patches should be e-mailed to one of the
addresses listed in the ‘Contact’ section below. Thank you!

Contact
=======

Philip Withnall <philip.withnall@collabora.co.uk>
http://people.collabora.com/~pwith/dbus-deviation/
