From a67bdabcdc27e814f35f6ce6286878407dfa4f30 Mon Sep 17 00:00:00 2001 From: luhongxu Date: Thu, 15 Oct 2026 14:06:48 +0800 Subject: [PATCH] docs: update ddm documentation to match current code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Describe ddm as the Deepin Display Manager for Treeland and drop the removed QtQuick greeter from README, INSTALL and ARCHITECTURE. 2. Document the ddm-helper session helper, dde-seatd and the treeland_ddm_v1 protocol, and the real login flow. 3. Add the missing [Autologin] section and fix stale options, paths and the removed --test-mode in the man pages. 4. Replace the obsolete SDDM theming guide with a pointer to Treeland's greeter. 5. Fix the ddm.service description, which still said "Simple Desktop Display Manager". Log: ddm documentation (README, INSTALL, ARCHITECTURE, THEMING and man pages) is now consistent with the current code. Influence: 1. Build the man pages with cmake -DBUILD_MAN_PAGES=ON and check ddm(1), ddm.conf(5) and ddm-state.conf(5). 2. Follow the README and INSTALL build instructions on a deepin system. 3. Compare the architecture description with the ddm to Treeland login flow. docs: 根据当前代码更新 ddm 文档 1. 将 ddm 描述为面向 Treeland 的 Deepin Display Manager，并在 README、 INSTALL 和 ARCHITECTURE 中移除已删除的 QtQuick greeter。 2. 补充 ddm-helper 会话助手、dde-seatd 与 treeland_ddm_v1 协议， 以及真实的登录流程。 3. 在 man 手册中补充缺失的 [Autologin] 段，修正过时选项、路径 和已删除的 --test-mode。 4. 用指向 Treeland greeter 的说明替换过时的 SDDM 主题文档。 5. 修正 ddm.service 中仍为 "Simple Desktop Display Manager" 的描述。 Log: ddm 文档（README、INSTALL、ARCHITECTURE、THEMING 和 man 手册）已与当前代码保持一致。 Influence: 1. 使用 cmake -DBUILD_MAN_PAGES=ON 构建 man 手册，检查 ddm(1)、ddm.conf(5)、ddm-state.conf(5)。 2. 在 deepin 系统上按 README 和 INSTALL 的说明进行构建验证。 3. 对照 ddm 到 Treeland 的登录流程检查架构描述。 --- INSTALL.md | 59 ++++++++----- README.md | 43 ++++++++- README.zh_CN.md | 70 ++++++++++++++- data/man/ddm-state.conf.rst.in | 8 +- data/man/ddm.conf.rst.in | 42 ++++++--- data/man/ddm.rst.in | 57 +++++++----- docs/ARCHITECTURE.md | 153 ++++++++++++++++++++++++++++++--- docs/THEMING.md | 99 +++++---------------- services/ddm.service.in | 2 +- 9 files changed, 379 insertions(+), 154 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 12e8a8a..3d86080 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -2,38 +2,53 @@ DDM uses CMake to configure and build the project. - 1. From the project root, create a build directory: `mkdir build` - 2. From the build directory, run cmake to the project root. Eg: `cd build && cmake ..` - 3. To build, run `make`. - 4. To install, run `make install`. + 1. From the project root, configure the build directory: + `cmake -B build` + 2. To build, run `cmake --build build`. + 3. To install, run `cmake --install build`. CMake accepts a number of standard and extra arguments: - - BUILD_MAN_PAGES, pass -DBUILD_MAN_PAGES=ON to build man pages - - ENABLE_JOURNALD, pass -DENABLE_JOURNALD=OFF - to disable logging to the journal + - `BUILD_MAN_PAGES`, pass `-DBUILD_MAN_PAGES=ON` to build man pages. This + requires `rst2man` from the python `docutils` package. + - `WERROR`, pass `-DWERROR=ON` to build with `-Werror`. + - `LOGIN_DEFS_PATH`, path of `login.defs` used to autodetect `UID_MIN` and + `UID_MAX`. Defaults to `/etc/login.defs`. + - `DDM_INITIAL_VT`, the virtual terminal ddm starts on. Defaults to `1`. + - Install locations such as `CONFIG_FILE`, `CONFIG_DIR`, `SYSTEM_CONFIG_DIR`, + `STATE_DIR`, `RUNTIME_DIR`, `DATA_INSTALL_DIR`, `DBUS_CONFIG_DIR` and + `LOG_FILE` can be overridden in the same way. -By default, a debug build is created. To build for production, use -`cmake -DCMAKE_BUILD_TYPE=Release`. +By default, a `Release` build is created. To build a debug build, use +`cmake -DCMAKE_BUILD_TYPE=Debug -B build`. -To see all the possible arguments, run `cmake -L ..`. +To see all the possible arguments, run `cmake -L -B build`. For documentation on standard CMake variables, see: - http://www.cmake.org/cmake/help/v3.0/manual/cmake-variables.7.html + https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html ### Post-installation steps -By default, DDM runs as its own user. An `ddm` user needs to be created, with -its home set to `/var/lib/ddm` by default. +DDM runs its greeter as its own user, named **dde**. The user, its group and +its home directory (`/var/lib/ddm` by default) are created by +`systemd-sysusers` from the installed `dde.conf`; the runtime and state +directories are created by `systemd-tmpfiles`. Both are installed by the +package, so on a systemd distribution no manual step is required. + +DDM is started by `ddm.service`. It starts `treeland.service` for the login +screen and requires `dde-seatd.service`. Make sure all three units and the PAM +services (`ddm` and `ddm-autologin` in `/etc/pam.d`) are installed. ### Dependencies -DDM depends on PAM for authorization and XCB to communicate with the X server. -Apart from other things, it also depends on Qt for the user interface and event -loop management. -DDM can optionally make use of logind (the systemd login manager API), or -ConsoleKit2, or upower to enable support for suspend, hibernate etc. -In order to build the man pages, you will need `rst2man` installed. It is -provided by the python `docutils` package +DDM depends on PAM for authorization and on systemd-logind for opening user +sessions, and uses libxau to write X authorization files. Apart from other +things, it also depends on Qt 6 for its event loop and D-Bus communication. +It uses wayland-client and the `treeland_ddm_v1` protocol from +treeland-protocols to talk to the Treeland compositor, and dde-seatd to manage +virtual terminals. + +X11 sessions additionally require an X server at runtime; the path is +configured with the `X11.ServerPath` option. -Note that DDM makes use of C++11 features for a modern and clean codebase, -therefore it needs a recent version of GCC to compile (4.7 at least). +DDM makes use of C++20 features, therefore it needs a recent version of GCC to +compile. diff --git a/README.md b/README.md index 5256638..1d41db8 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,36 @@ # DDM -The `ddm` project is Display Manager base `SDDM` fork. +`ddm` (Deepin Display Manager) is the display and login manager for the +[Treeland](https://github.com/linuxdeepin/treeland) Wayland compositor. It is based on [SDDM](https://github.com/sddm/sddm), but the +QtQuick greeter it inherited is gone: the login screen is drawn by Treeland +itself, and `ddm` only manages the compositor, authenticates users and starts +their desktop sessions. + +See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how the pieces fit together. ## Dependencies -Check `debian/control` for build-time and runtime dependencies, or use `cmake` to check the missing required dependencies. +Check `debian/control` for build-time and runtime dependencies, or use `cmake` +to check the missing required dependencies. + +Core build dependencies: + +- Qt 6 (Core, DBus, Network), version 6.6 or newer +- [treeland-protocols](https://github.com/linuxdeepin/treeland-protocols) +- PAM, libsystemd, libxau and wayland-client +- ECM (extra-cmake-modules) 1.4 or newer + +Runtime dependencies: + +- [treeland](https://github.com/linuxdeepin/treeland) — the greeter and, for + single-mode sessions, the compositor the user session runs in +- [dde-seatd](https://github.com/linuxdeepin/dde-seatd) — seat and virtual + terminal management +- systemd-logind, used to open user sessions ## Building -Regular CMake building steps applies, in short: +Regular CMake building steps apply, in short: ```shell $ cmake -Bbuild @@ -16,6 +38,9 @@ $ cmake --build build $ cmake --install build # only do this if you know what you are doing ``` +The man pages are only built with `-DBUILD_MAN_PAGES=ON`, and require `rst2man` +from the python `docutils` package. + A `debian` folder is provided to build the package under the *deepin* linux desktop distribution. To build the package, use the following command: ```shell @@ -23,6 +48,18 @@ $ sudo apt build-dep . # install build dependencies $ dpkg-buildpackage -uc -us -nc -b # build binary package(s) ``` +## Running + +`ddm` is meant to be started by its systemd unit as the display manager: + +```shell +$ systemctl start ddm.service +``` + +It starts `treeland.service` for the login screen and requires +`dde-seatd.service`. Both units, the PAM services and the `dde` greeter user +are installed by the package. + ## Getting Involved - [Code contribution via GitHub](https://github.com/linuxdeepin/ddm/) diff --git a/README.zh_CN.md b/README.zh_CN.md index bc60bf4..e0c939e 100644 --- a/README.zh_CN.md +++ b/README.zh_CN.md @@ -1 +1,69 @@ -TODO: +# DDM + +`ddm`（Deepin Display Manager）是 +[Treeland](https://github.com/linuxdeepin/treeland) Wayland 合成器的显示与登录 +管理器。它基于 [SDDM](https://github.com/sddm/sddm)，但不再使用从 +SDDM 继承的 QtQuick greeter：登录界面由 Treeland 自己绘制，`ddm` 只负责管理 +合成器、认证用户并启动用户桌面会话。 + +各组件之间的关系参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 + +## 依赖 + +查看 `debian/control` 了解构建时和运行时依赖，或者使用 `cmake` 检查缺失的 +必要组件。 + +核心构建依赖： + +- Qt 6（Core、DBus、Network），版本 6.6 或更高 +- [treeland-protocols](https://github.com/linuxdeepin/treeland-protocols) +- PAM、libsystemd、libxau 和 wayland-client +- ECM（extra-cmake-modules）1.4 或更高 + +运行时依赖： + +- [treeland](https://github.com/linuxdeepin/treeland) —— 提供登录界面，并在 + single 模式下作为用户会话所在的合成器 +- [dde-seatd](https://github.com/linuxdeepin/dde-seatd) —— seat 与虚拟终端管理 +- systemd-logind —— 用于打开用户会话 + +## 构建 + +常规的 CMake 构建步骤即可，简要如下： + +```shell +$ cmake -Bbuild +$ cmake --build build +$ cmake --install build # 只有明确知道后果时才执行安装 +``` + +只有传入 `-DBUILD_MAN_PAGES=ON` 才会构建 man 手册，且需要 python `docutils` +提供的 `rst2man`。 + +仓库提供了 `debian` 目录用于在 *deepin* Linux 发行版下打包。构建软件包使用 +以下命令： + +```shell +$ sudo apt build-dep . # 安装构建依赖 +$ dpkg-buildpackage -uc -us -nc -b # 构建二进制软件包 +``` + +## 运行 + +`ddm` 由自身的 systemd 服务作为显示管理器启动： + +```shell +$ systemctl start ddm.service +``` + +它会启动 `treeland.service` 以提供登录界面，并依赖 `dde-seatd.service`。 +这些服务、PAM 配置以及 `dde` greeter 用户均由软件包安装。 + +## 参与贡献 + +- [通过 GitHub 贡献代码](https://github.com/linuxdeepin/ddm/) +- [在 GitHub Issues 或 GitHub Discussions 提交问题或建议](https://github.com/linuxdeepin/developer-center/issues/new/choose) + +## 许可证 + +**ddm** 使用 GPL-2.0+ 许可证。详细信息参见 REUSE 文件。 diff --git a/data/man/ddm-state.conf.rst.in b/data/man/ddm-state.conf.rst.in index 6e695e7..222828f 100644 --- a/data/man/ddm-state.conf.rst.in +++ b/data/man/ddm-state.conf.rst.in @@ -14,12 +14,14 @@ ddm configuration SYNOPSIS ======== -~ddm/state.conf +@STATE_DIR@/state.conf DESCRIPTION =========== This file carries state configuration for the ddm display manager **ddm**\(1\). +It lives in the home directory of the **dde** user, which is **@STATE_DIR@**. +It is written by ddm and does not need to be edited by hand. OPTIONS ======= @@ -39,6 +41,6 @@ All options are configured in the [Last] section: SEE ALSO ======== -**ddm**\(1\) +**ddm**\(1\), **ddm.conf**\(5\) -The full documentation for ddm is available at https://github.com/ddm/ddm +The full documentation for ddm is available at https://github.com/linuxdeepin/ddm diff --git a/data/man/ddm.conf.rst.in b/data/man/ddm.conf.rst.in index 33d0055..2f5af33 100644 --- a/data/man/ddm.conf.rst.in +++ b/data/man/ddm.conf.rst.in @@ -55,10 +55,23 @@ OPTIONS `CursorTheme=` Name of the cursor theme to be set before starting - the display server. + an X11 display server. `CursorSize=` - Cursor size to be set before starting the display server. + Cursor size to be set before starting an X11 display server. + +[Autologin] section: + +`User=` + User to log in automatically. An empty value disables automatic login. + The user must not be the greeter user **dde**. + Default value is empty. + +`Session=` + Session to load for automatic login. This overrides the last used + session. If it is empty, the session remembered in + **ddm-state.conf**\(5\) is used. + Default value is empty. [X11] section: @@ -82,18 +95,16 @@ OPTIONS `SessionLogFile=` Path to the user session log file, relative to the home directory. - Default value is ".local/share/ddm/xorg-session.log". + Default value is ".local/share/ddm/xorg-session.log". `DisplayCommand=` - Path of script to execute when starting the display server. - The script will be executed as root when General.DisplayServer - is "x11", otherwise as ddm user. + Path of script to execute when starting the X11 display server. + The script is executed as root by the ddm daemon. Default value is "@DATA_INSTALL_DIR@/scripts/Xsetup". `DisplayStopCommand=` - Path of script to execute when stopping the display server. - The script will be executed as root when General.DisplayServer - is "x11", otherwise as ddm user. + Path of script to execute when stopping the X11 display server. + The script is executed as root by the ddm daemon. Default value is "@DATA_INSTALL_DIR@/scripts/Xstop". [Wayland] section: @@ -115,9 +126,12 @@ OPTIONS [Single] section: `SessionCommand=` - Path of script to execute when starting the user session for Treeland. - This script receives the value of the "Exec" setting in the ".desktop" file - of the selected session and run it. + Path of script to execute when starting the user session for a + single-mode Treeland session (a session whose desktop file sets + X-DDE-SINGLE-WAYLAND=true). Such a session runs inside the already + running Treeland instance instead of starting its own compositor. + The script receives the value of the "Exec" setting in the ".desktop" + file of the selected session and runs it. Default value is "@WAYLAND_SESSION_COMMAND@". [Users] section: @@ -142,6 +156,6 @@ OPTIONS SEE ALSO ======== -**ddm**\(1\) +**ddm**\(1\), **ddm-state.conf**\(5\) -The full documentation for ddm is available at https://github.com/ddm/ddm +The full documentation for ddm is available at https://github.com/linuxdeepin/ddm diff --git a/data/man/ddm.rst.in b/data/man/ddm.rst.in index cebc5d0..bcaf982 100644 --- a/data/man/ddm.rst.in +++ b/data/man/ddm.rst.in @@ -19,28 +19,27 @@ ddm [OPTIONS...] DESCRIPTION =========== -ddm is a display and login manager based on Qt technologies and using -Treeland as greeter. - -If pam and systemd are available, the greeter will go through logind, -which will give it access to drm devices. - -Distributions without pam and systemd will need to put the **ddm** user -into the **video** group, otherwise errors regarding GL and drm devices -might be experienced. - -For X11 sessions, the cookie for X authorization is written into a -temporary file `/tmp/xauth_XXXXXX`, owned and only accessible by the +ddm is the Deepin Display Manager, the display and login manager for the +Treeland Wayland compositor. It authenticates users with PAM, starts their +desktop sessions and keeps the login screen running on the initial virtual +terminal. + +The login screen itself is not part of ddm: it is drawn by Treeland, which ddm +starts as the **treeland.service** systemd unit. ddm talks to Treeland through +the private **treeland_ddm_v1** Wayland protocol and through a local socket, +and talks to **dde-seatd** for virtual terminal management. User sessions are +opened through systemd-logind. + +X11 sessions are also supported: for those, ddm stops Treeland and starts an X +server instead. For X11 sessions, the cookie for X authorization is written +into a temporary file `/tmp/xauth_XXXXXX`, owned and only accessible by the user. OPTIONS ======= ---test-mode - Start daemon in test mode. - --example-config - Print the complete current configuration to stdout + Print the complete current configuration to stdout and exit. --help, -h Show help message and exit. @@ -48,18 +47,30 @@ OPTIONS FILES ===== -**@SYSTEM_CONFIG_DIR@** - System configuration directory +**@CONFIG_FILE@** + Local configuration file. **@CONFIG_DIR@** - Local configuration directory + Local configuration directory, has higher precedence than the + configuration file. -**@CONFIG_FILE@** - Local configuration file for compatibility +**@SYSTEM_CONFIG_DIR@** + System configuration directory, has the lowest precedence. + +**@STATE_DIR@/state.conf** + State file remembering the last user and session. + See **ddm-state.conf**\(5\). + +**@RUNTIME_DIR@** + Runtime directory, holds the X11 authorization file of the display + server. + +**@LOG_FILE@** + Log file, used when ddm does not log to the journal. SEE ALSO ======== -**ddm.conf**\(5\) +**ddm.conf**\(5\), **ddm-state.conf**\(5\) -The full documentation for ddm is available at https://github.com/ddm/ddm +The full documentation for ddm is available at https://github.com/linuxdeepin/ddm diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b53dc80..bfc5960 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,14 +1,147 @@ ## Introduction -DDM consists of two main parts: the daemon (aka backend) and the greeter (aka frontend). -## Daemon -Below are the main responsibilities of the daemon. +DDM (Deepin Display Manager) is the display and login manager for the +[Treeland](https://github.com/linuxdeepin/treeland) Wayland compositor. It +authenticates users with PAM, starts their desktop sessions and keeps the login +screen running on the initial virtual terminal. -### Application Lifecycle management -### Seat management -### Display management -### Authentication -### Power management. +DDM does not draw the login screen. The greeter is part of Treeland, which DDM +starts as the `treeland.service` systemd unit and which runs as the `dde` user. +DDM only manages the lifecycle of the compositor, the seats and the user +sessions. -## Greeter -Greeter is responsible for presenting the user interface. User interfaces are developed using the QtQuick framework. For detailed information, check out [the theming page](https://github.com/ddm/ddm/wiki/Theming). +## Components + +| Component | Description | +| --- | --- | +| `ddm` | The daemon, started by `ddm.service` as root. | +| `ddm-helper` | Session helper, spawned by the daemon for every authentication. | +| `libddm-common` | Shared library with configuration, session and X authorization helpers. | +| `treeland.service` | The compositor providing the greeter, run as the `dde` user. | +| `dde-seatd.service` | Seat and virtual terminal management. | + +### Daemon + +The daemon (`src/daemon`) is a `QCoreApplication` that owns: + +- **Seat management** (`SeatManager`): enumerates logind seats and creates one + `Display` per graphical seat. +- **Display management** (`TreelandDisplayServer`, `XorgDisplayServer`): starts + and stops the Treeland compositor, or an X server for X11 sessions. +- **Authentication** (`Auth`): runs the PAM transaction through `ddm-helper` and + opens the logind session. +- **Application lifecycle** (`Display`): turns greeter requests into logins, + logouts, locks and unlocks. +- **Power management** (`PowerManager`): power off, reboot, suspend, hibernate + and hybrid sleep through logind, ConsoleKit2 or UPower, whichever is + available. +- **Virtual terminals** (`DdeSeatdControl`): asks `dde-seatd` to allocate + grouped VTs and reports VT changes. + +### Session helper + +`ddm-helper` (`src/helper`) is a standalone, single-threaded +`QCoreApplication`. The daemon spawns it with `fork()`/`exec()` and talks to it +over an inherited socketpair. It runs the full PAM transaction +(`pam_authenticate()` and `pam_open_session()`) and starts the user's session +process. + +Running PAM in a separate process keeps DDM safe from PAM modules that fork +inside `pam_open_session()` (for example gnome-keyring): forking a +multi-threaded Qt process and letting the child call `exit()` can deadlock on +Qt's inherited `atexit` handlers. + +### Treeland + +Treeland is the compositor and the greeter. It is started by DDM as +`treeland.service` with the `--lockscreen` option, running as the `dde` user. +Its greeter implementation lives in `src/greeter` and the `LockScreen` QML +plugin, and exposes `GreeterProxy`, `SessionModel` and `UserModel` to the login +screen. + +For sessions whose desktop file sets `X-DDE-SINGLE-WAYLAND=true`, the user +session runs inside the already running Treeland instance instead of starting +its own compositor. Otherwise DDM stops Treeland and starts the session's own +display server. + +### dde-seatd + +`dde-seatd` is a fork of `seatd`. DDM talks to its control socket +(`/run/dde-seatd-control.sock`) to allocate and destroy grouped VTs and to be +notified about VT changes. Treeland uses the regular libseat seatd backend +against `/run/dde-seatd.sock`. + +## Login flow + +1. `ddm.service` starts the daemon. `SeatManager` enumerates logind seats and + creates a `Display` for every graphical seat. +2. The `Display` picks a virtual terminal, starts `treeland.service`, starts a + local socket server and publishes the socket path over D-Bus as + `org.deepin.DisplayManager.AuthInfo`. +3. The Treeland greeter connects to that socket and sends `Connect` with the + path of its Wayland socket. The daemon connects to it and binds the private + `treeland_ddm_v1` protocol. It then sends the host name, the power + capabilities and `ShowGreeter`. +4. When the greeter sends `Login`, the daemon authenticates the user with + `ddm-helper`. On success it saves the last user and session in + `state.conf` and starts the session. +5. The session type decides what happens next: + - **Single-mode Treeland** (`X-DDE-SINGLE-WAYLAND=true`): the daemon asks + `dde-seatd` for a grouped VT, opens the logind session and asks Treeland to + switch to the user. + - **Wayland**: the daemon stops Treeland and runs the session's compositor + through the `Wayland.SessionCommand` script. + - **X11**: the daemon stops Treeland, starts the X server with an + authorization file in `RUNTIME_DIR` (`/run/ddm/xauth_XXXXXX`), writes the + user session's authorization cookie to `/tmp/xauth_XXXXXX` and runs the + session through the `X11.SessionCommand` script. +6. `Logout`, `Lock` and `Unlock` messages are forwarded to systemd-logind + (`TerminateSession()`, `LockSession()`, `UnlockSession()`). Unlocking also + activates the session again, either through Treeland or by switching to the + session's VT. +7. When the session process exits, the daemon removes the session and frees + its grouped VT. For X11 sessions the stopped X server also tears the + display down, which makes the seat recreate itself and start Treeland + again for the login screen. + +VT switches are driven by `dde-seatd`: on every VT change the daemon tells +Treeland to switch to the greeter or to the user owning the new VT. + +## Communication + +### Greeter socket + +The greeter talks to the daemon over a local socket named +`ddm-treeland-XXXXXX`. Messages are framed with a `quint32` opcode: + +- greeter to daemon: `Connect`, `Login`, `Logout`, `Lock`, `Unlock`, + `PowerOff`, `Reboot`, `Suspend`, `Hibernate`, `HybridSleep`, `BackToNormal`. +- daemon to greeter: `HostName`, `Capabilities`, `LoginFailed`, + `InformationMessage`, `UserActivateMessage`, `SwitchToGreeter`, + `UserLoggedIn`, `ShowGreeter`. + +The opcodes are defined in `src/common/Messages.h`. + +### Wayland protocol + +The daemon binds the private `treeland_ddm_v1` global of the Treeland +compositor (see the treeland-protocols repository) and uses it to switch +between the greeter and a user. The deprecated `switch_to_vt` and `acquire_vt` +events are ignored, as VT switching is handled by `dde-seatd` and +wlroots/libseat. + +### D-Bus + +The daemon registers `org.freedesktop.DisplayManager` at +`/org/freedesktop/DisplayManager` (seats, sessions, `LastSession`) and the +deepin-specific `org.deepin.DisplayManager` at `/org/deepin/DisplayManager` +(`AuthInfo`, `LastActivatedUser`). The greeter uses the latter to find the +daemon socket and to know which user was activated last. + +## Configuration + +Configuration is loaded, from lowest to highest precedence, from the system +configuration directory (`${CMAKE_INSTALL_PREFIX}/lib/ddm/ddm.conf.d`, which +defaults to `/usr/local/lib/ddm/ddm.conf.d`), `/etc/ddm.conf.d` and +`/etc/ddm.conf`. The last user and session are stored in `state.conf` in the +`dde` user's home directory. See **ddm.conf**(5) and **ddm-state.conf**(5). diff --git a/docs/THEMING.md b/docs/THEMING.md index ed85614..e38032c 100644 --- a/docs/THEMING.md +++ b/docs/THEMING.md @@ -1,82 +1,27 @@ ## Themes -DDM themes are created using the QtQuick framework, a declarative framework to develop next-generation, hardware-accelerated user interfaces with fluid animations. QtQuick offers some basic components. - -On top of QtQuick, we provide some custom components to make theme development even easier. For example a picturebox which can show user avatars. Most of the components can be used as views in a model-view sense. - -We also provide models containing information about the screens, available sessions and users. Connect these with the provided components and to have a fully working solution. For example, below is the whole _code_ needed to create a session selection combobox: - - ComboBox { - id: session - arrowIcon: "angle-down.png" - model: sessionModel - index: sessionModel.lastIndex - } - -## Proxy Object - -We provide a proxy object, called as `ddm` to the themes as a context property. This object holds some useful properties about the host system. It also acts as a proxy between the greeter and the daemon. All of the methods called on this object will be transferred to the daemon through a local socket to be executed there. - -### Properties - -**hostName:** Holds the name of the host computer. - -**canPowerOff:** true, if we can power off the machine; false, otherwise - -**canReboot:** true, if we can reboot the machine; false, otherwise - -**canSuspend:** true, if the machine supports suspending to the memory; false, otherwise - -**canHibernate:** true, if the machine supports hibernating, e.g suspending to the disk; false, otherwise - -**canHybridSleep:** true, if the machine supports hybrid sleep, e.g suspending to both memory and disk; false, otherwise - -### Methods - -**powerOff():** Powers of the machine. - -**reboot():** Reboots the machine. - -**suspend():** Suspends the machine to the memory. - -**hibernate():** Suspends the machine to the disk. - -**hybridSleep():** Suspends the machine both to the memory and the disk. - -**login(user, password, sessionIndex):** Attempts to login as the `user`, using the `password` into the session pointed by the `sessionIndex`. Either the `loginFailed` or the `loginSucceeded` signal will be emitted depending on whether the operation is successful or not. - -### Signals - -**loginFailed():** Emitted when a requested login operation fails. - -**loginSucceeded():** Emitted when a requested login operation succeeds. - -## Data Models -Besides the proxy object we offer a few models that can be hooked to the views to handle multiple screens or enable selection of users or sessions. - -**screenModel:** This is a list model containing geometry information of the screens available. This model only provides logical screen numbers and geometries. If you have two physical monitors, but configured to be duplicates we only report one screen. - -For each screen the model provides `name` and `geometry` properties. -The model also provides, a `primary` property pointing to the index of the primary monitor and a `geometry` method which takes a monitor index and returns the geometry of it. If you pass `-1` to the `geometry` method it will return the united geometry of all the screens available. - -**sessionModel:** This is a list model which contains information about the desktop sessions installed on the system. This information is gathered by parsing the desktop files in the `/usr/share/xsessions` directory. These desktop files are generally installed when you install a desktop environment or a window manager. - -For each session, the model provides `file`, `name`, `exec` and `comment` properties. -Also there is a `lastIndex` property, pointing to the last session the user successfully logged in. - -**userModel:** This is list model. Contains information about the users available on the system. This information is gathered by reading the user database provided by `getpwent()`. To prevent system users polluting the user model we only show users with user ids greater than a certain threshold. This threshold is adjustable through the config file and called `MinimumUid`. - -For each user the model provides `name`, `realName`, `homeDir` and `icon` properties. -This model also has a `lastIndex` property holding the index of the last user successfully logged in, and a `lastUser` property containing the name of the last user successfully logged in. +DDM does not implement a greeter and therefore ships no theming API of its own. +The login screen is drawn by +[Treeland](https://github.com/linuxdeepin/treeland), which runs the greeter as +the `LockScreen` QML plugin. + +The QtQuick greeter that DDM inherited from SDDM — the `ddm` context object, +`ddm-greeter`, and the `screenModel`, `sessionModel` and `userModel` models — +no longer exists in this repository. Their equivalents are provided by +Treeland's greeter: + +- `GreeterProxy` (QML singleton in the `Treeland` module) holds the host name, + the power capabilities and the lock state, and forwards login, logout, lock + and unlock requests to DDM over the greeter socket. +- `SessionModel` and `UserModel` (QML singletons in the `Treeland` module) + list the available desktop sessions and users. + +The login screen itself is the `Greeter`/`LoginView` QML in Treeland's +lockscreen plugin. Customizing the login screen therefore means changing that +QML in the Treeland repository, not adding a theme to DDM. ## Testing -You can test your themes using `ddm-greeter`. Note that in this mode, actions like shutdown, suspend or login will have no effect. - - ddm-greeter --test --theme /path/to/your/theme - -If you have compiled DDM with Qt4, you can also use it in a nested X session through Xephyr. To accomplish this use: - - ddm --test-mode - -When using Qt5, test-mode requires [at least xorg-server 1.15.0](https://bugs.freedesktop.org/show_bug.cgi?id=62346#c8), as older releases don't support GLX in Xephyr which is required by QtQuick2. +DDM no longer ships a `ddm-greeter` test binary. To test the login screen, +start `treeland.service` directly; the greeter connects to DDM through the +socket published on the `org.deepin.DisplayManager.AuthInfo` D-Bus property. diff --git a/services/ddm.service.in b/services/ddm.service.in index 9cf9b9f..2bf14f5 100644 --- a/services/ddm.service.in +++ b/services/ddm.service.in @@ -1,5 +1,5 @@ [Unit] -Description=Simple Desktop Display Manager +Description=Deepin Display Manager Documentation=man:ddm(1) man:ddm.conf(5) Conflicts=getty@tty${DDM_INITIAL_VT}.service After=systemd-user-sessions.service getty@tty${DDM_INITIAL_VT}.service plymouth-quit.service systemd-logind.service dde-seatd.service