toSource

lib.fileset.toSource

Docs pulled from | This Revision | 17 minutes ago

Add the local files contained in fileset to the store as a single store path rooted at root.

The result is the store path as a string-like value, making it usable e.g. as the src of a derivation, or in string interpolation:

stdenv.mkDerivation {
  src = lib.fileset.toSource { ... };
  # ...
}

The name of the store path is always source.

Inputs

Takes an attribute set with the following attributes

root (Path; required): The local directory path that will correspond to the root of the resulting store path. Paths in strings, including Nix store paths, cannot be passed as root. root has to be a directory.

Changing root only affects the directory structure of the resulting store path, it does not change which files are added to the store. The only way to change which files get added to the store is by changing the fileset attribute.
fileset (FileSet; required): The file set whose files to import into the store. File sets can be created using other functions in this library. This argument can also be a path, which gets implicitly coerced to a file set.

If a directory does not recursively contain any file, it is omitted from the store path contents.

Type

toSource :: {
  root :: Path,
  fileset :: FileSet,
} -> SourceLike

Examples

`lib.fileset.toSource` usage example

# Import the current directory into the store
# but only include files under ./src
toSource {
  root = ./.;
  fileset = ./src;
}
=> "/nix/store/...-source"

# Import the current directory into the store
# but only include ./Makefile and all files under ./src
toSource {
  root = ./.;
  fileset = union
    ./Makefile
    ./src;
}
=> "/nix/store/...-source"

# Trying to include a file outside the root will fail
toSource {
  root = ./.;
  fileset = unions [
    ./Makefile
    ./src
    ../LICENSE
  ];
}
=> <error>

# The root needs to point to a directory that contains all the files
toSource {
  root = ../.;
  fileset = unions [
    ./Makefile
    ./src
    ../LICENSE
  ];
}
=> "/nix/store/...-source"

# The root has to be a local filesystem path
toSource {
  root = "/nix/store/...-source";
  fileset = ./.;
}
=> <error>

Noogle detected

Implementation

The following is the current implementation of this function.

toSource =
    {
      root,
      fileset,
    }:
    let
      # We cannot rename matched attribute arguments, so let's work around it with an extra `let in` statement
      filesetArg = fileset;
    in
    let
      fileset = _coerce "lib.fileset.toSource: `fileset`" filesetArg;
      rootFilesystemRoot = (splitRoot root).root;
      filesetFilesystemRoot = (splitRoot fileset._internalBase).root;
      sourceFilter = _toSourceFilter fileset;
    in
    if !isPath root then
      if root ? _isLibCleanSourceWith then
        throw ''
          lib.fileset.toSource: `root` is a `lib.sources`-based value, but it should be a path instead.
              To use a `lib.sources`-based value, convert it to a file set using `lib.fileset.fromSource` and pass it as `fileset`.
              Note that this only works for sources created from paths.''
      else if isStringLike root then
        throw ''
          lib.fileset.toSource: `root` (${toString root}) is a string-like value, but it should be a path instead.
              Paths in strings are not supported by `lib.fileset`, use `lib.sources` or derivations instead.''
      else
        throw ''lib.fileset.toSource: `root` is of type ${typeOf root}, but it should be a path instead.''
    # Currently all Nix paths have the same filesystem root, but this could change in the future.
    # See also ../path/README.md
    else if !fileset._internalIsEmptyWithoutBase && rootFilesystemRoot != filesetFilesystemRoot then
      throw ''
        lib.fileset.toSource: Filesystem roots are not the same for `fileset` and `root` (${toString root}):
            `root`: Filesystem root is "${toString rootFilesystemRoot}"
            `fileset`: Filesystem root is "${toString filesetFilesystemRoot}"
            Different filesystem roots are not supported.''
    else if !pathExists root then
      throw ''lib.fileset.toSource: `root` (${toString root}) is a path that does not exist.''
    else if pathType root != "directory" then
      throw ''
        lib.fileset.toSource: `root` (${toString root}) is a file, but it should be a directory instead. Potential solutions:
            - If you want to import the file into the store _without_ a containing directory, use string interpolation or `builtins.path` instead of this function.
            - If you want to import the file into the store _with_ a containing directory, set `root` to the containing directory, such as ${toString (dirOf root)}, and set `fileset` to the file path.''
    else if !fileset._internalIsEmptyWithoutBase && !hasPrefix root fileset._internalBase then
      throw ''
        lib.fileset.toSource: `fileset` could contain files in ${toString fileset._internalBase}, which is not under the `root` (${toString root}). Potential solutions:
            - Set `root` to ${toString fileset._internalBase} or any directory higher up. This changes the layout of the resulting store path.
            - Set `fileset` to a file set that cannot contain files outside the `root` (${toString root}). This could change the files included in the result.''
    else
      seq sourceFilter cleanSourceWith {
        name = "source";
        src = root;
        filter = sourceFilter;
      };