search

viperML / wrapper-manager

Post-modern configuration management
https://viperml.github.io/wrapper-manager/
European Union Public License 1.2
235 stars 4 forks source link
nix nixos

readme

wrapper-manager

Post-modern configuration management

wrapped nixos logo 

{pkgs, ...}: {
  # Build a custom nushell wrapper
  # that self-bundles its configuration and dependencies
  # ~/.config/nushell is not neeeded!
  wrappers.nushell = {
    basePackage = pkgs.nushell;
    flags = [
      "--env-config"
      ./env.nu
      "--config"
      ./config.nu
    ];
    env.STARSHIP_CONFIG.value = ../starship.toml;
    pathAdd = [
      pkgs.starship
      pkgs.carapace
    ];
  };
}

Result (nushell executable):

#! /nix/store/51sszqz1d9kpx480scb1vllc00kxlx79-bash-5.2-p15/bin/bash -e
export STARSHIP_CONFIG=${STARSHIP_CONFIG-'/nix/store/9gyqz7x765dgh6jvjgnsmiq1zp8lm2y8-starship.toml'}
PATH=${PATH:+':'$PATH':'}
PATH=${PATH/':''/nix/store/11hrc3lnzp8jyb3afmmy9h4m4c30jkgs-starship-1.15.0/bin'':'/':'}
PATH='/nix/store/11hrc3lnzp8jyb3afmmy9h4m4c30jkgs-starship-1.15.0/bin'$PATH
PATH=${PATH#':'}
PATH=${PATH%':'}
export PATH
PATH=${PATH:+':'$PATH':'}
PATH=${PATH/':''/nix/store/vzvxm72pj68fc0120fw1k67b73iaf6g9-carapace-0.25.1/bin'':'/':'}
PATH='/nix/store/vzvxm72pj68fc0120fw1k67b73iaf6g9-carapace-0.25.1/bin'$PATH
PATH=${PATH#':'}
PATH=${PATH%':'}
export PATH
exec -a "$0" "/nix/store/k57j42qv2p1msgf9djsrzssnixlblw9v-nushell-0.82.0/bin/.nu-wrapped"  --env-config /nix/store/zx7cc0fmr3gsbxfvdri8b1pnybsh8hd9-env.nu --config /nix/store/n4mdvfbcc81i9bhrakw7r6wnk4nygbdl-config.nu "$@"

Wrapper-manager is a Nix library that allows you to configure your favorite applications without adding files into ~/.config. This is done by creating wrapper scripts that set the appropriate environment variables, like PATH, or pass extra flags to the wrapped program.

Nix offers very good reliability and reproducibility thanks to its read-only store. However, putting symlinks to it in your $HOME starts breaking this property. Because any program can tamper files in ~, the stability of your system is a bit more fragile.

Wrapper-manager leverages the nixpkgs' functions wrapProgram and symlinkJoin to create wrappers around your applications, providing an easy-to use interface, and also getting around some of their shortcomings.

Module documentation

https://viperml.github.io/wrapper-manager/docs/module

Installation/usage

First, you need to instantiate wrapper-manager's lib. This can be done by pulling the WM flake, or by pulling the repo tarball directly.

Flake

# flake.nix
{
  inputs = {
    nixpkgs.url = "...";

    # Add the wrapper-manager flake
    wrapper-manager = {
      url = "github:viperML/wrapper-manager";
      # WM's nixpkgs is only used for tests, you can safely drop this if needed.
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = {self, nixpkgs, wrapper-manager}: { ... };
}

Classic

Wrapper-manager can be pulled in a classic (non-flake) setup for a dev-shell or NixOS configuration, like so:

# shell.nix
let
  pkgs = import <nixpkgs> {};
  # optionally, pin a commit instead of using master
  wrapper-manager = import (builtins.fetchTarball "https://github.com/viperML/wrapper-manager/archive/refs/heads/master.tar.gz") {
    inherit (pkgs) lib;
  };
in
  mkShell { ..... }
# configuration.nix
{ config, pkgs, lib, ... }: let
  # optionally, pin a commit instead of using master
  wrapper-manager = import (builtins.fetchTarball "https://github.com/viperML/wrapper-manager/archive/refs/heads/master.tar.gz") {
    inherit (pkgs) lib;
  };
in {
    .....
}

Evaluating

Now that you already have wrapper-manager in scope, you need to evaluate wrapper-manager.lib. The argument is an attrset with following elements:

A convenience shorthand for (wrapper-manager.lib {...}).config.build.toplevel is available through: wrapper-manager.lib.build {}, which is probably what you want in 99% of the cases.

# This expression outputs a package, which collects all wrappers.
# You can add it to:
# - environment.systemPackages
# - home.packages
# - mkShell { packages = [...]; }
# - etc

(wrapper-manager.lib.build {
  inherit pkgs;
  modules = [
    ./my-module.nix
    {
      wrappers.foo = { ... };
    }
  ];
})
# => «derivation /nix/store/...»

For example, if you want to use wrapper-manager in the context of a dev-shell, you can instantiate it directly like so:

# pkgs and wrapper-manager in scope, see previous steps
# ...
mkShell {
  packages = [

    (wrapper-manager.lib.build {
      inherit pkgs;
      modules = [{
        wrappers.stack = {
          basePackage = pkgs.stack;
          flags = [
            "--resolver"
            "lts"
          ];
          env.NO_COLOR.value = "1";
        };
      }];
    })

  ];
}

Configuration examples

These are some examples of wrapper-manager used in the wild. Feel free to PR yours.

To-do's

https://github.com/viperML/wrapper-manager/issues

Changelog