ref / doc

overlaysPackagesBuilder.nix

@@ -1,8 +1,46 @@
 { flake-utils-plus }: let
 
- builtinPackagesBuilder = pkgs: channels:
+ overlaysPackagesBuilder = pkgs: channels:
+  /**
+  Synopsis: overlaysPackagesBuilder _pkgs_ _channels_
+
+  pkgs:     pkgs.<system>.<tree>
+  channels: channels.<name>.overlays
+
+  Returns valid packges that have been defined within an overlay so they
+  can be shared via self.packages with the world. This is especially useful
+  over sharing one's art via self.overlays in case you have a binary cache
+  running from which third parties could benefit.
+
+  First, flattens an arbitrarily nested _pkgs_ tree for each system into a flat
+  key in which nesting is aproximated by a "/" (e.g. "development/kakoune").
+  Also filter the resulting packages for attributes that _trivially_ would
+  fail flake checks (broken, system not supported or not a derivation).
+
+  Second, collects all overlays' packages' keys of all channels into a flat list.
+
+  Finally, only passes packages through the seive that are prefixed with a top level
+  key exposed by any of the overlays. Since overlays override (and do not emrge)
+  top level attributes, by filtering on the prefix, an overlay's entire packages
+  tree will be correctly captured.
+
+  Example:
+
+  pkgs'.<system> = {
+    "development/kakoune" = { ... };
+    "development/vim" = { ... };
+  };
+
+  overlays' = [
+    "development"
+  ];
+
+  overlays' will pass both pkgs' through the sieve.
+
+  **/
   let
 
+    # first, flatten and filter on valid packages (by nix flake check criterion)
     pkgs' =
       let
 
@@ -17,7 +55,7 @@
       in
       flattenTreeFilterSystem pkgs;
 
-
+    # second, flatten all overlays' packages' keys into a single list
     overlays' = channels:
       let
 
@@ -30,17 +68,20 @@
           in
             mapAttrs f overlay;
 
-       allOverlays =
-         let
-            f = _: channel:
-              concatMap (o: overlayNamesList o) channel.overlays;
+        overlays = map (c: c.overlays) (attrValues channels);
+
+        flattendOverlaysNames =
+          let
+            f = _: overlays:
+              concatMap (o: overlayNamesList o) overlays;
           in
-            concatMap f (attrValues channels);
+            concatMap f overlays;
 
       in
-        allOverlays;
+        flattendOverlaysNames;
 
   in
+    # finally, only retain those packages defined by overlays
     let
 
       nameValuePair = name: value: { inherit name value; };
@@ -53,11 +94,13 @@
         str: builtins.substring 0 (builtins.stringLength pref) str == pref;
 
     in
+    # pkgs'.<system>.<prefix/flattend/tree/attributes>
+    # overlays' = [ "prefix" ... ];
     builtins.mapAttrs (_: pkgs:
-      filterAttrs (v:
-        builtins.any (o: builtins.hasPrefix v o) overlays'
+      filterAttrs (name:
+        builtins.any (ovrl: builtins.hasPrefix name ovrl) overlays'
       ) pkgs
     ) pkgs';
 
 in
-builtinPackagesBuilder
+overlaysPackagesBuilder