[Backport staging-25.05] versionCheckHook: Default versionCheckProgram to mainProgram

doc/hooks/versionCheckHook.section.md

@@ -29,7 +29,7 @@ It does so in a clean environment (using `env --ignore-environment`), and it che
 The variables that this phase control are:
 
 - `dontVersionCheck`: Disable adding this hook to the [`preInstallCheckHooks`](#ssec-installCheck-phase). Useful if you do want to load the bash functions of the hook, but run them differently.
-- `versionCheckProgram`: The full path to the program that should print the `${version}` string. Defaults roughly to `${placeholder "out"}/bin/${pname}`. Using `$out` in the value of this variable won't work, as environment variables from this variable are not expanded by the hook. Hence using `placeholder` is unavoidable.
+- `versionCheckProgram`: The full path to the program that should print the `${version}` string. Defaults to using the first non-empty value `$binary` out of `${NIX_MAIN_PROGRAM}` and `${pname}`, in that order, to build roughly `${placeholder "out"}/bin/$binary`. `${NIX_MAIN_PROGRAM}`'s value comes from `meta.mainProgram`, and does not normally need to be set explicitly. When setting `versionCheckProgram`, using `$out` directly won't work, as environment variables from this variable are not expanded by the hook. Hence using `placeholder "out"` is unavoidable.
 - `versionCheckProgramArg`: The argument that needs to be passed to `versionCheckProgram`. If undefined the hook tries first `--help` and then `--version`. Examples: `version`, `-V`, `-v`.
 - `preVersionCheck`: A hook to run before the check is done.
 - `postVersionCheck`: A hook to run after the check is done.

doc/release-notes/rl-2511.section.md

@@ -17,6 +17,11 @@
 
 - Create the first release note entry in this section!
 
+- `meta.mainProgram`: Changing this `meta` entry can lead to a package rebuild due to being used to determine the `NIX_MAIN_PROGRAM` environment variable.
+
+- `versionCheckHook`: Packages that previously relied solely on `pname` to locate the program used to version check, but have a differing `meta.mainProgram` entry, might now fail.
+
+
 ## Nixpkgs Library {#sec-nixpkgs-release-25.11-lib}
 
 <!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->

pkgs/by-name/ve/versionCheckHook/hook.sh

@@ -25,18 +25,24 @@ versionCheckHook(){
     echo Executing versionCheckPhase
 
     local cmdProgram cmdArg echoPrefix
-    if [[ -z "${versionCheckProgram-}" ]]; then
-        if [[ -z "${pname-}" ]]; then
-            echo "both \$pname and \$versionCheckProgram are empty, so" \
-                "we don't know which program to run the versionCheckPhase" \
-                "upon" >&2
-            exit 2
-        else
-            cmdProgram="${!outputBin}/bin/$pname"
-        fi
-    else
+    if [[ ! -z "${versionCheckProgram-}" ]]; then
         cmdProgram="$versionCheckProgram"
+    elif [[ ! -z "${NIX_MAIN_PROGRAM-}" ]]; then
+        cmdProgram="${!outputBin}/bin/${NIX_MAIN_PROGRAM}"
+    elif [[ ! -z "${pname-}" ]]; then
+        echo "versionCheckHook: Package \`${pname}\` does not have the \`meta.mainProgram\` attribute." \
+            "We'll assume that the main program has the same name for now, but this behavior is deprecated," \
+            "because it leads to surprising errors when the assumption does not hold." \
+            "If the package has a main program, please set \`meta.mainProgram\` in its definition to make this warning go away." \
+            "Should the binary that outputs the intended version differ from \`meta.mainProgram\`, consider setting \`versionCheckProgram\` instead." >&2
+        cmdProgram="${!outputBin}/bin/${pname}"
+    else
+        echo "versionCheckHook: \$NIX_MAIN_PROGRAM, \$versionCheckProgram and \$pname are all empty, so" \
+            "we don't know how to run the versionCheckPhase." \
+            "To fix this, set one of \`meta.mainProgram\` or \`versionCheckProgram\`." >&2
+        exit 2
     fi
+
     if [[ ! -x "$cmdProgram" ]]; then
         echo "versionCheckHook: $cmdProgram was not found, or is not an executable" >&2
         exit 2

pkgs/stdenv/generic/make-derivation.nix

@@ -711,7 +711,9 @@ let
       );
 
     let
-      envIsExportable = isAttrs env && !isDerivation env;
+      mainProgram = meta.mainProgram or null;
+      env' = env // lib.optionalAttrs (mainProgram != null) { NIX_MAIN_PROGRAM = mainProgram; };
+      envIsExportable = isAttrs env' && !isDerivation env';
 
       derivationArg = makeDerivationArgument (
         removeAttrs attrs (
@@ -741,11 +743,11 @@ let
 
       checkedEnv =
         let
-          overlappingNames = attrNames (builtins.intersectAttrs env derivationArg);
+          overlappingNames = attrNames (builtins.intersectAttrs env' derivationArg);
           prettyPrint = lib.generators.toPretty { };
           makeError =
             name:
-            "  - ${name}: in `env`: ${prettyPrint env.${name}}; in derivation arguments: ${
+            "  - ${name}: in `env`: ${prettyPrint env'.${name}}; in derivation arguments: ${
                 prettyPrint derivationArg.${name}
               }";
           errors = lib.concatMapStringsSep "\n" makeError overlappingNames;
@@ -759,7 +761,7 @@ let
           assert assertMsg (isString v || isBool v || isInt v || isDerivation v)
             "The `env` attribute set can only contain derivation, string, boolean or integer attributes. The `${n}` attribute is of type ${builtins.typeOf v}.";
           v
-        ) env;
+        ) env';
 
       # Fixed-output derivations may not reference other paths, which means that
       # for a fixed-output derivation, the corresponding inputDerivation should