Phoc – 0: Getting started with Phoc development
Description: Reference for Phoc-0: Getting started with Phoc development

#### Getting started with Phoc development

## Overview

Phoc is a Wayland compositor based on the wlroots library. It’s often used as a compositor for phosh, but works perfectly well on its own.

## Running

After building phoc, it can be run in several ways.

### Running nested

The easiest way is to run it nested within another graphical session. The supplied run script is able to detect that:

        ./_build/run -E gnome-terminal

This will launch phoc with either the X11 or Wayland backend rendering everything within a window in your current graphical session. The `-E` option specifies a program to be started by phoc, in this case we use gnome-terminal but any other application that opens a window will do.

### Running on hardware

The simplest way is to log into a terminal and use the same invocation as above:

        ./_build/run -E gnome-terminal

The script will notice that neither `$DISPLAY` nor `$WAYLAND_DISPLAY` is set and hence use the DRM backend.

Sometimes it isn’t easy to get to a virtual terminal and also have keyboard input (e.g. on a mobile phone). To help with that there’s a systemd unit. This will start phoc on a tty for the user with uid `1000`:

        cp _build/data/phoc-dev.service /etc/systemd/system/
        systemctl daemon-reload
        systemctl start phoc-dev

Make sure you stop other graphical session and display managers first. If you want to override some settings (e.g. a different user id to run phoc with) put these in `/etc/systemd/system/phoc-dev.service.d/override.conf`).

The systemd unit makes sure it picks up phoc from the freshly built source tree so whenever you made any changes it’s enough to invoke:

        systemctl restart phoc-dev

to run your modified version. Note that the systemd unit doesn’t launch phoc directly but via a small shell wrapper at `_build/data/phoc-dev` which is another good place to make some temporary changes like setting `PHOC_DEBUG` or `G_MESSAGES_DEBUG`.

To start an application in the running phoc run:

        WAYLAND_DISPLAY=wayland-0 gnome-terminal

Make sure you do this as the same user phoc runs with (uid 1000 by default).

Note that the systemd unit is meant for development purposes only.