buildGoModule: Use the env attribute to pass environment variables

doc/languages-frameworks/go.section.md

@@ -176,31 +176,6 @@ Following example could be used to only build the example-cli and example-server
 
 Specified as a string or list of strings. Causes the builder to skip building child packages that match any of the provided values.
 
-### `CGO_ENABLED` {#var-go-CGO_ENABLED}
-
-When set to `0`, the [cgo](https://pkg.go.dev/cmd/cgo) command is disabled. As consequence, the build
-program can't link against C libraries anymore, and the resulting binary is statically linked.
-
-When building with CGO enabled, Go will likely link some packages from the Go standard library against C libraries,
-even when the target code does not explicitly call into C dependencies. With `CGO_ENABLED = 0;`, Go
-will always use the Go native implementation of these internal packages. For reference see
-[net](https://pkg.go.dev/net#hdr-Name_Resolution) and [os/user](https://pkg.go.dev/os/user#pkg-overview) packages.
-Notice that the decision whether these packages should use native Go implementation or not can also be controlled
-on a per package level using build tags (`tags`). In case CGO is disabled, these tags have no additional effect.
-
-When a Go program depends on C libraries, place those dependencies in `buildInputs`:
-
-```nix
-{
-  buildInputs = [
-    libvirt
-    libxml2
-  ];
-}
-```
-
-`CGO_ENABLED` defaults to `1`.
-
 ### `enableParallelBuilding` {#var-go-enableParallelBuilding}
 
 Whether builds and tests should run in parallel.
@@ -247,7 +222,34 @@ Alternatively, the primary derivation provides an overridable `passthru.override
 
 ## Controlling the Go environment {#ssec-go-environment}
 
-The Go build can be further tweaked by setting environment variables. In most cases, this isn't needed. Possible values can be found in the [Go documentation of accepted environment variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables). Notice that some of these flags are set by the builder itself and should not be set explicitly. If in doubt, grep the implementation of the builder.
+The Go build can be further tweaked by setting environment variables via the `env` attribute. In most cases, this isn't needed. Possible values can be found in the [Go documentation of accepted environment variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables). Notice that some of these flags are set by the build helper itself and should not be set explicitly. If in doubt, grep the implementation of the build helper.
+
+`buildGoModule` officially supports the following environment variables:
+
+### `env.CGO_ENABLED` {#var-go-CGO_ENABLED}
+
+When set to `0`, the [cgo](https://pkg.go.dev/cmd/cgo) command is disabled. As consequence, the build
+program can't link against C libraries anymore, and the resulting binary is statically linked.
+
+When building with CGO enabled, Go will likely link some packages from the Go standard library against C libraries,
+even when the target code does not explicitly call into C dependencies. With `env.CGO_ENABLED = 0;`, Go
+will always use the Go native implementation of these internal packages. For reference see
+[net](https://pkg.go.dev/net#hdr-Name_Resolution) and [os/user](https://pkg.go.dev/os/user#pkg-overview) packages.
+Notice that the decision whether these packages should use native Go implementation or not can also be controlled
+on a per package level using build tags (`tags`). In case CGO is disabled, these tags have no additional effect.
+
+When a Go program depends on C libraries, place those dependencies in `buildInputs`:
+
+```nix
+{
+  buildInputs = [
+    libvirt
+    libxml2
+  ];
+}
+```
+
+`env.CGO_ENABLED` defaults to `1`.
 
 ## Skipping tests {#ssec-skip-go-tests}
 

nixos/doc/manual/release-notes/rl-2505.section.md

@@ -63,6 +63,12 @@
 - `binwalk` was updated to 3.1.0, which has been rewritten in rust. The python module is no longer available.
   See the release notes of [3.1.0](https://github.com/ReFirmLabs/binwalk/releases/tag/v3.1.0) for more information.
 
+- `buildGoModule` now passes environment variables via the `env` attribute. `CGO_ENABLED` should now be specified with `env.CGO_ENABLED` when passing to buildGoModule. Direct specification of `CGO_ENABLED` is now redirected by a compatibility layer with a warning, but will become an error in future releases.
+
+  Go-related environment variables previously shadowed by `buildGoModule` now results in errors when specified directly. Such variables include `GOOS` and `GOARCH`.
+
+  Third-party projects supporting both stable and unstable channels could detect this change through the absence of the `CGO_ENABLED` function argument in `buildGoModule` (`!((lib.functionArgs buildGoModule) ? CGO_ENABLED)`).
+
 - `buildGoPackage` has been removed. Use `buildGoModule` instead. See the [Go section in the nixpkgs manual](https://nixos.org/manual/nixpkgs/unstable/#sec-language-go) for details.
 
 - `strawberry` has been updated to 1.2, which drops support for the VLC backend and Qt 5. The `strawberry-qt5` package

pkgs/applications/networking/cluster/helm/plugins/helm-cm-push.nix

@@ -23,7 +23,7 @@ buildGoModule rec {
     sed -e '/^hooks:/,+2 d' -i plugin.yaml
   '';
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   ldflags = [ "-s" "-w" ];
 

pkgs/applications/networking/cluster/helm/plugins/helm-dt.nix

@@ -30,7 +30,7 @@ buildGoModule rec {
 
   # require network/login
   doCheck = false;
-  CGO_ENABLED = 1;
+  env.CGO_ENABLED = 1;
 
   postInstall = ''
     install -dm755 $out/helm-dt/bin

pkgs/applications/networking/cluster/terraform-providers/default.nix

@@ -39,7 +39,7 @@ let
         doCheck = false;
         # https://github.com/hashicorp/terraform-provider-scaffolding/blob/a8ac8375a7082befe55b71c8cbb048493dd220c2/.goreleaser.yml
         # goreleaser (used for builds distributed via terraform registry) requires that CGO is disabled
-        CGO_ENABLED = 0;
+        env.CGO_ENABLED = 0;
         ldflags = [ "-s" "-w" "-X main.version=${version}" "-X main.commit=${rev}" ];
         src = mkProviderFetcher {
           name = "source-${rev}";

pkgs/applications/networking/discordo/default.nix

@@ -14,7 +14,7 @@ buildGoModule rec {
 
   vendorHash = "sha256-UTZIx4zXIMdQBQXfzk3+j43yx7vlitw4Mwmon8oYjd8=";
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   ldflags = [ "-s" "-w" ];
 

pkgs/applications/terminal-emulators/kitty/default.nix

@@ -120,7 +120,7 @@ buildPythonApplication rec {
     "fortify3"
   ];
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
   GOFLAGS = "-trimpath";
 
   configurePhase = ''

pkgs/build-support/go/module.nix

@@ -40,9 +40,6 @@
   # IE: programs coupled with the compiler.
 , allowGoReference ? false
 
-  # Go env. variable to enable CGO.
-, CGO_ENABLED ? go.CGO_ENABLED
-
   # Meta data for the final derivation.
 , meta ? { }
 
@@ -59,11 +56,12 @@
 }@args':
 
 let
-  args = removeAttrs args' [ "overrideModAttrs" ];
-
-  GO111MODULE = "on";
-  GOTOOLCHAIN = "local";
-
+  args = removeAttrs args' [
+    "overrideModAttrs"
+    # Compatibility layer to the directly-specified CGO_ENABLED.
+    # TODO(@ShamrockLee): Remove after Nixpkgs 25.05 branch-off
+    "CGO_ENABLED"
+  ];
 in
 (stdenv.mkDerivation (finalAttrs:
   args
@@ -77,8 +75,6 @@ in
     nativeBuildInputs = (finalAttrs.nativeBuildInputs or [ ]) ++ [ go git cacert ];
 
     inherit (finalAttrs) src modRoot;
-    inherit (go) GOOS GOARCH;
-    inherit GO111MODULE GOTOOLCHAIN;
 
     # The following inheritance behavior is not trivial to expect, and some may
     # argue it's not ideal. Changing it may break vendor hashes in Nixpkgs and
@@ -169,14 +165,33 @@ in
 
     nativeBuildInputs = [ go ] ++ nativeBuildInputs;
 
+  env = args.env or { } // {
     inherit (go) GOOS GOARCH;
 
+    GO111MODULE = "on";
+    GOTOOLCHAIN = "local";
+
+    CGO_ENABLED = args.env.CGO_ENABLED or (
+      if args'?CGO_ENABLED then
+        # Compatibility layer to the CGO_ENABLED attribute not specified as env.CGO_ENABLED
+        # TODO(@ShamrockLee): Remove and convert to
+        # CGO_ENABLED = args.env.CGO_ENABLED or go.CGO_ENABLED
+        # after the Nixpkgs 25.05 branch-off.
+        lib.warn
+          "${finalAttrs.finalPackage.meta.position}: buildGoModule: specify CGO_ENABLED with env.CGO_ENABLED instead."
+          args'.CGO_ENABLED
+      else
+        go.CGO_ENABLED
+    );
+  };
+
     GOFLAGS = GOFLAGS
       ++ lib.warnIf (lib.any (lib.hasPrefix "-mod=") GOFLAGS) "use `proxyVendor` to control Go module/vendor behavior instead of setting `-mod=` in GOFLAGS"
         (lib.optional (!finalAttrs.proxyVendor) "-mod=vendor")
       ++ lib.warnIf (builtins.elem "-trimpath" GOFLAGS) "`-trimpath` is added by default to GOFLAGS by buildGoModule when allowGoReference isn't set to true"
         (lib.optional (!allowGoReference) "-trimpath");
-    inherit CGO_ENABLED enableParallelBuilding GO111MODULE GOTOOLCHAIN;
+
+  inherit enableParallelBuilding;
 
     # If not set to an explicit value, set the buildid empty for reproducibility.
     ldflags = ldflags ++ lib.optional (!lib.any (lib.hasPrefix "-buildid=") ldflags) "-buildid=";

pkgs/by-name/ar/arkade/package.nix

@@ -15,7 +15,7 @@ buildGoModule rec {
     hash = "sha256-MFce+stC+OzUL0H0ahZZAfMwr9Y+EVJIMmhhRl4JYaU=";
   };
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   nativeBuildInputs = [ installShellFiles ];
 

pkgs/by-name/at/athens/package.nix

@@ -19,7 +19,7 @@ buildGoModule rec {
 
   vendorHash = "sha256-W65lQYGrRg8LwFERj5MBOPFAn2j+FE7ep4ANuAGmfgM=";
 
-  CGO_ENABLED = "0";
+  env.CGO_ENABLED = "0";
   ldflags = [
     "-s"
     "-X github.com/gomods/athens/pkg/build.version=${version}"

pkgs/by-name/au/authentik/ldap.nix

@@ -6,7 +6,7 @@ buildGoModule {
 
   vendorHash = "sha256-BcL9QAc2jJqoPaQImJIFtCiu176nxmVcCLPjXjNBwqI=";
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   subPackages = [ "cmd/ldap" ];
 

pkgs/by-name/au/authentik/package.nix

@@ -285,7 +285,7 @@ let
         --replace-fail './web' "${authentik-django}/web"
     '';
 
-    CGO_ENABLED = 0;
+    env.CGO_ENABLED = 0;
 
     vendorHash = "sha256-BcL9QAc2jJqoPaQImJIFtCiu176nxmVcCLPjXjNBwqI=";
 

pkgs/by-name/au/authentik/radius.nix

@@ -6,7 +6,7 @@ buildGoModule {
 
   vendorHash = "sha256-BcL9QAc2jJqoPaQImJIFtCiu176nxmVcCLPjXjNBwqI=";
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   subPackages = [ "cmd/radius" ];
 

pkgs/by-name/ba/bazel-watcher/package.nix

@@ -21,7 +21,7 @@ buildGoModule rec {
   vendorHash = "sha256-0I/bvuyosN55oNSMuom4C8rVjxneUaqV19l9OMiwWhU=";
 
   # The dependency github.com/fsnotify/fsevents requires CGO
-  CGO_ENABLED = if stdenv.hostPlatform.isDarwin then "1" else "0";
+  env.CGO_ENABLED = if stdenv.hostPlatform.isDarwin then "1" else "0";
   ldflags = [
     "-s"
     "-X main.Version=${version}"

pkgs/by-name/be/bee/package.nix

@@ -28,7 +28,7 @@ buildGoModule rec {
     "-X github.com/ethersphere/bee/v2/pkg/postage/listener.batchFactorOverridePublic=5"
   ];
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   postInstall = ''
     mkdir -p $out/lib/systemd/system

pkgs/by-name/be/betula/package.nix

@@ -13,7 +13,7 @@
   };
   vendorHash = "sha256-SWcQYF8LP6lw5kWlAVFt3qiwDnvpSOXenmdm6TSfJSc=";
 
-  CGO_ENABLED = 1;
+  env.CGO_ENABLED = 1;
   # These tests use internet, so are failing in Nix build.
   # See also: https://todo.sr.ht/~bouncepaw/betula/91
   checkFlags = "-skip=TestTitles|TestHEntries";

pkgs/by-name/bi/bingo/package.nix

@@ -17,7 +17,7 @@ buildGoModule rec {
     rm get_e2e_test.go get_e2e_utils_test.go
   '';
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   ldflags = [ "-s" "-w" ];
 

pkgs/by-name/bi/bitrise/package.nix

@@ -23,7 +23,7 @@ buildGoModule rec {
     "-X github.com/bitrise-io/bitrise/version.Commit=${src.rev}"
     "-X github.com/bitrise-io/bitrise/version.BuildNumber=0"
   ];
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   passthru.updateScript = nix-update-script { };
 

pkgs/by-name/bl/bluetuith/package.nix

@@ -17,7 +17,7 @@ buildGoModule rec {
 
   vendorHash = "sha256-tEVzuhE0Di7edGa5eJHLLqOecCuoj02h91TsZiZU1PM=";
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   ldflags = [
     "-s"

pkgs/by-name/br/brev-cli/package.nix

@@ -16,7 +16,7 @@ buildGoModule rec {
 
   vendorHash = "sha256-g+LjubG1s3z47I69mEfkSaAmi1+eNSp4M5Wic6h0+Xc=";
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
   subPackages = [ "." ];
 
   ldflags = [

pkgs/by-name/bu/buildkit-nix/package.nix

@@ -13,7 +13,7 @@ buildGoModule rec {
 
   vendorHash = "sha256-SFsf2QOIuUQY5Zzshb2190pQtOBGEsELBRihOvHYVGA=";
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   ldflags = [ "-s" "-w" ];
 

pkgs/by-name/ca/capslock/package.nix

@@ -20,7 +20,7 @@ buildGoModule rec {
 
   subPackages = [ "cmd/capslock" ];
 
-  CGO_ENABLED = "0";
+  env.CGO_ENABLED = "0";
 
   ldflags = [ "-s" ];
 

pkgs/by-name/ch/chamber/package.nix

@@ -11,7 +11,7 @@ buildGoModule rec {
     sha256 = "sha256-1ySOlP0sFk3+IRt/zstZK6lEE2pzoVSiZz3wFxdesgc=";
   };
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   vendorHash = "sha256-KlouLjW9hVKFi9uz34XHd4CzNOiyO245QNygkB338YQ=";
 

pkgs/by-name/ci/civo/package.nix

@@ -20,7 +20,7 @@ buildGoModule rec {
 
   nativeBuildInputs = [ installShellFiles ];
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   # Some lint checks fail
   doCheck = false;

pkgs/by-name/cl/cloudflare-dynamic-dns/package.nix

@@ -28,7 +28,7 @@ buildGoModule rec {
     "-X=main.date=1970-01-01"
   ];
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   passthru.tests.version = testers.testVersion { package = cloudflare-dynamic-dns; };
 

pkgs/by-name/co/colima/package.nix

@@ -41,7 +41,7 @@ buildGoModule rec {
   # https://hydra.nixos.org/build/212378003/log
   excludedPackages = "gvproxy";
 
-  CGO_ENABLED = 1;
+  env.CGO_ENABLED = 1;
 
   preConfigure = ''
     ldflags="-s -w -X github.com/abiosoft/colima/config.appVersion=${version} \

pkgs/by-name/co/commitizen-go/package.nix

@@ -22,7 +22,7 @@ buildGoModule rec {
 
   subPackages = [ "." ];
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   ldflags = [
     "-X 'github.com/lintingzhen/commitizen-go/cmd.revision=${commit_revision}'"

pkgs/by-name/co/copacetic/package.nix

@@ -22,7 +22,7 @@ buildGoModule rec {
 
   nativeBuildInputs = [ installShellFiles ];
 
-  CGO_ENABLED = "0";
+  env.CGO_ENABLED = "0";
   ldflags = [
     "-s"
     "-w"

pkgs/by-name/cu/cunicu/package.nix

@@ -34,7 +34,7 @@ buildGoModule rec {
     versionCheckHook
   ];
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   # These packages contain networking dependent tests which fail in the sandbox
   excludedPackages = [

pkgs/by-name/de/deck/package.nix

@@ -19,7 +19,7 @@ buildGoModule rec {
 
   nativeBuildInputs = [ installShellFiles ];
 
-  CGO_ENABLED = 0;
+  env.CGO_ENABLED = 0;
 
   ldflags = [
     "-s -w -X github.com/kong/deck/cmd.VERSION=${version}"