reword description of the cores setting (#9522)

* reword description of the `cores` setting

- be precise about the `builder` executable
- clearly distinguish between `builder` and job parallelism
- clarify the role of `mkDerivation` in the example
- remove prose for the default, it's shown programmatically
- mention relation to `max-jobs`

src/libstore/globals.hh

@@ -180,14 +180,21 @@ public:
         getDefaultCores(),
         "cores",
         R"(
-          Sets the value of the `NIX_BUILD_CORES` environment variable in the
+          Sets the value of the `NIX_BUILD_CORES` environment variable in the [invocation of the `builder` executable](@docroot@/language/derivations.md#builder-execution) of a derivation.
-          invocation of builders. Builders can use this variable at their
+          The `builder` executable can use this variable to control its own maximum amount of parallelism.
-          discretion to control the maximum amount of parallelism. For
+
-          instance, in Nixpkgs, if the derivation attribute
+          <!--
-          `enableParallelBuilding` is set to `true`, the builder passes the
+          FIXME(@fricklerhandwerk): I don't think this should even be mentioned here.
-          `-jN` flag to GNU Make. It can be overridden using the `--cores`
+          A very generic example using `derivation` and `xargs` may be more appropriate to explain the mechanism.
-          command line switch and defaults to `1`. The value `0` means that
+          Using `mkDerivation` as an example requires being aware of that there are multiple independent layers that are completely opaque here.
-          the builder should use all available CPU cores in the system.
+          -->
+          For instance, in Nixpkgs, if the attribute `enableParallelBuilding` for the `mkDerivation` build helper is set to `true`, it will pass the `-j${NIX_BUILD_CORES}` flag to GNU Make.
+
+          The value `0` means that the `builder` should use all available CPU cores in the system.
+
+          > **Note**
+          >
+          > The number of parallel local Nix build jobs is independently controlled with the [`max-jobs`](#conf-max-jobs) setting.
         )",
         {"build-cores"},
         // Don't document the machine-specific default value