Wrap... Inject... Done!

Nix-Wrappers makes wrappers for nix packages that creates a modified environment (see: #Features for specifics).

This can be used as an optimal way to modify the package's environment without:

• mutating the global environment of the user(s) or
• mutating the file system outside the nix-store (/nix/store).

This means there's never:

• dangling files left from old configurations or
• any special linker required to properly symlink files from the nix-store to paths outside the nix-store.

Under nominal conditions, this makes Nix-Wrappers ideal for managing dotfiles and other configurations in most situations. Situations where Nix-Wrappers is not ideal for managing such include packages that:

• do not have an command line flag or environment variable to the configuration path and
• do not respect XDG variables from the XDG Base Directory Specification.

In rare situations like these, we recommend using:

• hjem with their special linker or
• using systemd-tmpfilesd

Features

On a per package basis, Nix-Wrappers can:

• Change the directory of the package's environment.
• Set commands to run immediately after the program's execution as a part of the package environment.
• Prepend and/or append arguments to be ran as a part of the package environment.
• Set environment variables of the package's environment.
• Unset environment variables of the package's environment.
• Add values as prefixes and/or suffixes to the delimited list environment variables of the package's environment.

Getting Started

CLI Tools

Flake (Current recommendation):

In your flake.nix, add the following to inputs, outputs' arguments, and your NixOS configurations' modules.

{
  inputs = {
    # Add `wrappers` to inputs
    wrappers = {
      type = "git";
      url = "https://codeberg.org/midischwarz12/nix-wrappers";
    };
  };
}

Remember to nix flake update wrappers

And then consume it whatever way you see fit whether devShells, packages, etc.

Ad hoc with `nix shell` or `nix run`:

With nix run (which defaults to wrapProgram for usability):

$ nix run 'git+https://codeberg.org/midischwarz12/nix-wrappers' -- <args>

Please see #Usage section for details on command line arguments.

---

With nix shell:

$ nix shell 'git+https://codeberg.org/midischwarz12/nix-wrappers'
$ wrapProgram <exec> -- <args>

Or run with makeWrapper.

Please see #Usage section for details on command line arguments.

NixOS Module

Flake (Current recommendation):

In your flake.nix, add the following to inputs, outputs' arguments, and your NixOS configurations' modules.

{
  inputs = {
    # Add `wrappers` to inputs
    wrappers = {
      type = "git";
      url = "https://codeberg.org/midischwarz12/nix-wrappers";
    };
  };

  outputs =
    {
      # Add `wrappers` to outputs' arguments
      wrappers,
      ...
    }: {
      nixosConfigurations.foo = lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          # Add `wrappers` to list of modules
          wrappers.nixosModules.default
        ];
      };
    }
}

Remember to nix flake update wrappers

niv

Planned and coming soonTM

npins

Planned and coming soonTM

nix-channel

Planned and coming soonTM

fetchTarball

Planned and coming soonTM

Usage

CLI Tools

makeWrapper

$ makeWrapper <exec> <out-path> <args>

Where args are:

• --argv0 <name> set the name of the executed process to (if unset or empty, defaults to EXECUTABLE)

• --inherit-argv0 the executable inherits argv0 from the wrapper. (use instead of --argv0 '$0')

• --resolve-argv0 if argv0 doesn't include a / character, resolve it against PATH

• --set <var> <val> add with value to the executable's environment

• --set-default <var> <val> like --set, but only adds if not already set in the environment

• --unset <var> remove from the environment

• --chdir <dir> change working directory (use instead of --run "cd

  ")

• --run <command> run command before the executable

• --add-flag <arg> prepend the single argument to the invocation of the executable (that is, before any arguments passed on the command line)

• --append-flag <arg> append the single argument to the invocation of the executable (that is, after any arguments passed on the command line)

• --add-flags <args> prepend verbatim to the Bash-interpreted invocation of the executable

• --append-flags <args> append verbatim to the Bash-interpreted invocation of the executable

• --prefix <env> <sep> <val> suffix/prefix with separated by

• --suffix

• --prefix-each <env> <sep> <vals> like --prefix, but is a list

• --suffix-each <env> <sep> <vals> like --suffix, but is a list

• --prefix-contents <env> <sep> <files> like --suffix-each, but contents of are read first and used as

• --suffix-contents

wrapProgram

$ wrapProgram <exec> <args>

Where args are:

• --set <var> <val> add with value to the executable's environment

• --set-default <var> <val> like --set, but only adds if not already set in the environment

• --unset <var> remove from the environment

• --chdir <dir> change working directory (use instead of --run "cd

  ")

• --run <command> run command before the executable

• --add-flag <arg> prepend the single argument to the invocation of the executable (that is, before any arguments passed on the command line)

• --append-flag <arg> append the single argument to the invocation of the executable (that is, after any arguments passed on the command line)

• --add-flags <args> prepend verbatim to the Bash-interpreted invocation of the executable

• --append-flags <args> append verbatim to the Bash-interpreted invocation of the executable

• --prefix <env> <sep> <val> suffix/prefix with separated by

• --suffix

• --prefix-each <env> <sep> <vals> like --prefix, but is a list

• --suffix-each <env> <sep> <vals> like --suffix, but is a list

• --prefix-contents <env> <sep> <files> like --suffix-each, but contents of are read first and used as

• --suffix-contents

NixOS Module

In your NixOS configuration, add the following:

{
  wrappers = {
    # Creates a wrapper around the `foo` package
    foo = {
      # Specifically, wrap the binary `foo` inside package `foo`
      executables.foo = {
        # Set an environment variable in the wrapper
        environment."FOO_CONFIG".value = self + "/path/to/foo/config.toml";
      };
    };

    # Creates a wrapper around the `bar` package
    bar = {
      # Specifically, wrap the binary `bar` inside package `bar`
      executables.bar = {
        # Set an argument to be ran with the command
        args.suffix = [ "--config ${self + "/path/to/bar/config.json"}" ];
      };
    };
  };
}

Then the wrappers can be consumed by config.wrappers.foo.finalPackage and config.wrappers.bar.finalPackage respectively.

For example, to use in a .package option assuming programs.foo exists:

{
  programs.foo = {
    enable = true;
    package = config.wrappers.foo.finalPackage;
  };
}

Or to add a wrapper to a package list:

  environment.systemPackages = [
    config.wrappers.bar.finalPackage
  ];
}

Full documentation will be generated for all the available options soonTM.

Roadmap

• Thorough documentation with examples
• More installation methods
• Nix function for return wrappers