## Getting started with Phosh development

## Overview

Phosh is a graphical shell for Wayland. It’s target at mobile devices with small screens like Purism’s Librem 5 running adaptive GNOME applications.

It’s purpose is to provide a graphical user interface to launch applications, display status information (time, battery status, …), to provide a lock screen and to make often used functionality quickly accessible. It’s also meant to provide a proper interface when either connecting a keyboard and monitor to a phone or (but to a lesser extend) when running on a laptop.

Since it acts as a Wayland client it needs a compositor to function that provides the necessary protocols (most notably wlr-layer-shell). It’s usually used with phoc (the PHOne Compositor).

On the GNOME side it interfaces with the usual components (e.g. gnome-settings-daemon, upower, iio-sensor-proxy) via DBus. For haptic feedback it uses feedbackd.

It uses GTK as it’s GUI toolkit and libhandy for adaptive widgets.

Although targeted at touch devices Phosh does not implement a on screen keyboard (OSK) but leaves this to squeekboard.

The above combination of software is also often (a bit imprecisely) named Phosh.

### Wayland protocols

Since Phoc (in contrast to some other solutions) aims to be a minimal Wayland compositor that manages rendering, handle physical and virtual input and display devices but not much more it needs to provide some more protocols to enable graphical shells like Phosh. These are usually from wlr-protocols and Phoc uses the wlroots library for implementing them.

These are the most prominent ones use by Phosh:

- wlr-layer-shell: Usually Wayland clients have little influence on where the compositor places them. This protocol gives Phosh enough room to build the top bar via PhoshTopPanel, the home bar PhoshHome at the bottom, system modal dialogs e.g. #PhoshSystemPrompt and lock screens via PhoshLockscreen.

- wlr-foreign-toplevel-management: This allows the management of toplevels (windows). Phosh uses this to build an application switcher called PhoshOverview.

- wlr-output-management: This allows to manage a monitors power state (to e.g.turn it off when unused).

Besides those Phosh uses a number of “regular” Wayland client protocols like `xdg_output`, `wl_output` or `wl_seat` (see PhoshWayland for the full list).

### Session startup

Since Phosh is in many aspects a regular GTK application it’s started as part GNOME session so the start sequence looks like

    phoc (compositor) -> gnome-session -> phosh (and other session components)