Browse Source

Added a simple linux install guide (#6)

Léo Cazenave 1 year ago
parent
commit
74b763d308
1 changed files with 58 additions and 1 deletions
  1. 58 1
      kanata/README.md

+ 58 - 1
kanata/README.md

@@ -36,4 +36,61 @@ as two additional thumb keys. :-)
 Installation
 --------------------------------------------------------------------------------
 
-TBD — see [kanata](https://github.com/jtroo/kanata).
+You can install `kanata` by either downloading a [pre-built
+executable](https://github.com/jtroo/kanata/releases), or by running the
+following commands (if you have `rustc` installed):
+
+```bash
+rustup update stable
+cargo insall kanata
+```
+
+Linux users may want to run these extra steps:
+
+<details>
+<summary> Running kanata without `sudo` </summary>
+
+kanata needs to intercept `uinput` signals, which it cannot do without the
+proper authorisations. If you don’t want to run `kanata` with `sudo`, you’ll
+need to allow `kanata` to read from `uinput` with a udev rule at
+`/etc/udev/rules.d/50-kanata.rules`:
+
+```udev
+KERNEL=="uinput", MODE="0660", GROUP="uinput", OPTIONS+="static_node=uinput"
+```
+</details>
+
+<details>
+<summary> Making a user-side systemd service for kanata </summary>
+
+Note: This only works if `kanata` is able to run without `sudo` (and are using
+`systemd`).
+
+Using a `systemd service` allows running `kanata` as a daemon, possibly right
+after logging in. Here is a template for a service file:
+
+```
+[Unit]
+Description=Kanata keyboard remapper
+Documentation=https://github.com/jtroo/kanata
+
+[Service]
+Environment=PATH=/usr/local/bin:/usr/local/sbin:/usr/bin:/bin
+Environment=DISPLAY=:0
+Environment=HOME=/path/to/home/folder
+Type=simple
+ExecStart=/usr/local/bin/kanata --cfg /path/to/kanata/config/file
+Restart=no
+
+[Install]
+WantedBy=default.target
+```
+
+Copy-paste it into `~/.config/systemd/user/kanata.service`, fill in the
+placeholders, then run one of the following commands:
+
+- `systemctl --user start kanata.service` to manually start `kanata`
+- `systemctl --user enable kanata.service` so `kanata` may autostart whenever the current user logs in
+- `systemctl --user status kanata.service` to check if `kanata` is running
+
+</details>