glibc: comments on bin not being the first output

The glibc package does not respect a standard convention to put the
executables in the first output which should be as clear as possible
to anyone seeking to use such executables (e.g. `ldd`). This commit
adds a detailed comment a the top of `common.nix` explaining the
deviation from the convention and how to reference the binaries.

1 files changed, 17 insertions, 1 deletions

diff --git a/pkgs/development/libraries/glibc/common.nix b/pkgs/development/libraries/glibc/common.nix
index 5c7bbb32c330..f0a7e5703e95 100644
--- a/pkgs/development/libraries/glibc/common.nix
+++ b/pkgs/development/libraries/glibc/common.nix
@@ -1,5 +1,21 @@
 /* Build configuration used to build glibc, Info files, and locale
-   information.  */
+   information.
+
+   Note that this derivation has multiple outputs and does not respect the
+   standard convention of putting the executables into the first output. The
+   first output is `lib` so that the libraries provided by this derivation
+   can be accessed directly, e.g.
+
+     "${pkgs.glibc}/lib/ld-linux-x86_64.so.2"
+
+   The executables are put into `bin` output and need to be referenced via
+   the `bin` attribute of the main package, e.g.
+
+     "${pkgs.glibc.bin}/bin/ldd".
+
+  The executables provided by glibc typically include `ldd`, `locale`, `iconv`
+  but the exact set depends on the library version and the configuration.
+*/
 
 { stdenv, lib
 , buildPlatform, hostPlatform