A dwl-guile home service for GNU Guix

This repository contains a Guix Home service which installs and configures dwl-guile , a patched version of dwl that is configured in GNU Guile. You can install our home service with the help of the Guix channel below.

The main goal of dwl-guile is to serve as a minimal dwm-like Wayland compositor for those who use GNU Guix System — a GNU/Linux distribution in which the user can customize and configure their entire system in GNU Guile.

With dwl-guile, we can integrate the window manager customization with that of the rest of the system, which allows for a dynamic, programmable and reproducible configuration for our entire computing environment — all in Guile.

This is a work in progress — please report bugs to us and (if applicable) to upstream dwl!

Features

This Guix Home service can:

• install dwl-guile
• automatically start dwl-guile on the first TTY you log in to
• set necessary environment variables for Wayland support in GTK, Java, etc
• apply (some) other common dwl patches dynamically
• configure all options in dwl (in an Emacs-esque way) with Guile

Guix channel

We provide home-service-dwl-guile in a Guix channel.

Add the channel to your ~/.config/guix/channels.scm:

(channel
  (name 'home-service-dwl-guile)
  (url "https://github.com/engstrand-config/home-service-dwl-guile")
  (branch "main")
  (introduction
    (make-channel-introduction
      "314453a87634d67e914cfdf51d357638902dd9fe"
      (openpgp-fingerprint
        "C9BE B8A0 4458 FDDF 1268 1B39 029D 8EB7 7E18 D68C"))))

Afterwards, run guix pull.

Usage

Home service configuration

home-service-dwl-guile is enabled by adding it to your list of home services.

;; Import the service
(use-modules (dwl-guile home-service)
             (dwl-guile patches)) ; import if you want to apply patches dynamically

;; Create and add the dwl-guile home service to your home configuration.
(service home-dwl-guile-service-type
         ;; If you wish to configure the home service further, you can pass in
         ;; a configuration to the service. All options listed below are optional.
         (home-dwl-guile-configuration
          ;; Use a custom dwl-guile package.
          (package my-custom-dwl)

          ;; If you want to dynamically apply patches, you can create a new
          ;; modified package definition (multiple patches can be applied).
          ;; Note that some patches might have conflicts.
          ;;
          ;; (package
          ;;  (patch-dwl-guile-package dwl-guile
          ;;                           #:patches (list %patch-xwayland)))

          ;; Environment variables to set for Wayland compatibility with applications.
          ;; By default, native Wayland rendering will be enabled for most applications.
          ;; Native rendering of QT-applications is enabled using the @code{native-qt?}
          ;; option. This is because it requires the qtwayland package.
          ;;
          ;; Set it to an empty list to skip setting environment variables:
          ;; (environment-variables '())
          ;;
          ;; Or extend the default environment variables:
          ;; (environment-variables
          ;;  (append `(("var" . "value")) %dwl-guile-base-env-variables))

          ;; A string containing a command to execute after starting dwl-guile.
          ;; This is the equivalent of specifying a script to the '-s' flag of dwl.
          ;; The gexp's will be executed in the same order as in the list.
          ;;
          ;; The preferred way of running commands/applications (that does not need
          ;; to access the stdout of dwl) on startup is by using the
          ;; dwl:startup-hook in your Guile config.
          ;;
          ;; By default, this option is not used.
          (startup-command "foot --server <&-")

          ;; If QT-applications should be rendered natively. Enabled by default.
          ;; This will set QT_QPA_PLATFORM="wayland-egl" and install
          ;; the "qtwayland" package to enable support for Wayland.
          (native-qt? #t)

          ;; If dwl-guile should auto-start on first login. Enabled by default.
          (auto-start? #t)

          ;; If the dwl-guile config should be automatically reloaded on change.
          ;; This will allow you to see (most of) the effects of your config changes
          ;; dynamically, without restarting dwl-guile.
          (reload-config-on-change? #t)

          ;; Create a custom configuration for dwl.
          (config '())

Shepherd service

After enabling the dwl-guile home service and reconfiguring, a new Shepherd service will be added. This allows you to control the dwl-guile executable using herd.

For example:

herd start dwl-guile
herd stop dwl-guile
herd restart dwl-guile

Using these commands, dwl-guile will start with the correct options. Logs are available at $XDG_LOG_HOME/dwl-guile.log. If the XDG environment variable is not set, the log will be saved to your HOME directory.

Runtime evaluation of Guile expressions

As of v2.0.0, you can execute arbitrary GNU Guile expressions in the context of dwl-guile during runtime. This allows for some scripting capabilities, as well as dynamic changes of the config.

Executing an expression is done using the dwl-guile executable, like so:

dwl-guile -e "(dwl:reload-config)"

The result of the evaluation will be shown in stdout, or in stderr if an error occured. These types of evaluations will be executed in their thread, which means that it will not block dwl-guile. In other words, you can safely run commands that run for a longer time. Note that the expression is not evaluated in a shell context, which means that procedures such as system* will not work, but you can always use dwl:shcmd or dwl:spawn instead.

Using the Guile REPL for interacting with dwl-guile

During runtime, it is possible to use the Guile REPL to interact with dwl-guile. In order to do this, you need to explicitly start the REPL server in your config by calling (dwl:start-repl-server). You can then connect to the server in e.g. Emacs using Geiser.

For more information, see the man pages (man dwl-guile).

Configuring dwl-guile

Using dwl-guile, all configuration is done in Guile by providing an alist of (Emacs-like) commands to the config field of the home service configuration.

A minimal set of keybindings will automatically be loaded, unless inhibitied using (setq inhibit-defaults? #t). You can see the defaults in /share/defaults.scm of this repo. There are also some utilities that can be used in your config defined in /share/init.scm.

For more information, see the man pages (man dwl-guile).

C-bindings for dwl

All functions that allow you to interact with dwl are exposed using the libguile API in dwl-guile. Each binding is prefixed with dwl: and uses kebab-case as naming scheme, e.g. dwl:toggle-fullscreen. There are currently no documentation for these bindings, other than the definitions and implementations here.

Patches

%patch-attachabove

Puts newly spawned clients above the currently selected client. This is useful when you want to be able to spawn new clients without changing the master client.

%patch-focusmonpointer

Move cursor with monitor focus. This will teleport your mouse to the center of focused monitor.

%patch-monitor-config

Allows configuration of monitor resolution, refresh rate and adaptive sync, directly in your dwl config.

%patch-movestack

Move clients up and down the stack. Exposes the dwl:move-stack binding that can be used to move clients up or down.

%patch-swallow

Allows applications such as terminals to render launched applications in the same window. For example, opening a PDF using zathura will (if enabled) render zathura on top of the terminal, in the same client. Adds additional options to the dwl-rule record.

Note that swallowing does not work for XWayland clients.

%patch-xwayland

Enable xwayland support.

Extending the home service

You can extend the home service in order to extend the configuration. This is especially useful if you use something like rde .

Consider the following example that adds two new keybindings that dismiss notifications from mako :

(simple-service
 'add-mako-dwl-keybindings
 home-dwl-guile-service-type
 `((set-keys ,dismiss-key
             (lambda () (dwl:shcmd ,(file-append mako "/bin/makoctl") "dismiss"))
             ,dismiss-all-key
             (lambda () (dwl:shcmd ,(file-append mako "/bin/makoctl")
                                   "dismiss" "--all")))))

You can find more examples of this in our GNU Guix configuration, mainly in the engstrand/features/wayland.scm file.