Document that build scripts should not modify files outside OUT_DIR.

Co-authored-by: Gabriel Feron <feron.gabriel@gmail.com>

diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md
index beb762869ca5b3c29efdfb62f2e5e14e7f7ac079..fbf71a6d6f72dc644b6c5219ac50f29f8fa4338e 100644 (file)
--- a/src/doc/src/reference/build-scripts.md
+++ b/src/doc/src/reference/build-scripts.md
@@ -272,6 +272,11 @@ There’s a couple of points of note here:
   output files should be located. It can use the process’ current working
   directory to find where the input files should be located, but in this case we
   don’t have any input files.
+* In general, build scripts should not modify any files outside of `OUT_DIR`.
+  It may seem fine on the first blush, but it does cause problems when you use
+  such crate as a dependency, because there's an *implicit* invariant that
+  sources in `.cargo/registry` should be immutable. `cargo` won't allow such
+  scripts when packaging.
 * This script is relatively simple as it just writes out a small generated file.
   One could imagine that other more fanciful operations could take place such as
   generating a Rust module from a C header file or another language definition,