fdo-mirrors/dbus
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/dbus/dbus.git synced 2025-12-25 05:50:07 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

2006-11-07 Havoc Pennington <hp@redhat.com>

Browse source 
* doc/dbus-specification.xml, doc/dbus-faq.xml, README: various
	documentation updates. Bump faq/spec versions (not to 1.0; I don't
	think the spec will be "finished"/1.0 when we ship the 1.0 library).
This commit is contained in:
Havoc Pennington 2006-11-07 06:13:53 +00:00
parent 4c31ea9ee2
commit 151b3aaaef
6 changed files with 144 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
COPYING
View file

@ -3,8 +3,8 @@ License version 2.1, or the GNU General Public License version 2.
Both licenses are included here. Some of the standalone binaries are
under the GPL only; in particular, but not limited to,
tools/dbus-cleanup-sockets.c and test/decode-gcov.c. Each source code
file is marked with the proper copyright information.
file is marked with the proper copyright information - if you find a
file that isn't marked please bring it to our attention.
The Academic Free License

6
ChangeLog
View file

@ -1,3 +1,9 @@
2006-11-07 Havoc Pennington <hp@redhat.com>
* doc/dbus-specification.xml, doc/dbus-faq.xml, README: various
documentation updates. Bump faq/spec versions (not to 1.0; I don't
think the spec will be "finished"/1.0 when we ship the 1.0 library).
2006-11-06 John (J5) Palmieri <johnp@redhat.com>
* bus/bus.c: Missed patch - pass in the context to the directory watch

129
README
View file

@ -1,17 +1,64 @@
D-BUS is a simple IPC library based on messages.
Sections in this file describe:
- introduction and overview
- low-level vs. high-level API
- version numbers
- options to the configure script
- ABI stability policy
See also the file HACKING for notes of interest to developers working on D-BUS.
Introduction
===
D-Bus is a simple system for interprocess communication and coordination.
The "and coordination" part is important; D-Bus provides a bus daemon that does things like:
- notify applications when other apps exit
- start services on demand
- support single-instance applications
See http://www.freedesktop.org/software/dbus/ for lots of documentation,
mailing lists, etc.
Note
See also the file HACKING for notes of interest to developers working on D-Bus.
If you're considering D-Bus for use in a project, you should be aware
that D-Bus was designed for a couple of specific use cases, a "system
bus" and a "desktop session bus." These are documented in more detail
in the D-Bus specification and FAQ available on the web site.
If your use-case isn't one of these, D-Bus may still be useful, but
only by accident; so you should evaluate carefully whether D-Bus makes
sense for your project.
Note: low-level API vs. high-level binding APIs
===
A core concept of the D-BUS implementation is that "libdbus" is
intended to be a low-level API, similar to Xlib. Most programmers are
intended to use the bindings to GLib, Qt, Python, Mono, Java, or
whatever. These bindings have varying levels of completeness.
A core concept of the D-Bus implementation is that "libdbus" is
intended to be a low-level API. Most programmers are intended to use
the bindings to GLib, Qt, Python, Mono, Java, or whatever. These
bindings have varying levels of completeness and are maintained as
separate projects from the main D-Bus package. The main D-Bus package
contains the low-level libdbus, the bus daemon, and a few command-line
tools such as dbus-launch.
If you use the low-level API directly, you're signing up for some
pain. Think of the low-level API as analogous to Xlib or GDI, and the
high-level API as analogous to Qt/GTK+/HTML.
Version numbers
===
D-Bus uses the common "Linux kernel" versioning system, where
even-numbered minor versions are stable and odd-numbered minor
versions are development snapshots.
So for example, development snapshots: 1.1.1, 1.1.2, 1.1.3, 1.3.4
Stable versions: 1.0, 1.0.1, 1.0.2, 1.2.1, 1.2.3
All pre-1.0 versions were development snapshots.
Development snapshots make no ABI stability guarantees for new ABI
introduced since the last stable release. Development snapshots are
likely to have more bugs than stable releases, obviously.
Configuration flags
===
@ -48,15 +95,9 @@ the ./configure program.
API/ABI Policy
===
D-BUS API/ABI and protocol necessarily remain in flux until we are
sure it will meet the various needs it's intended to meet. This means
we need to see some significant sample usage in the contexts of GNOME,
KDE, desktop applications, and systemwide uses such as print queue
monitoring, hotplug events, or whatever. We need the flexibility to
incorporate feedback from this sample usage.
Once we feel confident in the protocol and the API, we will release a
version 1.0. At that point, the intent is:
Now that D-Bus has reached version 1.0, the objective is that all
applications dynamically linked to libdbus will continue working
indefinitely with the most recent system and session bus daemons.
- The protocol will never be broken again; any message bus should
work with any client forever. However, extensions are possible
@ -67,23 +108,47 @@ version 1.0. At that point, the intent is:
it will always be possible to compile against and use the older
API, and apps will always get the API they expect.
Until 1.0 is released, feedback that requires API changes may be
incorporated into D-BUS. This may break the API, the ABI, the
protocol, or all three.
Interfaces can and probably will be _added_. This means both new
functions and types in libdbus, and new methods exported to
applications by the bus daemon.
To avoid a huge soname, the plan is to increment the soname only
between official stable releases, not with every development snapshot.
Versions numbered 0.x are considered development snapshots.
The above policy is intended to make D-Bus as API-stable as other
widely-used libraries (such as GTK+, Qt, Xlib, or your favorite
example). If you have questions or concerns they are very welcome on
the D-Bus mailing list.
Until 1.0 is released, you have to define -DDBUS_API_SUBJECT_TO_CHANGE
just as a safety check to be sure everyone is aware of this API/ABI
policy and has the right expectations.
NOTE ABOUT DEVELOPMENT SNAPSHOTS AND VERSIONING
We do need people to test the APIs, so please do use the development
snapshots of D-BUS. They are intended to work and we do actively
address bugs.
Odd-numbered minor releases (1.1.x, 1.3.x, 2.1.x, etc. -
major.minor.micro) are devel snapshots for testing, and any new ABI
they introduce relative to the last stable version is subject to
change during the development cycle.
However, if you're shipping a commercial binary-only application that
needs to keep running on M future versions of N operating systems, you
might want to include your own copy of D-BUS rather than relying on
the installed copy, for example.
Any ABI found in a stable release, however, is frozen.
ABI will not be added in a stable series if we can help it. i.e. the
ABI of 1.2.0 and 1.2.5 you can expect to be the same, while the ABI of
1.4.x may add more stuff not found in 1.2.x.
NOTE ABOUT STATIC LINKING
We are not yet firmly freezing all runtime dependencies of the libdbus
library. For example, the library may read certain files as part of
its implementation, and these files may move around between versions.
As a result, we don't yet recommend statically linking to
libdbus. Also, reimplementations of the protocol from scratch might
have to work to stay in sync with how libdbus behaves.
To lock things down and declare static linking and reimplementation to
be safe, we'd like to see all the internal dependencies of libdbus
(for example, files read) well-documented in the specification, and
we'd like to have a high degree of confidence that these dependencies
are supportable over the long term and extensible where required.
NOTE ABOUT HIGH-LEVEL BINDINGS
Note that the high-level bindings are _separate projects_ from the
main D-Bus package, and have their own release cycles, levels of
maturity, and ABI stability policies. Please consult the documentation
for your binding.

