source: general/sysutils/dbus.xml@ d2bd92f

10.0 10.1 11.0 11.1 11.2 11.3 12.0 12.1 7.10 7.5 7.6 7.6-blfs 7.6-systemd 7.7 7.8 7.9 8.0 8.1 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind gnome kde5-13430 kde5-14269 kde5-14686 kea ken/TL2024 ken/inkscape-core-mods ken/tuningfonts krejzi/svn lazarus lxqt nosym perl-modules plabs/newcss plabs/python-mods python3.11 qt5new rahul/power-profiles-daemon renodr/vulkan-addition systemd-11177 systemd-13485 trunk upgradedb xry111/intltool xry111/llvm18 xry111/soup3 xry111/test-20220226 xry111/xf86-video-removal
Last change on this file since d2bd92f was 7776909, checked in by Fernando de Oliveira <fernando@…>, 11 years ago

Update to dbus-1.6.18.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@12143 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 18.0 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY dbus-download-http "http://dbus.freedesktop.org/releases/dbus/dbus-&dbus-version;.tar.gz">
8 <!ENTITY dbus-download-ftp " ">
9 <!ENTITY dbus-md5sum "b02e9c95027a416987b81f9893831061">
10 <!ENTITY dbus-size "1.9 MB">
11 <!ENTITY dbus-buildsize "86 MB (additional 26 MB installed)">
12 <!ENTITY dbus-time "0.36 SBU (additional 1.2 SBU for tests)">
13]>
14
15<sect1 id="dbus" xreflabel="D-Bus-&dbus-version;">
16 <?dbhtml filename="dbus.html"?>
17
18 <sect1info>
19 <othername>$LastChangedBy$</othername>
20 <date>$Date$</date>
21 </sect1info>
22
23 <title>D-Bus-&dbus-version;</title>
24
25 <indexterm zone="dbus">
26 <primary sortas="a-D-Bus">D-Bus</primary>
27 </indexterm>
28
29 <sect2 role="package">
30 <title>Introduction to D-Bus</title>
31
32 <para>
33 <application>D-Bus</application> is a message bus system, a simple
34 way for applications to talk to one another.
35 <application>D-Bus</application> supplies both a system daemon (for events
36 such as <quote>new hardware device added</quote> or <quote>printer queue
37 changed</quote>) and a per-user-login-session daemon (for general IPC needs
38 among user applications). Also, the message bus is built on top of a
39 general one-to-one message passing framework, which can be used by any two
40 applications to communicate directly (without going through the message bus
41 daemon).
42 </para>
43
44 &lfs74_checked;
45
46 <bridgehead renderas="sect3">Package Information</bridgehead>
47 <itemizedlist spacing="compact">
48 <listitem>
49 <para>
50 Download (HTTP): <ulink url="&dbus-download-http;"/>
51 </para>
52 </listitem>
53 <listitem>
54 <para>
55 Download (FTP): <ulink url="&dbus-download-ftp;"/>
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 Download MD5 sum: &dbus-md5sum;
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 Download size: &dbus-size;
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 Estimated disk space required: &dbus-buildsize;
71 </para>
72 </listitem>
73 <listitem>
74 <para>
75 Estimated build time: &dbus-time;
76 </para>
77 </listitem>
78 </itemizedlist>
79
80 <bridgehead renderas="sect3">D-Bus Dependencies</bridgehead>
81
82 <bridgehead renderas="sect4">Required</bridgehead>
83 <para role="required">
84 <xref linkend="expat"/> or
85 <xref linkend="libxml2"/>
86 </para>
87
88 <bridgehead renderas="sect4">Recommended</bridgehead>
89 <para role="recommended">
90 <xref linkend="xorg7-lib"/>
91 (for <command>dbus-launch</command> program)
92 </para>
93
94 <bridgehead renderas="sect4">Optional</bridgehead>
95 <para role="optional">
96 <xref linkend="dbus-glib"/> (to run tests - it may be necessary to
97 reinstall it, after upgrading this package),
98 <xref linkend="python2"/> (to run tests),
99 <xref linkend="dbus-python"/> (to run tests), and
100 <xref linkend="doxygen"/> (to generate the API documentation)
101 </para>
102
103 <para>
104 Note that the <command>configure</command> script will look for
105 <xref linkend="xmlto"/> but it does nothing as the XML/HTML documentation is
106 already shipped in the source tree.
107 </para>
108
109 <para condition="html" role="usernotes">User Notes:
110 <ulink url="&blfs-wiki;/dbus"/>
111 </para>
112 </sect2>
113
114 <sect2 role="installation">
115 <title>Installation of D-Bus</title>
116
117 <para>
118 As the <systemitem class="username">root</systemitem> user, create a
119 system user and group to handle the system message bus activity:
120 </para>
121
122<screen role="root"><userinput>groupadd -g 18 messagebus &amp;&amp;
123useradd -c "D-Bus Message Daemon User" -d /var/run/dbus \
124 -u 18 -g messagebus -s /bin/false messagebus</userinput></screen>
125
126 <para>
127 Install <application>D-Bus</application> by running the following
128 commands (you may wish to review the output from
129 <command>./configure --help</command> first and add any desired parameters
130 to the <command>configure</command> command shown below):
131 </para>
132
133<screen><userinput>./configure --prefix=/usr \
134 --sysconfdir=/etc \
135 --localstatedir=/var \
136 --libexecdir=/usr/lib/dbus-1.0 \
137 --with-console-auth-dir=/run/console/ \
138 --without-systemdsystemunitdir \
139 --disable-systemd \
140 --disable-static &amp;&amp;
141make</userinput></screen>
142
143 <para>
144 See below for test instructions.
145 </para>
146
147 <para>
148 Now, as the <systemitem class="username">root</systemitem> user:
149 </para>
150
151<screen role="root"><userinput>make install &amp;&amp;
152mv -v /usr/share/doc/dbus /usr/share/doc/dbus-&dbus-version;</userinput></screen>
153
154 <para>
155 If you are still building your system in chroot or you did not start the
156 daemon yet, but you want to compile some packages that require
157 <application>D-Bus</application>, generate
158 <application>D-Bus</application> UUID to avoid warnings when compiling
159 some packages with the following command as the
160 <systemitem class="username">root</systemitem> user:
161 </para>
162
163<screen role="root"><userinput>dbus-uuidgen --ensure</userinput></screen>
164
165 <para>
166 The dbus tests cannot be run until after <xref linkend="dbus-glib"/>
167 has been installed. If you want to run only the unit tests, replace,
168 below, <parameter>--enable-tests</parameter> by
169 <parameter>--enable-embedded-tests</parameter>, otherwise,
170 <xref linkend="dbus-python"/> has to be installed, before.
171 The tests require passing additional parameters to
172 <command>configure</command> and exposing additional functionality in
173 the binaries. These interfaces are not intended to be used in a
174 production build of <application>D-Bus</application>. If you would
175 like to run the tests, issue the following commands:
176 </para>
177
178<screen><userinput>make distclean &amp;&amp;
179./configure --enable-tests --enable-asserts &amp;&amp;
180make &amp;&amp;
181make check &amp;&amp;
182make distclean</userinput></screen>
183
184 <para>
185 If <command>run-test.sh</command> fails, it can be disabled with the
186 following sed, before running the commands for the tests:
187 </para>
188
189<screen><userinput>sed -i -e 's:run-test.sh:$(NULL):g' test/name-test/Makefile.in</userinput></screen>
190
191 <para>
192 Note there has been a report that the tests may fail if running
193 inside a Midnight Commander shell.
194 You may get out-of-memory error messages when running the tests.
195 These are normal and can be safely ignored.
196 </para>
197
198 </sect2>
199
200 <sect2 role="commands">
201 <title>Command Explanations</title>
202
203 <para>
204 <parameter>--with-console-auth-dir=/run/console/</parameter>: This
205 parameter specifies location of the
206 <application>ConsoleKit</application> auth dir.
207 </para>
208
209 <para>
210 <parameter>--without-systemdsystemunitdir</parameter>: This switch
211 prevents installation of systemd unit files.
212 </para>
213
214 <para>
215 <parameter>--disable-systemd</parameter>: This switch disables systemd
216 support in <application>D-Bus</application>
217 </para>
218
219 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
220 href="../../xincludes/static-libraries.xml"/>
221
222 <para>
223 <parameter>--enable-tests</parameter>: Build extra parts of the code to
224 support all tests. Configure will end with a NOTE warning about increased
225 size of libraries and decreased security.
226 </para>
227
228 <para>
229 <parameter>--enable-embedded-tests</parameter>: Build extra parts of the
230 code to support only unit tests. Configure will end with a NOTE warning
231 about increased size of libraries and decreased security.
232 </para>
233
234 <para>
235 <parameter>--enable-asserts</parameter>: Enable debugging code to run
236 assertions for statements normally assumed to be true. This prevents a
237 warning that '<parameter>--enable-tests</parameter>' on its own is only
238 useful for profiling and might not give true results for all tests, but
239 adds its own NOTE that this should not be used in a production build.
240 </para>
241
242 </sect2>
243
244 <sect2 role="configuration">
245 <title>Configuring dbus</title>
246
247 <sect3 id="dbus-config">
248 <title>Config Files</title>
249
250 <para>
251 <filename>/etc/dbus-1/session.conf</filename>,
252 <filename>/etc/dbus-1/system.conf</filename> and
253 <filename>/etc/dbus-1/system.d/*</filename>
254 </para>
255
256 <indexterm zone="dbus dbus-config">
257 <primary sortas="e-etc-dbus-1-session.conf">/etc/dbus-1/session.conf</primary>
258 </indexterm>
259
260 <indexterm zone="dbus dbus-config">
261 <primary sortas="e-etc-dbus-1/system.conf">/etc/dbus-1/system.conf</primary>
262 </indexterm>
263
264 <indexterm zone="dbus dbus-config">
265 <primary sortas="e-etc-dbus-1-system.d-star">/etc/dbus-1/system.d/*</primary>
266 </indexterm>
267
268 </sect3>
269
270 <sect3 id="dbus-session-config" xreflabel="D-Bus custom services directory">
271 <title>Configuration Information</title>
272
273 <para>
274 The configuration files listed above should probably not be
275 modified. If changes are required, you should create
276 <filename>/etc/dbus-1/session-local.conf</filename> and/or
277 <filename>/etc/dbus-1/system-local.conf</filename> and make any
278 desired changes to these files.
279 </para>
280
281 <para>
282 If any packages install a
283 <application>D-Bus</application> <filename>.service</filename>
284 file outside of the standard <filename
285 class="directory">/usr/share/dbus-1/services</filename> directory,
286 that directory should be added to the local session configuration.
287 For instance, <filename
288 class="directory">/usr/local/share/dbus-1/services</filename> can
289 be added by performing the following commands as the
290 <systemitem class="username">root</systemitem> user:
291 </para>
292
293<screen role="root"><userinput>cat &gt; /etc/dbus-1/session-local.conf &lt;&lt; "EOF"
294<literal>&lt;!DOCTYPE busconfig PUBLIC
295 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
296 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"&gt;
297&lt;busconfig&gt;
298
299 &lt;!-- Search for .service files in /usr/local --&gt;
300 &lt;servicedir&gt;/usr/local/share/dbus-1/services&lt;/servicedir&gt;
301
302&lt;/busconfig&gt;</literal>
303EOF</userinput></screen>
304
305 </sect3>
306
307 <sect3 id="dbus-init">
308 <title>Boot Script</title>
309
310 <para>
311 To automatically start <command>dbus-daemon</command> when the
312 system is rebooted, install the
313 <filename>/etc/rc.d/init.d/dbus</filename> bootscript from the
314 <xref linkend="bootscripts"/> package.
315 </para>
316
317 <indexterm zone="dbus dbus-init">
318 <primary sortas="f-dbus">dbus</primary>
319 </indexterm>
320
321<screen role="root"><userinput>make install-dbus</userinput></screen>
322
323 <para>
324 Note that this boot script only starts the system-wide
325 <application>D-Bus</application> daemon. Each user requiring access to
326 <application>D-Bus</application> services will also need to run a
327 session daemon as well. There are many methods you can use to start a
328 session daemon using the <command>dbus-launch</command> command. Review
329 the <command>dbus-launch</command> man page for details about the
330 available parameters and options. Here are some suggestions and
331 examples:
332 </para>
333
334 <itemizedlist spacing="compact">
335 <listitem>
336 <para>
337 Add <command>dbus-launch</command> to the line in the
338 <filename>~/.xinitrc</filename> file that starts your graphical
339 desktop environment.
340 </para>
341 </listitem>
342 <listitem>
343 <para>
344 If you use <command>xdm</command> or some other display manager
345 that calls the <filename>~/.xsession</filename> file, you can add
346 <command>dbus-launch</command> to the line in your
347 <filename>~/.xsession</filename> file that starts your graphical
348 desktop environment. The syntax would be similar to the example in
349 the <filename>~/.xinitrc</filename> file.
350 </para>
351 </listitem>
352 <listitem>
353 <para>
354 The examples shown previously use
355 <command>dbus-launch</command> to specify a program to be run. This
356 has the benefit (when also using the
357 <parameter>--exit-with-session</parameter> parameter) of stopping the
358 session daemon when the specified program is stopped. You can also
359 start the session daemon in your system or personal startup scripts
360 by adding the following lines:
361 </para>
362
363<screen><userinput><literal># Start the D-Bus session daemon
364eval `dbus-launch`
365export DBUS_SESSION_BUS_ADDRESS</literal></userinput></screen>
366
367 <para>
368 This method will not stop the session daemon when you exit
369 your shell, therefore you should add the following line to your
370 <filename>~/.bash_logout</filename> file:
371 </para>
372
373<screen><userinput><literal># Kill the D-Bus session daemon
374kill $DBUS_SESSION_BUS_PID</literal></userinput></screen>
375 </listitem>
376
377 <listitem>
378 <para>
379 A hint has been written that provides ways to start scripts
380 using the KDM session manager of KDE. The concepts in this hint could
381 possibly be used with other session managers as well. The hint is
382 located at <ulink
383 url="&hints-root;/downloads/files/execute-session-scripts-using-kdm.txt"/>.
384 </para>
385 </listitem>
386
387 </itemizedlist>
388
389 </sect3>
390
391 </sect2>
392
393 <sect2 role="content">
394 <title>Contents</title>
395
396 <segmentedlist>
397 <segtitle>Installed Programs</segtitle>
398 <segtitle>Installed Library</segtitle>
399 <segtitle>Installed Directories</segtitle>
400
401 <seglistitem>
402 <seg>
403 dbus-cleanup-sockets, dbus-daemon, dbus-launch, dbus-monitor,
404 dbus-send and dbus-uuidgen
405 </seg>
406 <seg>
407 libdbus-1.so
408 </seg>
409 <seg>
410 /etc/dbus-1,
411 /usr/include/dbus-1.0,
412 /usr/lib/dbus-1.0,
413 /usr/share/dbus-1,
414 /usr/share/doc/dbus-&dbus-version;,
415 /var/lib/dbus and
416 /var/run/dbus
417 </seg>
418 </seglistitem>
419 </segmentedlist>
420
421 <variablelist>
422 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
423 <?dbfo list-presentation="list"?>
424 <?dbhtml list-presentation="table"?>
425
426 <varlistentry id="dbus-cleanup-sockets">
427 <term><command>dbus-cleanup-sockets</command></term>
428 <listitem>
429 <para>
430 is used to clean up leftover sockets in a directory.
431 </para>
432 <indexterm zone="dbus dbus-cleanup-sockets">
433 <primary sortas="b-dbus-cleanup-sockets">dbus-cleanup-sockets</primary>
434 </indexterm>
435 </listitem>
436 </varlistentry>
437
438 <varlistentry id="dbus-daemon">
439 <term><command>dbus-daemon</command></term>
440 <listitem>
441 <para>
442 is the <application>D-Bus</application> message bus daemon.
443 </para>
444 <indexterm zone="dbus dbus-daemon">
445 <primary sortas="b-dbus-daemon">dbus-daemon</primary>
446 </indexterm>
447 </listitem>
448 </varlistentry>
449
450 <varlistentry id="dbus-launch">
451 <term><command>dbus-launch</command></term>
452 <listitem>
453 <para>
454 is used to start <command>dbus-daemon</command> from a shell
455 script. It would normally be called from a user's login
456 scripts.
457 </para>
458 <indexterm zone="dbus dbus-launch">
459 <primary sortas="b-dbus-launch">dbus-launch</primary>
460 </indexterm>
461 </listitem>
462 </varlistentry>
463
464 <varlistentry id="dbus-monitor">
465 <term><command>dbus-monitor</command></term>
466 <listitem>
467 <para>
468 is used to monitor messages going through a
469 <application>D-Bus</application> message bus.
470 </para>
471 <indexterm zone="dbus dbus-monitor">
472 <primary sortas="b-dbus-monitor">dbus-monitor</primary>
473 </indexterm>
474 </listitem>
475 </varlistentry>
476
477 <varlistentry id="dbus-send">
478 <term><command>dbus-send</command></term>
479 <listitem>
480 <para>
481 is used to send a message to a <application>D-Bus</application>
482 message bus.
483 </para>
484 <indexterm zone="dbus dbus-send">
485 <primary sortas="b-dbus-send">dbus-send</primary>
486 </indexterm>
487 </listitem>
488 </varlistentry>
489
490 <varlistentry id="dbus-uuidgen">
491 <term><command>dbus-uuidgen</command></term>
492 <listitem>
493 <para>
494 is used to generate a universally unique ID.
495 </para>
496 <indexterm zone="dbus dbus-uuidgen">
497 <primary sortas="b-dbus-uuidgen">dbus-uuidgen</primary>
498 </indexterm>
499 </listitem>
500 </varlistentry>
501
502 <varlistentry id="libdbus-1">
503 <term><filename class="libraryfile">libdbus-1.so</filename></term>
504 <listitem>
505 <para>
506 contains the API functions used by the
507 <application>D-Bus</application> message daemon.
508 <application>D-Bus</application> is first a library that provides
509 one-to-one communication between any two applications;
510 <command>dbus-daemon</command> is an application that uses this
511 library to implement a message bus daemon.
512 </para>
513 <indexterm zone="dbus libdbus-1">
514 <primary sortas="c-libdbus-1">libdbus-1.so</primary>
515 </indexterm>
516 </listitem>
517 </varlistentry>
518
519 </variablelist>
520
521 </sect2>
522
523</sect1>
524
Note: See TracBrowser for help on using the repository browser.