lib.cleanSourceWith: Allow name to be set, optional filter, doc

This change is API-compatible and hash-compatible with the previous
version.

At first I considered to write a rename function too, but adding
it name to cleanSourceWith was a no-brainer for ease of use. It
turns out that a rename function isn't any more useful than
cleanSourceWith.
To avoid having to write the identity predicate when renaming,
the filter is now optional.

builtins.path is supported since Nix 2.0 which is required by nixpkgs

1 files changed, 33 insertions, 4 deletions

diff --git a/lib/sources.nix b/lib/sources.nix
index c4680087b24..51bcf5559e3 100644
--- a/lib/sources.nix
+++ b/lib/sources.nix
@@ -36,18 +36,47 @@ rec {
   # allowing you to chain multiple calls together without any
   # intermediate copies being put in the nix store.
   #
-  #     lib.cleanSourceWith f (lib.cleanSourceWith g ./.)     # Succeeds!
-  #     builtins.filterSource f (builtins.filterSource g ./.) # Fails!
-  cleanSourceWith = { filter, src }:
+  #     lib.cleanSourceWith {
+  #       filter = f;
+  #       src = lib.cleanSourceWith {
+  #         filter = g;
+  #         src = ./.;
+  #       };
+  #     }
+  #     # Succeeds!
+  #
+  #     builtins.filterSource f (builtins.filterSource g ./.)
+  #     # Fails!
+  #
+  # Parameters:
+  #
+  #   src:      A path or cleanSourceWith result to filter and/or rename.
+  #
+  #   filter:   A function (path -> type -> bool)
+  #             Optional with default value: constant true (include everything)
+  #             The function will be combined with the && operator such
+  #             that src.filter is called lazily.
+  #             For implementing a filter, see
+  #             https://nixos.org/nix/manual/#builtin-filterSource
+  #
+  #   name:     Optional name to use as part of the store path.
+  #             This defaults `src.name` or otherwise `baseNameOf src`.
+  #             We recommend setting `name` whenever `src` is syntactically `./.`.
+  #             Otherwise, you depend on `./.`'s name in the parent directory,
+  #             which can cause inconsistent names, defeating caching.
+  #
+  cleanSourceWith = { filter ? _path: _type: true, src, name ? null }:
     let
       isFiltered = src ? _isLibCleanSourceWith;
       origSrc = if isFiltered then src.origSrc else src;
       filter' = if isFiltered then name: type: filter name type && src.filter name type else filter;
+      name' = if name != null then name else if isFiltered then src.name else baseNameOf src;
     in {
       inherit origSrc;
       filter = filter';
-      outPath = builtins.filterSource filter' origSrc;
+      outPath = builtins.path { filter = filter'; path = origSrc; name = name'; };
       _isLibCleanSourceWith = true;
+      name = name';
     };
 
   # Filter sources by a list of regular expressions.