Auto merge of #10326 - matklad:out-dir-for-intermediates, r=alexcrichton

doc: it's valid to use OUT_DIR for intermediate artifacts

Eg, storing `.o` files in OUT_DIR is ok! See
#9661 (comment)
for some discussion.

src/doc/src/reference/build-scripts.md

@@ -69,9 +69,9 @@ the source directory of the build script’s package.
 
 ### Outputs of the Build Script
 
-Build scripts may save any output files in the directory specified in the
-[`OUT_DIR` environment variable][build-env]. Scripts should not modify any
-files outside of that directory.
+Build scripts may save any output files or intermediate artifacts in the
+directory specified in the [`OUT_DIR` environment variable][build-env]. Scripts
+should not modify any files outside of that directory.
 
 Build scripts communicate with Cargo by printing to stdout. Cargo will
 interpret each line that starts with `cargo:` as an instruction that will

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

@@ -318,9 +318,9 @@ let out_dir = env::var("OUT_DIR").unwrap();
     * `CARGO_CFG_TARGET_POINTER_WIDTH=64` — The CPU [pointer width].
     * `CARGO_CFG_TARGET_ENDIAN=little` — The CPU [target endianness].
     * `CARGO_CFG_TARGET_FEATURE=mmx,sse` — List of CPU [target features] enabled.
-* `OUT_DIR` — the folder in which all output should be placed. This folder is
-              inside the build directory for the package being built, and it is
-              unique for the package in question.
+* `OUT_DIR` — the folder in which all output and intermediate artifacts should
+              be placed. This folder is inside the build directory for the
+              package being built, and it is unique for the package in question.
 * `TARGET` — the target triple that is being compiled for. Native code should be
              compiled for this triple. See the [Target Triple] description
              for more information.