Awesome Open Source
Awesome Open Source

succade - a Lemonbar manager

Feed your Lemonbar with succade! It repeatedly runs blocks, piping their output to Lemonbar. Every block is a script or program that provides text to be displayed on your bar. Configuration is done with a simple ini file.

succade lemonbar example 1 succade lemonbar example 2 succade lemonbar example 3 succade lemonbar example 4

How it works

  • Starts lemonbar for you
  • Reads the config file (default is ~/.config/succade/succaderc)
  • Loads blocks (programs or scripts defined in the config file)
  • Updates Lemonbar based on the blocks' output

The config needs to have one section for lemonbar (bar) and one per block, plus an optional section for common styles (default) that will apply to all blocks. The bar's section lists the blocks that should be displayed on the bar (and where), and can set some lemonbar properties like its size and position. Block sections define the styling of individual blocks, as well as how often the blocks should be reloaded. Alternatively, trigger commands can be defined. Once a trigger produces output, the associated block will be run (optionally with the trigger's output as command line argument).

Notable features

  • Define labels for your blocks. E.g., for a volume block, have it return 35 % and define the label Vol. in the config.
  • Define a prefix and suffix for every block. Want to wrap all blocks in square brackets? That's 2 lines in the main config.
  • Define a minimum width for your blocks to achieve a uniform look when using fixed-width fonts.
  • Prefix, suffix, label and actual block content can have different foreground and background colors.
  • Most settings can be set once for all blocks, then overwritten for individual blocks, if need be.

Dependencies

  • inih (libinih-dev in Debian, but also included in this repo, see below)

Portability

succade uses libkita to manage child processes. libkita uses epoll, which is Linux only. I've attempted to port libkita to BSD using kqueue, but couldn't get it to work reliably (yet).

Installation

Make sure you have lemonbar (obviously), gcc (for compiling the source code) and all dependencies, as listed above, installed. If inih is not available in your distribution, just replace ./build with ./build-inih below and you should be good to go.

  1. Clone succade and change into its directory:
    git clone https://github.com/domsson/succade.git
    cd succade
  2. Make the build script executable, then run it:
    chmod +x ./build
    ./build
  3. Create the config directory (assuming .config as your config dir):
    mkdir ~/.config/succade
  4. Copy the example config:
    cp ./cfg/example1.ini ~/.config/succade/succaderc
  5. Make succade executable and put it somewhere that's included in your path:
    chmod +x ./bin/succade
    cp ./bin/succade ~/.local/bin/

Configuration

Take a look at the example configurations in this repository and refer to the following documentation.

Possible property values, based on their types as listed in the tables below, are:

  • string: Text within quotes, for example "Hello World"
  • number: A number, for example 34
  • boolean: Either true or false
  • color: RGB hex string, for example #F3BD70

Commands in config options

The config options command, trigger, mouse-left, mouse-middle, mouse-right, scroll-up, scroll-down expect a script or binary to execute. For performance reasons, succade does not invoke a shell to run the commands. This means that shell built-in functionality, like echo, pipes or redirection, will not work (as expected). If you want to use those, wrap those commands in a simple shell script and give succade the path to that script in these config options. You also don't need (and should not) background commands via &, succade will take care of that for you already.

You can, however, use variable substituion, . and ~, as succade internally uses wordexp. Also see the following paragraph from the wordexp man page:

