Install Window Maker as a startx session on Gentoo

Steps#

1. Set Window Maker's USE flags.

   echo 'x11-wm/windowmaker png jpeg webp xinerama xpm nls xrandr' | sudo tee /etc/portage/package.use/windowmaker
   

   $ cat /etc/portage/package.use/windowmaker
   x11-wm/windowmaker png jpeg webp xinerama xpm nls xrandr
   

   Expected: the one line. xinerama and xrandr are what keep the binhost package from being used (step 2). The binhost build of 0.96.0-r1 has gif jpeg nls png tiff webp xpm and neither of them. Without them, the binary package matches. xinerama adds Xinerama multi-monitor geometry queries (use.desc); xrandr enables XRandR extension support (metadata.xml).

2. Emerge Window Maker.

   $ sudo emerge --ask x11-wm/windowmaker
   …
   [ebuild  N     ] x11-wm/windowmaker-0.96.0-r1  USE="gif jpeg nls png tiff webp xinerama xpm xrandr -imagemagick -modelock"
   
   !!! The following binary packages have been ignored due to non matching USE:
   
       =x11-wm/windowmaker-0.96.0-r1 -xinerama -xrandr
   …
   >>> Completed (1 of 1) x11-wm/windowmaker-0.96.0-r1::gentoo
   

   Expected: Completed (1 of 1). [ebuild means a source build, [binary a binhost package. The "ignored due to non matching USE" lines are a notice, not an error (Failure modes, row 3).

3. Accept the ~amd64 keyword for wmsystemtray. It is the only one of the four dockapps without a stable amd64 keyword (KEYWORDS="~amd64 ~ppc64 ~x86"). Write it without a version, so later releases are accepted too:

   $ echo 'x11-plugins/wmsystemtray ~amd64' | sudo tee /etc/portage/package.accept_keywords/wmsystemtray
   x11-plugins/wmsystemtray ~amd64
   

   Expected: the line echoed back. If you skip this step, step 4 fails with Failure modes, row 2.

4. Emerge the dockapps from x11-plugins. The category is x11-plugins, not x11-misc (Failure modes, row 1).

   $ sudo emerge --ask x11-plugins/wmclock x11-plugins/wmifs x11-plugins/wmmemload x11-plugins/wmsystemtray
   …
   [binary  N g   ] x11-libs/libdockapp-0.7.3-1  USE="X -static-libs"
   [binary  N g   ] x11-plugins/wmclock-1.0.16-r1-2
   [binary  N g   ] x11-plugins/wmmemload-0.1.8-r1-1
   [ebuild  N    ~] x11-plugins/wmsystemtray-1.4-r3
   [binary  N g   ] x11-plugins/wmifs-1.9-1
   …
   >>> Jobs: 5 of 5 complete                                               Load avg: 1.02, 1.19, 1.13
   

   Expected: 5 of 5 complete. libdockapp comes in as a dependency. Only wmsystemtray builds from source.

5. Seed ~/GNUstep with wmaker.inst --batch. It needs no X display. This copies the stock WindowMaker defaults, generates WMRootMenu with wmgenmenu, and creates Library/WindowMaker/ with an executable autostart:

   $ wmaker.inst --batch
   Installing WindowMaker 0.96.0 for current user...
   Creating ~/GNUstep user directory
   Copying defaults database...
   Creating icon library directory ~/GNUstep/Library/Icons
   Creating WindowMaker data library directory ~/GNUstep/Library/WindowMaker
   Creating style library ~/GNUstep/Library/WindowMaker/Styles
   Creating theme library ~/GNUstep/Library/WindowMaker/Themes
   Creating bg image library ~/GNUstep/Library/WindowMaker/Backgrounds
   Creating icon setup library ~/GNUstep/Library/WindowMaker/IconSets
   Creating pixmap library ~/GNUstep/Library/WindowMaker/Pixmaps
   Installation Finished
   $ ls ~/GNUstep/Defaults
   WMRootMenu
   WindowMaker
   

   Expected: Installation Finished and the two files. (This transcript is from a re-run on the same box with a scratch HOME; the first seed's output was not saved. Paths shortened to ~.)

   WarningRun wmaker.inst --batch once

   Batch mode never prompts. On a second run it replaces Defaults/WindowMaker with the stock file and regenerates WMRootMenu, so every edit made in steps 6 onward is lost. autostart survives because it is copied only if absent. Proof: Failure modes, row 4. To refresh only the menu, use wmgenmenu > ~/GNUstep/Defaults/WMRootMenu.

6. Stop Window Maker painting over your wallpaper (optional). The stock WorkspaceBack is a solid colour. If something draws the root window before wmaker starts (my x11/common does, step 10), set it to (none):

   $ wdread WindowMaker WorkspaceBack
   (solid, "rgb:50/50/75")
   $ wdwrite WindowMaker WorkspaceBack '(none)'
   $ wdread WindowMaker WorkspaceBack
   (none)
   

   Expected: (none) on read-back. (Transcript from the same scratch HOME as step 5; my real defaults read (none) too, see Verify.) Skip this step if Window Maker is the only thing that sets a background.

7. Start the dockapps from autostart. Window Maker runs this script before it starts handling events and waits for it to exit, so every command gets a trailing &. It also runs the script again on every Restart (root menu), while the first dockapps are still alive, so each line starts its program only if it is not already running. wmmemload -b -c leaves buffers and page cache out of "used" memory; without it the meter read 86% on a box with 13 GiB available. The file must stay executable. Append the four lines under the stock comment header:

   cat >> ~/GNUstep/Library/WindowMaker/autostart <<'EOF'
   pgrep -x wmclock >/dev/null || wmclock &
   pgrep -x wmifs >/dev/null || wmifs &
   pgrep -x wmmemload >/dev/null || wmmemload -b -c &
   pgrep -x wmsystemtray >/dev/null || wmsystemtray &
   EOF
   

   (Transcript from a scratch HOME; my live file has one more dockapp, wmix, and a comment.)

   $ tail -4 ~/GNUstep/Library/WindowMaker/autostart
   pgrep -x wmclock >/dev/null || wmclock &
   pgrep -x wmifs >/dev/null || wmifs &
   pgrep -x wmmemload >/dev/null || wmmemload -b -c &
   pgrep -x wmsystemtray >/dev/null || wmsystemtray &
   $ sh -n ~/GNUstep/Library/WindowMaker/autostart; echo rc=$?
   rc=0
   $ stat -c "%A %n" ~/GNUstep/Library/WindowMaker/autostart
   -rwxr-xr-x ~/GNUstep/Library/WindowMaker/autostart
   

   Expected: the four lines, rc=0, x bits set.

8. Write a minimal startx client script. One file per window manager, so startx can be pointed at it:

   cat > ~/.xinitrc-windowmaker <<'EOF'
   #!/bin/sh
   exec wmaker
   EOF
   chmod 755 ~/.xinitrc-windowmaker
   

   $ cat ~/.xinitrc-windowmaker
   #!/bin/sh
   exec wmaker
   $ sh -n ~/.xinitrc-windowmaker; echo rc=$?
   rc=0
   $ stat -c "%A %n" ~/.xinitrc-windowmaker
   -rwxr-xr-x ~/.xinitrc-windowmaker
   

   Expected: rc=0 and x bits set. exec wmaker is also what upstream's install page puts in ~/.xinitrc. (Transcript from a scratch HOME, paths shortened to ~; on my box this file is the longer script in step 10.) [UNVERIFIED: this minimal script was not started; my box runs the step 10 script]

9. (My box) Give the session its own OpenRC user runlevel. My session daemons are OpenRC user services; each window manager gets a runlevel with default stacked in, so entering it never stops dbus or PipeWire. Skip steps 9 to 11 if you don't run user services or a tty menu. The two commands are from my rebuild notes (the original run was not captured); the output below is from 2026-11-02 20:56:

   mkdir -p ~/.config/rc/runlevels/windowmaker
   rc-update --user -s add default windowmaker
   

   $ rc-status --user windowmaker
   Runlevel: windowmaker
   Stacked Runlevel: default
    dbus                                                  [  started 20:41:24 (0) ]
    pipewire                                              [  started 20:41:24 (0) ]
    wireplumber                                           [  started 20:41:24 (0) ]
    pipewire-pulse                                        [  started 20:41:24 (0) ]
   

   Expected: Stacked Runlevel: default. I add no services of my own to this runlevel: my terminal and notification services there need Wayland.

10. (My box) Replace the client script with the glue version. This is my ~/.xinitrc-windowmaker as it is on the box. It needs two things this manual does not create: ~/.config/x11/common (my shared X startup: keyboard layout, settings daemon, wallpaper, idle lock), and, for the openrc lines, the runlevel from step 9. /bin/sh stops at a failed ., so without that file wmaker never starts. In the comments, "the Path-B chooser" is the tty menu in step 11 and sway-session is my Wayland launcher. It runs wmaker without exec so the script can leave the runlevel after Window Maker exits:

    #!/bin/sh
    # X session: Window Maker. Launched by the Path-B chooser via
    # `startx ~/.xinitrc-windowmaker -- vtN`.
    #
    # Shared startup (env, xkb layout, xsettingsd, cursor, root colour, .Xdefaults)
    # lives in ~/.config/x11/common so the bare X WMs cannot drift apart.
    . "$HOME/.config/x11/common"
    
    export XDG_CURRENT_DESKTOP=WindowMaker
    
    # Enter this WM's own OpenRC user runlevel. `default` (dbus/pipewire/wireplumber)
    # is stacked into it, and -n (--no-stop) makes entry purely additive, so this can
    # never stop the session bus out from under us. Done here rather than in each
    # WM's own config so all the bare X WMs share one mechanism.
    openrc -U -n windowmaker
    
    # NOTE: deliberately not `exec` -- this script must outlive the WM to run the
    # teardown below, exactly as /usr/local/bin/sway-session does.
    #
    # Window Maker provides its own Dock and Clip, so no external panel/bar is
    # started here (unlike openbox/fvwm3, which run a standalone xfce4-panel).
    # Dockapps go in ~/GNUstep/Library/WindowMaker/autostart if wanted.
    #
    # ~/GNUstep/Defaults/ was seeded with `wmaker.inst --batch`, so the user
    # defaults database (WindowMaker, WMRootMenu) exists and edits go here instead
    # of the read-only /etc/X11/WindowMaker fallback. Re-seed only if it is missing.
    wmaker
    
    # WM has exited. Leave its runlevel so any WM-bound service stops rather than
    # lingering with a dead display. `default` is stacked, so dbus/pipewire survive;
    # pam_openrc stops those at PAM session close.
    openrc -U default >/dev/null 2>&1
    

    $ sh -n ~/.xinitrc-windowmaker; echo rc=$?
    rc=0
    

    Expected: rc=0.

11. (My box) Add the session to the tty menu. My tty1 login runs a small menu script (~/.local/bin/session-chooser) whose startx_session function execs startx "$HOME/.xinitrc-$1" -- vtN, with N taken from the current tty. All ten digits were already used, so Window Maker got a letter. One line goes into the menu's list of printf lines, the other into the case before the *) fallback:

    printf '   [w] windowmaker (X11)\n'
    

    	w|W) startx_session windowmaker ;;
    

    Checked with stubs for startx and sway-session on PATH, a scratch HOME holding a copy of the step 10 script, and the real menu script driven through script:

    $ printf 'w\n' | script -qec 'bash /home/user/.local/bin/session-chooser' /dev/null | tail -3
       [w] windowmaker (X11)
    
      session [1]: STUB startx ~/.xinitrc-windowmaker -- vt0
    

    Expected: the stub prints the startx line. vt0 is the pseudo-terminal's number under script; on tty1 it is vt1. An unmatched key still falls through to my default session (STUB sway-session).

12. Start the session. Log in on a tty and run:

    startx ~/.xinitrc-windowmaker -- vt1
    

    Use the number of the tty you are on in place of 1.