Sunday, July 31, 2016

How To: Install bspwm

Are you a Gnome or KDE user who is tired of the ordinary? Are you an i3 or herbstluftwm user who has heard the benefits of using bspwm? If you are, you have probably looked into it. And, furthermore, when you looked into it you may have found that it's a bit more involved than you had hoped. No worries! Following this guide should get you up and running with your very own bspwm configuration.

Install the Packages
Installing the packages is, unfortunately, a little but harder than just calling apt-get. We have to compile them. Now, a bit more fortunately, all of the dependencies for bspwm are readily available in your repositories.

On Ubuntu:
sudo apt-get install xcb libxcb-util0-dev libxcb-ewmh-dev libxcb-randr0-dev libxcb-icccm4-dev libxcb-keysyms1-dev libxcb-xinerama0-dev libasound2-dev libxcb-xtest0-dev

On Fedora:
sudo dnf install xcb-util-devel xcb-util-keysyms-devel xcb-util-wm-devel alsa-lib-devel dmenu rxvt-unicode terminus-fonts

Not too bad. What these commands do is install the dependencies that will be needed when we're building bspwm.

Build Tools
Since we're manually building bspwm, we need certain build tools. Libraries, compilers, etc. 
sudo apt-get install gcc make
sudo dnf groupinstall "Development Tools"
Alrighty. So, we have the dependencies and the build tools. Now, we need to download BSPWM.

The Packages

Let's download the two packages using git, now.
cd Downloads
git clone
git clone
If all went well, you should have two folders in your 'Downloads' folder - "bspwm" and "sxhkd"

The final step to installing the bspwm system itself is compiling it. To do this, go into the Downloads folder and type 

cd bspwm
sudo make install

   Now, if you're not used to compiling things, this process probably looks a tad scary. There should be a lot of text scrolling along in the terminal - that is okay. Unless you see "Error, exiting" during this step, everything is working fine.

After this, issue:

cd ..
cd sxhkd
sudo make install
If everything went well, we're ready to start doing some of the initial configuration. Awesome!


Since bspwm and sxhkd are both installed, let's take a minute to analyze exactly where we are. We've installed bspwm, the window manager, and sxhkd, the keyboard daemon. How bspwm works this:

bspwm manages your windows. Where they're placed, their layout on your desktop, etc. It doesn't handle anything else, unlike traditional window managers.

bspc tells bspwm what to do. When you see bspwm moving windows, closing windows, etc. it's because bspc told bspwm over its socket file.

sxhkd listens to the keyboard for keyboard shortcuts. These keyboard shortcuts can execute any arbitrary command, although they are commonly used to issue bspc commands, such as the command that tells bspc to close a window, etc.

Running - With a display manager
Display managers control your X11 / Wayland (what makes your computer graphical, instead of all commands) sessions, as well as logging in. When you start your computer and see "username" and "password", you're looking at your display manager. Some common display managers on Linux are lightdm (commonly ubuntu), gdm (commonly gnome), lxdm (commonly lxde), and kdm (commonly kde).

bspwm comes with the files necessary to add the window manager to the display manager you already use. In order to use your display manager to log in, you need to copy the "bspwm.desktop" file (from bspwm/contrib/freedesktop). In the Downloads folder:

sudo cp bspwm/contrib/freedesktop/bspwm.desktop /usr/share/xsessions
Now, you can restart your display manager, or choose to reboot. bspwm should be an option in your display manager. You can skip the "Without a display manager" section and move onto configuration.

Running - Without a display manager

Without a display manager, things are a bit more advanced. I'm assuming that if you're choosing to forego using a display manager, that you're a fairly advanced user, so I'll keep it short. Change the contents of your ~/.xinitrc file to say
exec bspwm
And you'll be good to go. But wait! We have to configure the keybindings.

Keybindings and Autostart
Now, you should have bspwm completely installed on your system. However, if you tried to log into bspwm right now you would be greeted with... well, nothing. And, for the moment, that's fine. But the bad part is you won't be able to do anything either. In order to fix this, we need to set ourselves up some keybindings.

Bspwm comes with files with default configurations. Let's get started with the window manager by copying these default keybindings and behavior's over to their respective directories. First, we must create those directories.

mkdir ~/.config/bspwm
mkdir ~/.config/sxhkd

bspwm's configuration:

cp ~/Downloads/bspwm/examples/bspwmrc ~/.config/bspwm/
chmod +x ~/.config/bspwm/bspwmrc
sxhkd's configuration:

cp ~/Downloads/bspwm/examples/sxhkdrc ~/.config/sxhkd
Further configuration
Now, it may be preferable to edit either of these files. The function of bspwmrc in .config/bspwm is essentially an "autostart" file. It lists commands that bspwm should run when it starts up. Now, remember, bspwm is controlled via commands, so rules which govern how bspwm behaves are located in this file.

Things such as how monitors should be handled, window borders, rules for allowing certain windows to float, etc. are all configured here, as well as any programs you want to run when bspwm starts up (like, say, your bluetooth daemon).

sxhkdrc in .config/sxhkd controls keybindings. Keybindings for bspc are common, and important to make note of. By default, some of the most important default commands are:

super + return | urxvt
super + space | dmenu_run
super + escape | [reload sxhkd configuration]
super+alt+Escape | logout of bspwm
super+m | Change the desktop mode

These commands, especially super+return should get you started.
Note: super is the mod4 key on the keyboard, commonly called the "Windows" key as it usually dons the Windows logo
Now, with all of these files in place, we should be ready to start bspwm for the first time. If you don't have urxvt already installed, it's important to issue:

sudo dnf install rxvt-unicode
sudo apt-get install rxvt-unicode
So that you're able to use the terminal when you start using bspwm. The terminal is essential, as it will allow you to modify your sxhkd configuration once you're in bspwm.

If you'd like dmenu (it's an application launcher), issue:

sudo dnf install dmenu

sudo apt-get install suckless-tools
Using bspwm
 Now, start bspwm. If you installed bspwm into your display manager, you can select it from the menu there. If you chose to use .xinitrc, then use "startx" at a tty.

It may seem like it's not working when you start it. It will either show a black screen or the "splash screen" of the display manager when you first log into it.

This is how it looks on Ubuntu

Since we installed urxvt, we can launch the terminal with super+enter, or whatever you changed it to.

By default, it takes up the entire screen like this. But, notice that when you open another program, it will split the total space in half.

This is showcasing bspwm's tiling ability. However, bspwm can do so much more than the default sxhkd and bspwmrc files allow you to do.

Well, there we have it. We now have a working bspwm configuration, and we're ready to get tinkering! Typing "man bspc" at a terminal will show you all of the awesome things that you can do with bspwm, so there's plenty to try out in the new desktop.

This is the beginning of a series of articles about bspwm and sxhkd on this blog. For more, see below, where I'll be adding additional content as it is made:

Modifying keybindings in bspwm : [In Progress]

Happy hacking!

Huge thanks to by windelicato, where most of this guide was sourced from. I paraphrased much of this guide from his original writeup here for the purpose of clearing up the process, and fixing one mistake he made in the original guide.

No comments:

Post a Comment