Hipe manual: Running hiped

Running `hiped`

hiped is the Hipe display server. Hipe applications need it to be running, and need to be able to find the files it creates.

Where to run it

hiped is a Qt application, and runs on any of Qt's display platforms that hipecore is built for.

Within an existing desktop environment (X11 or Wayland). Top-level Hipe applications appear as ordinary windows, managed by the desktop's window manager or compositor.
```
hiped &
```
As the entire desktop, on a bare X session. No window manager is needed. Start hiped with --fill so that top-level applications fill the screen; the first one is normally a framing manager that runs the rest of the desktop. From a text console, this starts it on a new X display:
```
xinit hiped --fill -- :1
```
The screen stays blank until a Hipe application is started. The script server/start_hipe_standalone_x11 does the same.
As the entire desktop, without X or Wayland, through Qt's EGLFS platform, which draws directly on the graphics hardware. This needs Qt and hipecore built with EGLFS support, and is less regularly tested than X11 and Wayland. Use --fill here too.

Choosing the platform

Qt picks a platform automatically. To choose one, set QT_QPA_PLATFORM when starting hiped:

Command	Runs on
`QT_QPA_PLATFORM=xcb hiped`	X11. On a Wayland desktop this runs through XWayland, which applications need in order to embed X11 windows (`HIPE_OP_GET_X11_XID`).
`QT_QPA_PLATFORM=wayland hiped`	Wayland.
`QT_QPA_PLATFORM=eglfs hiped --fill`	EGLFS, with no display server.

hiped doesn't accept Qt's -platform command line option; use the environment variable.

Socket file and host key

hiped creates two files when it starts:

hipe.socket, the socket that applications connect to.
hipe.hostkey, which holds the key an application needs to create a top-level frame. Each key can be used only once, so hiped writes a new one whenever a key is claimed.

By default both files go in the first of these directories that applies:

/run/, if hiped is run by the root user.
$XDG_RUNTIME_DIR, if set. This is usually a directory under /run/user/ belonging to the current user.
/tmp/.

Applications look in the same place, so on most systems they find hiped with no configuration. To put either file elsewhere, for example so that only trusted applications can read the host key, start hiped with:

hiped [--socket ⟨file path⟩] [--keyfile ⟨file path⟩]

and set HIPE_SOCKET and HIPE_KEYFILE to the same paths in the applications' environment.

Applications don't have to be started from the same terminal as hiped: any application that can find these files can be given a frame.

Giving keys to applications in your own desktop

When your own framing manager runs the desktop, ordinary applications shouldn't create top-level frames. Put the top-level key-file where only the framing manager can read it, and give applications keys to frames inside it instead, in one of two ways:

Through a key-file of its own. The framing manager keeps its own key-file, writing a new key each time one is claimed, and HIPE_KEYFILE points applications at it.
When it launches them. The framing manager starts applications itself and sets HIPE_HOSTKEY to a fresh key for each one. No key-file is needed, and it can treat particular applications differently, but applications can then only be started by the framing manager.

The sample framing manager, hipe-quadrant, does neither: it shows each new key on screen and in its terminal, to be given to applications by hand.

Command line options

Option	Effect
`--fill`	Top-level frames fill the entire screen. Use it when there's no window manager.
`--css` ⟨paths⟩	Default stylesheets for all applications (see below).
`--socket` ⟨file path⟩	Create the socket at this path.
`--keyfile` ⟨file path⟩	Create the top-level key-file at this path.
`--cursor`	Draw a mouse cursor, on systems where no regular cursor is available.
`--opengl`	Force OpenGL rendering.
`--random` ⟨file path⟩	Generate keys from this random device, e.g. `/dev/random`.
`--silent`	Print only critical errors.
`--help`	List the options.

Stylesheets and themes

--css takes one or more CSS files, separated by colons, which are read when hiped starts and applied to every application as default style rules. Use full paths rather than ~, which the shell might not expand when several files are listed.

Applications use the first stylesheet (index 1) by default. Setting HIPE_THEME in an application's environment selects another one by its index, counting from 1, or 0 for no default stylesheet.