add documentation for CARGO_WORKSPACE_DIR env var

src/cargo/core/compiler/mod.rs

@@ -728,7 +728,9 @@ fn prepare_rustc(
         base.env("CARGO_TARGET_TMPDIR", tmp.display().to_string());
 
         if cx.bcx.config.nightly_features_allowed {
-            // relative path from manifest directory to workspace directory
+            // Use a relative path and limit to integration tests and benchmarks in hopes
+            // that it conveys to the user that the meaning of this value is a bit fuzzy
+            // (very different meaning in the original repo vs once published).
             let cargo_workspace_dir = pathdiff::diff_paths(cx.bcx.ws.root(), unit.pkg.root())
                 .expect("both paths are absolute");
             base.env(

src/doc/src/reference/environment-variables.md

@@ -257,6 +257,12 @@ corresponding environment variable is set to the empty string, `""`.
   where integration tests or benchmarks are free to put any data needed by
   the tests/benches. Cargo initially creates this directory but doesn't
   manage its content in any way, this is the responsibility of the test code.
+* `CARGO_WORKSPACE_DIR` --- Only set when building [integration test] or benchmark code.
+  This is a path to the workspace directory. If the current package is not part of
+  a workspace, it is a path to the directory containing the manifest of the package.
+  For a published registry crate it is a path to the directory containing the manifest
+  of the package that (possibly transitively) imported that published crate.
+  Currently, it is implemented as a relative path.
 
 [Cargo target]: cargo-targets.md
 [binaries]: cargo-targets.md#binaries