#+title: xmobar, a minimalistic status bar #+begin_export html

hackage ci

#+end_export Xmobar is a minimalistic status bar. It was originally designed and implemented to work with [[http://xmonad.org][xmonad]], but it is actually usable with any window manager in X11 and also (via its text output mode) Wayland. Xmobar was inspired by the [[http://tuomov.iki.fi/software/][Ion3]] status bar, and supports similar features, like dynamic color management, icons, output templates, and extensibility through plugins. It is also able to write to standard output, in a variety of formats. [[file:doc/screenshots/xmobar-top.png]] [[file:doc/screenshots/xmobar-bottom.png]] [[file:doc/screenshots/xmobar-exwm.png]] Check [[./changelog.md][the change log]] for our release history. We also have an IRC channel, ~#xmobar~, at [[ircs://irc.libera.chat][Libera]]. * Installation :PROPERTIES: :CUSTOM_ID: installation :END: ** From your system's package manager Xmobar is probably available from your distributions package manager! Most distributions compile xmobar with the =all_extensions= flag, so you don't have to. - Arch Linux #+begin_src shell pacman -S xmobar #+end_src - Debian/Ubuntu based #+begin_src shell apt install xmobar #+end_src - OpenSUSE #+begin_src shell zypper install xmobar #+end_src - Void Linux #+begin_src shell xbps-install xmobar #+end_src - Gentoo #+begin_src shell emerge --ask xmobar #+end_src ** Using cabal-install Xmobar is available from [[http://hackage.haskell.org/package/xmobar/][Hackage]], and you can install it using =cabal-install=: #+begin_src shell cabal install xmobar #+end_src Starting with version 0.35.1, xmobar now requires at least GHC version 8.4.x. to build. See [[https://codeberg.org/xmobar/xmobar/issues/461][this issue]] for more information. See [[file:doc/compiling.org#optional-features][here]] for a list of optional compilation flags that will enable some optional plugins. For instance, to install xmobar with all the bells and whistles (this is probably what you want), use: #+begin_src shell cabal install xmobar --flags="all_extensions" #+end_src ** From source See [[file:doc/compiling.org][compiling]]. * Running xmobar ** Running xmobar with a configuration file You can run xmobar with: #+begin_src shell xmobar /path/to/config & #+end_src or #+begin_src shell xmobar & #+end_src if you have the default configuration file saved as =$XDG_CONFIG_HOME/xmobar/xmobarrc= (defaulting to =~/.config/xmobar/xmobarrc=), or =~/.xmobarrc=. All the available command line switches and configuration parameters are described in [[file:quick-start.org][the quick start guide]] and [[file:plugins.org][the plugins documentation]]. ** Writing your own xmobar in Haskell As shown above, one can use ~xmobar~ as a regular program, via its configuration file, without having to write any code. It also is possible to install xmobar as a library and use it to write your own xmobar using Haskell instead of using a configuration file. (This is very similar to how [[http://xmonad.org][xmonad]] works.) That gives you the ability of using Haskell and its libraries to extend xmobar to your heart's content. If you are a programmer, take a look [[file:doc/using-haskell.org][here]] to learn more. ** Running xmobar in text mode By default, xmobar will run as an X11 application, in a docked window, but it is possible to redirect xmobar's to the standard output, optionally with color escape sequences. In this mode, xmobar can be run inside a terminal o console, or its output piped to other applications, and there is no need for an X11 display (so, for instance, you could pipe xmobar's output to a Wayland application, such as swaybar.) To run xmobar in text mode, either pass the =-T= flag to its invocation: #+begin_src shell xmobar -T /path/to/config & #+end_src or set the parameter =textOutput= to True in its configuration. You can also specify the format of color escapes, for instance, omitting them altogether with ~Plain~: #+begin_src shell xmobar -TPlain /path/to/config & #+end_src Other options are ~Ansi~, ~Pango~, and ~Swaybar~. ** Using xmobar in Wayland with swaybar or waybar In text mode, xmobar can be told to ouput its information using pango markup for colors and fonts, and it that way you can use it with swaybar or waybar, if you don't have actions or boxes in your template. Here's a minimal ~bar~ configuration for sway's configuration file: #+begin_src conf bar { status_command xmobar -TPango pango_markup enabled } #+end_src In case you want to use boxes around text or click actions in your template, you can use instead the format ~Swaybar~, which supports both. This output format follows the JSON /swaybar-protocol/ defined by swaybar. Configure it simply with: #+begin_src conf bar { status_command xmobar -TSwaybar } #+end_src * Configuration and further documentation - If you want to jump straight into running xmobar, head over to the [[./doc/quick-start.org][quick start guide]]. - If you want to get a detailed overview of all available plugins and monitors, visit the [[./doc/plugins.org][plugins index]]. - [[./doc/window-managers.org][Interfacing with window managers]] describes plugins and extensions for interacting with xmobar from your window manager. - If you want to know how to contribute to the xmobar project, check out [[contributing.org][contributing]]. - For elaborated examples of how to use xmobar as a Haskell library see the [[file:doc/using-haskell.org][using Haskell docs]]. * Authors and credits Andrea Rossato originally designed and implemented xmobar up to version 0.11.1. Since then, it is maintained and developed by [[https://jao.io][jao]], with the help of the greater xmobar and Haskell communities. In particular, xmobar incorporates patches by Mohammed Alshiekh, Alex Ameen, Axel Angel, Dhananjay Balan, Claudio Bley, Dragos Boca, Ben Boeckel, Ivan Brennan, Duncan Burke, Roman Cheplyaka, Patrick Chilton, Antoine Eiche, Nathaniel Wesley Filardo, Guy Gastineau, John Goerzen, Patrick Günther, Reto Hablützel, Juraj Hercek, Tomáš Janoušek, Ada Joule, Spencer Janssen, Roman Joost, Pavel Kalugin, Jochen Keil, Sam Kirby, Lennart Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry Kurochkin, Todd Lunter, Vanessa McHale, Robert J. Macomber, Dmitry Malikov, David McLean, Joan MIlev, Marcin Mikołajczyk, Dino Morelli, Tony Morris, Eric Mrak, Thiago Negri, Edward O'Callaghan, Svein Ove, Martin Perner, Jens Petersen, Alexander Polakov, Sibi Prabakaran, Pavan Rikhi, Petr Rockai, Andrew Emmanuel Rosa, Sackville-West, Amir Saeid, Markus Scherer, Daniel Schüssler, Olivier Schneider, Alexander Shabalin, Valentin Shirokov, Peter Simons, Alexander Solovyov, Will Song, John Soo, John Soros, Felix Springer, Travis Staton, Artem Tarasov, Samuli Thomasson, Edward Tjörnhammar, Sergei Trofimovich, Thomas Tuegel, John Tyree, Jan Vornberger, Anton Vorontsov, Daniel Wagner, Zev Weiss, Phil Xiaojun Hu, Nikolay Yakimov, Edward Z. Yang, Leo Zhang, Norbert Zeh, and Michał Zielonka. Andrea wants to thank Robert Manea and Spencer Janssen for their help in understanding how X works. They gave him suggestions on how to solve many problems with xmobar. He also thanks Claus Reinke for making him understand existential types (or at least for letting him think he grasps existential types...;-). * License This software is released under a BSD-style license. See [[https://codeberg.org/xmobar/xmobar/src/branch/master/license][license]] for more details. Copyright © 2010-2022 Jose Antonio Ortega Ruiz Copyright © 2007-2010 Andrea Rossato