Merge branch 'dbus-1.6'
[platform/upstream/dbus.git] / README
1 Sections in this file describe:
2  - introduction and overview
3  - low-level vs. high-level API
4  - version numbers
5  - options to the configure script
6  - ABI stability policy
7
8 Introduction
9 ===
10
11 D-Bus is a simple system for interprocess communication and coordination.
12
13 The "and coordination" part is important; D-Bus provides a bus daemon that does things like:
14  - notify applications when other apps exit
15  - start services on demand
16  - support single-instance applications
17
18 See http://www.freedesktop.org/software/dbus/ for lots of documentation, 
19 mailing lists, etc.
20
21 See also the file HACKING for notes of interest to developers working on D-Bus.
22
23 If you're considering D-Bus for use in a project, you should be aware
24 that D-Bus was designed for a couple of specific use cases, a "system
25 bus" and a "desktop session bus." These are documented in more detail
26 in the D-Bus specification and FAQ available on the web site.
27
28 If your use-case isn't one of these, D-Bus may still be useful, but
29 only by accident; so you should evaluate carefully whether D-Bus makes
30 sense for your project.
31
32 Note: low-level API vs. high-level binding APIs
33 ===
34
35 A core concept of the D-Bus implementation is that "libdbus" is
36 intended to be a low-level API. Most programmers are intended to use
37 the bindings to GLib, Qt, Python, Mono, Java, or whatever. These
38 bindings have varying levels of completeness and are maintained as
39 separate projects from the main D-Bus package. The main D-Bus package
40 contains the low-level libdbus, the bus daemon, and a few command-line
41 tools such as dbus-launch.
42
43 If you use the low-level API directly, you're signing up for some
44 pain. Think of the low-level API as analogous to Xlib or GDI, and the
45 high-level API as analogous to Qt/GTK+/HTML.
46
47 Version numbers
48 ===
49
50 D-Bus uses the common "Linux kernel" versioning system, where
51 even-numbered minor versions are stable and odd-numbered minor
52 versions are development snapshots.
53
54 So for example, development snapshots: 1.1.1, 1.1.2, 1.1.3, 1.3.4
55 Stable versions: 1.0, 1.0.1, 1.0.2, 1.2.1, 1.2.3
56
57 All pre-1.0 versions were development snapshots.
58
59 Development snapshots make no ABI stability guarantees for new ABI
60 introduced since the last stable release. Development snapshots are
61 likely to have more bugs than stable releases, obviously.
62
63 Configuration 
64 ===
65
66 dbus could be build by using autotools or cmake. 
67
68 When using autotools the configure step is initiated by running ./configure 
69 with or without additional configuration flags. dbus requires GNU Make
70 (on BSD systems, this is typically called gmake) or a "make" implementation
71 with compatible extensions.
72
73 When using cmake the configure step is initiated by running the cmake 
74 program with or without additional configuration flags. 
75
76 Configuration flags
77 ===
78
79 When using autotools, run "./configure --help" to see the possible
80 configuration options and environment variables.
81
82 When using cmake, inspect README.cmake to see the possible
83 configuration options and environment variables.
84     
85 API/ABI Policy
86 ===
87
88 Now that D-Bus has reached version 1.0, the objective is that all
89 applications dynamically linked to libdbus will continue working
90 indefinitely with the most recent system and session bus daemons.
91
92  - The protocol will never be broken again; any message bus should 
93    work with any client forever. However, extensions are possible
94    where the protocol is extensible.
95
96  - If the library API is modified incompatibly, we will rename it 
97    as in http://ometer.com/parallel.html - in other words, 
98    it will always be possible to compile against and use the older 
99    API, and apps will always get the API they expect.
100
101 Interfaces can and probably will be _added_. This means both new
102 functions and types in libdbus, and new methods exported to
103 applications by the bus daemon.
104
105 The above policy is intended to make D-Bus as API-stable as other
106 widely-used libraries (such as GTK+, Qt, Xlib, or your favorite
107 example). If you have questions or concerns they are very welcome on
108 the D-Bus mailing list.
109
110 NOTE ABOUT DEVELOPMENT SNAPSHOTS AND VERSIONING
111
112 Odd-numbered minor releases (1.1.x, 1.3.x, 2.1.x, etc. -
113 major.minor.micro) are devel snapshots for testing, and any new ABI
114 they introduce relative to the last stable version is subject to
115 change during the development cycle.
116
117 Any ABI found in a stable release, however, is frozen.
118
119 ABI will not be added in a stable series if we can help it. i.e. the
120 ABI of 1.2.0 and 1.2.5 you can expect to be the same, while the ABI of
121 1.4.x may add more stuff not found in 1.2.x.
122
123 NOTE ABOUT STATIC LINKING
124
125 We are not yet firmly freezing all runtime dependencies of the libdbus
126 library. For example, the library may read certain files as part of
127 its implementation, and these files may move around between versions.
128
129 As a result, we don't yet recommend statically linking to
130 libdbus. Also, reimplementations of the protocol from scratch might
131 have to work to stay in sync with how libdbus behaves.
132
133 To lock things down and declare static linking and reimplementation to
134 be safe, we'd like to see all the internal dependencies of libdbus
135 (for example, files read) well-documented in the specification, and
136 we'd like to have a high degree of confidence that these dependencies
137 are supportable over the long term and extensible where required.
138
139 NOTE ABOUT HIGH-LEVEL BINDINGS
140
141 Note that the high-level bindings are _separate projects_ from the
142 main D-Bus package, and have their own release cycles, levels of
143 maturity, and ABI stability policies. Please consult the documentation
144 for your binding.
145
146 Bootstrapping D-Bus on new platforms
147 ===
148
149 A full build of D-Bus, with all regression tests enabled and run, has some
150 dependencies which themselves depend on D-Bus, either for compilation or
151 for some of *their* regression tests: GLib, dbus-glib and dbus-python are
152 currently affected.
153
154 To avoid circular dependencies, when bootstrapping D-Bus for the first time
155 on a new OS or CPU architecture, you can either cross-compile some of
156 those components, or choose the build order and options carefully:
157
158 * build and install D-Bus without tests
159   - do not use the --enable-modular-tests=yes configure option
160   - do not use the --enable-tests=yes configure option
161 * build and install GLib, again without tests
162 * use those versions of libdbus and GLib to build and install dbus-glib
163 * ... and use those to install dbus-python
164 * rebuild libdbus; this time you can run all of the tests
165 * rebuild GLib; this time you can run all of the tests