Building a bspwm desktop (a guide)

This posting will be/is superseded, in large part, by the following series:

An adventure creating a single user environment with 4 desktops.


Let me begin by noting that there are numerous tutorials on superbly built bspwm (binary space partition manager) installations/ setups… and they are readily available. I used those mentioned below, quite extensively in the creation of my desktop and this article.  As an aside: the following tutorials are most helpful even if, like me, you choose to implement things a ‘tad differently’.

I used all the other sites/locations referenced in this document, as well.

Setting up & installing bspwm

To quote Frank Sinatra: “I did it my way.”

First by way of expectation setting, here’s a small set of photo images of my bspwm desktop….

A simple use case

I wanted a desktop that offered:

  • A function focused control panel. Specifically, I want a control panel/ environment to support my work (hobbies?). I want to create separate workbenches for:
    • Genealogical Research
    • podcasting & video-casting
    • Early childhood learning & teaching
  • The following very subjective features are also on my list of objectives:
    • Light-weight (the ability to create and manage multiple applications with little response lag)
    • Responsive (applications open rapidly, operate appropriately)
    • Reliable (meaning stable)
    • Function across multiple monitors logically & simultaneously
    • Have applications open in specific, targeted locations
    • Be technically challenging (Yes, I want my control panel infrastructure to provide me with the basis to learn things I have not done before… in ways I have not tried before.)
    • Provide a highly tailorable look & feel (be fun to tweak)

The reasons I choose to work with (explore) bspwm are many. I’ll start with a few “personal qualifications/ observations”:

  • I tried many tiling managers including Awesome, Xmonad, dwm, spectrwm, among others. For one reason or another:
    • I found many too difficult to use (perhaps I’m just too dumb).
    • Others were simply not very much fun.
    • A few were eliminated because of systemd dependence.
  • In the end, I elected to conduct a detailed exploration of bspwm (first). Yes, I will try a couple of others which were second or third on my list of viable contenders (herbstluftwm and i3/ sway).

…and we’re off.

To begin, I have chosen and have built a bspwm environment using the following key components:

  • I have implemented the use of two menu bars:
    • tint2 (primarily used as an active task tracker and a quick launcher).
    • polybar as a workspace navigator, system tray manager, and resource tracker (a little like conky)
  • As a task launcher and application finder, I use rofi.
    • rofi is used to access keybinding help (to assist my “remembery”…)
    • in another, more traditional, mode rofi provides access to:
      • ssh
      • active items by workspace
      • launching facilities for applications via:
        • ‘run’ mode which allows users to quickly search for and launch a program (much like typing a command in terminal mode)
        • ‘drun’ mode which provides:
          • a favorites list, with frequently used programs “like cream” floating on top
          • Search selectable/accessible application autostart

My bspwm install contains the following “major building blocks”…

I am almost ‘pretty sure’ the following list is ‘probably’ complete… Yes, this is a definite maybe.

  1. bspwm
  2. sxhkd
  3. tint2
  4. polybar
  5. rofi
  6. Thunar
  7. compton (compositor)
  8. Debian (I’m still on Stretch, not Buster.)
  9. dunst (notification manager)
  10. pywal (wallpaper & background changer)- eye candy
  11. bash pipes – eye candy

Other items of note

I am “not” using the following more typically ‘used’ bspwm ‘building blocks’:

  • arch linux
  • systemd
  • dmenu
  • bspwm-panel
  • lemonbar

As a result my bspwm environment is a bit exceptional, in the sense that it is uncommon.

Now to my system build

To begin building the system, I started by making certain bspwm key Debian software dependencies were taken care of (installed).

Depending on which software/ functions you elect to build into your bspwm desktop system, as well as, what may or may not be available natively on your installation platform, this list will change/evolve.

Here are the items I found I needed to make everything work (I am pretty certain this list is complete):

sudo apt-get install xcb libxcb-util0-dev libxcb-ewmh-dev libxcb-randr0-dev libxcb-icccm4-dev libxcb-keysyms1-dev libasound2-dev libxcb-xtest0-dev libxcb-shape0-dev cmake cmake-data libcairo2-dev libxcb1-dev libxcb-ewmh-dev libxcb-icccm4-dev libxcb-image0-dev libxcb-randr0-dev libxcb-util0-dev libxcb-xkb-dev pkg-config python-xcbgen xcb-proto libxcb-xrm-dev libasound2-dev libmpdclient-dev libiw-dev libcurl4-openssl-dev libpulse-dev jgmenumoc entr moc-ffmpeg-plugin meson python3-pip jq

Additionally, you will need the following items. You may use your native software installer (repos) or the command line to install them:

Command line install (my preferred approach):

sudo apt install moc rofi bspwm sxhkd dunst tint2 

You may choose to add a few tools to your desktop to keep it ‘pretty’ and functionality. Here are some I added:

sudo apt install lxappearance roxterm-gtk2 roxterm-common mpv gnome-mpv

Be advised: Because I co-install bspwm on a machine with xfce4, I make use of numerous xfce tools. I, also, leverage MXTools (from MXLinux) and/or antiX Tools (when I install on either distro). If you are not using one those Debian distros and/or you are not using xfce, you will likely need to augment your setup to obtain desired functionality.

