penrose - a tiling window manager library

Penrose is a modular library for configuring your own X11 window manager in Rust.

This means that, unlike most other tiling window managers, Penrose is not a binary that you install on your system. Instead, you use it like a normal dependency in your own crate for writing your own window manager. Don't worry, the top level API is well documented and a lot of things will work out of the box, and if you fancy digging deeper you'll find lots of opportunities to customise things to your liking.

FAQs

The faqs should always be up to date with current develop and actual frequently asked questions. Please read through them and check the issues on GitHub before opening a new issue to see if your question has already been answered previously.

Getting Started

If you are new to Rust it is worthwhile reading the penrose getting started guide for details on how to get Rust set up on your system and how to get a minimal config in place. Once you've managed that, you might want to take a look at some of the configurations in the examples directory or my personal config which has several custom extensions.

After that, it's a good idea to read the documentation on docs.rs or the tutorial and overview videos on youtube.

Project Goals

Understandable code

Penrose was born out of my failed attempts to refactor the dwm codebase into something that I could more easily understand and hack on. While I very much admire and aim for minimalism in code, it becomes a problem when your complex code base starts playing code golf to keep things under an arbitrary line limit.

I won't claim that Penrose has the cleanest code base you've ever seen, but it should be readible in addition to being fast. If something is confusing or unclear, then I count that as a bug (and please raise it as such!)

Simple to configure

I've also tried my hand at Xmonad in the past. I love the set-ups people can achive with it (this one is a personal favourite) but doing everything in Haskell was a deal breaker for me. I'm sure many people will say the same thing about Rust but then at least I'm giving you some more options!

With Penrose, a simple config can be written in about 5 minutes and roughly 50 lines of code. It will be pretty minimal but each additional feature (such as a status bar, scratch-pads, custom layouts, dynamic menus...) can be added in as little as a single line. If the functionality you want isn't available however then that leads us on to...

Easy to extend

dwm patches, qtile lazy APIs, i3 IPC configuration; all of these definitely work but they are not what I'm after. Again, the Xmonad model of companion libraries that you bring in and use as part of writing your own window manager has always felt like the right model for me for extending the window manager. (Though, again, while Haskell is great fun for tinkering I've never felt productive in it)

Penrose provides a set of Rust traits for defining the various ways you can interact with the main WindowManager struct. You are free to write your own implementations, write code that manipulates them and extend them however you see fit. If you want to check out some examples of what is possible, take a look in the contrib directory.

Want to run some particular logic every time you connect external monitors? Write a hook that listens for randr triggers.

Want to scatter your windows at random over the screen? Write a custom layout and make use of all of the helper methods on regions.

Have an idea that you can't currently implement? Raise an issue and suggest an extension to the API!

Project Non-goals

An external config file

Parsing a config file and dynamically switching behaviour on the contents adds a huge amount of complexity to the code: not to mention the need for validating the config file! By default, Penrose is configured statically in your main.rs and compiled each time you want to make changes (similar to Xmonad and dwm).

That said, the extensibility of Penrose means that you are free to define your own config file format and parse that as part of your startup, if that is something you want. You could read from xresources, or a stand alone file of your design.

The choice is yours!

IPC / relying on external programs

There are several places where Penrose makes use of external programs for utility functionality (reading the user's key-map or spawning a program launcher for example), but core window manager functionality is always going to stay internal.

As you might expect, you can definitely write your own extensions that provide some sort of IPC or client/server style mechanism if you want to mirror the kinds of things possible in other window managers such as i3 or bspwm, but that is not going to be included at the expense of statically defined control in your binary as a default.