source: general/sysutils/dbus.xml@ adf6dd9a

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 adf6dd9a was 4947a7a, checked in by Fernando de Oliveira <fernando@…>, 11 years ago

Rephrase tests intructions for dbus-1.6.16.

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

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