Installation

oxbow may be installed with opam, or via Nix/NixOS using flakes.

Attention

oxbow requires river 0.4.6 or later. See Configure River to install and configure river.

Opam

oxbow is packaged in opam’s repository, making it easy to install on many systems.

Setup

Install opam and the necessary dependencies:

sudo pacman -S base-devel git rsync opam libxkbcommon

sudo dnf install gcc make patch pkg-config git rsync opam libxkbcommon-devel

sudo apt install build-essential pkg-config git rsync opam libxkbcommon-dev

sudo zypper install gcc make patch pkg-config git rsync opam libxkbcommon-devel

sudo xbps-install -S base-devel git rsync opam libxkbcommon-devel

Once opam is installed run

opam init
eval $(opam env)

Note

opam init asks to add a hook to your shell configuration. If you answer yes, the hook adds packages installed through opam to your shell’s PATH. Without it, you must run eval $(opam env) in every new shell.

Install

opam install oxbow

Shell completion

oxbow provides completion scripts for oxbow and oxctl, with support for bash and zsh.

Add the following to your shell configuration:

# ~/.bashrc
source "$(opam var share)/bash-completion/completions/oxctl"
source "$(opam var share)/bash-completion/completions/oxbow"

# ~/.zshrc, before compinit
fpath+=("$(opam var share)/zsh/site-functions")

Nix/NixOS

You can install oxbow with or without flakes.

Add oxbow as a flake input, then put the package in environment.systemPackages:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    oxbow = {
      url = "github:3L0C/oxbow";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, oxbow, ... }: {
    nixosConfigurations.CHANGEME = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [({ pkgs, ... }: {
        nixpkgs.overlays = [ oxbow.overlays.default ];
        environment.systemPackages = [ pkgs.oxbow ];
      })];
    };
  };
}

Attention

Replace CHANGEME with your system’s hostname.

Attention

The rest of the instructions assume your config contains nixpkgs.overlays = [ oxbow.overlays.default ]. This overlay adds oxbow as a package to pkgs. If you’d rather not add this overlay, you can use the following in place of pkgs.oxbow:

oxbow.packages.${pkgs.stdenv.hostPlatform.system}.default

You may need to use specialArgs to pass either inputs or oxbow to additional modules.

Use standalone Home Manager for a declarative install on a distribution other than NixOS. Add oxbow as a flake input, then put the package in home.packages:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    oxbow = {
      url = "github:3L0C/oxbow";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, home-manager, oxbow, ... }: {
    homeConfigurations.CHANGEME = home-manager.lib.homeManagerConfiguration {
      pkgs = import nixpkgs {
        system = "x86_64-linux";
        overlays = [ oxbow.overlays.default ];
      };
      modules = [({ pkgs, ... }: {
        home.packages = [ pkgs.oxbow ];
      })];
    };
  };
}

Attention

Replace CHANGEME with your username.

Attention

The rest of the instructions assume your config contains the pkgs overlay shown above. This overlay adds oxbow as a package to pkgs. If you’d rather not add this overlay, you can use the following in place of pkgs.oxbow:

oxbow.packages.${pkgs.stdenv.hostPlatform.system}.default

You may need to use extraSpecialArgs to pass either inputs or oxbow to additional modules.

{pkgs, ...}: let
  version = "0.1.1";

  oxbow-src = builtins.fetchTarball {
    url = "https://github.com/3L0C/oxbow/archive/refs/tags/v${version}.tar.gz";
    sha256 = "18f239rd7pw6x96wgvv8iwrwj3g556612r0s3zlbr2garvghi5iv";
  };
in {
  nixpkgs.overlays = [ (import "${oxbow-src}/nix/overlay.nix") ];
  environment.systemPackages = [ pkgs.oxbow ];
}

Attention

To upgrade, change to the desired version. Replace sha256 with pkgs.lib.fakeHash. Build the configuration once, and replace pkgs.lib.fakeHash with the expected value.

Note

Replace environment.systemPackages with home.packages for a Home Manager configuration.

For an imperative install into your user profile:

nix profile install github:3L0C/oxbow

To upgrade later:

nix profile upgrade oxbow

To try oxbow in a temporary shell without an install:

nix shell github:3L0C/oxbow

Shell completion

Make sure programs.bash.completion.enable/programs.zsh.enableCompletion are set to true.

Make sure programs.bash.enableCompletion/programs.zsh.enableCompletion are set to true.

Make sure programs.bash.enableCompletion/programs.zsh.enableCompletion are set to true.

For bash, make sure ~/.nix-profile/share is in $XDG_DATA_DIRS:

echo $XDG_DATA_DIRS | tr : '\n' | grep nix-profile

For zsh, add the following line before compinit:

fpath+=(~/.nix-profile/share/zsh/site-functions)