Merge staging-next into staging

Building software with Nix often requires downloading source code and other files from the internet.

To this end, we use functions that we call _fetchers_, which obtain remote sources via various protocols and services.

Nix provides built-in fetchers such as [`builtins.fetchTarball`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchTarball).

Nix provides built-in fetchers such as [`fetchTarball`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchTarball).

Nixpkgs provides its own fetchers, which work differently:

- A built-in fetcher will download and cache files at evaluation time and produce a [store path](https://nixos.org/manual/nix/stable/glossary#gloss-store-path).

They are useful for creating files from Nix expression, and are all implemented as convenience wrappers around `writeTextFile`.

Each of these functions will cause a derivation to be produced.

When you coerce the result of each of these functions to a string with [string interpolation](https://nixos.org/manual/nix/stable/language/string-interpolation) or [`builtins.toString`](https://nixos.org/manual/nix/stable/language/builtins#builtins-toString), it will evaluate to the [store path](https://nixos.org/manual/nix/stable/store/store-path) of this derivation.

When you coerce the result of each of these functions to a string with [string interpolation](https://nixos.org/manual/nix/stable/language/string-interpolation) or [`toString`](https://nixos.org/manual/nix/stable/language/builtins#builtins-toString), it will evaluate to the [store path](https://nixos.org/manual/nix/stable/store/store-path) of this derivation.

:::: {.note}

Some of these functions will put the resulting files within a directory inside the [derivation output](https://nixos.org/manual/nix/stable/language/derivations#attr-outputs).

`allowSubstitutes` (Bool, _optional_)

: Whether to allow substituting from a binary cache.

  Passed through to [`allowSubstitutes`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-allowSubstitutes) of the underlying call to `builtins.derivation`.

  Passed through to [`allowSubstitutes`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-allowSubstitutes) of the underlying call to `derivation`.

  It defaults to `false`, as running the derivation's simple `builder` executable locally is assumed to be faster than network operations.

  Set it to true if the `checkPhase` step is expensive.

: Whether to prefer building locally, even if faster [remote build machines](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substituters) are available.

  Passed through to [`preferLocalBuild`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-preferLocalBuild) of the underlying call to `builtins.derivation`.

  Passed through to [`preferLocalBuild`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-preferLocalBuild) of the underlying call to `derivation`.

  It defaults to `true` for the same reason `allowSubstitutes` defaults to `false`.

  libset =

    toplib:

    builtins.map (subsetname: {

    map (subsetname: {

      subsetname = subsetname;

      functions = libDefPos [ ] toplib.${subsetname};

    }) (builtins.map (x: x.name) libsets);

    }) (map (x: x.name) libsets);

  flattenedLibSubset =

    { subsetname, functions }:

    builtins.map (fn: {

    map (fn: {

      name = "lib.${subsetname}.${fn.name}";

      value = fn.location;

    }) functions;

  locatedlibsets = libs: builtins.map flattenedLibSubset (libset libs);

  locatedlibsets = libs: map flattenedLibSubset (libset libs);

  removeFilenamePrefix =

    prefix: filename:

    let

    in

    substr;

  removeNixpkgs = removeFilenamePrefix (builtins.toString nixpkgsPath);

  removeNixpkgs = removeFilenamePrefix (toString nixpkgsPath);

  liblocations = builtins.filter (elem: elem.value != null) (lib.lists.flatten (locatedlibsets lib));

      };

    };

  relativeLocs = (builtins.map fnLocationRelative liblocations);

  relativeLocs = (map fnLocationRelative liblocations);

  sanitizeId = builtins.replaceStrings [ "'" ] [ "-prime" ];

  urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}";

  jsonLocs = builtins.listToAttrs (

    builtins.map (

    map (

      { name, value }:

      {

        name = sanitizeId name;

        value =

          let

            text = "${value.file}:${builtins.toString value.line}";

            target = "${urlPrefix}/${value.file}#L${builtins.toString value.line}";

            text = "${value.file}:${toString value.line}";

            target = "${urlPrefix}/${value.file}#L${toString value.line}";

          in

          "[${text}](${target}) in `<nixpkgs>`";

      }

# ./example.nix

let

  nixpkgs = builtins.fetchTarball {

  nixpkgs = fetchTarball {

    url = "https://github.com/NixOS/nixpkgs/archive/94b2848559b12a8ed1fe433084686b2a81123c99.tar.gz";

    hash = "sha256-B4Q3c6IvTLg3Q92qYa8y+i4uTaphtFdjp+Ir3QQjdN0=";

  };

`importNpmLock` uses the following fetchers:

- `pkgs.fetchurl` for `http(s)` dependencies

- `builtins.fetchGit` for `git` dependencies

- `fetchGit` for `git` dependencies

It is possible to provide additional arguments to individual fetchers as needed: