Attachment 129789 Details for Bug 99825 – dbus-daemon(1): Describe how session and system services are found

[patch] dbus-daemon(1): Describe how session and system services are found

0001-dbus-daemon-1-Describe-how-session-and-system-servic.patch (text/plain), 10.09 KB, created by Simon McVittie on 2017-02-21 11:55:12 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2017-02-21 11:55:12 UTC

Size: 10.09 KB

patch

obsolete

>From c6074830b5d0cc9984b10528a4c22736a53fc76f Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Fri, 17 Feb 2017 20:54:44 +0000
>Subject: [PATCH] dbus-daemon(1): Describe how session and system services are
> found
>
>For Unix, this partially duplicates the D-Bus Specification, but
>provides more detail about the intention of each search path element.
>It also documents the non-standardized path elements searched by the
>reference implementation.
>
>For Windows, there are no standardized path elements in the D-Bus
>Specification (and it isn't clear how useful it would be to standardize
>them, since Windows software that uses D-Bus tends to be installed
>as an integrated "stack" with a bundled copy of a suitable dbus-daemon),
>so we just document what the reference implementation does.
>
>Bug: https://bugs.freedesktop.org/show_bug.cgi?id=99825
>Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
>---
> doc/dbus-daemon.1.xml.in | 194 ++++++++++++++++++++++++++++++++++++++++++-----
> 1 file changed, 177 insertions(+), 17 deletions(-)
>
>diff --git a/doc/dbus-daemon.1.xml.in b/doc/dbus-daemon.1.xml.in
>index f2170377..04029641 100644
>--- a/doc/dbus-daemon.1.xml.in
>+++ b/doc/dbus-daemon.1.xml.in
>@@ -467,15 +467,22 @@ which mechanisms are listed is not meaningful.</para>
> 
> </itemizedlist>
> 
>-<para>Adds a directory to scan for .service files. Directories are
>-scanned starting with the first to appear in the config file
>-(the first .service file found that provides a particular
>-service will be used).</para>
>-
>-
>-<para>Service files tell the bus how to automatically start a program.
>-They are primarily used with the per-user-session bus,
>-not the systemwide bus.</para>
>+<para>
>+  Adds a directory to search for .service files, which tell the
>+  dbus-daemon how to start a program to provide a particular well-known
>+  bus name. See the D-Bus Specification for more details about the
>+  contents of .service files.
>+</para>
>+
>+<para>
>+  If a particular service is found in more than one &lt;servicedir&gt;,
>+  the first directory listed in the configuration file takes precedence.
>+  If two service files providing the same well-known bus name are found
>+  in the same directory, it is arbitrary which one will be chosen
>+  (this can only happen if at least one of the service files does not
>+  have the recommended name, which is its well-known bus name followed
>+  by ".service").
>+</para>
> 
> <itemizedlist remap='TP'>
> 
>@@ -484,17 +491,126 @@ not the systemwide bus.</para>
> 
> </itemizedlist>
> 
>-<para>&lt;standard_session_servicedirs/&gt; is equivalent to specifying a series
>-of &lt;servicedir/&gt; elements for each of the data directories in the "XDG
>-Base Directory Specification" with the subdirectory "dbus-1/services",
>-so for example "/usr/share/dbus-1/services" would be among the
>-directories searched.</para>
>-
>+<para>&lt;standard_session_servicedirs/&gt; requests a standard set of
>+  session service directories. Its effect is similar to specifying a series
>+  of &lt;servicedir/&gt; elements for each of the data directories,
>+  in the order given here.
>+  It is not exactly equivalent, because there is currently no way
>+  to disable directory monitoring or enforce strict service file naming
>+  for a &lt;servicedir/&gt;.</para>
>+
>+<para>
>+  As with &lt;servicedir/&gt; elements, if a particular service is found
>+  in more than one service directory, the first directory takes precedence.
>+  If two service files providing the same well-known bus name are found
>+  in the same directory, it is arbitrary which one will be chosen
>+  (this can only happen if at least one of the service files does not
>+  have the recommended name, which is its well-known bus name followed
>+  by ".service").
>+</para>
>+
>+<para>
>+  On Unix, the standard session service directories are:
>+  <itemizedlist>
>+    <listitem>
>+      <para>
>+        <emphasis>$XDG_RUNTIME_DIR</emphasis>/dbus-1/services,
>+        if XDG_RUNTIME_DIR is set (see the XDG Base Directory
>+        Specification for details of XDG_RUNTIME_DIR):
>+        this location is suitable for transient services created at runtime
>+        by systemd generators (see
>+        <citerefentry>
>+          <refentrytitle>systemd.generator</refentrytitle>
>+          <manvolnum>7</manvolnum>
>+        </citerefentry>),
>+        session managers or other session infrastructure.
>+        It is an extension provided by the reference implementation
>+        of dbus-daemon, and is not standardized in the D-Bus Specification.
>+      </para>
>+      <para>
>+        Unlike the other standard session service directories, this directory
>+        enforces strict naming for the service files: the filename must be
>+        exactly the well-known bus name of the service, followed by
>+        ".service".
>+      </para>
>+      <para>
>+        Also unlike the other standard session service directories, this
>+        directory is never monitored with
>+        <citerefentry>
>+          <refentrytitle>inotify</refentrytitle>
>+          <manvolnum>7</manvolnum>
>+        </citerefentry>
>+        or similar APIs. Programs that create service files in this directory
>+        while a dbus-daemon is running are expected to call the dbus-daemon's
>+        ReloadConfig() method after they have made changes.
>+      </para>
>+    </listitem>
>+    <listitem>
>+      <para>
>+        <emphasis>$XDG_DATA_HOME</emphasis>/dbus-1/services,
>+        where XDG_DATA_HOME defaults to ~/.local/share
>+        (see the XDG Base Directory Specification): this location is
>+        specified by the D-Bus Specification, and is suitable for per-user,
>+        locally-installed software.
>+      </para>
>+    </listitem>
>+    <listitem>
>+      <para>
>+        <emphasis>directory</emphasis>/dbus-1/services for each
>+        directory in XDG_DATA_DIRS, where XDG_DATA_DIRS defaults to
>+        /usr/local/share:/usr/share
>+        (see the XDG Base Directory Specification): these locations are
>+        specified by the D-Bus Specification. The defaults are suitable
>+        for software installed locally by a system administrator
>+        (/usr/local/share) or for software installed from operating system
>+        packages (/usr/share). Per-user or system-wide configuration that
>+        sets the XDG_DATA_DIRS environment variable can extend this search
>+        path to cover installations in other locations, for example
>+        ~/.local/share/flatpak/exports/share/ and
>+        /var/lib/flatpak/exports/share/ when
>+        <citerefentry>
>+          <refentrytitle>flatpak</refentrytitle>
>+          <manvolnum>1</manvolnum>
>+        </citerefentry>
>+        is used.
>+      </para>
>+    </listitem>
>+    <listitem>
>+      <para>
>+        <emphasis>${datadir}</emphasis>/dbus-1/services
>+        for the <emphasis>${datadir}</emphasis> that was specified when
>+        dbus was compiled, typically /usr/share: this location is an
>+        extension provided by the reference dbus-daemon implementation,
>+        and is suitable for software stacks installed alongside dbus-daemon
>+      </para>
>+    </listitem>
>+  </itemizedlist>
>+</para>
> 
> <para>The "XDG Base Directory Specification" can be found at
> <ulink url='http://freedesktop.org/wiki/Standards/basedir-spec'>http://freedesktop.org/wiki/Standards/basedir-spec</ulink> if it hasn't moved,
> otherwise try your favorite search engine.</para>
> 
>+<para>
>+  On Windows, the standard session service directories are:
>+  <itemizedlist>
>+    <listitem>
>+      <para>
>+        <emphasis>%CommonProgramFiles%</emphasis>/dbus-1/services
>+        if %CommonProgramFiles% is set: this location is suitable for
>+        system-wide installed software packages
>+      </para>
>+    </listitem>
>+    <listitem>
>+      <para>
>+        A share/dbus-1/services directory found in the same
>+        directory hierarchy (prefix) as the dbus-daemon: this location
>+        is suitable for software stacks installed alongside dbus-daemon
>+      </para>
>+    </listitem>
>+  </itemizedlist>
>+</para>
>+
> 
> <para>The &lt;standard_session_servicedirs/&gt; option is only relevant to the
> per-user-session bus daemon defined in
>@@ -509,9 +625,53 @@ configuration file would probably be nonsense.</para>
> </itemizedlist>
> 
> <para>&lt;standard_system_servicedirs/&gt; specifies the standard system-wide
>-activation directories that should be searched for service files.
>-This option defaults to @EXPANDED_DATADIR@/dbus-1/system-services.</para>
>+  activation directories that should be searched for service files.
>+  As with session services, the first directory listed has highest
>+  precedence.</para>
>+
>+<para>
>+  On Unix, the standard session service directories are:
>+  <itemizedlist>
>+    <listitem>
>+      <para>
>+        /usr/local/share/dbus-1/system-services: this location is
>+        specified by the D-Bus Specification, and is suitable for
>+        software installed locally by the system administrator
>+      </para>
>+    </listitem>
>+    <listitem>
>+      <para>
>+        /usr/share/dbus-1/system-services: this location is
>+        specified by the D-Bus Specification, and is suitable for
>+        software installed by operating system packages
>+      </para>
>+    </listitem>
>+    <listitem>
>+      <para>
>+        <emphasis>${datadir}</emphasis>/dbus-1/system-services
>+        for the <emphasis>${datadir}</emphasis> that was specified when
>+        dbus was compiled, typically /usr/share: this location is an
>+        extension provided by the reference dbus-daemon implementation,
>+        and is suitable for software stacks installed alongside dbus-daemon
>+      </para>
>+    </listitem>
>+    <listitem>
>+      <para>
>+        /lib/dbus-1/system-services: this location is
>+        specified by the D-Bus Specification, and was intended for
>+        software installed by operating system packages and used during
>+        early boot (but it should be considered deprecated, because
>+        the reference dbus-daemon is not designed to be available during
>+        early boot)
>+      </para>
>+    </listitem>
>+  </itemizedlist>
>+</para>
> 
>+<para>
>+  On Windows, there is no standard system bus, so there are no standard
>+  system bus directories either.
>+</para>
> 
> <para>The &lt;standard_system_servicedirs/&gt; option is only relevant to the
> per-system bus daemon defined in
>-- 
>2.11.0
>

Actions: View | Splinter Review

Attachments on bug 99825: 129626 | 129627 | 129628 | 129629 | 129630 | 129631 | 129632 | 129633 | 129634 | 129635 | 129636 | 129700 | 129701 | 129702 | 129703 | 129704 | 129705 | 129706 | 129707 | 129708 | 129709 | 129710 | 129711 | 129712 | 129713 | 129714 | 129715 | 129716 | 129717 | 129718 | 129719 | 129721 | 129722 | 129762 | 129763 | 129764 | 129765 | 129766 | 129767 | 129768 | 129769 | 129770 | 129771 | 129773 | 129774 | 129775 | 129776 | 129777 | 129778 | 129789 | 129791 | 129792 | 129800 | 129804

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.