path: root/readme.org

[[http://hackage.haskell.org/package/xmobar][https://img.shields.io/hackage/v/xmobar.svg]]

* About

Xmobar is a minimalistic status bar. It was originally designed and
implemented by Andrea Rossato to work with [[http://xmonad.org][xmonad]], but it is actually
usable with any window manager.

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.

These are some xmobar [[file:doc/screenshots][screenshots]] using the author's configuration:

[[file:doc/screenshots/xmobar-top.png]]

[[file:doc/screenshots/xmobar-bottom.png]]

[[file:doc/screenshots/xmobar-exwm.png]]

This is the [[https://xmobar.org/changelog.html][changelog]] for recent releases.

* Installation
** From your Systems Package Manager

Xmobar is probably available from your distribution package manager!
Most distributions do compile with the =all_extensions= flag, so you
don't have to. For more information on that, see the [[Optional features][optional features]]
item below.

*** Arch Linux

#+begin_src shell
  pacman -S xmobar
#+end_src

*** Debian/Ubuntu based

#+begin_src shell
  apt install xmobar
#+end_src

*** Void Linux

#+begin_src shell
  xbps-install 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://github.com/jaor/xmobar/issues/461][this issue]] for more information.

See below for a list of optional compilation flags that will enable some
optional plugins. For instance, to install xmobar with all the bells and
whistles, use:

#+begin_src shell
  cabal install xmobar --flags="all_extensions"
#+end_src

** From source

If you don't have =cabal-install= installed, you can get xmobar's source
code in a variety of ways:

- From [[http://hackage.haskell.org/package/xmobar/][Hackage]]. Just download the latest release from xmobar's hackage
  page.

- From [[http://github.com/jaor/xmobar/][Github]]. There are also tarballs available for every tagged
  release on [[https://github.com/jaor/xmobar/releases][Github's releases page]]

- From the bleeding edge repo. If you prefer to live dangerously, just
  get the latest and greatest (and buggiest, I guess) using git:

  #+begin_src shell
    git clone git://github.com/jaor/xmobar
  #+end_src

If you have cabal installed, you can now use it from within xmobar's
source tree:

#+begin_src shell
  cabal install --flags="all_extensions"
#+end_src

There is also a barebones =stack.yaml= file that will allow you to
install the xmobar executable with

#+begin_src shell
  stack install
#+end_src

See the =stack.yaml= file for the enabled extensions. You can also pass
them to =stack= directly:

#+begin_src shell
  stack install --flag xmobar:all_extensions
#+end_src

** Optional features

You can configure xmobar to include some optional plugins and features,
which are not compiled by default. To that end, you need to add one or
more flags to either the cabal install command or the configure setup
step, as shown in the examples above.

Extensions need additional libraries (listed below) that will be
automatically downloaded and installed if you're using cabal install.
Otherwise, you'll need to install them yourself.

- =with_dbus= Enables support for DBUS by making xmobar to publish a
  service on the session bus. Requires the [[http://hackage.haskell.org/package/dbus][dbus]] package.

- =with_threaded= Uses GHC's threaded runtime. Use this option if xmobar
  enters a high-CPU regime right after starting.

- =with_utf8= UTF-8 support. Requires the [[http://hackage.haskell.org/package/utf8-string/][utf8-string]] package.

- =with_xft= Antialiased fonts. Requires the [[http://hackage.haskell.org/package/X11-xft/][X11-xft]] package. This
  option automatically enables UTF-8. To use XFT fonts you need to use
  the =xft:= prefix in the =font= configuration option. For instance:

  #+begin_src haskell
    font = "xft:Times New Roman-10:italic"
  #+end_src

  Or to have fallback fonts, just separate them by commas:

  #+begin_src haskell
    font = "xft:Open Sans:size=9,WenQuanYi Zen Hei:size=9"
  #+end_src

- =with_mpd= Enables support for the [[http://mpd.wikia.com/][MPD]] daemon. Requires the [[http://hackage.haskell.org/package/libmpd/][libmpd]]
  package.

- =with_mpris= Enables support for MPRIS v1/v2 protocol. Requires the
  [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][text]] packages.

- =with_inotify= Support for inotify in modern Linux kernels. This
  option is needed for the MBox and Mail plugins to work. Requires the
  [[http://hackage.haskell.org/package/hinotify/][hinotify]] package.

- =with_nl80211= Support for wireless cards on Linux via nl80211 (all
  upstream drivers). Enables the Wireless plugin. Requires [netlink] and
  [cereal] packages.

- =with_iwlib= Support for wireless cards via Wext ioctls (deprecated).
  Enables the Wireless plugin. No Haskell library is required, but you
  will need the [[http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html][iwlib]] C library and headers in your system (e.g.,
  install =libiw-dev= in Debian-based systems or =wireless_tools= on
  Arch Linux). Conflicts with =with_nl80211=.

- =with_alsa= Support for ALSA sound cards. Enables the Volume plugin.
  Requires the [[http://hackage.haskell.org/package/alsa-mixer][alsa-mixer]] package.  To install the latter, you'll need
  the [[http://packages.debian.org/stable/libasound2-dev][libasound]] C library and headers in your system (e.g., install
  =libasound2-dev= in Debian-based systems).

- =with_datezone= Support for other timezones. Enables the DateZone
  plugin. Requires [[http://hackage.haskell.org/package/timezone-olson][timezone-olson]] and [[http://hackage.haskell.org/package/timezone-series][timezone-series]] package.

- =with_xpm= Support for xpm image file format. This will allow loading
  .xpm files in =<icon>=. Requires the [[http://cgit.freedesktop.org/xorg/lib/libXpm][libXpm]] C library.

- =with_uvmeter= Enables UVMeter plugin. The plugin shows UV data for
  Australia.

- =with_weather= Support to display weather information. Enables Weather
  plugin.

- =all_extensions= Enables all the extensions above.

* Running xmobar

You can now 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=.

** Signal Handling

Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2:

- After receiving SIGUSR1 xmobar moves its position to the next screen.

- After receiving SIGUSR2 xmobar repositions itself on the current
  screen.

* Configuration and Further Links

- If you want to jump straight into configuring xmobar, head over to the
  [[./doc/quick-start.org][quick-start]] guide.

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

* 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, John Goerzen, Reto Hablützel,
Juraj Hercek, Tomáš Janoušek, Ada Joule, Spencer Janssen, Roman Joost,
Jochen Keil, Lennart Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry
Kurochkin, Todd Lunter, Vanessa McHale, Robert J. Macomber, Dmitry
Malikov, David McLean, 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, Markus Scherer, Daniel
Schüssler, Olivier Schneider, Alexander Shabalin, Valentin Shirokov,
Peter Simons, Alexander Solovyov, Will Song, 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, Edward Z. Yang and
Norbert Zeh.

** Thanks

*Andrea Rossato*:

Thanks to Robert Manea and Spencer Janssen for their help in
understanding how X works. They gave me suggestions on how to solve many
problems with xmobar.

Thanks to Claus Reinke for make me understand existential types (or at
least for letting me think I grasp existential types...;-).

*jao*:

Thanks to Andrea for creating xmobar in the first place, and for giving
me the chance to contribute.

* Related

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

* License

This software is released under a BSD-style license. See [[https://github.com/jaor/xmobar/raw/master/license][license]] for
more details.

Copyright © 2010-2020 Jose Antonio Ortega Ruiz

Copyright © 2007-2010 Andrea Rossato