==============
telepathy-glib
==============

Telepathy is a D-Bus framework for unifying real time communication,
including instant messaging, voice calls and video calls. It abstracts
differences between protocols to provide a unified interface for
applications.

telepathy-glib is a C library using GLib, for use in Telepathy clients,
connection managers (protocol backends) and other components. It can
also be used from C++ via extern "C" linkage, and from higher-level
languages including Python and JavaScript via GObject-Introspection.

Optional components:

• telepathy-farstream implements the actual streaming for Telepathy
  Call channels using Farstream and GStreamer, and should be used in
  VoIP client user interfaces

• telepathy-logger provides a logging daemon and a log-access library,
  see telepathy-logger/README for more details

Telepathy specification
=======================

The copy of the Telepathy specification in the spec/ directory indicates
the specification that this library claims to implement.

Requirements
============

Building telepathy-glib requires:
  GLib, GObject <http://ftp.gnome.org/pub/GNOME/sources/glib/>
  libdbus <http://dbus.freedesktop.org/releases/dbus/>
  The D-Bus GLib bindings <http://dbus.freedesktop.org/releases/dbus-glib/>

  GNU make <http://www.gnu.org/software/make/>
  pkg-config <http://ftp.gnome.org/pub/GNOME/sources/pkg-config/>
  libxslt, xsltproc <http://xmlsoft.org/XSLT/>
  Python <http://www.python.org/>

and can also make use of:
  GObject-Introspection <http://ftp.gnome.org/pub/GNOME/sources/gobject-introspection/>
  Vala <http://ftp.gnome.org/pub/GNOME/sources/vala/>
  gtkdoc <http://ftp.gnome.org/pub/GNOME/sources/gtk-doc/>

See configure.ac for full details, including versions required.
Of the packages listed above, only GLib, GObject, libdbus and dbus-glib are
required at runtime.

The optional components additionally require:

  Farstream <http://farsight.freedesktop.org/releases/farstream/>
  GStreamer base plugins <http://gstreamer.freedesktop.org/>
  sqlite <https://www.sqlite.org/download.html>
  libxml2 <http://xmlsoft.org/>

Configure with --enable-farstream, --enable-logger to make the build
fail if suitable versions are not found, or --disable-farstream etc. to
disable an optional component even if its dependencies are present.
The default is to compile all optional components whose dependencies are
satisfied.

Building from git also requires the GNU build system (Autoconf, Automake,
libtool).

Bugs, feature requests and to-do list
=====================================

Report all bugs, feature requests and "to-do" items here:
  <https://bugs.freedesktop.org/enter_bug.cgi?product=Telepathy&component=tp-glib>

Running "make check" will produce FIXME.out, which lists all the mentions of
FIXME, TODO or XXX in the source code. Ideally, all of these should be in
Bugzilla, but sometimes they're not.

API stability policy
====================

We use an "odd/even" versioning scheme where the minor version (the y in
x.y.z) determines stability - stable branches have y even, development
branches have y odd.

In a stable (even) branch, we will not make incompatible API or ABI changes
between one release tarball and the next.

In a development (odd) branch, we will attempt to avoid incompatible API
or ABI changes. If we break ABI relative to the previous stable (even)
release, we will increase the library SONAME to avoid breaking existing
code. If we break ABI relative to a previous development (odd) release,
we will not necessarily increase the library SONAME: in other words,
API/ABI added by a development release is not guaranteed until it appears
in a stable release. (This is basically the same policy as GLib - in
versions 0.22 and earlier, we had a more restrictive policy.)

The GObject-Introspection and Vala bindings are more or less stable,
but might break compatibility between one development branch and the next.

Unreleased builds straight from git identify themselves as version
"x.y.z.1". We DO NOT make any API guarantees about unreleased builds.

Unreleased builds are compiled with -Werror, so they might stop working
if your gcc version issues more warnings than ours. If this is a problem
for you, use a release tarball or configure with --disable-fatal-warnings.

Contact info
============

This library is maintained by the Telepathy project:
  <http://telepathy.freedesktop.org/>
  <mailto:telepathy@lists.freedesktop.org>
  <irc://irc.freenode.net/telepathy>

Telepathy development is supported by Collabora Ltd.
  <http://www.collabora.co.uk/>.

Hacking
=======

The current development version of telepathy-glib is available from the
'master' branch in the git repository:
  <git://git.collabora.co.uk/git/telepathy-glib.git>
  <git+ssh://git.collabora.co.uk/git/telepathy-glib.git> (for committers)
  <http://git.collabora.co.uk/?p=telepathy-glib.git> (gitweb)

Stable branches are available from branches with names like
'telepathy-glib-0.6' in the same repository.

Proposed patches awaiting review can usually be found in freedesktop.org bugzilla.
Our review procedure is described by:
  <http://telepathy.freedesktop.org/wiki/Review%20Procedure>

Please follow <http://telepathy.freedesktop.org/wiki/Style>.

GObject Introspection
=====================

telepathy-glib's high level API has experimental GObject-Introspection
support.

You can easily test it from the source directory by defining this environment
variable:
  GI_TYPELIB_PATH=`pwd`/telepathy-glib
  export GI_TYPELIB_PATH

  LD_LIBRARY_PATH=`pwd`/telepathy-glib/.libs
  export LD_LIBRARY_PATH

In Python you can access the API using;
  from gi.repository import TelepathyGLib