{"id":13341298,"url":"https://github.com/vilfa/bonsai","last_synced_at":"2026-01-18T06:05:52.808Z","repository":{"id":37421069,"uuid":"488561057","full_name":"vilfa/bonsai","owner":"vilfa","description":"A small Wayland compositor focusing on out-of-the-box user experience. ","archived":false,"fork":false,"pushed_at":"2023-01-28T15:47:08.000Z","size":7747,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-24T08:29:52.056Z","etag":null,"topics":["compositor","out-of-the-box","user-experience","wayland","wayland-compositor","wlroots"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vilfa.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}},"created_at":"2022-05-04T11:27:48.000Z","updated_at":"2023-01-30T07:34:31.000Z","dependencies_parsed_at":"2023-02-15T17:30:48.001Z","dependency_job_id":null,"html_url":"https://github.com/vilfa/bonsai","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vilfa%2Fbonsai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vilfa%2Fbonsai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vilfa%2Fbonsai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vilfa%2Fbonsai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vilfa","download_url":"https://codeload.github.com/vilfa/bonsai/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243109392,"owners_count":20237847,"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":["compositor","out-of-the-box","user-experience","wayland","wayland-compositor","wlroots"],"created_at":"2024-07-29T19:25:23.999Z","updated_at":"2025-03-11T20:33:20.878Z","avatar_url":"https://github.com/vilfa.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bonsai\n\nBonsai is a simple Wayland compositor focusing on out-of-the-box user experience.\nIt includes support for screenshots, screensharing and touchpad gestures without\nany extra configuration required.\n\n## Description\n\nThe aim of this project is to solve some issues that tend to arise when using Wayland\nin combination with screencasting/screenshots and touchpads. As a laptop user I also\nwanted to have support for touchpad gestures. Even though the major desktop environments\non Linux now include these features, this is still a fun project for me, just to see\nwhat can be built. The compositor is based on the [wlroots](https://gitlab.freedesktop.org/wlroots/wlroots)\nlibrary, meaning a rock-solid foundation to build on.\n\n## Getting Started\n\n### Build dependencies\n\n* `meson`\n* `wlroots` (currently based on commit [972a5cdf](https://gitlab.freedesktop.org/wlroots/wlroots/-/commit/972a5cdf7a9701a266119d60da48624ca8ebf703) from Jul 21st, support for v0.16 will be added upon release)\n* `libinput`\n* `libevdev`\n* `libudev`\n* `xkbcommon`\n* `glesv2`\n* `libdrm`\n* `wayland-server`\n* `wayland-client`\n* `wayland-cursor`\n* `wayland-egl`\n* `wayland-protocols`\n* `xdg-desktop-portal`\n* `pixman-1`\n* `cairo`\n\n### Runtime dependencies\n\n* `swaybg` (wallpaper support)\n* `swaylock` (screen locking support)\n* `bemenu` (run menu)\n* `waybar` (status bar)\n* `slurp` (screenshot support)\n* `grim` (screenshot support)\n* `wl-clipboard` (screenshot \u0026 clipboard)\n* `brightnessctl` (brightness control via waybar)\n\n### Using the Vagrant development environment\nFor the optimal developer experience, it is recommended you use the provided \nVagrant development environment. Currently this environment is only configured \nwith the `libvirt` provider, however, multiple Vagrant providers could quite easily\nbe added in the future.\n\nTo use this environment, make sure, you have the latest versions of the following\npackages:\n* `vagrant` (manages virtual machines)\n* `vagrant-libvirt` (the `libvirt` plugin for Vagrant)\n* `libvirt` + `qemu` (should be installed automatically with `vagrant`)\n* `virt-manager` (graphical frontend to `libvirt`)\n* `virt-viewer` (connect to virtual machine display)\n\nAfter installing the necessary dependencies (a restart may be required), move to\nthe project root and simply run\n```bash\nvagrant up\n```\n\nThis should automatically create a new virtual machine that is set up with all\nnecessary compile- and run-time dependencies. As far as using this setup goes,\nthere are several commands/provisioners that are available to you, to make working\nwith the development virtual machine easier. These should be run in the project \nroot, in the following form\n```bash\nvagrant provision --provision-with \u003ccommand/provisioner\u003e\n```\n\nThe available commands/provisioners are\n* `connect` -\u003e connect to the dev env display using `virt-manager`\n* `prepare_git` -\u003e clone the git upstream \u0026 prepare meson build env\n* `prepare_local` -\u003e copy local sources from your project root \u0026 prepare meson build env\n* `build` -\u003e build the project in the build env\n* `update` -\u003e update build env with sources from your project root\n* `run` -\u003e run bonsai in the graphical session on the dev env (currently not working)\n* `kill` -\u003e kill the bonsai process on the dev env\n* `clean` -\u003e clean the meson build artefacts from the project folder on the dev env\n\nThus, the steps for the first build could be\n```bash\ngit clone https://github.com/vilfa/bonsai.git \u0026\u0026 cd bonsai\nvagrant up\nvagrant provision --provision-with prepare_local\nvagrant provision --provision-with build\n```\n\nThen, in the dev env graphical session, login as vagrant:vagrant, and run the built\nproject with\n```bash\ncd home/vagrant/bonsai \u0026\u0026 ./builddir/bonsai/bonsai\n```\n\nThen, when you make some changes, you might want to update your source on the dev env\nand rerun the compositor. That could also be done by running\n```bash\nvagrant provision --provision-with kill\nvagrant provision --provision-with update\nvagrant provision --provision-with build\n```\n\n...and repeating the above step for running.\n\nTo make this even easier, VS Code tasks are also provided. Search for 'devenv'.\n\n### Building and installing\n\n* Clone the repo\n\n```bash\ngit clone https://github.com/vilfa/bonsai.git\ncd bonsai\n```\n\n* Install build and runtime dependencies\n\n* Create Meson build directory (Meson will let you know about missing stuff at this point)\n\n```bash\nmeson builddir\n```\n\n* Compile the project\n\n```bash\nmeson compile -C builddir\n```\n\n* Install the project\n\n```bash\nmeson install -C builddir\n```\n\nIt is also possible to build and install Bonsai from a distro package (currently,\nonly an Arch Linux package spec is provided). In case you would like to install it\nfrom a package, follow the steps below.\n\n* Move to the `package/arch` directory\n\n```bash\ncd package/arch\n```\n\n* Build and install the package\n\n```bash\nmakepkg -si\n```\n\n* You can also build and install separately\n\n```bash\nmakepkg -s\npacman -U bonsai-0.1.0.dev-1-x86_64.pkg.tar.zst\n```\n\n### Running\n\n* After install a `bonsai.desktop` file will be placed in your `/usr/share/wayland-sessions` directory.\nThis file allows you to start the desktop session straight from the display manager,\nsimply by selecting the 'Bonsai (Wayland)' session on your login screen.\n* Another option is to run Bonsai as a client of main compositor. This option will\nstart Bonsai in a window, allowing you to give it a test drive. You can start it simply\nby opening a shell and typing\n\n```bash\nbonsai\n```\n\nor if for some reason `/usr/bin` is not in your system PATH\n\n```bash\n/usr/bin/bonsai\n```\n\n### Keyboard shortcuts\n\n* `Print` -\u003e screenshot all outputs\n* `Escape` -\u003e un-fullscreen if fulscreen\n* `F11` -\u003e fullscreen focused view\n* `Ctrl`+`Print` -\u003e screenshot active output\n* `Alt`+`Tab` -\u003e cycle views\n* `Super`+`L` -\u003e lock session\n* `Super`+`D` -\u003e bemenu\n* `Super`+`Return` -\u003e term\n* `Super`+`Up` -\u003e maximize active\n* `Super`+`Down` -\u003e unmaximize active\n* `Super`+`Left` -\u003e tile left/untile\n* `Super`+`Right` -\u003e tile right/untile\n* `Super`+`X` -\u003e hide all workspace views\n* `Super`+`Z` -\u003e show all workspace views\n* `Ctrl`+`Alt`+`Right` -\u003e next workspace\n* `Ctrl`+`Alt`+`Left` -\u003e previous workspace\n* `Ctrl`+`Shift`+`Print` -\u003e screenshot selection\n* `Super`+`Shift`+`Q` -\u003e exit\n\n## Help\n\nIf you would like to customize settings for your install, you can do so via a\nconfig file. The following configuration files are recognized by Bonsai when\ninstalling from source (in order of search):\n\n* `.config/bonsai`\n* `.config/bonsai/config`\n* `/usr/local/etc/bonsai`\n* `/usr/local/etc/bonsai/config`\n\nIf you are installing Bonsai from a package, the system-wide config locations will\nbe:\n\n* `/etc/bonsai`\n* `/etc/bonsai/config`\n\nThe default configuration file is located at `/etc/bonsai/config`\nor `/usr/local/etc/bonsai/config` if installing with Meson with the default prefix.\nYou can use this file as a template, copy it to your user configuration folder,\nand customize it as you see fit. The configuration file is documented in the comments\nthat it contains. You might find the following command handy for looking up the\ndevice names to use in the configuration file:\n\n```bash\nsudo libinput list-devices\n```\n\n## Authors\n\n[Luka V.](mailto:luka.vilfan@protonmail.com)\n\n## Version History\n\n* [0.1.0-dev](https://github.com/vilfa/bonsai/releases/tag/v0.1.0-dev)\n  * Initial development release\n\n## License\n\n[MIT](https://github.com/vilfa/bonsai/blob/master/LICENSE)\n\n## Acknowledgments\n\n* [wlroots](https://gitlab.freedesktop.org/wlroots/wlroots)\n* [sway](https://github.com/swaywm/sway)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvilfa%2Fbonsai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvilfa%2Fbonsai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvilfa%2Fbonsai/lists"}