From 2471324f4e57b47c70541b35278ffb95e0268207 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 17 Feb 2017 20:54:44 +0000 Subject: [PATCH 15/15] dbus-daemon(1): Describe how session services are found Signed-off-by: Simon McVittie --- doc/dbus-daemon.1.xml.in | 94 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 88 insertions(+), 6 deletions(-) diff --git a/doc/dbus-daemon.1.xml.in b/doc/dbus-daemon.1.xml.in index f2170377..13d5e279 100644 --- a/doc/dbus-daemon.1.xml.in +++ b/doc/dbus-daemon.1.xml.in @@ -484,17 +484,99 @@ not the systemwide bus. -<standard_session_servicedirs/> is equivalent to specifying a series -of <servicedir/> 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. - +<standard_session_servicedirs/> requests a standard set of + session service directories. Its effect is similar to specifying a series + of <servicedir/> elements for each of the data directories + (although not exactly equivalent, because there is currently no way + to disable directory monitoring or enforce strict service file naming + for a <servicedir/>). + + + On Unix, the standard session service directories are: + + + + $XDG_RUNTIME_DIR/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 + + systemd.generator + 7 + ), + session managers or other session infrastructure. + + + 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". + + + Also unlike the other standard session service directories, this + directory is never monitored with + + inotify + 7 + + 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. + + + + + $XDG_DATA_HOME/dbus-1/services, + where XDG_DATA_HOME defaults to ~/.local/share + (see the XDG Base Directory Specification): this location is + suitable for per-user, locally-installed software + + + + + directory/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 + suitable for locally-installed or system-wide software + + + + + ${datadir}/dbus-1/services + for the ${datadir} that was specified when + dbus was compiled, typically /usr/share: this location is + suitable for software stacks installed alongside dbus-daemon + + + + The "XDG Base Directory Specification" can be found at http://freedesktop.org/wiki/Standards/basedir-spec if it hasn't moved, otherwise try your favorite search engine. + + On Windows, the standard session service directories are: + + + + %CommonProgramFiles%/dbus-1/services + if %CommonProgramFiles% is set: this location is suitable for + system-wide installed software packages + + + + + 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 + + + + + The <standard_session_servicedirs/> option is only relevant to the per-user-session bus daemon defined in -- 2.11.0