polybar/README.md

134 lines
4.9 KiB
Markdown
Raw Normal View History

2016-11-19 05:22:44 +00:00
# Polybar
2016-11-19 05:31:59 +00:00
:star: **Previously called Lemonbuddy**
2016-05-19 14:41:06 +00:00
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)
[![MIT License](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000?style=plastic)](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.
Heres a few screenshots showing you what it can look like:
[![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)
Please note that the project still is in early development, so please report any
2016-11-19 05:22:44 +00:00
problems by [creating an issue ticket](https://github.com/jaagr/polybar/issues/new).
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)
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.
It has built-in functionality to generate content for the most commonly used widgets, such as:
2016-06-29 02:44:55 +00:00
- 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)
- 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
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. If you are using **Void Linux**
you can install the package [polybar](https://github.com/voidlinux/void-packages/blob/master/srcpkgs/polybar/template) available in the official xbps repository.
2016-11-12 12:54:27 +00:00
If you create a package for any other distribution, please consider contributing the template.
2016-06-23 23:14:43 +00:00
2016-06-29 02:44:55 +00:00
### Dependencies
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
- boost
2016-10-12 05:42:22 +00:00
- xcb-util-wm
- xcb-util-image
- libXft
- python2
2016-06-23 23:14:43 +00:00
2016-06-29 02:44:55 +00:00
Optional dependencies for module support:
2016-06-23 23:14:43 +00:00
- jsoncpp (required by `internal/i3`)
- Because some distributions only offer pre-historic releases of jsoncpp,
a local copy of the library source (jsoncpp-1.7.7) will be built and linked
statically as a fallback if a valid version is not found.
- wireless_tools (required by `internal/network`)
- alsa-lib (required by `internal/volume`)
- libmpdclient (required by `internal/mpd`)
2016-06-23 23:14:43 +00:00
~~~ sh
$ pacman -S cmake python2 boost xcb-util-image xcb-util-wm libxft wireless_tools alsa-lib libmpdclient
$ apt-get install cmake cmake-data libboost-dev libfreetype6-dev libxcb1-dev libx11-xcb-dev libxcb-util0-dev libxcb-image0-dev libxcb-randr0-dev libxcb-ewmh-dev libxcb-icccm4-dev xcb-proto python-xcbgen i3-wm libiw-dev libasound2-dev libmpdclient-dev
~~~
2016-06-29 02:44:55 +00:00
### Building from source
2016-05-24 02:06:29 +00:00
2016-11-19 05:22:44 +00:00
Please [report any problems](https://github.com/jaagr/polybar/issues/new) you run into when building the project.
2016-06-29 02:44:55 +00:00
~~~ sh
2016-11-19 05:50:42 +00:00
$ git clone --branch 2.3.0 --recursive https://github.com/jaagr/polybar
2016-11-19 05:22:44 +00:00
$ mkdir polybar/build
$ cd polybar/build
2016-10-25 19:07:58 +00:00
$ cmake -DCMAKE_BUILD_TYPE=Release ..
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
~~~
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).
2016-11-12 12:54:27 +00:00
~~~ sh
# Install the example configuration
$ make userconfig
# Launch the example bar
2016-11-19 05:22:44 +00:00
$ polybar example
~~~
**NOTE:** If the bar output looks odd, it's probably because you're
2016-11-18 02:06:32 +00:00
missing the fonts defined in the config. Update the config or install the
missing fonts.
2016-06-20 15:05:23 +00:00
### Running
2016-11-19 05:22:44 +00:00
See the wiki page on [how to launch the bar when starting your WM](https://github.com/jaagr/polybar/wiki/Running-the-app).
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).