doc: discuss build script instruction order

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

@@ -77,6 +77,15 @@ Build scripts communicate with Cargo by printing to stdout. Cargo will
 interpret each line that starts with `cargo:` as an instruction that will
 influence compilation of the package. All other lines are ignored.
 
+> Note: The order of `cargo:` instructions printed by the build script *may*
+> affect the order of arguments that `cargo` passes to `rustc`. In turn, the
+> order of arguments passed to `rustc` may affect the order of arguments passed
+> to the linker. Therefore, you will want to pay attention to the order of the
+> build script's instructions. For example, if object `foo` needs to link against
+> library `bar`, you may want to make sure that library `bar`'s
+> [`cargo:rustc-link-lib`](#rustc-link-lib) instruction appears *after*
+> instructions to link object `foo`.
+
 The output of the script is hidden from the terminal during normal
 compilation. If you would like to see the output directly in your terminal,
 invoke Cargo as "very verbose" with the `-vv` flag. This only happens when the

tests/testsuite/build_script.rs

@@ -1789,18 +1789,21 @@ fn output_separate_lines_new() {
                 fn main() {
                     println!("cargo:rustc-link-search=foo");
                     println!("cargo:rustc-link-lib=static=foo");
+                    println!("cargo:rustc-link-lib=bar");
+                    println!("cargo:rustc-link-search=bar");
                 }
             "#,
         )
         .build();
+    // The order of the arguments passed to rustc is important.
     p.cargo("build -v")
         .with_status(101)
         .with_stderr_contains(
             "\
 [COMPILING] foo v0.5.0 ([CWD])
 [RUNNING] `rustc [..] build.rs [..]`
 [RUNNING] `[..]/foo-[..]/build-script-build`
-[RUNNING] `rustc --crate-name foo [..] -L foo -l static=foo`
+[RUNNING] `rustc --crate-name foo [..] -L foo -L bar -l static=foo -l bar`
 [ERROR] could not find native static library [..]
 ",
         )