Phosh Overview

• About
• Latest Posts

Guido Günther

Phone Developer

Latest posts by Guido Günther (see all)

• Opportunistic Word Completion - December 21, 2023
• Developing for Mobile Linux with Phosh – Part 0: Running Nested - February 21, 2023
• Phosh 2022 in Retrospect - January 9, 2023

This article is a repost from https://honk.sigxcpu.org/con/phosh_overview.html

phosh is graphical shell for mobile, touch based devices like smart phones. It’s the default graphical shell on Purism’s Librem 5 (and that’s where it came to life) but projects like Postmarket OS, Mobian and Debian 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 object system and GTK to build up the user interface components. Mobile specific patterns are brought in via libhandy.

Since phosh is meant to blend into GNOME as seamlessly as possible it uses the common interfaces present there via D-Bus like org.gnome.Screensaver or org.gnome.keyring.SystemPrompter and retrieves user configuration like keybindings via 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 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 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 for PHone Compositor.

One of these additional protocols is wlr-layer-shell. 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 to get information on and control properties of monitors or wlr-foreign-toplevel-management 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 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 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.

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 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 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 but is also available in the source code.

Besides the projects mentioned above credits go to Purism for allowing me and others to work on the above and other parts related to moving Free Software on mobile Linux forward.