From 8535f5a83d3c77994face997540d469e292c3e64 Mon Sep 17 00:00:00 2001 From: Michael Carlberg Date: Tue, 24 May 2016 23:30:05 +0200 Subject: [PATCH] docs(config): Documentation of module configuration --- README.md | 796 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 740 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 604cc56a..6353e2c7 100644 --- a/README.md +++ b/README.md @@ -24,12 +24,11 @@ A package will be written for XBPS so stay tuned. A C++ compiler with C++14 support. For example `clang`. -- lemonbar (obviously) - - NOTE: The application has only been tested against the `single-mon` fork. - If you have trouble with your version of lemonbar, install the fork which is - included in the `contrib` folder. - - There are plans to integrate `lemonbar` into the project. +- lemonbar + > **NOTE:** The application has only been tested against the `single-mon` fork. + > If you have trouble running it with your current version, install the one + > included in `contrib/lemonbar-sm-git`. + > Plans are to make `lemonbar` an internal module. - cmake - boost - libx11 @@ -39,80 +38,765 @@ A C++ compiler with C++14 support. For example `clang`. - libmpdclient _(optional: used by the mpd module)_ - libsigc++ _(optional: used by the i3 module)_ -**Installing using pacman:** +**Install dependencies using pacman:** ~~~ sh -$ pacman -S cmake boost libx11 libxrandr wireless_tools alsa-lib libmpdclient libsigc++ i3-wm +$ sudo pacman -S cmake boost libx11 libxrandr wireless_tools alsa-lib libmpdclient libsigc++ i3-wm ~~~ -**Installing using xbps-install:** +**Install dependencies using xbps-install:** ~~~ sh -$ xbps-install -S cmake alsa-lib-devel boost-devel i3-devel libX11-devel libXrandr-devel libmpdclient-devel libsigc++-devel wireless_tools-devel +$ sudo xbps-install -S cmake alsa-lib-devel boost-devel i3-devel libX11-devel libXrandr-devel libmpdclient-devel libsigc++-devel wireless_tools-devel ~~~~ -**Installing using apt-get:** +**Install dependencies using apt-get:** -> NOTE: `libmpdclient-dev` and `i3-wm` are located in the `universe` repository, so if you want support for the -> mpd/i3 modules you need to make sure it's included in the list of sources in `/etc/apt/sources.list`. -> For example: +> **NOTE:** To get support for the mpd and i3 modules, the `universe` repository +> needs to be added to the list of sources in `/etc/apt/sources.list`. > -> `deb http://archive.ubuntu.com/ubuntu/ xenial main restricted universe` +> Packages in the `universe` repository: `libmpdclient-dev` `i3-wm` ~~~ sh -$ apt-get install cmake libx11-dev libxrandr-dev libboost-dev libiw-dev libmpdclient-dev libsigc++-dev i3-wm +$ sudo apt-get install cmake libx11-dev libxrandr-dev libboost-dev libiw-dev libmpdclient-dev libsigc++-dev i3-wm ~~~~ -
+### Building from source -## Building from source - -#### Automatic installation using ./build.sh - -If you haven't worked with builds before you could try to run the following -command chain: - -~~~ sh -$ git clone --branch 0.1.2 --recursive https://github.com/jaagr/lemonbuddy.git -$ cd lemonbuddy -$ ./build.sh -~~~ - -> NOTE: `git-perl` is required for submodules to work in **Void Linux** - -#### It is of course recommended that you control the build process yourself. +> **NOTE:** In Void Linux you will need to install `git-perl` to get support for submodules. ~~~ sh $ git clone --branch 0.1.2 --recursive https://github.com/jaagr/lemonbuddy.git $ mkdir lemonbuddy/build $ cd lemonbuddy/build $ cmake .. - # Optionally list and edit build variables - $ make edit_cache + # Optionally list and edit build settings before compiling + # $ make edit_cache $ sudo make install ~~~ ---- -
+## Running + +Before customizing the bar, make sure everything works as expected by trying +out one of the example configurations installed with the application. +The following code will get you started: + + ~~~ sh + # Create the config root directory + $ mkdir -p ${XDG_CONFIG_HOME:-$HOME/.config}/lemonbuddy + $ cd ${XDG_CONFIG_HOME:-$HOME/.config}/lemonbuddy + + # Copy sample config for the running wm (uses a wm agnostic config as fallback) + $ __wm=$(pgrep -l "(bspwm|i3)") + $ cp /usr/share/examples/lemonbuddy/config${__wm:+.${__wm##* }} config + + # Launch the bar + # (where "example" is the name of the bar as defined by [bar/NAME] in the config) + $ lemonbuddy_wrapper.sh example + + # When making changes to the configuration, make sure to try it out using + # only the lemonbuddy executable, before launching it with the wrapper: + $ lemonbuddy example + (Ctrl-C to terminate) + + # "lemonbuddy_wrapper.sh" is just a simple shell script that takes care + # of redirecting the in-/output streams between "lemonbuddy" and "lemonbar". + # It should be considered experimental and needs more assertions, but if + # it the above command doesn't report any error it is generally safe to + # assume that the wrapper will launch the bar successfully as well. + ~~~ + +**It is recommended** to always use `lemonbuddy_wrapper.sh` when launching the bars. + +If you handle the in-/output stream redirection's manually, the internal command +handlers (e.g. mpd or volume controls) might stop working. It won't change the +output of the bar but you will miss out on the internal API calls, which is one +of the main advantages of using the application. + +The `lemonbuddy_wrapper.sh` will be deprecated once `lemonbar` is integrated +into the project. + + +## Launching the bar in your wm's bootstrap routine + +When using the wrapper to start the bar in in your wm's autostart routine, make sure to include +a kill directive before launching the bar. This is done to make sure that any previously spawned +processes gets terminated before before we launch the new ones. For example in +`$HOME/.config/bspwmrc`: + + ~~~ sh + # Terminate already running bar instances + pgrep -f '(lemonbuddy_wrapper.sh|^lemonb(uddy|ar))' | xargs kill -9 >/dev/null 2>&1 + + # Launch bar1 and bar2 + lemonbuddy_wrapper.sh bar1 & + lemonbuddy_wrapper.sh bar2 & + + echo "Bars launched..." + ~~~ + + +## Configuration + +The configuration syntax is very much **WIP**. If you have any feedback or suggestions, please +[create an issue ticket](https://github.com/jaagr/lemonbuddy/issues). + +When working with unicode symbols, remember that fonts render them differently. Changing font +can change the quality of your generated output drastically. One must-have font +is [Unifont](http://unifoundry.com/unifont.html), which has great unicode coverage. + +Also try different icon fonts, such as [Font Awesome](http://fontawesome.io/icons/) and [Material Icons](https://design.google.com/icons/). + +The values used in the examples below are to be considered placeholder values, and +the resulting output might not be award-winning. + +`🟊 = module is still flagged as work in progress` + + +### Module `internal/backlight` + ~~~ ini + [module/backlight] + type = internal/backlight + + ; Use the following command to list available cards: + ; $ ls -1 /sys/class/backlight/ + card = intel_backlight + ~~~ + +##### Extra formatting (example) + ~~~ ini + ; Available tags: + ;