From b116ba58dceb2fe1f0643a8c23c75a093dc9fcd1 Mon Sep 17 00:00:00 2001
From: Jade Lovelace <jadel@mercury.com>
Date: Mon, 9 Jun 2025 11:53:14 -0700
Subject: [PATCH] buildEnv: improve error messages a little bit

buildEnv didn't previously make it exceedingly clear that it was
responsible for errors so finding docs for it was less clear.

Now it says it was responsible and suggests ways to compare the paths,
but only prints this if it's in your critical path and hard-failed.

```
> pkgs.buildEnv error: two given paths contain a conflicting subpath:
>   `/nix/store/kiifd22fh7pcwzbljy0zznzaw3nq508c-hello-2.12.2/bin/hello' and
>   `/nix/store/3sxwkxdm96bn84rhn2g867shsi284qja-hello-2.12.2/bin/hello'
> hint: this may be caused by two different versions of the same package in buildEnv's `paths` parameter
> hint: `pkgs.nix-diff` can be used to compare derivations
```

Tested with:

```nix
let
  pkgs = import ./. { };
  pkgs' = pkgs.stdenv.__bootPackages.stdenv.__bootPackages.stdenv.__bootPackages;
in

pkgs'.buildEnv {
  name = "meow";
  paths = [
    pkgs'.hello
    (pkgs'.hello.overrideAttrs (old: {
      dontCheck = true;
      dontVersionCheck = true;
      postInstall = ''
        > $out/bin/hello
      '';
    }))
  ];
}
```
---
 pkgs/build-support/buildenv/builder.pl | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pkgs/build-support/buildenv/builder.pl b/pkgs/build-support/buildenv/builder.pl
index 76606716d808..f2fdf36f79e5 100755
--- a/pkgs/build-support/buildenv/builder.pl
+++ b/pkgs/build-support/buildenv/builder.pl
@@ -9,8 +9,8 @@ use JSON::PP;
 
 STDOUT->autoflush(1);
 
-$SIG{__WARN__} = sub { warn "warning: ", @_ };
-$SIG{__DIE__}  = sub { die "error: ", @_ };
+$SIG{__WARN__} = sub { warn "pkgs.buildEnv warning: ", @_ };
+$SIG{__DIE__}  = sub { die "pkgs.buildEnv error: ", @_ };
 
 my $out = $ENV{"out"};
 my $extraPrefix = $ENV{"extraPrefix"};
@@ -109,7 +109,7 @@ sub findFiles($relName, $target, $baseName, $ignoreCollisions, $checkCollisionCo
     # The store path must not be a file when not ignoreSingleFileOutputs
     if (-f $target && isStorePath $target) {
         if ($ignoreSingleFileOutputs) {
-            warn "The store path $target is a file and can't be merged into an environment using pkgs.buildEnv";
+            warn "The store path $target is a file and can't be merged into an environment using pkgs.buildEnv, ignoring it";
             return;
         } else {
             die "The store path $target is a file and can't be merged into an environment using pkgs.buildEnv!";
@@ -173,12 +173,12 @@ sub findFiles($relName, $target, $baseName, $ignoreCollisions, $checkCollisionCo
         my $oldTargetRef = prependDangling($oldTarget);
 
         if ($ignoreCollisions) {
-            warn "collision between $targetRef and $oldTargetRef\n" if $ignoreCollisions == 1;
+            warn "colliding subpath (ignored): $targetRef and $oldTargetRef\n" if $ignoreCollisions == 1;
             return;
         } elsif ($checkCollisionContents && checkCollision($oldTarget, $target)) {
             return;
         } else {
-            die "collision between $targetRef and $oldTargetRef\n";
+            die "two given paths contain a conflicting subpath:\n  $targetRef and\n  $oldTargetRef\nhint: this may be caused by two different versions of the same package in buildEnv's `paths` parameter\nhint: `pkgs.nix-diff` can be used to compare derivations\n";
         }
     }