Software Installation Guide(s)

Some of the following tools may be available from synaptic or your distro repos.  If for any reason they are not available through your distro installer(s), you can build them manually.

Polybar

Polybar (is one tool where a manual install is required for most Debian based systems.):

  • Git the software: git clone https://github.com/jaagr/polybar.git
  • Install it: cd polybar && ./build.sh
  • polybar Install/build note: Build using clang not gcc. Remember to load the example setup!

PyWal

PyWal also will probably require a manual install.  [sarcasm]So far as I can tell, only arch folks are allowed to get a copy in their repos. [/sarcasm]

You can get instructions and guidance on PyWal installation from the developer on GitHub.

In order to successfully perform the pip3 install, dependency software was installed as part of the dependency installation above.

In my setup (which you will find contained in the dotfiles I provide), you’ll notice that each opening of your terminal (Roxterm or your preferred terminal) triggers an update of the bspwm desktop wallpaper as well as changes to polybar, rofi, and terminal themes.  This all happens through the magic of PyWal. Currently, dunst and Thunar are not affected. I may explore seeing if I can do something about that later.

dotfiles (the magic elixir)

In my exploration, I have come across some pretty resource rich sites/ places. I used all of them to figure out how-to build and use the dotfiles I now have and use. These dotfiles are central to the creation of my environment. If you have not worked with tiling windows managers (wm) before, you need to know that dotfiles are central to the creation of a tiling wm and they are fairly readily converted from one wm to another.

Caveat emptor: Without dotfiles, you may be left with an extremely sparse, non-functioning desktop.

What follows is a list of most (I wish I could say all) of the sites/ resources I used:

Rofi setup

Build & show sxhkd keybindings help with fuzzy search/rofi

I use rofi as a key component of my bspwm environment. It is very malleable. One of most useful rofi features I have discovered is that it allows me to build keybinding help such that I am able to view all of my keybindings whenever I need to use them but can’t remember them. I simply use Super+F1 .

If you install my dotfiles, this should all work magically for you.  If not, I hope you learn more quickly than I do. 😉

Note: if you change the format of your sxhkd keybindings dotfile, you will get a garbled, useless keybinding pop-up.  You can certainly add and edit your dotfile, simply make certain you adhere to its current format/ layout.

Rofi setup information:

Rofi (to pick a theme for rofi) all you need do is enter the following command in terminal (and follow the instructions):

rofi-theme-selector

Rofi, below are some options you can use/ try:

  • rofi -show combi -switchers combi -combi-modi window,run
  • rofi -show drun -eh 2 -padding 14 —-better spacing
  • rofi -combi-modi window,drun -show combi -modi combi
  • rofi -combi-modi window,drun -show combi -modi combi -lines 20 -font roboto\ 12
  • rofi -modi run,drun,window,ssh,urxvt -show drun -show-icons -sidebar-mode -location 0 -width 35
  • rofi -modi run,drun,window -show drun -show-icons -sidebar-mode

The bolded setup above is the one I currently use.

Help on dealing with gksudo & pkexec when using rofi. 

Here is the help command used to access keybinding desktop help:

awk ‘/^[a-z]/ && last {print $0,”\t”,last} {last=””} /^#/{last=$0}’ ~/.config/sxhkd/sxhkdrc | column -t -s $’\t’ | rofi -dmenu -i -no-show-icons -width 1000

Dotfiles & scripts

dotfiles/ scripts that I use and provide are not original to me. All dotfiles & scripts are compilations and edited versions of guidance/ examples from other sources; the sources are listed as references/links strewn about this document.

Install (paste, drop, move) my scripts (assuming you want them to work) into the following directory locations.  Or, change the dotfiles to reflect your preferred location(s).

  • Scripts ($Home/.local/share/scripts) included in this directory are:
    • backlight.sh- allows my Dell e5470 Latitude function keys to adjust backlighting. Without this script and the sxhkdrc dotfile I would have no backlight function.
    • desktop-session-logout.sh- is currently untested and will only work on antiX, as written.
    • system-usb-mount.sh- is a script that integrates with my polybar config dotfile to all identification of mounted usb(s) and more.
    • touchpad-toggle.sh- allows my laptop trackpad to be turned on/off. My e5470 Latitude does not have the function natively.
  • Wallpapers ( $Home/.local/share/wallpapers)- included
  • Themes ($Home/.local/share/themes)- included
  • fonts ( $Home/.local/share/fonts)- included
  • icons ( $Home/.local/share/icons)- included
  • bspwmrc ($Home/.config/bspwm)- included
  • polybar ($Home/.config/polybar)- included
  • sxhkd ($Home/.config/sxhkd)- included
  • tint2 ($Home/.config/tint2)- included

Here are links to downloads of my current dotfiles (on GitHub and on GitLab )

Remember, like with all of my work, I am only able to provide the following assurance(s):

  • It is almost certainly going to work until it breaks; although I have to admit it may never work and that would be sad.
  • When/if it does break, you may keep all of the pieces.
  • If you find my materials helpful, both you & I will be happy, at least for a little while.
  • My advice is worth every penny you paid for it!