path: root/readme.org

#+title: xmobar, a minimalistic status bar

#+begin_export html
<p align="right">
  <a href="http://hackage.haskell.org/package/xmobar">
    <img src="https://img.shields.io/hackage/v/xmobar.svg" alt="hackage"/>
  </a>
  <a href="https://ci.codeberg.org/xmobar/xmobar">
    <img src="https://ci.codeberg.org/api/badges/xmobar/xmobar/status.svg" alt="ci"/>
  </a>
</p>
#+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][compiling]] 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=.

*** Writing your own xmobar in Haskell
    :PROPERTIES:
    :CUSTOM_ID: xmobar-in-haskell
    :END:

    It 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.)

    Make sure that ~ghc~ will be able to locate the xmobar library, e.g. with

    #+begin_src shell
      cabal install --lib xmobar
    #+end_src

    and then write your Haskell configuration and main function using the
    functions and types exported in the library, which closely resemble those
    used in configuration files.  Here's a small example:

    #+begin_src haskell
      import Xmobar

      config :: Config
      config =
        defaultConfig
          { font = "xft:Terminus-8",
            allDesktops = True,
            alpha = 200,
            commands =
              [ Run XMonadLog,
                Run $ Memory ["t", "Mem: <usedratio>%"] 10,
                Run $ Kbd [],
                Run $ Date "%a %_d %b %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10
              ],
            template = "%XMonadLog% }{ %kbd% | %date% | %memory%",
            alignSep = "}{"
          }

      main :: IO ()
      main = xmobar config
    #+end_src

    You can then for instance run =ghc --make xmobar.hs= to create a new xmobar
    executable running exactly the monitors defined above.  Or put your
    =xmobar.hs= program in =~/.config/xmobar/xmobar.hs= and, when running the
    system-wide xmobar, it will notice that you have your own implementation
    and (re)compile and run it as needed.  See also this [[./examples/xmobar.hs][extended example]].

*** 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 Links

  - 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]].

  - If you want to write your own plugins, see [[./doc/write-your-own-plugin.org][Write your own plugin]].

  - For elaborated examples of how to use xmobar as a Haskell library
    to create your monitors, see [[https://codeberg.org/jao/xmobar-config][this repo at jao/xmobar-config]].

  - To understand the internal mysteries of xmobar you may try reading
    [[https://wiki.haskell.org/X_window_programming_in_Haskell][this tutorial]] on X Window Programming in Haskell.

* 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