river/README.md

85 lines
2.8 KiB
Markdown
Raw Normal View History

2020-04-10 14:18:34 -07:00
# river
2020-03-28 10:02:38 -07:00
River is a dynamic tiling Wayland compositor with flexible runtime
2021-07-17 07:10:07 -07:00
configuration.
Install from your [package manager](https://repology.org/project/river/versions) —
Join us at [#river](https://web.libera.chat/?channels=#river) on irc.libera.chat —
Read our man pages and [wiki](https://github.com/riverwm/river/wiki)
2020-03-28 10:02:38 -07:00
*Note: river is currently early in development. Expect breaking
changes and missing features. Bugs should however be rare at
this point, if you run into one don't hesitate to [open an
issue](https://github.com/riverwm/river/issues/new)*
2020-03-28 10:02:38 -07:00
## Design goals
- Simple and predictable behavior, river should be easy to use and have a
low cognitive load.
- Window management based on a stack of views and tags.
- Dynamic layouts generated by external, user-written executables. A default
`rivertile` layout generator is provided.
- Scriptable configuration and control through a custom Wayland protocol and
2020-06-17 03:40:43 -07:00
separate `riverctl` binary implementing it.
2020-03-28 10:02:38 -07:00
2020-04-12 05:12:48 -07:00
## Building
On cloning the repository, you must init and update the submodules as well
with e.g.
2020-11-02 04:59:59 -08:00
```
git submodule update --init
```
2020-04-12 05:12:48 -07:00
To compile river first ensure that you have the following dependencies
installed. The "development" versions are required if applicable to your
distribution.
2020-04-12 05:12:48 -07:00
2022-11-04 16:29:51 -07:00
- [zig](https://ziglang.org/download/) 0.10
2020-04-12 05:12:48 -07:00
- wayland
- wayland-protocols
2022-11-11 11:25:21 -08:00
- [wlroots](https://gitlab.freedesktop.org/wlroots/wlroots) 0.16
2020-04-12 05:12:48 -07:00
- xkbcommon
- libevdev
2020-05-28 07:27:49 -07:00
- pixman
- pkg-config
- scdoc (optional, but required for man page generation)
2020-04-12 05:12:48 -07:00
Then run, for example:
```
zig build -Drelease-safe --prefix ~/.local install
```
To enable experimental Xwayland support pass the `-Dxwayland` option as well.
2022-05-22 06:35:16 -07:00
If you are packaging river for distribution, see also
[PACKAGING.md](PACKAGING.md).
## Usage
River can either be run nested in an X11/Wayland session or directly
from a tty using KMS/DRM. Simply run the `river` command.
2020-04-12 05:12:48 -07:00
On startup river will run an executable file at `$XDG_CONFIG_HOME/river/init`
2021-07-19 17:20:02 -07:00
if such an executable exists. If `$XDG_CONFIG_HOME` is not set,
`~/.config/river/init` will be used instead.
Usually this executable is a shell script invoking *riverctl*(1) to create
mappings, start programs such as a layout generator or status bar, and
2022-01-23 03:07:34 -08:00
perform other configuration.
An example init script with sane defaults is provided [here](example/init)
in the example directory.
For complete documentation see the `river(1)`, `riverctl(1)`, and
`rivertile(1)` man pages.
2020-06-05 01:34:26 -07:00
## Licensing
2020-05-26 14:13:43 -07:00
River is released under the GNU General Public License v3.0 only.
2020-05-26 14:13:43 -07:00
2020-05-26 14:15:51 -07:00
The protocols in the `protocol` directory are released under various licenses by
various parties. You should refer to the copyright block of each protocol for
the licensing information. The protocols prefixed with `river` and developed by
2020-05-26 14:13:43 -07:00
this project are released under the ISC license (as stated in their copyright
blocks).