Running hiped
hiped is the utility that provides the Hipe display server itself. To be able to run Hipe applications, hiped needs to be running, and the client applications need to be able to locate and access the appropriate files generated by the hiped instance.
hiped is implemented using Qt so needs to be run within an appropriate environment.
- One way to run it is within an existing X desktop environment. Client applications can then be allowed to create top-level frames within Hipe, which means they will appear as ordinary application windows within the desktop environment.
- Another way to run the hipe server is within its own dedicated X environment. Hipe doesn't require
an X window manager so the X environment can be kept almost completely empty apart from a Hipe framing manager/
desktop environment that manages the whole screen. The GNU/Linux environment usually reserves two TTYs for
graphical purposes (usually accessible using Ctrl+Alt+F7 and Ctrl+Alt+F8). Assuming you already have an X desktop
environment running in the first one, the following command would start hiped in the second one:
xinit hiped -- :1
At this point the user sees a blank screen, because no framing manager or client applications are running. Hipe is ready to accomodate them, but the actual desktop environment hasn't been launched yet. - Another way to run hiped is by using the LinuxFb platform provided by the Qt runtime environment. When run in this mode, X is not required, but hardware acceleration is not available. This mode is suitable for embedded systems. The Linux framebuffer is not a protected medium. Care must therefore be taken to set the system to a blank TTY before running hiped in this mode, or the TTY running behind hiped may receive the same keystrokes as the user's Hipe session. For more information about running a hiped, or any other Qt application, in such a mode, refer to the documentation on Qt's website.
Socket file, and host key
hiped generates the following files when running:
- A socket file, hipe.socket, which client applications connect to in order to utilise the Hipe display server.
- A hostkey file, hipe.hostkey. This file contains a unique key string that authorises a client application to create a top-level frame managing the entire screen. Each key can only be claimed once so the file is updated whenever a key is claimed. Multiple top-level frames can be created in which case the least recently created top-level frame will be covered up and hidden from view by more newly-created top-level clients. When hiped is run within an existing desktop environment, top-level frames are created as ordinary windows within the desktop environment.
By default, hiped creates the socket and hostkey files in one of the following directories (shown in order of precedence):
- If hiped is run by the root user, files are placed in /run/.
- If the environment variable XDG_RUNTIME_DIR has been set, this path is used. This is usually a subdirectory of /run/user/ which is uniquely assigned to each user of the operating system.
- As a last resort, hiped places the files in /tmp/.
The file placement scheme is formalised in this way to ensure that Hipe client applications will be able to locate and connect to the Hipe display server on most systems and create top-level frames without needing additional configuration. However, in many cases you will want to configure the file placement so that only trusted applications can create top-level frames, or to place the socket in a different location. The following command line parameters are available for this purpose:
hiped [--socket ⟨file path⟩] [--keyfile ⟨file path⟩]
With the above parameters, you can specify an alternative path (including the desired filename) for either or both files.
Having specified non-default locations, you now need to set up a runtime environment so that client applications can find the required files. Set the following environment variables to the same file paths:
- HIPE_SOCKET
- HIPE_KEYFILE
If set, Hipe client applications will look at these environment variables instead of looking in the default directory (as determined by the order of precedence above).
Hipe client applications do not have to be started from the same TTY as hiped. As long as the client application can locate the hiped runtime files as described above, the application will be granted a frame (window) in Hipe.
When you provide your own framing manager, you won't normally want to allow ordinary client applications to create their own top-level frames. Instead of accessing host-keys for creating top-level frames, the user's client applications will need to access host-keys for creating frames that are integrated within your desktop environment. In this case you have two options, and an additional environment variable you can utilise:
- Your framing manager can create and maintain its own hostkey file, updating it each time a new application creates a frame in the desktop environment. In this case, you would set up the environment variable HIPE_KEYFILE to point to the framing manager's hostkey file, rather than hiped's top-level hostkey file, once the framing manager has started running. You would also place the top-level hostkey file in a location that is inaccessible to ordinary applications.
- You can create a desktop environment that is responsible for launching applications itself. In this case, there is no need for a hostkey file. Instead, your desktop environment can set the HIPE_HOSTKEY environment variable uniquely for each application it spawns. This approach affords greater control to the desktop environment, and allows particular applications to be framed differently as special cases. However, because each hostkey expires as soon as it is claimed, this approach does not enable multiple client applications to be run directly from a TTY.
The demonstration framing manager, hipe-quadrant, doesn't do either of these things. Instead, it simply displays the newest hostkey on the screen and TTY, and the user then has to feed these into the test applications by hand. This manual approach demonstrates the concept, but would be far less than ideal in a real-world computing environment.
Other hiped command line options
The following invocation will list available command line options to your standard output:
hiped --help
The --fill option causes all top-level hipe clients to attempt to fill the entire screen in an environment where no window manager is running. This is particularly useful for embedded applications.
The --css option allows you to specify one or more CSS files which
will be read when hiped starts up. This allows you to specify global
default style rules which will be applied to all client applications running
within this session. Multiple CSS files should be separated by colons :
and use full path rather than the ~ token (which might not be correctly
expanded by the shell when multiple CSS files are specified).
When a client application is launched, the first CSS stylesheet (index 1)
is used by default, or the environment variable HIPE_THEME may be set
to an integer value to make the client use a different stylesheet. HIPE_THEME should be set
to the index number (countinng from 1) of the stylesheet to be used, or 0 if
no default stylesheet should be applied to the client session.