xbar Deployment and Usage Guide

Prerequisites

macOS - xbar requires macOS Catalina or newer (>= 10.15)
Go - Required for building from source (version 1.16 or later)
Wails - Required for building the desktop application (version 2.x)

Installation

Option 1: Download Pre-built Binary

Visit the xbar releases page
Download the latest .dmg file for macOS
Open the .dmg and drag the xbar app to your Applications folder
Launch xbar from your Applications folder

Option 2: Build from Source

# Clone the repository
git clone https://github.com/matryer/xbar.git
cd xbar

# Build the application
go build -o xbar ./app

# Run the application
./xbar

Configuration

Plugin Directory

xbar uses a specific directory for plugins:

~/Library/Application Support/xbar/plugins

This is where all your plugins will be stored
If you're transitioning from Bitbar, move your plugins into this new folder

Cache Directory

xbar stores cache files at:

~/Library/Application Support/xbar/cache

Configuration File

xbar uses a JSON configuration file:

~/Library/Application Support/xbar/xbar.config.json

Build & Run

Development Build

# Install Wails dependencies
go install github.com/wailsapp/wails/v2/cmd/wails@latest

# Build for development
wails build -d

# Run in development mode
wails dev

Production Build

# Build for production
wails build

# Run the built application
./xbar

Plugin Development

To create your own plugins, refer to the Writing plugins guide.

Deployment

xbar is a desktop application for macOS, so deployment involves:

Distribution: Package the built application using standard macOS distribution methods
Updates: xbar includes built-in update functionality
Plugin Management: Users can install plugins through the Preferences > Plugins menu

For distributing to other users:

Use the pre-built .dmg file from releases
Or build your own distribution package using standard macOS packaging tools

Troubleshooting

Common Issues

Plugin Not Showing in Menu Bar

Verify the plugin file is executable (chmod +x plugin.sh)
Check that the plugin is in the correct directory: ~/Library/Application Support/xbar/plugins
Ensure the plugin has the correct file extension (.sh, .py, .js, etc.)

Plugin Not Updating

Check the refresh interval in the plugin's metadata
Verify the plugin is not timing out (default timeout is 30 seconds)
Check for errors in the plugin's output

Application Won't Launch

Ensure you're on macOS Catalina or newer (>= 10.15)
Check if there are any permission issues with the application
Verify the cache directory exists and is writable

Plugin Dependencies Missing

Install any required dependencies listed in the plugin's metadata
Check the plugin's documentation for specific requirements

Debug Mode

Enable verbose output to help diagnose issues:

Open xbar Preferences
Enable "Verbose output" in the settings
Check the console output for detailed error messages

Plugin Development Issues

Use the built-in plugin editor to test changes
Check the plugin's stdout and stderr output
Verify the plugin's syntax and permissions

For additional help, visit the xbar website or check the plugin repository.

How to Deploy & Use matryer/bitbar