Project overview

Channels

You can install wrapper-manager-fds with Nix channels.

nix-channel --add https://github.com/foo-dogsquared/nix-module-wrapper-manager-fds/archive/master.tar.gz wrapper-manager-fds
nix-channel --update

Then in your environment configuration, you’ll have to import the user entrypoint. For more details, see User entrypoint.

Pinning tool

A recommended (non-flakes) way to install Nix dependencies is to use a pinning tool. There are a handful of pinning tool out there but in this case, we’ll use npins as our tool of choice. Assuming you have already initialized npins, you can simply add wrapper-manager-fds to your Nix project with the following command.

npins add --name wrapper-manager github foo-dogsquared nix-module-wrapper-manager-fds --at 0.1.0

Similar to channels installation, you’ll have to import the User entrypoint object.

Manual pinning

Though not recommended, you could manually pin the Nix library yourself and then import the user entrypoint like in the following code.

{ pkgs, ... }:

let
  wrapper-manager-fds-src = builtins.fetchTarball "https://github.com/foo-dogsquared/nix-module-wrapper-manager-fds/archive/0.1.0.tar.gz";
  wrapper-manager = import wrapper-manager-fds-src { };
  wrapperManagerLib = import wrapper-manager.wrapperManagerLib { inherit pkgs; }
in
wrapperManagerLib.env.build { }

Flakes

This project also has a flake object. In your flake definition, just import it as one of the inputs. Unlike the other methods, the flake output is the user entrypoint so no need to import it or anything.

{
  inputs.wrapper-manager-fds.url = "github:foo-dogsquared/nix-module-wrapper-manager-fds/0.1.0";

  outputs = { nixpkgs, ... }@inputs: {
    nixosConfigurations.desktop = nixpkgs.lib.nixosSystem {
      modules = [
        ./hosts/desktop.nix
        inputs.wrapper-manager-fds.nixosModules.default
      ];
    };
  };
}

User entrypoint

Most of the things you need from the project are all retrieveable from the entrypoint of this project (default.nix in project root) which is an attribute set closely structured from a typical Nix flake that you see. For example, if you want the NixOS module for wrapper-manager, you could refer to nixosModules.default. Here’s the breakdown of the attrset entries in the entrypoint.

The module environment

One part of the project is the module environment. Just like home-manager and disko and the original source, wrapper-manager-fds comes with its own module environment. Instead of a home environment from home-manager, an entire operating system from NixOS, or an installation script from disko, wrapper-manager-fds module environment evaluates to a package similar to how certain environments treats them (e.g., environment.systemPackages for NixOS, home.packages for home-manager).

Much of the module environment relies on makeWrapper. In fact, this can be thought of as a declarative layer over makeWrapper with some other integrations.

If you want to view the module options, you can see it in wrapper-manager module options.

Here’s a very simple example of a wrapper for Neofetch.

{ lib, pkgs, ... }:

{
  wrappers.neofetch = {
    arg0 = lib.getExe' pkgs.neofetch "neofetch";
    appendArgs = [
      "--ascii_distro" "guix"
      "--title_fqdn" "off"
      "--os_arch" "off"
    ];
  };
}

Or if you want fastfetch…​

{ lib, pkgs, ... }:

{
  wrappers.fastfetch = {
    arg0 = lib.getExe' pkgs.fastfetch "fastfetch";
    appendArgs = [ "--logo" "Guix" ];
    env.NO_COLOR.value = "1";
  };
}

Or even both in the same configuration (which you can do). If evaluated, this should result in a single derivation that contains two executables in $out/bin/{fastfetch, neofetch}.

{
  imports = [
    ./fastfetch.nix
    ./neofetch.nix
  ];
}

You could even create XDG desktop entry files useful for the application to be launched through an application launcher/menu. For example, you could create an executable and a desktop entry to launch a custom Firefox profile in your home-manager configuration.

{ config, lib, pkgs, ... }:

{
  programs.firefox.profiles.custom-profile = {
    # Put some profile-specific settings here.
  };

  wrapper-manager.packages.browsers = {
    wrappers.firefox-custom-profile = {
      arg0 = lib.getExe' config.programs.firefox.package "firefox";
      prependArgs = [
        "-P" "custom-profile"
      ];
      xdg.desktopEntry = {
        enable = true;
        settings = {
          desktopName = "Firefox (custom-profile)";
          startupNotify = true;
          startupWMClass = "firefox";
          icon = "firefox";
          mimeTypes = [
            "text/html"
            "application/xhtml+xml"
            "application/vnd.mozilla.xul+xml"
            "x-scheme-handler/http"
            "x-scheme-handler/https"
          ];
        };
      };
    };
  };
}

