systemd/docs/WRITING_DESKTOP_ENVIRONMENTS.md
Frantisek Sumsal 0d592a5e17 docs: use absolute links for our pages
Since 56b2970 has proven to be a no-go for us, as it breaks existing
links, let's embrace the trailing slash and use absolute links
everywhere for our pages. This way we'll get around browser cleverly
appending the relative link to the current location (since it ends with
a slash), and given our docs/ layout is flat it's not much of a hassle
either.

Converted using this beauty:
  $ sed -ri 's/(\[.+\]\()([A-Z_]+\))/\1\/\2/g' *.md

Resolves: #32088 (again) and #32310
2024-04-17 21:21:23 +02:00

3.9 KiB

title category layout SPDX-License-Identifier
Writing Desktop Environments Documentation for Developers default LGPL-2.1-or-later

Writing Desktop Environments

Or: how to hook up your favorite desktop environment with logind

systemd's logind service obsoletes ConsoleKit which was previously widely used on Linux distributions. This provides a number of new features, but also requires updating of the Desktop Environment running on it, in a few ways.

This document should be read together with Writing Display Managers which focuses on the porting work necessary for display managers.

If required it is possible to implement ConsoleKit and systemd-logind support in the same desktop environment code, detecting at runtime which interface is needed. The sd_booted() call may be used to determine at runtime whether systemd is used.

To a certain level ConsoleKit and systemd-logind may be used side-by-side, but a number of features are not available if ConsoleKit is used.

Please have a look at the Bus API of logind and the C API as documented in sd-login(7). (Also see below)

Here are the suggested changes:

  • Your session manager should listen to "Lock" and "Unlock" messages that are emitted from the session object logind exposes for your DE session, on the system bus. If "Lock" is received the screen lock should be activated, if "Unlock" is received it should be deactivated. This can easily be tested with "loginctl lock-sessions". See the Bus API of logind for further details.
  • Whenever the session gets idle the DE should invoke the SetIdleHint(True) call on the respective session object on the session bus. This is necessary for the system to implement auto-suspend when all sessions are idle. If the session gets used again it should call SetIdleHint(False). A session should be considered idle if it didn't receive user input (mouse movements, keyboard) in a while. See the Bus API of logind for further details.
  • To reboot/power-off/suspend/hibernate the machine from the DE use logind's bus calls Reboot(), PowerOff(), Suspend(), Hibernate(), HybridSleep(). For further details see Bus API of logind.
  • If your session manager handles the special power, suspend, hibernate hardware keys or the laptop lid switch on its own it is welcome to do so, but needs to disable logind's built-in handling of these events. Take one or more of the handle-power-key, handle-suspend-key, handle-hibernate-key, handle-lid-switch inhibitor locks for that. See Inhibitor Locks for further details on this.
  • Before rebooting/powering-off/suspending/hibernating and when the operation is triggered by the user by clicking on some UI elements (or suchlike) it is recommended to show the list of currently active inhibitors for the operation, and ask the user to acknowledge the operation. Note that PK often allows the user to execute the operation ignoring the inhibitors. Use logind's ListInhibitors() call to get a list of these inhibitors. See Inhibitor Locks for further details on this.
  • If your DE contains a process viewer of some kind ("system monitor") it's a good idea to show session, service and seat information for each process. Use sd_pid_get_session(), sd_pid_get_unit(), sd_session_get_seat() to determine these. For details see sd-login(7).

And that's all! Thank you!