Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sminez/penrose

A library for writing an X11 tiling window manager
https://github.com/sminez/penrose

manager rust window wm x11 x11-wm xcb xcb-api

Last synced: 4 days ago
JSON representation

A library for writing an X11 tiling window manager

Awesome Lists containing this project

README 

        

penrose - a tiling window manager library

=========================================



[![Build](https://github.com/sminez/penrose/workflows/Build/badge.svg?branch=develop)](https://github.com/sminez/penrose/actions?query=workflow%3ABuild) [![crates.io version](https://img.shields.io/crates/v/penrose)](https://crates.io/crates/penrose) [![docs.rs](https://img.shields.io/docsrs/penrose?logo=rust)](https://docs.rs/penrose) [![Book Build](https://github.com/sminez/penrose/actions/workflows/book.yml/badge.svg)](https://github.com/sminez/penrose/actions/workflows/book.yml)



### `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.



![screenshot](https://raw.githubusercontent.com/sminez/penrose/develop/screenshot.png)



### tl;dr - getting started



The user facing docs for penrose are written using mdBook and published to GitHub Pages [here][0].

They cover some more general concepts about how to get up and running as opposed to the

[crate docs][1] on docs.rs which are more aimed at covering the APIs themselves and are

what you would expect from an open source library.



> The current version of the docs build from the head of the `develop` branch can be found [here][2].



If you want to have a look at how it all comes together then the [examples][3] directory

of this repo has several different starting points for you to begin with and my personal

set up can be found [here][4]. (You almost certainly _don't_ want to use my set up in

full but it should serve as a good reference for what a real use case looks like!)



#### Penrose from scratch



The [penrose from scratch](https://github.com/sminez/penrose-from-scratch) repo is an example

window manager written using `penrose` that was developed as part of a [video series](https://www.youtube.com/playlist?list=PLy2HjaQiG8lOxCKzuWKfmmXov4iEVOGOF)

available on YouTube. Each video focuses on a different aspect of the library and guides you through

how the APIs work, how the library is designed and how to customise the behaviour of your window

manager.



#### Discord



First and foremost, you should refer to the docs (both the book and API docs) if you are looking

to learn about Penrose and how it all works. The GitHub issue tracker is also an excellent

resource for learning about solutions to common problems. That said, I have had repeated requests

for somewhere that people can have more open ended discussions about things and chat about their

individual set ups so with that in mind, you can join us on discord [here](https://discord.gg/jtFsg2K3Fw)

if that sounds like your thing.







### Project Goals



#### Understandable code



`Penrose` was born out of my failed attempts to refactor the [dwm][5] codebase into

something that I could more easily understand and hack on. While I very much

admire and aim for minimalism in code, I personally feel that it becomes a problem

when your code base starts playing code golf to keep things short for the sake of it.



I certainly won't claim that `Penrose` has the cleanest code base you've ever seen,

but it should be readable in addition to being fast.



#### Simple to configure



I've also tried my hand at [Xmonad][6] in the past. I love the setups people can

achieve with it ([this one][7] 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 window manager can be written in about 5 minutes and under

100 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,

that leads us on to...



#### Easy to extend



[dwm][5] patches, [qtile][8] lazy APIs, [i3][9] IPC configuration; all of these

definitely work but they are not what I'm after. Again, the [Xmonad][7] 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.



`Penrose` provides a set of traits and APIs for extending the minimal core library

that is provided out of the box. By default, you essentially get an event loop and

a nice clean split between the "pure" state manipulation APIs for managing your

windows and a "diff and render" layer that interacts with the X server. There are

enough built-in pieces to show how everything works and then some more interesting

/ useful code available in the [extensions][10] module.







### Project Non-goals



#### An external config file



Parsing a config file and dynamically switching behaviour on the contents adds a

large 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][7] and [dwm][6]).

There is no built-in support for hot reloading of changes or wrappers around the

main window manager process.



That said, the extensibility of `Penrose` means that you are definitely able to define

your own config file format and parse that as part of your startup, if that is something

you want.



The choice is yours!



#### IPC / relying on external programs for core functionality



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 contained in the pure state

data structures. This makes it a lot simpler to maintain the codebase and (importantly)

provide a nice API to work with for extending the behaviour of your window manager.



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 supported in the core of the library itself.



  [0]: https://sminez.github.io/penrose

  [1]: https://docs.rs/penrose

  [2]: https://sminez.github.io/penrose/rustdoc/penrose

  [3]: https://github.com/sminez/penrose/tree/develop/examples

  [4]: https://github.com/sminez/my-penrose-config

  [5]: https://dwm.suckless.org/

  [6]: https://xmonad.org/

  [7]: https://www.youtube.com/watch?v=70IxjLEmomg

  [8]: http://www.qtile.org/

  [9]: https://i3wm.org/

  [10]: src/extensions/