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.

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

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.

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?

@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.

Thanks!

@bors r+

📌 Commit 43ce1e7 has been approved by ehuss

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

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