source: general/sysutils/dbus.xml@ 33c9d33

10.0 10.1 11.0 11.1 7.10 7.8 7.9 8.0 8.1 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind lazarus nosym perl-modules qt5new trunk upgradedb xry111/intltool xry111/test-20220226
Last change on this file since 33c9d33 was 33c9d33, checked in by Bruce Dubbs <bdubbs@…>, 7 years ago

Tags

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

  • Property mode set to 100644
File size: 20.9 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 "5af6297348107a906c8449817a728b3b">
10 <!ENTITY dbus-size "2 MB">
11 <!ENTITY dbus-buildsize "28 MB (additional 81 MB with doxygen and xml documents, without tests))">
12 <!ENTITY dbus-time "0.3 SBU (without 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 way
34 for applications to talk to one another.
35 <application>D-Bus</application> supplies both a system daemon (for
36 events such as <quote>new hardware device added</quote> or <quote>printer
37 queue changed</quote>) and a per-user-login-session daemon (for general
38 IPC needs among user applications). Also, the message bus is built on top
39 of a general one-to-one message passing framework, which can be used by
40 any two applications to communicate directly (without going through the
41 message bus daemon).
42 </para>
43
44 &lfs78_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<!--
83 <bridgehead renderas="sect4">Required</bridgehead>
84 <para role="required">
85 <xref linkend="expat"/>
86 </para>
87-->
88 <bridgehead renderas="sect4">Recommended</bridgehead>
89 <para role="recommended">
90 <xref linkend="xorg7-lib"/> (for <command>dbus-launch</command> program)
91 </para>
92
93 <bridgehead renderas="sect4">Optional</bridgehead>
94 <para role="optional">
95 For the tests:
96 <xref linkend="dbus-glib"/>,
97 <xref linkend="dbus-python"/>,
98 <xref linkend="pygobject2"/>, and
99 <xref linkend="valgrind"/>;
100
101 for documentation:
102 <xref linkend="doxygen"/>,
103 <xref linkend="xmlto"/>,
104 <ulink url="https://pypi.python.org/pypi/mallard-ducktype">Ducktype</ulink>,
105 and
106 <ulink url="http://ftp.gnome.org/pub/gnome/sources/yelp-tools/">Yelp Tools</ulink>
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 If they do not already exist,
119 as the <systemitem class="username">root</systemitem> user, create a
120 system user and group to handle the system message bus activity:
121 </para>
122
123<screen role="root"><userinput>groupadd -g 18 messagebus &amp;&amp;
124useradd -c "D-Bus Message Daemon User" -d /var/run/dbus \
125 -u 18 -g messagebus -s /bin/false messagebus</userinput></screen>
126
127 <para>
128 Install <application>D-Bus</application> by running the following
129 commands (you may wish to review the output from <command>./configure
130 --help</command> first and add any desired parameters to the
131 <command>configure</command> command shown below):
132 </para>
133
134<screen><userinput>./configure --prefix=/usr \
135 --sysconfdir=/etc \
136 --localstatedir=/var \
137 --disable-doxygen-docs \
138 --disable-xml-docs \
139 --disable-static \
140 --disable-systemd \
141 --without-systemdsystemunitdir \
142 --with-console-auth-dir=/run/console/ \
143 --docdir=/usr/share/doc/dbus-&dbus-version; &amp;&amp;
144make</userinput></screen>
145
146 <para>
147 See below for test instructions.
148 </para>
149
150 <para>
151 Now, as the <systemitem class="username">root</systemitem> user:
152 </para>
153
154<screen role="root"><userinput>make install</userinput></screen>
155
156 <para>
157 If you are using a DESTDIR install,
158 <command>dbus-daemon-launch-helper</command> needs to be fixed
159 afterwards. Issue, as <systemitem class="username">root</systemitem>
160 user:
161 </para>
162
163<screen role="root"><userinput>chown -v root:messagebus /usr/libexec/dbus-daemon-launch-helper &amp;&amp;
164chmod -v 4750 /usr/libexec/dbus-daemon-launch-helper</userinput></screen>
165
166 <para>
167 If you are still building your system in chroot or you did not start the
168 daemon yet, but you want to compile some packages that require
169 <application>D-Bus</application>, generate
170 <application>D-Bus</application> UUID to avoid warnings when compiling
171 some packages with the following command as the
172 <systemitem class="username">root</systemitem> user:
173 </para>
174
175<screen role="root"><userinput>dbus-uuidgen --ensure</userinput></screen>
176
177 <para>
178 The dbus tests cannot be run until after <xref linkend="dbus-glib"/> has
179 been installed. They must be run as an unprivileged user from a local
180 session with bus address. Tests fail through ssh. If you want to run only
181 the unit tests, replace, below, <parameter>--enable-tests</parameter> by
182 <parameter>--enable-embedded-tests</parameter>, otherwise, <xref
183 linkend="dbus-python"/> has to be installed, before. The tests require
184 passing additional parameters to <command>configure</command> and
185 exposing additional functionality in the binaries. These interfaces are
186 not intended to be used in a production build of
187 <application>D-Bus</application>. If you would like to run the tests,
188 issue the following commands (for the tests, you don't need to build the
189 docs):
190 </para>
191
192<screen><userinput>make distclean &amp;&amp;
193./configure --enable-tests \
194 --enable-asserts \
195 --disable-doxygen-docs \
196 --disable-xml-docs &amp;&amp;
197make &amp;&amp;
198make check</userinput></screen>
199
200 <para>
201 If <command>run-test.sh</command> fails, it can be disabled with the
202 following sed, before running the commands for the tests:
203 </para>
204
205<screen><userinput>sed -i -e 's:run-test.sh:$(NULL):g' test/name-test/Makefile.in</userinput></screen>
206
207 <para>
208 There has been a report that the tests may fail if running inside a
209 Midnight Commander shell. You may get out-of-memory error messages when
210 running the tests. These are normal and can be safely ignored.
211 </para>
212
213 </sect2>
214
215 <sect2 role="commands">
216 <title>Command Explanations</title>
217
218 <para>
219 <parameter>--disable-doxygen-docs</parameter>: This switch disables
220 doxygen documentation build and install, if you have
221 <application>doxygen</application> installed. Delete, if
222 <application>doxygen</application> is installed and you wish to build and
223 install them.
224 </para>
225
226 <para>
227 <parameter>--disable-xml-docs</parameter>: This switch disables html
228 documentation build and install, if you have
229 <application>xmlto</application> installed. Delete, if
230 <application>xmlto</application> is installed and you wish to build and
231 install them.
232 </para>
233
234 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
235 href="../../xincludes/static-libraries.xml"/>
236
237 <para>
238 <parameter>--disable-systemd</parameter>: This switch disables systemd
239 support in <application>D-Bus</application>.
240 </para>
241
242 <para>
243 <parameter>--without-systemdsystemunitdir</parameter>: This switch
244 prevents installation of systemd unit files.
245 </para>
246
247 <para>
248 <parameter>--with-console-auth-dir=/run/console/</parameter>: This
249 parameter specifies location of the
250 <application>ConsoleKit</application> auth dir.
251 </para>
252
253 <para>
254 <parameter>--enable-tests</parameter>: Build extra parts of the code to
255 support all tests. Configure will end with a NOTE warning about increased
256 size of libraries and decreased security.
257 </para>
258
259 <para>
260 <parameter>--enable-embedded-tests</parameter>: Build extra parts of the
261 code to support only unit tests. Configure will end with a NOTE warning
262 about increased size of libraries and decreased security.
263 </para>
264
265 <para>
266 <parameter>--enable-asserts</parameter>: Enable debugging code to run
267 assertions for statements normally assumed to be true. This prevents a
268 warning that '<parameter>--enable-tests</parameter>' on its own is only
269 useful for profiling and might not give true results for all tests, but
270 adds its own NOTE that this should not be used in a production build.
271 </para>
272
273 </sect2>
274
275 <sect2 role="configuration">
276 <title>Configuring dbus</title>
277
278 <sect3 id="dbus-config">
279 <title>Config Files</title>
280
281 <para>
282 <filename>/etc/dbus-1/session.conf</filename>,
283 <filename>/etc/dbus-1/system.conf</filename> and
284 <filename>/etc/dbus-1/system.d/*</filename>
285 </para>
286
287 <indexterm zone="dbus dbus-config">
288 <primary sortas="e-etc-dbus-1-session.conf">/etc/dbus-1/session.conf</primary>
289 </indexterm>
290
291 <indexterm zone="dbus dbus-config">
292 <primary sortas="e-etc-dbus-1/system.conf">/etc/dbus-1/system.conf</primary>
293 </indexterm>
294
295 <indexterm zone="dbus dbus-config">
296 <primary sortas="e-etc-dbus-1-system.d-star">/etc/dbus-1/system.d/*</primary>
297 </indexterm>
298
299 </sect3>
300
301 <sect3 id="dbus-session-config" xreflabel="D-Bus custom services directory">
302 <title>Configuration Information</title>
303
304 <para>
305 The configuration files listed above should probably not be
306 modified. If changes are required, you should create
307 <filename>/etc/dbus-1/session-local.conf</filename> and/or
308 <filename>/etc/dbus-1/system-local.conf</filename> and make any
309 desired changes to these files.
310 </para>
311
312 <para>
313 If any packages install a
314 <application>D-Bus</application> <filename>.service</filename>
315 file outside of the standard <filename
316 class="directory">/usr/share/dbus-1/services</filename> directory,
317 that directory should be added to the local session configuration.
318 For instance, <filename
319 class="directory">/usr/local/share/dbus-1/services</filename> can
320 be added by performing the following commands as the
321 <systemitem class="username">root</systemitem> user:
322 </para>
323
324<screen role="root"><userinput>cat &gt; /etc/dbus-1/session-local.conf &lt;&lt; "EOF"
325<literal>&lt;!DOCTYPE busconfig PUBLIC
326 "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
327 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"&gt;
328&lt;busconfig&gt;
329
330 &lt;!-- Search for .service files in /usr/local --&gt;
331 &lt;servicedir&gt;/usr/local/share/dbus-1/services&lt;/servicedir&gt;
332
333&lt;/busconfig&gt;</literal>
334EOF</userinput></screen>
335
336 </sect3>
337
338 <sect3 id="dbus-init">
339 <title>Boot Script</title>
340
341 <para>
342 To automatically start <command>dbus-daemon</command> when the
343 system is rebooted, install the
344 <filename>/etc/rc.d/init.d/dbus</filename> bootscript from the
345 <xref linkend="bootscripts"/> package.
346 </para>
347
348 <indexterm zone="dbus dbus-init">
349 <primary sortas="f-dbus">dbus</primary>
350 </indexterm>
351
352<screen role="root"><userinput>make install-dbus</userinput></screen>
353
354 <para>
355 Note that this boot script only starts the system-wide
356 <application>D-Bus</application> daemon. Each user requiring access to
357 <application>D-Bus</application> services will also need to run a
358 session daemon as well. There are many methods you can use to start a
359 session daemon using the <command>dbus-launch</command> command. Review
360 the <command>dbus-launch</command> man page for details about the
361 available parameters and options. Here are some suggestions and
362 examples:
363 </para>
364
365 <itemizedlist spacing="compact">
366 <listitem>
367 <para>
368 Add <command>dbus-launch</command> to the line in the
369 <filename>~/.xinitrc</filename> file that starts your graphical
370 desktop environment.
371 </para>
372 </listitem>
373 <listitem>
374 <para>
375 If you use <command>xdm</command> or some other display manager
376 that calls the <filename>~/.xsession</filename> file, you can add
377 <command>dbus-launch</command> to the line in your
378 <filename>~/.xsession</filename> file that starts your graphical
379 desktop environment. The syntax would be similar to the example in
380 the <filename>~/.xinitrc</filename> file.
381 </para>
382 </listitem>
383 <listitem>
384 <para>
385 The examples shown previously use
386 <command>dbus-launch</command> to specify a program to be run. This
387 has the benefit (when also using the
388 <parameter>--exit-with-session</parameter> parameter) of stopping the
389 session daemon when the specified program is stopped. You can also
390 start the session daemon in your system or personal startup scripts
391 by adding the following lines:
392 </para>
393
394<screen><userinput><literal># Start the D-Bus session daemon
395eval `dbus-launch`
396export DBUS_SESSION_BUS_ADDRESS</literal></userinput></screen>
397
398 <para>
399 This method will not stop the session daemon when you exit
400 your shell, therefore you should add the following line to your
401 <filename>~/.bash_logout</filename> file:
402 </para>
403
404<screen><userinput><literal># Kill the D-Bus session daemon
405kill $DBUS_SESSION_BUS_PID</literal></userinput></screen>
406 </listitem>
407
408 <listitem>
409 <para>
410 A hint has been written that provides ways to start scripts
411 using the KDM session manager of KDE. The concepts in this hint could
412 possibly be used with other session managers as well. The hint is
413 located at <ulink
414 url="&hints-root;/downloads/files/execute-session-scripts-using-kdm.txt"/>.
415 </para>
416 </listitem>
417
418 </itemizedlist>
419
420 </sect3>
421
422 </sect2>
423
424 <sect2 role="content">
425 <title>Contents</title>
426
427 <segmentedlist>
428 <segtitle>Installed Programs</segtitle>
429 <segtitle>Installed Library</segtitle>
430 <segtitle>Installed Directories</segtitle>
431
432 <seglistitem>
433 <seg>
434 dbus-cleanup-sockets, dbus-daemon, dbus-launch, dbus-monitor,
435 dbus-run-session, dbus-send, dbus-test-tool,
436 dbus-update-activation-environment, and dbus-uuidgenn
437 </seg>
438 <seg>
439 libdbus-1.so
440 </seg>
441 <seg>
442 /{etc,/usr/share}/dbus-1,
443 /usr/{include,lib}/dbus-1.0,
444 /usr/share/doc/dbus-&dbus-version; and
445 /var/{lib,run}/dbus
446 </seg>
447 </seglistitem>
448 </segmentedlist>
449
450 <variablelist>
451 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
452 <?dbfo list-presentation="list"?>
453 <?dbhtml list-presentation="table"?>
454
455 <varlistentry id="dbus-cleanup-sockets">
456 <term><command>dbus-cleanup-sockets</command></term>
457 <listitem>
458 <para>
459 is used to clean up leftover sockets in a directory.
460 </para>
461 <indexterm zone="dbus dbus-cleanup-sockets">
462 <primary sortas="b-dbus-cleanup-sockets">dbus-cleanup-sockets</primary>
463 </indexterm>
464 </listitem>
465 </varlistentry>
466
467 <varlistentry id="dbus-daemon">
468 <term><command>dbus-daemon</command></term>
469 <listitem>
470 <para>
471 is the <application>D-Bus</application> message bus daemon.
472 </para>
473 <indexterm zone="dbus dbus-daemon">
474 <primary sortas="b-dbus-daemon">dbus-daemon</primary>
475 </indexterm>
476 </listitem>
477 </varlistentry>
478
479 <varlistentry id="dbus-launch">
480 <term><command>dbus-launch</command></term>
481 <listitem>
482 <para>
483 is used to start <command>dbus-daemon</command> from a shell
484 script. It would normally be called from a user's login
485 scripts.
486 </para>
487 <indexterm zone="dbus dbus-launch">
488 <primary sortas="b-dbus-launch">dbus-launch</primary>
489 </indexterm>
490 </listitem>
491 </varlistentry>
492
493 <varlistentry id="dbus-monitor">
494 <term><command>dbus-monitor</command></term>
495 <listitem>
496 <para>
497 is used to monitor messages going through a
498 <application>D-Bus</application> message bus.
499 </para>
500 <indexterm zone="dbus dbus-monitor">
501 <primary sortas="b-dbus-monitor">dbus-monitor</primary>
502 </indexterm>
503 </listitem>
504 </varlistentry>
505
506 <varlistentry id="dbus-run-session">
507 <term><command>dbus-run-session</command></term>
508 <listitem>
509 <para>
510 start a process as a new <application>D-Bus</application> session.
511 </para>
512 <indexterm zone="dbus dbus-run-session">
513 <primary sortas="b-dbus-run-session">dbus-run-session</primary>
514 </indexterm>
515 </listitem>
516 </varlistentry>
517
518 <varlistentry id="dbus-send">
519 <term><command>dbus-send</command></term>
520 <listitem>
521 <para>
522 is used to send a message to a <application>D-Bus</application>
523 message bus.
524 </para>
525 <indexterm zone="dbus dbus-send">
526 <primary sortas="b-dbus-send">dbus-send</primary>
527 </indexterm>
528 </listitem>
529 </varlistentry>
530
531 <varlistentry id="dbus-test-tool">
532 <term><command>dbus-test-tool</command></term>
533 <listitem>
534 <para>
535 <application>D-Bus</application> traffic generator and test tool; it
536 is a multi-purpose tool for debugging and profiling
537 <application>D-Bus</application>.
538 </para>
539 <indexterm zone="dbus dbus-test-tool">
540 <primary sortas="b-dbus-test-tool">dbus-test-tool</primary>
541 </indexterm>
542 </listitem>
543 </varlistentry>
544
545 <varlistentry id="dbus-update-activation-environment">
546 <term><command>dbus-update-activation-environment</command></term>
547 <listitem>
548 <para>
549 update environment used for <application>D-Bus</application> session
550 services; it updates the list of environment variables used by
551 <command>dbus-daemon --session</command> when it activates session
552 services without using systemd.
553 </para>
554 <indexterm zone="dbus dbus-update-activation-environment">
555 <primary sortas="b-dbus-update-activation-environment">
556 dbus-update-activation-environment</primary>
557 </indexterm>
558 </listitem>
559 </varlistentry>
560
561 <varlistentry id="dbus-uuidgen">
562 <term><command>dbus-uuidgen</command></term>
563 <listitem>
564 <para>
565 is used to generate a universally unique ID.
566 </para>
567 <indexterm zone="dbus dbus-uuidgen">
568 <primary sortas="b-dbus-uuidgen">dbus-uuidgen</primary>
569 </indexterm>
570 </listitem>
571 </varlistentry>
572
573 <varlistentry id="libdbus-1">
574 <term><filename class="libraryfile">libdbus-1.so</filename></term>
575 <listitem>
576 <para>
577 contains the API functions used by the
578 <application>D-Bus</application> message daemon.
579 <application>D-Bus</application> is first a library that provides
580 one-to-one communication between any two applications;
581 <command>dbus-daemon</command> is an application that uses this
582 library to implement a message bus daemon.
583 </para>
584 <indexterm zone="dbus libdbus-1">
585 <primary sortas="c-libdbus-1">libdbus-1.so</primary>
586 </indexterm>
587 </listitem>
588 </varlistentry>
589
590 </variablelist>
591
592 </sect2>
593
594</sect1>
595
Note: See TracBrowser for help on using the repository browser.