ironbar/README.md

# Ironbar

Ironbar is a customisable and feature-rich bar for wlroots compositors, written in Rust.
It uses GTK3 and gtk-layer-shell.

The bar can be styled to your liking using CSS and hot-loads style changes.
For information and examples on styling please see the [wiki](https://github.com/JakeStanger/ironbar/wiki).

![Screenshot of fully configured bar with MPD widget open](https://f.jstanger.dev/github/ironbar/bar.png?raw)

## Features

- First-class support for Sway and Hyprland, but should (mostly) work on any wlroots compositor.
- Fully themeable with CSS and hot-loaded styles. 
- Support for multiple configuration languages.
- Popups used by widgets to show rich content and controls on click.
- Out of the box widgets which can be used to create anything from a lightweight to a more traditional desktop experience.
- Ability to create custom widgets (including popups), run scripts and inject dynamic content. 

## Installation

### Cargo

Ensure you have the [build dependencies](https://github.com/JakeStanger/ironbar/wiki/compiling#Build-requirements) installed.

```sh
cargo install ironbar
```

[crate](https://crates.io/crates/ironbar)

### Arch Linux

```sh
yay -S ironbar-git
```

[aur package](https://aur.archlinux.org/packages/ironbar-git)

### Nix Flake

A flake is included with the repo which can be used with home-manager.

#### Example

Here is an example nix flake that uses Ironbar.

```nix
{
  # Add the ironbar flake input
  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  inputs.ironbar = {
    url = "github:JakeStanger/ironbar";
    inputs.nixpkgs.follows = "nixpkgs";
  };
  inputs.hm = {
    url = "github:nix-community/home-manager";
    inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = inputs: {
    homeManagerConfigurations."USER@HOSTNAME" = inputs.hm.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [
        # And add the home-manager module
        inputs.ironbar.homeManagerModules.default
        {
          # And configure
          programs.ironbar = {
            enable = true;
            config = {};
            style = "";
            package = inputs.ironbar;
            features = ["feature" "another_feature"];
          };
        }
      ];
    };
  };
}
```

#### Binary Caching

There is a Cachix cache available at `https://app.cachix.org/cache/jakestanger`
in case you don't want to compile Ironbar.

### Source

Ensure you have the [build dependencies](https://github.com/JakeStanger/ironbar/wiki/compiling#Build-requirements) installed.

```sh
git clone https://github.com/jakestanger/ironbar.git
cd ironbar
cargo build --release
# change path to wherever you want to install
install target/release/ironbar ~/.local/bin/ironbar
```

By default, all features are enabled. 
See [here](https://github.com/JakeStanger/ironbar/wiki/compiling#features) for controlling which features are included.

[repo](https://github.com/jakestanger/ironbar)

## Running

All of the above installation methods provide a binary called `ironbar`.

You can set the `IRONBAR_LOG` or `IRONBAR_FILE_LOG` environment variables to 
`error`, `warn`, `info`, `debug` or `trace` to configure the log output level.
These default to `IRONBAR_LOG=info` and `IRONBAR_FILE_LOG=error`.
File output can be found at `~/.local/share/ironbar/error.log`.

## Configuration

Ironbar gives a lot of flexibility when configuring, including multiple file formats
and options for scaling complexity: you can use a single config across all monitors,
or configure different/multiple bars per monitor.

A full configuration guide can be found [here](https://github.com/JakeStanger/ironbar/wiki/configuration-guide).

## Styling

To get started, create a stylesheet at `.config/ironbar/style.css`. Changes will be hot-reloaded every time you save the
file.

A full styling guide can be found [here](https://github.com/JakeStanger/ironbar/wiki/styling-guide).

## Project Status

This project is in alpha, but should be usable.
Everything that is implemented works and should be documented.
Proper error handling is in place so things should either fail gracefully with detail, or not fail at all.

There is currently room for lots more modules, and lots more configuration options for the existing modules.
The current configuration schema is not set in stone and breaking changes could come along at any point;
until the project matures I am more interested in ease of use than backwards compatibility.

A few bugs do exist, and I am sure there are plenty more to be found.

The project will be *actively developed* as I am using it on my daily driver.
Bugs will be fixed, features will be added, code will be refactored.

## Contribution Guidelines

Please check [here](https://github.com/JakeStanger/ironbar/blob/master/CONTRIBUTING.md).

## Acknowledgements

- [Waybar](https://github.com/Alexays/Waybar) - A lot of the initial inspiration, and a pretty great bar.
- [Rustbar](https://github.com/zeroeightysix/rustbar) - Served as a good demo for writing a basic GTK bar in Rust
- [Smithay Client Toolkit](https://github.com/Smithay/client-toolkit) - Essential in being able to communicate to Wayland