README.md

   1 # 🌱 herbe
   2 > Daemon-less notifications without D-Bus. Minimal and lightweight.
   3
   4 <p align="center">
   5   <img src="https://user-images.githubusercontent.com/24730635/90975811-cd62fd00-e537-11ea-9169-92e68a71d0a0.gif" />
   6 </p>
   7
   8 ## Usage
   9 ```shell
  10 $ herbe "herbe notifications" " " "Daemon-less notifications without D-Bus. Minimal and lightweight."
  11 ```
  12 will display the notification shown above
  13
  14 * [Dismiss a notification](#dismiss-a-notification)
  15 * [Actions](#actions)
  16 * [Newlines](#newlines)
  17 * [Multiple notifications](#multiple-notifications)
  18 * [Notifications don't show up](#notifications-dont-show-up)
  19
  20 ### Dismiss a notification
  21 A notification can be dismissed either by clicking on it with `DISMISS_BUTTON` (set in config.h, defaults to left mouse button) or sending a `SIGUSR1` signal to it:
  22 ```shell
  23 $ pkill -SIGUSR1 herbe
  24 ```
  25 Dismissed notifications return exit code 2.
  26
  27 ### Actions
  28 Action is a piece of shell code that runs when a notification gets accepted. Accepting a notification is the same as dismissing it, but you have to use either `ACTION_BUTTON` (defaults to right mouse button) or the `SIGUSR2` signal.
  29 An accepted notification always returns exit code 0. To specify an action:
  30 ```shell
  31 $ herbe "Notification body" && echo "This is an action"
  32 ```
  33 Where everything after `&&` is the action and will get executed after the notification gets accepted.
  34
  35 ### Newlines
  36 Every command line argument gets printed on a separate line by default e.g.:
  37 ```shell
  38 $ herbe "First line" "Second line" "Third line" ...
  39 ```
  40 You can also use `\n` e.g. in `bash`:
  41 ```shell
  42 $ herbe $'First line\nSecond line\nThird line'
  43 ```
  44 But by default `herbe` prints `\n` literally:
  45 ```shell
  46 $ herbe "First line\nStill the first line"
  47 ```
  48 Output of other programs will get printed correctly, just make sure to escape it (so you don't end up with every word on a separate line):
  49 ```shell
  50 $ herbe "$(ps axch -o cmd:15,%cpu --sort=-%cpu | head)"
  51 ```
  52
  53 ### Multiple notifications
  54 Notifications are put in a queue and shown one after another in order of creation (first in, first out). They don't overlap and each one is shown for its entire duration.
  55
  56 ### Notifications don't show up
  57 Most likely a running notification got terminated forcefully (SIGKILL or any uncaught signal) which caused the semaphore not getting unlocked. First, kill any `herbe` instance that is stuck:
  58 ```shell
  59 $ pkill -SIGKILL herbe
  60 ```
  61 Then just call `herbe` without any arguments:
  62 ```shell
  63 $ herbe
  64 ```
  65 Notifications should now show up as expected.
  66
  67 Don't ever send any signals to `herbe` except these:
  68 ```shell
  69 # same as pkill -SIGTERM herbe, terminates every running herbe process
  70 $ pkill herbe
  71
  72 $ pkill -SIGUSR1 herbe
  73 $ pkill -SIGUSR2 herbe
  74 ```
  75 And you should be fine. That's all you really need to interact with `herbe`.
  76
  77 ## Installation
  78 ### Dependencies
  79 * X11 (Xlib)
  80 * Xft
  81 * freetype2
  82
  83 The names of packages are different depending on which distribution you use.
  84 For example, if you use [Void Linux](https://voidlinux.org/) you will have to install these dependencies:
  85 ```shell
  86 sudo xbps-install base-devel libX11-devel libXft-devel
  87 ```
  88
  89 ### Build
  90 ```shell
  91 git clone https://github.com/dudik/herbe
  92 cd herbe
  93 sudo make install
  94 ```
  95 `make install` requires root privileges because it copies the resulting binary to `/usr/local/bin`. This makes `herbe` accessible globally.
  96
  97 You can also use `make clean` to remove the binary from the build folder, `sudo make uninstall` to remove the binary from `/usr/local/bin` or just `make` to build the binary locally.
  98
  99 ## Configuration
 100 herbe is configured at compile-time by editing `config.h`. Every option should be self-explanatory. There is no `height` option because height is determined by font size and text padding.
 101
 102 ## Contribute
 103 If you want to report a bug or you have a feature request, feel free to [open an issue](https://github.com/dudik/herbe/issues).