doc: discuss build script instruction order

[tmfink]

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?

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) soon.

Please see the contribution instructions for more information.

[ehuss]

I'm a little uneasy about making statements about the ordering, though in rust-lang/rust#96328 (comment) it seems to imply this is ok. @petrochenkov, do you think the statements made in this PR are reasonable?

I would also feel a little more comfortable if there is a test to ensure the order is preserved (at least as passed into rustc). Can you maybe include something like the following?

diff --git a/tests/testsuite/build_script.rs b/tests/testsuite/build_script.rs
index d0ef3a2e7..8ca259d1e 100644
--- a/tests/testsuite/build_script.rs
+++ b/tests/testsuite/build_script.rs
@@ -1789,10 +1789,13 @@ 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(
@@ -1800,7 +1803,7 @@ fn output_separate_lines_new() {
 [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 [..]
 ",
         )

[tmfink]

I'm a little uneasy about making statements about the ordering, though in rust-lang/rust#96328 (comment) it seems to imply this is ok. @petrochenkov, do you think the statements made in this PR are reasonable?

I tried to avoid being too strong with my wording by using IETF RFC2119-style language like:

... may affect the order of arguments.

I understand that certain behavior may change, such rustc and/or cargo trying to optimize order of arguments. However, this is a problem today (as shown by rust-lang/rust#96328). To make the added text more clear, we could add language along the lines of "this information is subject to change in future releases of rustc/cargo.

I could also clarify the example by saying, "For example, Unix-like systems often require dynamic libraries to listed after objects that depend on them." Different platforms (real, imaginary, or yet-to-be invented) may not care about order or even require the opposite order.

[tmfink]

Side note: both cargo and rustc potentially affect the final order of arguments passed to the linker.
Should this also be documented somewhere for rustc?

[petrochenkov]

@ehuss

do you think the statements made in this PR are reasonable?

Yes, I think they are reasonable.
Native library ordering is important during linking in practice, and therefore it's important for cargo to guarantee that it's preserved.

[ehuss]

Thanks!

@bors r+

[bors]

📌 Commit 43ce1e7 has been approved by ehuss

[bors]

⌛ Testing commit 43ce1e7 with merge 39ad103...

[bors]

☀️ Test successful - checks-actions
Approved by: ehuss
Pushing 39ad103 to master...