DOCSEARCHbyAlgolia
Submit Docs

Cage Kiosk Compositor

repository·master·Indexed 24 days ago

https://github.com/cage-kiosk/cage

A Wayland kiosk compositor designed to run a single, maximized application. Based on wlroots, Cage is intended for dedicated hardware setups and supports multi-output modes, XWayland, and KMS+DRM backend operation.

Tokens
913
Snippets
4
Records
6
Agent score
34%

What's inside Cage

  1. Build Cage from source

    master

    Cage uses the meson build system. To build Cage, you must have wayland, wlroots, and xkbcommon installed on your system. Optionally, install scdoc to generate manual pages.

    Cage is currently based on branch 0.20 of wlroots. If you require XWayland support, ensure your wlroots version is compiled with XWayland support and that the XWayland binary is installed on your system.

    $ meson setup build
$ meson compile -C build

  3. Run Cage with an application

    master

    To start Cage, run the compiled binary followed by the application you wish to run in kiosk mode.

    Behavior depends on the environment:

    • Inside an existing X11 or Wayland session: Cage opens in a virtual output as a window.
    • At a TTY: Cage runs using the KMS+DRM backend.

    In debug builds (the default Meson build type), you can quit Cage by pressing Alt+Esc.

    ./build/cage APPLICATION

  4. Terminate the Cage server with server_terminate()

    master

    To gracefully shut down the Cage server instance, call server_terminate(). This function takes a pointer to a cg_server struct and handles the termination process.

    void server_terminate(struct cg_server *server);

  5. Reference the cg_server structure members

    master

    The cg_server struct is the central state container for the Cage Wayland kiosk. It manages Wayland displays, wlroots backend components, scene graphs, and various protocol managers.

    Key functional groups within cg_server include:

    Core Wayland & wlroots Components

    • wl_display: The Wayland display instance.
    • backend: The wlroots backend.
    • renderer: The wlroots renderer.
    • allocator: The wlroots allocator.
    • session: The wlroots session.
    • scene: The wlroots scene graph.

    Output Management

    • output_mode: Current cg_multi_output_mode.
    • output_layout: The wlr_output_layout.
    • scene_output_layout: The wlr_scene_output_layout.
    • outputs: A wl_list of cg_output objects.

    Input & Interaction

    • seat: The cg_seat managing input.
    • idle: wlr_idle_notifier_v1 for idle detection.
    • idle_inhibit_v1: Manager for inhibiting idle state.
    • relative_pointer_manager: wlr_relative_pointer_manager_v1.
    • xcursor_manager: wlr_xcursor_manager.
    • cursor_shape_manager_v1: wlr_cursor_shape_manager_v1.

    Protocol Managers

    • output_manager_v1: wlr_output_manager_v1.
    • foreign_toplevel_manager: wlr_foreign_toplevel_manager_v1.
    • drm_lease_v1: wlr_drm_lease_v1_manager (if WLR_HAS_DRM_BACKEND is enabled).

    Configuration Flags

    • xdg_decoration: Boolean to enable/disable XDG decoration.
    • allow_vt_switch: Boolean to allow Virtual Terminal switching.
    • enable_xwayland: Boolean to enable XWayland support.
    • return_app_code: Boolean to determine if application exit codes are returned.
    • terminated: Boolean indicating if the server has been terminated.
    • log_level: The wlr_log_importance level.

  6. Configure multi-output modes in cg_server

    master

    The cg_server struct uses the cg_multi_output_mode enum to determine how multiple outputs are handled in the kiosk environment. You can choose between extending the workspace across all outputs or focusing on the last output.

    Available modes:

    • CAGE_MULTI_OUTPUT_MODE_EXTEND: Extends the workspace across outputs.
    • CAGE_MULTI_OUTPUT_MODE_LAST: Focuses on the last output.
    enum cg_multi_output_mode {
	CAGE_MULTI_OUTPUT_MODE_EXTEND,
	CAGE_MULTI_OUTPUT_MODE_LAST,
};