Merge branch 'master' into staging-next

3 files changed, 42 insertions, 17 deletions

diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix
index 5faa99b3e89e..9e1fdedd2cb9 100644
--- a/doc/doc-support/lib-function-docs.nix
+++ b/doc/doc-support/lib-function-docs.nix
@@ -4,24 +4,31 @@
 
 with pkgs;
 
-let
-  locationsJSON = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };
-in
 stdenv.mkDerivation {
   name = "nixpkgs-lib-docs";
-  src = ../../lib;
+  src = pkgs.lib.fileset.toSource {
+    root = ../..;
+    fileset = ../../lib;
+  };
 
-  buildInputs = [ nixdoc ];
+  buildInputs = [ nixdoc nix ];
   installPhase = ''
+    export NIX_STATE_DIR=$(mktemp -d)
+    nix-instantiate --eval --strict --json ${./lib-function-locations.nix} \
+      --arg nixpkgsPath "./." \
+      --argstr revision ${nixpkgs.rev or "master"} \
+      --argstr libsetsJSON ${pkgs.lib.escapeShellArg (builtins.toJSON libsets)} \
+      > locations.json
+
     function docgen {
       name=$1
       baseName=$2
       description=$3
       # TODO: wrap lib.$name in <literal>, make nixdoc not escape it
-      if [[ -e "../lib/$baseName.nix" ]]; then
-        nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName.nix" > "$out/$name.md"
+      if [[ -e "lib/$baseName.nix" ]]; then
+        nixdoc -c "$name" -d "lib.$name: $description" -l locations.json -f "lib/$baseName.nix" > "$out/$name.md"
       else
-        nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName/default.nix" > "$out/$name.md"
+        nixdoc -c "$name" -d "lib.$name: $description" -l locations.json -f "lib/$baseName/default.nix" > "$out/$name.md"
       fi
       echo "$out/$name.md" >> "$out/index.md"
     }
diff --git a/doc/doc-support/lib-function-locations.nix b/doc/doc-support/lib-function-locations.nix
index e6794617fdd8..feab0bce0b24 100644
--- a/doc/doc-support/lib-function-locations.nix
+++ b/doc/doc-support/lib-function-locations.nix
@@ -1,13 +1,14 @@
-{ pkgs, nixpkgs ? { }, libsets }:
+{ nixpkgsPath, revision, libsetsJSON }:
 let
-  revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.rev or "master");
+  lib = import (nixpkgsPath + "/lib");
+  libsets = builtins.fromJSON libsetsJSON;
 
   libDefPos = prefix: set:
     builtins.concatMap
       (name: [{
         name = builtins.concatStringsSep "." (prefix ++ [name]);
         location = builtins.unsafeGetAttrPos name set;
-      }] ++ nixpkgsLib.optionals
+      }] ++ lib.optionals
         (builtins.length prefix == 0 && builtins.isAttrs set.${name})
         (libDefPos (prefix ++ [name]) set.${name})
       ) (builtins.attrNames set);
@@ -20,8 +21,6 @@ let
       })
       (builtins.map (x: x.name) libsets);
 
-  nixpkgsLib = pkgs.lib;
-
   flattenedLibSubset = { subsetname, functions }:
   builtins.map
     (fn: {
@@ -38,13 +37,13 @@ let
       substr = builtins.substring prefixLen filenameLen filename;
       in substr;
 
-  removeNixpkgs = removeFilenamePrefix (builtins.toString pkgs.path);
+  removeNixpkgs = removeFilenamePrefix (builtins.toString nixpkgsPath);
 
   liblocations =
     builtins.filter
       (elem: elem.value != null)
-      (nixpkgsLib.lists.flatten
-        (locatedlibsets nixpkgsLib));
+      (lib.lists.flatten
+        (locatedlibsets lib));
 
   fnLocationRelative = { name, value }:
     {
@@ -72,4 +71,4 @@ let
     relativeLocs);
 
 in
-pkgs.writeText "locations.json" (builtins.toJSON jsonLocs)
+jsonLocs
diff --git a/doc/languages-frameworks/go.section.md b/doc/languages-frameworks/go.section.md
index d98ecb1c0421..b20308c7b4ab 100644
--- a/doc/languages-frameworks/go.section.md
+++ b/doc/languages-frameworks/go.section.md
@@ -66,6 +66,25 @@ The following is an example expression using `buildGoModule`:
 
 The function `buildGoPackage` builds legacy Go programs, not supporting Go modules.
 
+::: {.warning}
+`buildGoPackage` is deprecated and will be removed for the 25.05 release.
+:::
+
+### Migrating from `buildGoPackage` to `buildGoModule` {#buildGoPackage-migration}
+
+Go modules, released 6y ago, are now widely adopted in the ecosystem.
+Most upstream projects are using Go modules, and the tooling previously used for dependency management in Go is mostly deprecated, archived or at least unmaintained at this point.
+
+In case a project doesn't have external dependencies or dependencies are vendored in a way understood by `go mod init`, migration can be done with a few changes in the package.
+
+- Switch the builder from `buildGoPackage` to `buildGoModule`
+- Remove `goPackagePath` and other attributes specific to `buildGoPackage`
+- Set `vendorHash = null;`
+- Run `go mod init <module name>` in `postPatch`
+
+In case the package has external dependencies that aren't vendored or the build setup is more complex the upstream source might need to be patched.
+Examples for the migration can be found in the [issue tracking migration withing nixpkgs](https://github.com/NixOS/nixpkgs/issues/318069).
+
 ### Example for `buildGoPackage` {#example-for-buildgopackage}
 
 In the following is an example expression using `buildGoPackage`, the following arguments are of special significance to the function: