Commit c6712eca authored by Benjamin Berg's avatar Benjamin Berg Committed by Ray Strode

doc: Add description of important systemd units to man page

parent fffd116f
......@@ -79,10 +79,63 @@ RequiredComponents=gnome-shell;gnome-settings-daemon;
.in
.fi
.PP
In \fBsystemd\fP managed sessions the RequiredComponents may be provided by
systemd units instead. In this case the corresponding \fB.desktop\fP file needs
to contain \fBX-GNOME-HiddenUnderSystemd=true\fP. \fIgnome-session\fP will
ignore these components and rely on \fIsystemd\fP to manage them appropriately,
see the \fIsystemd\fP for more information on how this works.
.PP
The \fB.session\fP files are looked for in
\fB$XDG_CONFIG_HOME/gnome-session/sessions\fP,
\fB$XDG_CONFIG_DIRS/gnome-session/sessions\fP and
\fB$XDG_DATA_DIRS/gnome-session/sessions\fP.
.SH systemd
\fIgnome-session\fP can pass much of the session management over to systemd
(see the \fI--systemd\fP option which may be the default since 3.34). In this
case, startup components that have \fBX-GNOME-HiddenUnderSystemd=true\fP
set in their \fB.desktop\fP file will be ignored by \fIgnome-session\fP. It
instead relies on the fact that these components are managed by systemd.
.PP
As of GNOME 3.34 the systemd support is new and the customizing the
configuration is not yet easily possible. With GNOME 3.34 it may be best to use
\fI--builtin\fP if session customizations are required. This is due to the way
that GNOME currently defines the components that will be started on each session
type.
.PP
\fBsystemd\fP provides the two special targets \fBgraphical-session.target\fP
and \fBgraphical-session-pre.target\fP which are fully functional and should be
used. \fIgnome-session\fP provides the following main targets:
.TP
.I "gnome-session.target"
Generic unit that will be active throughout the session. Similar to
\fBgraphical-session.target\fP.
.TP
.I "gnome-session-pre.target"
Used for tasks that need to be done before session startup. Similar to
\fBgraphical-session-pre.target\fP.
.TP
.I "gnome-session-x11@SESSION.target" "gnome-session-wayland@SESSION.target"
Main unit started for X11/wayland based session. \fBSESSION\fP is set according
to the session that is passed in \fI--session\fP.
.TP
.I "gnome-session-x11.target" "gnome-session-wayland.target"
Convenience units without the session embedded into the target.
.TP
.I "gnome-session@SESSION.target"
Convenience unit with just the \fBSESSION\fP information embedded.
.TP
.I "gnome-session-x11-services.target"
Special unit started when X11 services are needed. This will be used from GNOME
3.36 onwards. Programs will need to use the special \fBGNOME_SETUP_DISPLAY\fP
environment variable instead of \fIDISPLAY\fP.
.PP
Note that care must be taken to set appropriate \fBAfter=\fP rules. It is also
strongly recommended to always do this in combination with \fBBindsTo=\fP or
\fBPartOf=\fP on one of the core targets (e.g. \fBgraphical-session.target\fP).
.PP
Units are required to set \fBCollectMode=inactive-or-failed\fP. In addition, it
is strongly recommended to set \fBTimeoutStopSec=5\fP so that logout
will not be delayed indefinitely in case the process does not stop properly.
.SH ENVIRONMENT
\fIgnome-session\fP sets several environment variables for the use of
its child processes:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment