Zander671/river
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: improve startup and config information

Browse Source
This commit is contained in:
Isaac Freund 2020-12-30 20:29:45 +01:00
parent c7bc47d6d4
commit 53d4c12d41
No known key found for this signature in database
GPG Key ID: 86DED400DDFD7A11
2 changed files with 38 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
README.md
View File

@ -42,48 +42,33 @@ installed:
*Note: NixOS users may refer to the
[Building on NixOS wiki page](https://github.com/ifreund/river/wiki/Building-on-NixOS)*
Then run, for example,
Then run, for example:
```
zig build -Drelease-safe=true --prefix /usr/local install
zig build -Drelease-safe=true --prefix /usr install
```
to build and install the binaries and man pages to `/usr/local/bin` and
`/usr/local/share/man`. To enable experimental Xwayland support pass the
`-Dxwayland=true` option as well.
To enable experimental Xwayland support pass the `-Dxwayland=true` option as well.
## Usage
River can either be run nested in an X11/wayland session or directly
from a tty using KMS/DRM.
River has no keybindings by default; mappings can be created using the `map`
command of `riverctl`. Generally, creating mappings and other configuration is
done with a shell script. River will execute any arbitrary shell command passed
with the `-c` flag during startup. For example:
On startup river will look for and run an executable file at one of the
following locations, checked in the order listed:
```
river -c /path/to/config.sh
```
- `$XDG_CONFIG_HOME/river/init`
- `$HOME/.config/river/init`
- `/etc/river/init`
An example script with sane defaults is provided [here](contrib/config.sh) in
the contrib directory.
Usually this executable init file will be a shell script invoking riverctl
to create mappings and preform other configuration. The init file path may
be overridden with the `-c` flag.
For a complete list of commands see the `riverctl(1)` man page.
An example init script with sane defaults is provided [here](example/init)
in the example directory and installed to `/etc/river/init`.
Keyboard configuration is not yet implemented in river, but since river uses
libxkbcommon you may use the following environment variables to set defaults:
- `XKB_DEFAULT_RULES`
- `XKB_DEFAULT_MODEL`
- `XKB_DEFAULT_LAYOUT`
- `XKB_DEFAULT_VARIANT`
- `XKB_DEFAULT_OPTIONS`
Possible values for these variables can be found in the `xkeyboard-config(7)`
man page. For example, to use a dvorak layout one could start river with
```
XKB_DEFAULT_LAYOUT="us(dvorak)" river
```
For a complete list of commands and documentation see the `riverctl(1)`
man page.
## Development

32
doc/river.1.scd
View File

@ -16,13 +16,9 @@ on wlroots and written in Zig.
# OPTIONS
*-c* _shell_command_
Run a shell command or give the path to a script that will be run after
river's wayland server is initialized but before entering the main
loop. You may use this to configure river and define keymaps using
*riverctl*(1), start programs such as a status bar, or perhaps run a
service manager. If the process started by this flag is still running
when river exits, river will send SIGTERM and and wait for it to
terminate.
Override the default search paths for an init executable: instead
_shell_command_ will be run with `/bin/sh -c`. See the *CONFIGURATION*
section for more details.
*-l* _log_level_
Set the log level of river to a value from 0 to 7 with 0 being the
@ -31,8 +27,20 @@ on wlroots and written in Zig.
# CONFIGURATION
Experimental XWayland support can be enabled on compile-time with the
_-Dxwayland=true_ flag.
On startup river will look for and run an executable file at one of the
following locations, checked in the order listed:
- $XDG_CONFIG_HOME/river/init
- $HOME/.config/river/init
- /etc/river/init
This executable init file will be run after river's wayland server is
initialized but before entering the main loop. If the process started by
this flag is still running when river exits, river will send SIGTERM and
and wait for it to terminate.
Usually this will be a shell script invoking *riverctl*(1) to create mappings,
start programs such as a status bar, and preform other configuration.
# ENVIRONMENT
@ -45,6 +53,12 @@ The following environment variables are used to configure the keyboard. See
- XKB_DEFAULT_OPTIONS
- XKB_DEFAULT_RULES
# EXAMPLES
Set the keyboard layout to colemak:
XKB_DEFAULT_LAYOUT="us(colemak)" river
# AUTHORS
Maintained by Isaac Freund <ifreund@ifreund.xyz> who is assisted by open