move lib.nix to default.nix, update docs

viperML · Nov 8, 2023 · e3720cf · e3720cf
1 parent 2ce0163
commit e3720cf
Show file tree

Hide file tree

Showing 3 changed files with 118 additions and 73 deletions.
diff --git a/lib.nix → default.nix b/lib.nix → default.nix
@@ -13,7 +13,9 @@
       specialArgs = {inherit pkgs;} // specialArgs;
     };
 in {
-  __functor = _: eval;
-
-  build = args: (eval args).config.build.toplevel;
+  lib = {
+    inherit eval;
+    __functor = _: eval;
+    build = args: (eval args).config.build.toplevel;
+  };
 }
diff --git a/doc/content/_index.md b/doc/content/_index.md
@@ -79,19 +79,22 @@ around some of their shortcomings.
 https://viperml.github.io/wrapper-manager/docs/module
 
 
+## **Installation/usage**
 
-## **Installation**
+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.
 
-First, bring wrapper-manager as a flake input:
+### Flake
 
 ```nix
 # 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";
     };
   };
@@ -100,36 +103,74 @@ First, bring wrapper-manager as a flake input:
 }
 ```
 
-The `lib` output is a function that evaluates the module:
+### Classic
+
+Wrapper-manager can be pulled in a classic (non-flake) setup for a devshell or nixos configuration, like so:
 
 ```nix
-wrapper-manager.lib {
-  inherit pkgs;
-  modules = [
-    ./my-module.nix
-  ];
-}
+# shell.nix , or configuration.nix
+
+# or {pkgs, config, ...}: if you are in NixOS...
+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
+  ...
 ```
 
-As a shorthand for `(wrapper-manager.lib { ... }).config.build.toplevel`, you can use `wrapper-manager.lib.build` instead.
+### 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:
 
-### Standalone application
+- `pkgs`: your nixpkgs instance used to bring `symlinkJoin` and `makeWrapper`, as well as passing it through the modules for convenience.
+- `modules`: a list of wrapper-manager modules. As with NixOS, a module can be passed as a path to a module or directly. A proper module is either an attset, or a function to attrset.
+- `specialArgs`: extra arguments passed to the module system.
 
-Wrapper-manager can be evaluated in any context that accepts a package, like in
-`environment.systemPackages`, `users.users.my-user.packages`, `home.packages`, etc.
+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.
 
+```nix
+# 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 devshell, you can instatiate it directly like so:
 ```nix
-# configuration.nix
-{config, pkgs, ...}: {
-  users.users.my-user.packages = [
+# pkgs and wrapper-manager in scope, see previous steps
+# ...
+mkShell {
+  packages = [
 
     (wrapper-manager.lib.build {
       inherit pkgs;
-      modules = [
-        ./my-module.nix
-      ];
+      modules = [{
+        wrappers.stack = {
+          basePackage = pkgs.stack;
+          flags = [
+            "--resolver"
+            "lts"
+          ];
+          env.NO_COLOR.value = "1";
+        };
+      }];
     })
 
   ];

diff --git a/flake.nix b/flake.nix
@@ -25,60 +25,62 @@
         inherit pkgs;
         optionsCommonMark = self.legacyPackages.${pkgs.system}.optionsCommonMark;
       });
-  in {
-    lib = import ./lib.nix {
-      inherit (nixpkgs) lib;
-    };
-
-    formatter = forAllSystems (pkgs: pkgs.alejandra);
+  in
+    (
+      import ./default.nix {
+        inherit (nixpkgs) lib;
+      }
+    )
+    // {
+      formatter = forAllSystems (pkgs: pkgs.alejandra);
 
-    checks = forAllSystems (pkgs:
-      (self.lib {
-        inherit pkgs;
-        modules = [./tests/test-module.nix];
-        specialArgs = {
-          some-special-arg = "foo";
-        };
-      })
-      .config
-      .build
-      .packages);
+      checks = forAllSystems (pkgs:
+        (self.lib {
+          inherit pkgs;
+          modules = [./tests/test-module.nix];
+          specialArgs = {
+            some-special-arg = "foo";
+          };
+        })
+        .config
+        .build
+        .packages);
 
-    packages = forAllSystems (pkgs: doc.${pkgs.system}.packages);
+      packages = forAllSystems (pkgs: doc.${pkgs.system}.packages);
 
-    devShells = forAllSystems (pkgs: doc.${pkgs.system}.devShells);
+      devShells = forAllSystems (pkgs: doc.${pkgs.system}.devShells);
 
-    legacyPackages = forAllSystems (
-      pkgs:
-        pkgs.nixosOptionsDoc {
-          options =
-            (self.lib {
-              inherit pkgs;
-              modules = [
-                {
-                  options._module.args = pkgs.lib.mkOption {internal = true;};
-                }
-              ];
-            })
-            .options;
-          transformOptions = opt:
-            opt
-            // {
-              declarations = with pkgs.lib;
-                map
-                (decl:
-                  if hasPrefix (toString ./.) (toString decl)
-                  then let
-                    rev = self.rev or "master";
-                    subpath = removePrefix "/" (removePrefix (toString ./.) (toString decl));
-                  in {
-                    url = "https://github.com/viperML/wrapper-manager/blob/${rev}/${subpath}";
-                    name = subpath;
+      legacyPackages = forAllSystems (
+        pkgs:
+          pkgs.nixosOptionsDoc {
+            options =
+              (self.lib {
+                inherit pkgs;
+                modules = [
+                  {
+                    options._module.args = pkgs.lib.mkOption {internal = true;};
                   }
-                  else decl)
-                opt.declarations;
-            };
-        }
-    );
-  };
+                ];
+              })
+              .options;
+            transformOptions = opt:
+              opt
+              // {
+                declarations = with pkgs.lib;
+                  map
+                  (decl:
+                    if hasPrefix (toString ./.) (toString decl)
+                    then let
+                      rev = self.rev or "master";
+                      subpath = removePrefix "/" (removePrefix (toString ./.) (toString decl));
+                    in {
+                      url = "https://github.com/viperML/wrapper-manager/blob/${rev}/${subpath}";
+                      name = subpath;
+                    }
+                    else decl)
+                  opt.declarations;
+              };
+          }
+      );
+    };
 }