posts: Copy over phosh overview

This appeared first at

https://honk.sigxcpu.org/con/phosh_overview.html

but let's make sure we have all the content together

4 files changed, 171 insertions, 0 deletions

diff --git a/content/posts/phosh-overview/index.md b/content/posts/phosh-overview/index.md
new file mode 100644
index 0000000..7095598
--- /dev/null
+++ b/content/posts/phosh-overview/index.md
@@ -0,0 +1,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
+
+![phosh's overview 2](overview2.png)
+![phosh's lockscreen](lockscreen.png)
+![phosh's overview 1](overview.png)
+
+- 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:
+
+![phosh session](session.png)
+
+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
diff --git a/content/posts/phosh-overview/lockscreen.png b/content/posts/phosh-overview/lockscreen.png
new file mode 100644
index 0000000..89e0471
--- /dev/null
+++ b/content/posts/phosh-overview/lockscreen.png
diff --git a/content/posts/phosh-overview/overview.png b/content/posts/phosh-overview/overview.png
new file mode 100644
index 0000000..e3c946f
--- /dev/null
+++ b/content/posts/phosh-overview/overview.png
diff --git a/content/posts/phosh-overview/overview2.png b/content/posts/phosh-overview/overview2.png
new file mode 100644
index 0000000..6d6dfdb
--- /dev/null
+++ b/content/posts/phosh-overview/overview2.png