File set combinators base: lib.fileset.toSource

[infinisil]

Description of changes

This is the first PR split off from the more complete file set combinators PR, in order to make it easier to incrementally review and merge it. This PR implements a severely limited interface, only containing a single new function:

# Imports ./. into the store, only including files under ./some/path
lib.fileset.toSource {
  root = ./.;
  fileset = ./some/path;
}

Despite that, it's kind of neat how even this simple filtering was previously rather tricky to implement using lib.sources filters, and simple mistakes can break it:

How to do it without this function

Edit: Actually it occurred to me that this might have a mistake, iirc something relating to the filesystem root.

{
  functionBased =
    let
      # The toString and extra "/" is necessary!
      subpath = toString ./some/path + "/";
    in
    lib.cleanSourceWith {
      src = ./.;
      filter = path: type:
        lib.strings.hasPrefix path subpath || lib.strings.hasPrefix subpath path;
    };

  regexBased = lib.sourceByRegex ./. [
    "some"
    "some/path"
    "some/path/.*"
  ];
}

This work is sponsored by Antithesis ✨

Things done

• Implementation
  • Tested
  • Commented
  • Benchmarked
• Contributor documentation
  • Design document
• User documentation
  • Function reference
  • General library documentation

[infinisil]

I'll mark this as ready to review because it's almost done, there's only two relatively minor things left:

• Clean up and add better commenting in internal.nix
• Squash the Git history a bit

[infinisil]

This is now very ready!

[fricklerhandwerk]

Just tiny nitpicks in the docs to clarify wording.

Thanks @infinisil and @roberth for making this happen, step by step.

[fricklerhandwerk]

Suggested change

	- Require IFD if `builtins.path` is used as the underlying primitive
	- Require [Import From Derivation](../../pkgs/README.md#import-from-derivation) if `builtins.path` is used as the underlying primitive

[infinisil]

Hmm that section is only saying that IFD is disallowed in Nixpkgs, but the file set library isn't really meant to be used in Nixpkgs. I'd say let's leave this for now and wait for NixOS/nix#7332

[infinisil]

Thanks, applied all your suggestions!

[infinisil]

This is as ready as it gets, I'll merge this myself! 🚀

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/easy-source-filtering-with-file-sets/29117/11