{"id":13611802,"url":"https://github.com/sminez/penrose","last_synced_at":"2025-05-13T21:03:35.628Z","repository":{"id":37618506,"uuid":"121132585","full_name":"sminez/penrose","owner":"sminez","description":"A library for writing an X11 tiling window manager","archived":false,"fork":false,"pushed_at":"2025-04-16T19:40:43.000Z","size":16581,"stargazers_count":1313,"open_issues_count":3,"forks_count":86,"subscribers_count":25,"default_branch":"develop","last_synced_at":"2025-04-28T13:59:45.834Z","etag":null,"topics":["manager","rust","window","wm","x11","x11-wm","xcb","xcb-api"],"latest_commit_sha":null,"homepage":"https://sminez.github.io/penrose/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sminez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-02-11T14:39:12.000Z","updated_at":"2025-04-26T17:33:14.000Z","dependencies_parsed_at":"2023-12-18T08:29:32.924Z","dependency_job_id":"7815f71e-3a74-42bd-abeb-0a480cfe662f","html_url":"https://github.com/sminez/penrose","commit_stats":{"total_commits":610,"total_committers":25,"mean_commits":24.4,"dds":0.09508196721311479,"last_synced_commit":"bd6e6d13c1d3e927b3a7dcb47ae06c07c88b3ab1"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sminez%2Fpenrose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sminez%2Fpenrose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sminez%2Fpenrose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sminez%2Fpenrose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sminez","download_url":"https://codeload.github.com/sminez/penrose/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254027858,"owners_count":22002125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["manager","rust","window","wm","x11","x11-wm","xcb","xcb-api"],"created_at":"2024-08-01T19:02:09.609Z","updated_at":"2025-05-13T21:03:35.581Z","avatar_url":"https://github.com/sminez.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"\u003cimage width=\"100px\" src=\"https://raw.githubusercontent.com/sminez/penrose/develop/icon.svg\" align=\"left\"\u003e\u003c/image\u003e\npenrose - a tiling window manager library\n=========================================\n\n[![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)\n\n### `Penrose` is a modular library for configuring your own X11 window manager in Rust.\n\nThis means that, unlike most other tiling window managers, `Penrose` is not a\nbinary that you install on your system. Instead, you use it like a normal\ndependency in your own crate for writing your own window manager. Don't worry,\nthe top level API is well documented and a lot of things will work out of the\nbox, and if you fancy digging deeper you'll find lots of opportunities to\ncustomise things to your liking.\n\n![screenshot](https://raw.githubusercontent.com/sminez/penrose/develop/screenshot.png)\n\n\n### tl;dr - getting started\n\nThe user facing docs for penrose are written using mdBook and published to GitHub Pages [here][0].\nThey cover some more general concepts about how to get up and running as opposed to the\n[crate docs][1] on docs.rs which are more aimed at covering the APIs themselves and are\nwhat you would expect from an open source library.\n\n\u003e The current version of the docs build from the head of the `develop` branch can be found [here][2].\n\nIf you want to have a look at how it all comes together then the [examples][3] directory\nof this repo has several different starting points for you to begin with and my personal\nset up can be found [here][4]. (You almost certainly _don't_ want to use my set up in\nfull but it should serve as a good reference for what a real use case looks like!)\n\n#### Penrose from scratch\n\nThe [penrose from scratch](https://github.com/sminez/penrose-from-scratch) repo is an example\nwindow manager written using `penrose` that was developed as part of a [video series](https://www.youtube.com/playlist?list=PLy2HjaQiG8lOxCKzuWKfmmXov4iEVOGOF)\navailable on YouTube. Each video focuses on a different aspect of the library and guides you through\nhow the APIs work, how the library is designed and how to customise the behaviour of your window\nmanager.\n\n#### Discord\n\nFirst and foremost, you should refer to the docs (both the book and API docs) if you are looking\nto learn about Penrose and how it all works. The GitHub issue tracker is also an excellent\nresource for learning about solutions to common problems. That said, I have had repeated requests\nfor somewhere that people can have more open ended discussions about things and chat about their\nindividual set ups so with that in mind, you can join us on discord [here](https://discord.gg/jtFsg2K3Fw)\nif that sounds like your thing.\n\n\u003cbr\u003e\n\n\n### Project Goals\n\n#### Understandable code\n\n`Penrose` was born out of my failed attempts to refactor the [dwm][5] codebase into\nsomething that I could more easily understand and hack on. While I very much\nadmire and aim for minimalism in code, I personally feel that it becomes a problem\nwhen your code base starts playing code golf to keep things short for the sake of it.\n\nI certainly won't claim that `Penrose` has the cleanest code base you've ever seen,\nbut it should be readable in addition to being fast.\n\n\n#### Simple to configure\n\nI've also tried my hand at [Xmonad][6] in the past. I love the setups people can\nachieve with it ([this one][7] is a personal favourite), but doing everything in\nHaskell was a deal breaker for me. I'm sure many people will say the same thing\nabout Rust, but then at least I'm giving you some more options!\n\nWith `Penrose`, a simple window manager can be written in about 5 minutes and under\n100 lines of code. It will be pretty minimal, but each additional feature (such as a\nstatus bar, scratch-pads, custom layouts, dynamic menus...) can be added in as\nlittle as a single line. If the functionality you want isn't available however,\nthat leads us on to...\n\n\n#### Easy to extend\n\n[dwm][5] patches, [qtile][8] lazy APIs, [i3][9] IPC configuration; all of these\ndefinitely work but they are not what I'm after. Again, the [Xmonad][7] model of\ncompanion libraries that you bring in and use as part of writing your own window\nmanager has always felt like the right model for me for extending the window\nmanager.\n\n`Penrose` provides a set of traits and APIs for extending the minimal core library\nthat is provided out of the box. By default, you essentially get an event loop and\na nice clean split between the \"pure\" state manipulation APIs for managing your\nwindows and a \"diff and render\" layer that interacts with the X server. There are\nenough built-in pieces to show how everything works and then some more interesting\n/ useful code available in the [extensions][10] module.\n\n\u003cbr\u003e\n\n### Project Non-goals\n\n#### An external config file\n\nParsing a config file and dynamically switching behaviour on the contents adds a\nlarge amount of complexity to the code, not to mention the need for _validating_\nthe config file! By default, `Penrose` is configured statically in your **main.rs**\nand compiled each time you want to make changes (similar to [Xmonad][7] and [dwm][6]).\nThere is no built-in support for hot reloading of changes or wrappers around the\nmain window manager process.\n\nThat said, the extensibility of `Penrose` means that you are definitely able to define\nyour own config file format and parse that as part of your startup, if that is something\nyou want.\n\nThe choice is yours!\n\n\n#### IPC / relying on external programs for core functionality\n\nThere are several places where `Penrose` makes use of external programs for\nutility functionality (reading the user's key-map or spawning a program launcher\nfor example), but core window manager functionality is contained in the pure state\ndata structures. This makes it a lot simpler to maintain the codebase and (importantly)\nprovide a nice API to work with for extending the behaviour of your window manager.\n\nAs you might expect, you can definitely write your own extensions that provide\nsome sort of IPC or client/server style mechanism if you want to mirror the\nkinds of things possible in other window managers such as `i3` or `bspwm`, but\nthat is not going to be supported in the core of the library itself.\n\n\n  [0]: https://sminez.github.io/penrose\n  [1]: https://docs.rs/penrose\n  [2]: https://sminez.github.io/penrose/rustdoc/penrose\n  [3]: https://github.com/sminez/penrose/tree/develop/examples\n  [4]: https://github.com/sminez/my-penrose-config\n  [5]: https://dwm.suckless.org/\n  [6]: https://xmonad.org/\n  [7]: https://www.youtube.com/watch?v=70IxjLEmomg\n  [8]: http://www.qtile.org/\n  [9]: https://i3wm.org/\n  [10]: src/extensions/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsminez%2Fpenrose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsminez%2Fpenrose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsminez%2Fpenrose/lists"}