2
doc/TODO
View file

@ -8,6 +8,8 @@ Important for 1.0
- the spec should say "the protocol will not be changed incompatibly after Month DD, YYYY"
- the README documents the configure flags, should check this for being in sync with reality
Important for 1.0 GLib Bindings
===

30
doc/dbus-faq.xml
View file

@ -7,8 +7,8 @@
<article id="index">
<articleinfo>
<title>D-Bus FAQ</title>
<releaseinfo>Version 0.1</releaseinfo>
<date>22 January 2005</date>
<releaseinfo>Version 0.2</releaseinfo>
<date>07 November 2006</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
@ -38,10 +38,14 @@
</question>
<answer>
<para>
This is probably best answered by reading the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink>. In
This is probably best answered by reading the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink> or
the introduction to the <ulink url="dbus-specification.html">specification</ulink>. In
short, it is a system consisting of 1) a wire protocol for exposing a
typical object-oriented language/framework to other applications; and
2) a bus daemon that allows applications to find and monitor one another.
Phrased differently, D-Bus is 1) an interprocess communication (IPC) system and 2) some higher-level
structure (lifecycle tracking, service activation, security policy) provided by two bus daemons,
one systemwide and one per-user-session.
</para>
</answer>
</qandaentry>
@ -54,12 +58,13 @@
</question>
<answer>
<para>
D-Bus has not yet reached 1.0. The <ulink url="README">README</ulink>
file has a discussion of the API/ABI stability guarantees before and
after 1.0. In short, there are no guarantees before 1.0, and stability
of both protocol and reference library will be maintained after 1.0.
As of January 2005 we don't expect major protocol or API changes prior
to the 1.0 release, but anything is possible.
The low-level library "libdbus" and the protocol specification are considered
ABI stable. The <ulink url="README">README</ulink>
file has a discussion of the API/ABI stability guarantees.
Higher-level bindings (such as those for Qt, GLib, Python, Java, C#) each
have their own release schedules and degree of maturity, not linked to
the low-level library and bus daemon release. Check the project page for
the binding you're considering to understand that project's policies.
</para>
</answer>
</qandaentry>
@ -144,6 +149,13 @@
are normally launched according to the bus name they will
have.
</para>
<para>
People often misuse the word "service" for any
bus name, but this tends to be ambiguous and confusing so is discouraged.
In the D-Bus docs we try to use "service" only when talking about
programs the bus knows how to launch, i.e. a service always has a
.service file.
</para>
</answer>
</qandaentry>

21
doc/dbus-specification.xml
View file

@ -7,8 +7,8 @@
<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
<releaseinfo>Version 0.11</releaseinfo>
<date>6 February 2005</date>
<releaseinfo>Version 0.12</releaseinfo>
<date>7 November 2006</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
@ -114,9 +114,20 @@
</itemizedlist>
D-Bus is not intended to be a generic IPC system for any possible
application, and intentionally omits many features found in other
IPC systems for this reason. D-Bus may turn out to be useful
in unanticipated applications, but future versions of this
spec and the reference implementation probably will not
IPC systems for this reason.
</para>
<para>
At the same time, the bus daemons offer a number of features not found in
other IPC systems, such as single-owner "bus names" (similar to X
selections), on-demand startup of services, and security policies.
In many ways, these features are the primary motivation for developing
D-Bus; other systems would have sufficed if IPC were the only goal.
</para>
<para>
D-Bus may turn out to be useful in unanticipated applications, but future
versions of this spec and the reference implementation probably will not
incorporate features that interfere with the core use cases.
</para>