The expansion done consists of the following stages: tilde expansion (replacing ~user by user's home directory), variable substitution (replacing $FOO by the value of the environment variable FOO), command substitution (replacing $(command) or command by the output of command), arithmetic expansion, field splitting, wildcard expansion, quote removal.

lemonbar

The special section bar configures Lemonbar itself and can define common formatting for all blocks. It is required for succade to run, but the only mandatory property is blocks.

Parameter Type Description
command string The command to start the bar; defaults to lemonbar
blocks string Specifies the blocks to display on the bar. Example: desktop | title | volume time
width number Width of the bar in pixel - omit this value for a full-width bar.
height number Height of the bar in pixel - omit to get the minimum required height.
left number x-position of the bar - omit to have it sit at the edge of your screen.
top number y-position of the bar - omit to have it sit at the edge of your screen.
bottom boolean Dock the bar at the bottom instead of the top of the screen.
force boolean Set to true if you want to force docking of Lemonbar; default is false.
foreground color Default foreground (font) color for all blocks.
background color Default background color for the entire bar.
font string Font to use for all blocks.
label-font string Font to use for all block's labels, if any.
affix-font string Font to use for all block's prefixes / suffixes, if any.
line-color color Color for all underlines / overlines, if any.
line-width number Thickness of all underlines / overlines, if any, in pixels.
separator string String to place in between any two blocks of the same alignment.

blocks

Every block that has been named in blocks needs its own config section. Most of these values can also be specified in the special default section, which will apply to all blocks.

Parameter Type Description
command string The command to run the block; defaults to the section name.
interval number Run the block every interval seconds; 0 (default) means the block will only be run once.
trigger string Run the block whenever the command given here prints something to stdout.
consume boolean Use the trigger's output as command line argument when running the block.
live boolean The block is supposed to keep running; succade will monitor it for new output on stdout.
raw boolean If true, succade will not escape '%' characters, allowing you to use format strings directly.
prefix string Shown before the block's main text and label.
suffix string Shown after the block's main text and unit, if any.
label string Shown before the block's main text; useful to display icons when using fonts like Siji.
min-width number Minimum width of the block's main text, which will be left-padded with spaces if neccessary.
foreground color Font color for the whole block (including label and affixes).
background color Background color for the whole block (including label and affixes).
label-foreground color Font color for the block's label, if any.
label-background color Background color for the block's label, if any.
affix-foreground color Font color for the block's prefix and suffix, if any.
affix-background color Background color for the block's prefix and suffix, if any.
line-color color Overline / underline color for the block.
overline boolean Whether or not to draw an overline for the block.
underline boolean Whether or not to draw an underline for the block.
margin number Distance to the next block (or edge of bar) on the left and right, in pixels.
margin-left number Distance to the next block (or edge of bar) on the left, in pixels.
margin-right number Distance to the next block (or edge of bar) on the right, in pixels.
padding number Number of spaces that will be added around a block's output on the left and right.
padding-left number Number of spaces that will be added on the left side of a block's output.
padding-right number Number of spaces that will be added on the right side of a block's output.
mouse-left string Command to run when you left-click the block.
mouse-middle string Command to run when you middle-click the block.
mouse-right string Command to run when you right-click the block.
scroll-up string Command to run when you scroll your mouse wheel up while hovering over the block.
scroll-down string Command to run when you scroll your mouse whell down while hovering over the block.

Usage and command line arguments

Usage:

succade [OPTIONS...]

Options:

  • c CONFIG: config file to use
  • e: run bar even if it is empty (no blocks defined or loaded)
  • h: print help text and exit
  • s SECTION: config section name for the bar (default is "bar")
  • V: print version information and exit

Support

ko-fi

Blocks - Fetching System Information

Looking for scripts, programs or code that can fetch information to display on your bar? Check out fetch-all-the-things.

License

succade is public domain software, do with it whatever you want. However, succade uses inih, which is under the New BSD license.

Motivation

With projects like polybar, the question for the relevance of succade is justified. Personally, I prefer succade - and similar solutions, like Captain - because they enforce the separation of concerns as described by the UNIX philosophy.

For example, imagine someone created a fork of Lemonbar that works with Wayland. As long as they would keep the same interface (same format specifiers supported as with Lemonbar), you can immediately switch to that new bar, without changing anything else. You can still use the same blocks, because they are not tied to the bar or succade.

Additionally, I like minimalistic setups. I don't want most of the additional features of other bars, like true type fonts or rounded borders. Hence, I might as well save a bit of RAM by going with more minimalistic solutions.

Fun fact: polybar started out as a lemonbar wrapper just like succade, but eventually the project maintainers decided to include lemonbar's functionality right into the project. Therefore, in a way, succade is what polybar used to be.


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
C (275,794
Linux (16,452
Wrapper (2,402
Manager (848
Rice (213
Bar (171
Related Projects