Auto merge of #10600 - tmfink:doc-build-script-link-order, r=ehuss

doc: discuss build script instruction order

### What does this PR try to resolve?

It is currently not documented that the order of build script `cargo:` instructions may be relevant to linking.

This has caused issues such as: rust-lang/rust#96328

### How should we test and review this PR?

Build/view documentation.

### Additional information

- Cargo maintainers should fact check my wording.
- We may need to discuss if this should also be documented for `rustc`
- Maintainers should ensure that this change does not prevent a change in what is currently unspecified behavior. Perhaps `cargo` will want to rearrange link arguments itself to resolve issues in the future?

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 [..]
 ",
         )