polybar/README.md

181 lines
7.3 KiB
Markdown
Raw Normal View History

2018-05-27 07:37:56 +00:00
![Polybar](banner.png)
2016-05-19 14:41:06 +00:00
2018-08-26 11:34:54 +00:00
[![Release](https://img.shields.io/github/release/jaagr/polybar.svg)](https://github.com/jaagr/polybar/releases)
2016-11-19 05:22:44 +00:00
[![Build Status](https://travis-ci.org/jaagr/polybar.svg?branch=master)](https://travis-ci.org/jaagr/polybar)
[![Coverage Status](https://codecov.io/gh/jaagr/polybar/branch/master/graph/badge.svg)](https://codecov.io/gh/jaagr/polybar/branch/master)
2018-05-09 12:19:23 +00:00
[![MIT License](https://img.shields.io/github/license/jaagr/polybar.svg)](https://github.com/jaagr/polybar/blob/master/LICENSE)
2016-10-12 03:35:33 +00:00
A fast and easy-to-use tool for creating status bars.
2016-05-19 14:41:06 +00:00
2016-11-19 05:22:44 +00:00
**Polybar** aims to help users build beautiful and highly customizable status bars
2016-06-29 02:44:55 +00:00
for their desktop environment, without the need of having a black belt in shell scripting.
2017-01-20 07:15:55 +00:00
Here are a few screenshots showing you what it can look like:
2016-06-29 02:44:55 +00:00
[![sample screenshot](http://i.imgur.com/xvlw9iHt.png)](http://i.imgur.com/xvlw9iH.png)
[![sample screenshot](http://i.imgur.com/cYQOuRrt.png)](http://i.imgur.com/cYQOuRr.png)
[![sample screenshot](http://i.imgur.com/A6spiZZt.png)](http://i.imgur.com/A6spiZZ.png)
[![sample screenshot](http://i.imgur.com/TY5a5r9t.png)](http://i.imgur.com/TY5a5r9.png)
You can find polybar configs for these example images (and other configs) [here](https://github.com/jaagr/dots/tree/master/.local/etc/themer/themes).
If you need help, check out the [Support](SUPPORT.md) page.
Please report any issues or bugs you may find by [creating an issue ticket](https://github.com/jaagr/polybar/issues/new/choose) here on GitHub.
2017-01-14 12:16:20 +00:00
Make sure you include steps on how to reproduce it. There's also an irc channel available at freenode, cleverly named `#polybar`.
2016-06-29 02:44:55 +00:00
## Table of Contents
* [Introduction](#introduction)
* [Getting started](#getting-started)
* [Dependencies](#dependencies)
* [Building from source](#building-from-source)
* [Configuration](#configuration)
* [Running](#running)
2018-05-27 09:11:50 +00:00
* [Contributors](#contributors)
2016-06-29 02:44:55 +00:00
* [License](#license)
## Introduction
2016-11-19 05:22:44 +00:00
The main purpose of **Polybar** is to help users create awesome status bars.
2017-01-20 07:15:55 +00:00
It has built-in functionality to display information about the most commonly used services.
2017-05-12 07:43:36 +00:00
Some of the services included so far:
2016-06-29 02:44:55 +00:00
2016-12-15 17:22:50 +00:00
- Systray icons
- Window title
2016-06-29 02:44:55 +00:00
- Playback controls and status display for [MPD](https://www.musicpd.org/) using [libmpdclient](https://www.musicpd.org/libs/libmpdclient/)
- [ALSA](http://www.alsa-project.org/main/index.php/Main_Page) volume controls
- Workspace and desktop panel for [bspwm](https://github.com/baskerville/bspwm) and [i3](https://github.com/i3/i3)
2016-12-15 17:22:50 +00:00
- Workspace module for [EWMH compliant](https://specifications.freedesktop.org/wm-spec/wm-spec-1.3.html#idm140130320786080) window managers
- Keyboard layout and indicator status
2016-06-29 02:44:55 +00:00
- CPU and memory load indicator
- Battery display
- Network connection details
- Backlight level
- Date and time label
- Time-based shell script execution
- Command output tailing
- User-defined menu tree
2016-11-18 17:56:15 +00:00
- Inter-process messaging
2016-06-29 02:44:55 +00:00
- And more...
2016-11-19 05:22:44 +00:00
[See the wiki for more details](https://github.com/jaagr/polybar/wiki).
2016-11-18 17:56:15 +00:00
2016-06-29 02:44:55 +00:00
## Getting started
2017-07-04 15:34:00 +00:00
<a href="https://repology.org/metapackage/polybar">
<img src="https://repology.org/badge/vertical-allrepos/polybar.svg" alt="Packaging status" align="right">
</a>
Polybar was already packaged for the distros listed below.
If you can't find your distro here, you will have to [build from source](#building-from-source).
If you create a package for any other distribution, please consider contributing the template.
2016-11-19 05:22:44 +00:00
If you are using **Arch Linux**, you can install the AUR package [polybar-git](https://aur.archlinux.org/packages/polybar-git/) to get the latest version, or
[polybar](https://aur.archlinux.org/packages/polybar/) for the latest stable release.
2016-06-23 23:14:43 +00:00
If you are using **Void Linux**, you can install [polybar](https://github.com/void-linux/void-packages/blob/master/srcpkgs/polybar/template) using `xbps-install -S polybar`.
2017-01-09 19:50:52 +00:00
2017-07-04 15:34:00 +00:00
If you are using **NixOS**, polybar is available in both the stable and unstable channels and can be installed with the command `nix-env -iA nixos.polybar`.
If you are using **Slackware**, polybar is available from the [SlackBuilds](https://slackbuilds.org/repository/14.2/desktop/polybar/) repository.
2018-02-02 13:15:29 +00:00
If you are using **Source Mage GNU/Linux**, polybar spell is available in test grimoire and can be installed via `cast polybar`.
2016-06-23 23:14:43 +00:00
If you are using **openSUSE**, polybar is available from [OBS](https://build.opensuse.org/package/show/home:sysek/polybar) repository. Package is available for openSUSE Leap 15 and Tumbleweed.
2018-04-18 11:27:30 +00:00
If you are using **FreeBSD**, [polybar](https://svnweb.freebsd.org/ports/head/x11/polybar/) can be installed using `pkg install polybar`. Make sure you are using the `latest` package branch.
2018-04-18 11:27:30 +00:00
If you are using **Gentoo**, both release and git-master versions are available in the [main](https://packages.gentoo.org/packages/x11-misc/polybar) repository.
2018-05-05 02:40:05 +00:00
2016-06-29 02:44:55 +00:00
### Dependencies
2018-06-18 11:48:52 +00:00
A compiler with C++14 support ([clang-3.4+](http://llvm.org/releases/download.html), [gcc-5.1+](https://gcc.gnu.org/releases.html)), [cmake 3.1+](https://cmake.org/download/), [git](https://git-scm.com/downloads)
2018-09-16 19:21:50 +00:00
- `cairo`
- `libxcb`
- `python2`
- `xcb-proto`
- `xcb-util-image`
- `xcb-util-wm`
2016-06-23 23:14:43 +00:00
**Optional dependencies:**
2018-09-16 19:21:50 +00:00
- `xcb-util-cursor` *required for the `cursor-click` and `cursor-scroll` settings*
- `xcb-util-xrm` *required for accessing X resources with `${xrdb:...}`*
**Optional dependencies for extended module support:**
- `xcb-xkb` *required by `internal/xkeyboard`*
2018-09-16 19:21:50 +00:00
- `alsa-lib` *required by `internal/alsa`*
- `libpulse` *required by `internal/pulseaudio`*
- `i3-wm` *required by `internal/i3`*
- `jsoncpp` *required by `internal/i3`*
- `libmpdclient` *required by `internal/mpd`*
- `libcurl` *required by `internal/github`*
- `libnl-genl` or `wireless_tools` *required by `internal/network`*
2016-06-23 23:14:43 +00:00
2017-01-14 12:16:20 +00:00
Find a more complete list on the [dedicated wiki page](https://github.com/jaagr/polybar/wiki/Compiling).
2016-06-29 02:44:55 +00:00
### Building from source
2016-05-24 02:06:29 +00:00
Please [report any problems](https://github.com/jaagr/polybar/issues/new/choose) you run into when building the project.
2016-06-29 02:44:55 +00:00
~~~ sh
Release 3.2.0 (#1338) Breaking Changes: * `0 < label-NAME-maxlen < 3` will now throw an exception and disable the containing module, if ellipsis is enabled for that label. (#1198) Changelog: Deprecations: * `internal/volume` is now called `internal/alsa` (#967) * temperature: The `%temperature%` is deprecated in favor of `%temperature-c%`(#897) * mpd: `icon-repeatone` is deprecated in favor of `icon-single` (#1295), see #1279 Features: * feat(mpd): Add support for icon-consume (#861) * feat(bspwm): Add workspace separator (#942) * feat(i3): Add workspace separator (#938), see #929 * feat(build): Make polybar build on FreeBSD (#931, jaagr/xpp#8), see #239 * feat(volume): Add pulseaudio backend (#779) * feat(script): Add %pid% token for tail commands (#934) * feat(temp): Add temperature tokens without unit (#897) * feat(memory): Add memory used/free ramp (#1038), see #1037 * feat(memory): Add swap tokens (#1018) * feat(net): Add unknown-as-up option (#1077), see #457 * feat(config): Support fractional size and offset (#972), see #953 * feat(xwindow): Add label-empty (#1136) * feat(battery): Add animation-discharging (analog to animation-charging) (#1190) * feat(config): Support pixel offset for bar size and offset values (#1224) * feat(mpd): Add `%album-artist%` token (#1263) * feat(net): Add local_ip6 token (#1239), see #1234 * feat(net): Add nl80211 support (#1009), see #277 Fixes: * fix(mpd): Wrong elapsed time when after standby (#921), see #915 * fix(config): Wrong min, maxlen when using the same token multiple times (#974), see #971 * fix(battery): use power_now correctly (#958), see #928 * fix(mpd): Crash when mpd isn't running (#983), see #979 * fix(xworkspaces): Respect 'enable-scroll' (#1002) * fix(xbacklight): Respect 'enable-scroll' (#1014) * fix(build): support xcb-proto >=1.13 (jaagr/xpp#11), see #973 * fix(mpd): Respect MPD_HOST env variable (#1025), see #1007 * fix(i3): Reconnect i3 IPC socket on restart/error (#1099), see #762 * fix(cursor): Occasional crash on mouseover (#1124), see #1117 * fix(net): Mark 'not connected' on querying failure (#1171), see #1163 * fix(gcc): Fix -Wstringop-truncation warning (#1216, jaagr/i3ipcpp#7), see #1215 * fix(builder): Don't truncate colors with same channels (#1217), see #1183 * fix(bspwm): Consistent behavior when scrolling through multiple desktops (#986), see #981 * fix(builder): Respect label-ellipsis option (#1198), see #1194
2018-07-23 13:17:29 +00:00
$ git clone --branch 3.2 --recursive https://github.com/jaagr/polybar
2016-11-19 05:22:44 +00:00
$ mkdir polybar/build
$ cd polybar/build
2017-01-14 12:16:20 +00:00
$ cmake ..
2016-06-29 02:44:55 +00:00
$ sudo make install
~~~
2016-05-24 02:06:29 +00:00
2016-11-12 12:54:27 +00:00
There's also a helper script available in the root folder:
2016-05-24 02:06:29 +00:00
2016-11-12 12:54:27 +00:00
~~~ sh
$ ./build.sh
~~~
For more info, have a look at the [Compiling wiki page](https://github.com/jaagr/polybar/wiki/Compiling).
2016-11-12 12:54:27 +00:00
### Configuration
2016-11-19 05:22:44 +00:00
Details on how to setup and configure the bar and each module have been moved to [the wiki](https://github.com/jaagr/polybar/wiki/Configuration).
2017-01-14 12:16:20 +00:00
#### Install the example configuration
Run the following inside the build directory:
~~~ sh
$ make userconfig
~~~
2017-01-14 12:16:20 +00:00
#### Launch the example bar
~~~ sh
2016-11-19 05:22:44 +00:00
$ polybar example
~~~
### Running
2016-11-25 06:32:57 +00:00
[See the wiki for details on how to run polybar](https://github.com/jaagr/polybar/wiki).
2016-06-29 02:44:55 +00:00
2018-05-27 09:11:50 +00:00
## Contributors
### Owner
* Michael Carlberg [**@jaagr**](http://github.com/jaagr/)
2018-05-27 09:11:50 +00:00
### Maintainers
* [**@NBonaparte**](https://github.com/NBonaparte)
* Chase Geigle [**@skystrife**](https://github.com/skystrife)
* Patrick Ziegler [**@patrick96**](https://github.com/patrick96)
### Logo Design by
* [**@Tobaloidee**](https://github.com/Tobaloidee)
### [All Contributors](https://github.com/jaagr/polybar/graphs/contributors)
2016-06-29 02:44:55 +00:00
## License
2016-11-19 05:22:44 +00:00
Polybar is licensed under the MIT license. [See LICENSE for more information](https://github.com/jaagr/polybar/blob/master/LICENSE).