As a library

wrapper-manager also comes with a library set which you can use to evaluate and build wrapper-manager packages yourself. This is found in the wrapperManagerLib attribute from the user entrypoint where it needs an attribute set containing a nixpkgs instance in pkgs.

{ pkgs }:

let
  wrapper-manager = import (builtins.fetchgit { }) { };

  wmLib = import wrapper-manager.wrapperManagerLib { inherit pkgs; };
in
wmLib.env.build {
  inherit pkgs;
  modules = [ ./fastfetch.nix ];
  specialArgs.yourMomName = "Joe Mama";
}

Here’s a quick rundown of what you can do with the library.

There is also lib attribute if all you want to do is to build and/or evaluate a wrapper-manager configuration. It only contains the function from env subset which contains build and eval.

As a composable module

The most user-friendly way of using wrapper-manager would be as a composable nixpkgs module of an existing environment. wrapper-manager provides a Nix module specifically for NixOS and home-manager environment. ^[2] You can import them through the {nixos,home}Modules.default from the user entrypoint of the project.

You can view the module options for each environment.

Most of the things set up here are implemented to make declaring wrappers ergonomic with the environment. For a start, wrapper-manager-fds sets up a module namespace in wrapper-manager. Here’s a quick breakdown of the features that the module has.

Here’s an example of adding wrappers through wrapper-manager inside of a home-manager configuration. The following configuration will create a wrapped package for yt-dlp with an additional wrapper script named yt-dlp-audio and yt-dlp-video.

{ config, lib, pkgs, ... }:

{
  home.packages = with pkgs; [
    flowtime
    blanket
  ];

  wrapper-manager.packages = {
    music-setup = {
      basePackages = [ pkgs.yt-dlp ];
      wrappers.yt-dlp-audio = {
        arg0 = lib.getExe' pkgs.yt-dlp "yt-dlp";
        prependArgs = [
          "--config-location" ./config/yt-dlp/audio.conf
        ];
      };
      wrappers.yt-dlp-video = {
        arg0 = lib.getExe' pkgs.yt-dlp "yt-dlp";
        prependArgs = [
          "--config-location" ./config/yt-dlp/video.conf
        ];
      };
    };
  };
}

Library set and modules

This Nix project has a test infrastructure set up at test directory covering the library set and the wrapper-manager module environment. For its library set, it makes use of the nixpkgs library and a JSON schema to validate if it passes the whole test suite. To make use of it, just run the following commands.

There is also a test suite for different types of wrapper-manager configurations at test directory from the source code. You can check them the same way as before (e.g., it’s the same for flake-using contributors, nix-build tests/ -A configs for non-flake-using contributors).

The derivation output should be successfully built if all of the tests in the suite passes. Otherwise, it should fail and you’ll have to see the build log containing all of the tests that failed.

On another note, there is a quicker way of checking the test suite with nix eval -f tests lib (or nix-instantiate --eval --strict tests/ -A lib) where it contains the raw test data which is useful if you don’t want to essentially build a new derivation each time. It is also quicker to eyeball results in this way especially if you’re always working with the tests anyways.

Website

This project also has a website set up with Hugo. The files that you need to see are in docs/website directory.

There is also a dedicated development environment placed in docs/website/shell.nix but this should be a part of the primary development environment already. You can enter it with nix develop .#devPackages.${SYSTEM}.website or nix-shell docs/website.

Just take note that the website also requires the NixOS options which comes in a JSON file. This should be already taken care of in the package definition of the website but otherwise it is something that you’ll have to be aware of.

The more important task to developing this part of the project is continuously getting feedback from it. You can do so simply with the following commands:

Nix environment

As for developing the environment with Nix itself, it is very much preferred to make wrapper-manager-fds work with non-flake setups. This also includes the workflow of the development itself for the purpose of easier time bootstrapping wrapper-manager-fds.

Due to the unfortunate situation with flakes as an experimental feature, it is more like a second-class citizen in terms of support. This is because it is pretty easy to make a flake with non-flake tools compared to vice versa. ^[3]

Here’s an exhaustive guidelines that you have to keep in mind when developing related files within the project: