Hipe : The DOM on the desktop
How Hipe Works  |  Installation  |  Running hiped  |  Hipe API

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.

Socket file, and host key

hiped generates the following files when running:

By default, hiped creates the socket and hostkey files in one of the following directories (shown in order of precedence):

  1. If hiped is run by the root user, files are placed in /run/.
  2. 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.
  3. 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:

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:

  1. 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.
  2. 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.