1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
+++
authors = ["Guido Günther"]
title = "Phosh Overview"
date = "2020-12-28"
tags = [ "phosh",
"development",
]
images = ["posts/phosh-overview/session.png"]
series = [
"Phosh internals"
]
+++
*This post first appeared on [Colors of Noise][1]. It's duplicated here
for reference to have the Phosh related posts together. URLs were updated
to point to current project locations.*
[phosh]() is graphical shell for mobile, touch based devices like
smart phones. It's the default graphical shell on Purism's
[Librem 5](https://puri.sm/products/librem-5/) (and that's where
it came to life) but projects like [postmarketOS](https://wiki.postmarketos.org/wiki/Phosh),
[Mobian](https://wiki.mobian-project.org/doku.php?id=intro) and
[Debian](https://packages.debian.org/sid/phosh) have picked it up
putting it into use on other devices as well and contributing patches.
This post is meant as a short overview how things are tied together so
further posts can provide more details.
## A PHone SHell
As mobile shell *phosh* provides the interface components commonly
found on mobile devices to
- launch applications
- switch between running applications and close them
- lock and unlock the screen
- display status information (e.g. network connectivity, battery level)
- provide quick access to things like torch or Bluetooth
- show notifications
It uses
[GObject](https://en.wikipedia.org/wiki/GObject) object system and
[GTK](https://en.wikipedia.org/wiki/GTK) to build up the user
interface components. Mobile specific patterns are brought in via
[libhandy](https://gitlab.gnome.org/GNOME/libhandy).
Since phosh is meant to blend into [GNOME](https://www.gnome.org/) as seamlessly as possible it
uses the common interfaces present there via
[D-Bus](https://en.wikipedia.org/wiki/D-Bus) like
`org.gnome.Screensaver` or `org.gnome.keyring.SystemPrompter` and
retrieves user configuration like keybindings via
[GSettings](https://developer.gnome.org/GSettings/) from preexisting
schema.
The components of a running graphical session roughly look like this:
The blue boxes are the very same found on GNOME desktop sessions
while the white ones are currently only found on
phones.
[feedbackd](https://source.puri.sm/Librem5/feedbackd) is explained
quickly: It's used for providing haptic or visual user feedback and
makes your phone rumble and blink when applications \(or the shell)
want to notify the user about certain events like incoming phone calls
or new messages. What about phoc and squeekboard?
## phoc and squeekboard
Although some stacks combine the graphical shell with the display server
(the component responsible for drawing applications and handling user
input) this isn't the case for phosh. phosh relies on a
[Wayland](https://en.wikipedia.org/wiki/Wayland_(display_server_protocol))
compositor to be present for that. Keeping shell and compositor apart
has some advantages like being able to restart the shell without
affecting other applications but also adds the need for some
additional communication between compositor and shell. This additional
communication is implemented via Wayland protocols. The Wayland
compositor used with phosh is called
[*phoc*](https://gitlab.gnome.org/World/Phosh/phoc) for *PHone
Compositor*.
One of these additional protocols is [wlr-layer-shell](https://gitlab.freedesktop.org/wlroots/wlr-protocols/-/blob/master/unstable/wlr-layer-shell-unstable-v1.xml).
It allows the shell to reserve space on the screen that is not used
by other applications and allows it to draw things like the top and
bottom bar or lock screen. Other protocols used by phosh (and hence implemented by phoc) are
[wlr-output-management](https://gitlab.freedesktop.org/wlroots/wlr-protocols/-/blob/master/unstable/wlr-output-management-unstable-v1.xml)
to get information on and control properties of monitors or
[wlr-foreign-toplevel-management](https://gitlab.freedesktop.org/wlroots/wlr-protocols/-/blob/master/unstable/wlr-foreign-toplevel-management-unstable-v1.xml)
to get information about other windows on the display. The later
is used to allow to switch between running applications.
However these (and other) Wayland protocols are not implemented in
phoc from scratch. phoc leverages the
[wlroots](https://gitlab.freedesktop.org/wlroots/wlroots) library for that. The library
also handles many other compositor parts like interacting with the
video and input hardware.
The details on how phoc actually puts things up on the screen deserves
a separate post. For the moment it's sufficient to note that phosh
requires a Wayland compositor like phoc.
We've not talked about entering text without a physical keyboard yet -
phosh itself does not handle that either.
[squeekboard](https://gitlab.gnome.org/World/Phosh/squeekboard) is the on
screen keyboard for text (and emoji) input. It again uses Wayland
protocols to talk to the Wayland compositor and it's (like phosh) a
component that wants exclusive access to some areas of the screen
(where the keyboard is drawn) and hence leverages the *layer-shell*
protocol. Very roughly speaking it turns touch input in that area into
text and sends that back to the compositor that then passes it back to
the application that currently gets the text input. squeekboard's main
author dcz has some more details
[here](https://dcz_self.gitlab.io/posts/input_method/).
## The session
So how does the graphical session in the picture above come into existence?
As this is meant to be close to a regular GNOME session it's done via
[gnome-session](https://gitlab.gnome.org/GNOME/gnome-session) that is
invoked somewhat like:
phoc -E 'gnome-session --session=phosh'
So the compositor *phoc* is started up, launches *gnome-session* which
then looks at *phosh.session* for the session's components. These are
*phosh*, *squeekboard* and *gnome-settings-daemon*.
These then either connect to already running services via D-Bus
(e.g. NetworkManager, ModemManager, ...) or spawn them via D-Bus
activation when required (e.g. feedbackd).
## Calling conventions
So when talking about phosh it's good to keep several things apart:
* phosh - the graphical *shell*
* phoc - the *compositor*
* squeekboard - the *on screen keyboard*
* phosh.session: The *session* that ties these and GNOME together
On top of that people sometimes refer to 'Phosh' as the software
collection consisting of the above plus more components from GNOME
(*Settings*, *Contacs*, *Clocks*, *Weather*, *Evince*, ...) and components that
currently aren't part of GNOME but adapt to small screen sizes, use
the same technologies and are needed to make a phone fun to use
e.g. *Geary* for email, *Calls* for making phone calls and *Chats* for SMS
handling.
Since just overloading the term Phosh is confusing *GNOME/Phosh
Mobile Environment* or *Phosh Mobile Environment* have been [used](https://salsa.debian.org/DebianOnMobile-team/meta-phosh/-/blob/debian/master/debian/control)
to describe the above collection of software and I've contacted GNOME on how to name
this properly, to not infringe on the GNOME trademark but also give proper credit
and hopefully being able to move things upstream that can live upstream.
That's it for a start. phosh's development documentation can be
browsed [here](https://world.pages.gitlab.gnome.org/Phosh/phosh) but is
also available in the [source code](https://gitlab.gnome.org/World/Phosh/phosh).
Besides the projects mentioned above credits go to
[Purism](https://puri.sm/) for allowing me and others to work on the
above and other parts related to moving Free Software on mobile Linux
forward.
[phosh]: https://source.puri.sm/Librem5/phosh
[phoc]: https://source.puri.sm/Librem5/phoc
[GTK]: https://gtk.org/
[documentation]: https://honk.sigxcpu.org/projects/phosh/docs/
[1]: https://honk.sigxcpu.org/con/phosh_overview.html
|
