Cleanup for rustc-link-arg-cdylib (#15326)

This does a little bit of cleanup around rustc-link-arg-cdylib build
script instruction:

* Reorders the documentation so that it is consistent.
* Updates the documentation to mention both the new
(`rustc-link-arg-cdylib`) and old (`rustc-cdylib-link-arg`) forms are
documented, with the new form as the primary form.
* Adds a test for the old form, since we didn't have any.

Somehow I missed all this in
#8441 and
#9557.

Author: weihanglo

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

@@ -105,6 +105,8 @@ one detailed below.
   to re-run the script.
 * [`cargo::rustc-link-arg=FLAG`](#rustc-link-arg) --- Passes custom flags to a
   linker for benchmarks, binaries, `cdylib` crates, examples, and tests.
+* [`cargo::rustc-link-arg-cdylib=FLAG`](#rustc-cdylib-link-arg) --- Passes custom
+  flags to a linker for cdylib crates.
 * [`cargo::rustc-link-arg-bin=BIN=FLAG`](#rustc-link-arg-bin) --- Passes custom
   flags to a linker for the binary `BIN`.
 * [`cargo::rustc-link-arg-bins=FLAG`](#rustc-link-arg-bins) --- Passes custom
@@ -126,8 +128,6 @@ one detailed below.
 * [`cargo::rustc-check-cfg=CHECK_CFG`](#rustc-check-cfg) -- Register custom `cfg`s as
   expected for compile-time checking of configs. 
 * [`cargo::rustc-env=VAR=VALUE`](#rustc-env) --- Sets an environment variable.
-* [`cargo::rustc-cdylib-link-arg=FLAG`](#rustc-cdylib-link-arg) --- Passes custom
-  flags to a linker for cdylib crates.
 - [`cargo::error=MESSAGE`](#cargo-error) --- Displays an error on the terminal.
 * [`cargo::warning=MESSAGE`](#cargo-warning) --- Displays a warning on the
   terminal.
@@ -147,6 +147,16 @@ linker script.
 
 [link-arg]: ../../rustc/codegen-options/index.md#link-arg
 
+### `cargo::rustc-link-arg-cdylib=FLAG` {#rustc-cdylib-link-arg}
+
+The `rustc-link-arg-cdylib` instruction tells Cargo to pass the [`-C
+link-arg=FLAG` option][link-arg] to the compiler, but only when building a
+`cdylib` library target. Its usage is highly platform specific. It is useful
+to set the shared library version or the runtime-path.
+
+For historical reasons, the `cargo::rustc-cdylib-link-arg` form is an alias
+for `cargo::rustc-link-arg-cdylib`, and has the same meaning.
+
 ### `cargo::rustc-link-arg-bin=BIN=FLAG` {#rustc-link-arg-bin}
 
 The `rustc-link-arg-bin` instruction tells Cargo to pass the [`-C
@@ -161,6 +171,24 @@ link-arg=FLAG` option][link-arg] to the compiler, but only when building a
 binary target. Its usage is highly platform specific. It is useful
 to set a linker script or other linker options.
 
+### `cargo::rustc-link-arg-tests=FLAG` {#rustc-link-arg-tests}
+
+The `rustc-link-arg-tests` instruction tells Cargo to pass the [`-C
+link-arg=FLAG` option][link-arg] to the compiler, but only when building a
+tests target.
+
+### `cargo::rustc-link-arg-examples=FLAG` {#rustc-link-arg-examples}
+
+The `rustc-link-arg-examples` instruction tells Cargo to pass the [`-C
+link-arg=FLAG` option][link-arg] to the compiler, but only when building an examples
+target.
+
+### `cargo::rustc-link-arg-benches=FLAG` {#rustc-link-arg-benches}
+
+The `rustc-link-arg-benches` instruction tells Cargo to pass the [`-C
+link-arg=FLAG` option][link-arg] to the compiler, but only when building a benchmark
+target.
+
 ### `cargo::rustc-link-lib=LIB` {#rustc-link-lib}
 
 The `rustc-link-lib` instruction tells Cargo to link the given library using
@@ -185,24 +213,6 @@ The optional `KIND` may be one of `dylib`, `static`, or `framework`. See the
 [option-link]: ../../rustc/command-line-arguments.md#option-l-link-lib
 [FFI]: ../../nomicon/ffi.md
 
-### `cargo::rustc-link-arg-tests=FLAG` {#rustc-link-arg-tests}
-
-The `rustc-link-arg-tests` instruction tells Cargo to pass the [`-C
-link-arg=FLAG` option][link-arg] to the compiler, but only when building a
-tests target.
-
-### `cargo::rustc-link-arg-examples=FLAG` {#rustc-link-arg-examples}
-
-The `rustc-link-arg-examples` instruction tells Cargo to pass the [`-C
-link-arg=FLAG` option][link-arg] to the compiler, but only when building an examples
-target.
-
-### `cargo::rustc-link-arg-benches=FLAG` {#rustc-link-arg-benches}
-
-The `rustc-link-arg-benches` instruction tells Cargo to pass the [`-C
-link-arg=FLAG` option][link-arg] to the compiler, but only when building a benchmark
-target.
-
 ### `cargo::rustc-link-search=[KIND=]PATH` {#rustc-link-search}
 
 The `rustc-link-search` instruction tells Cargo to pass the [`-L`
@@ -307,13 +317,6 @@ Cargo][env-cargo].
 [env-macro]: ../../std/macro.env.html
 [env-cargo]: environment-variables.md#environment-variables-cargo-sets-for-crates
 
-### `cargo::rustc-cdylib-link-arg=FLAG` {#rustc-cdylib-link-arg}
-
-The `rustc-cdylib-link-arg` instruction tells Cargo to pass the [`-C
-link-arg=FLAG` option][link-arg] to the compiler, but only when building a
-`cdylib` library target. Its usage is highly platform specific. It is useful
-to set the shared library version or the runtime-path.
-
 ### `cargo::error=MESSAGE` {#cargo-error}
 
 The `error` instruction tells Cargo to display an error after the build script

tests/testsuite/build_script_extra_link_arg.rs

@@ -403,3 +403,43 @@ fn build_script_extra_link_arg_examples() {
         )
         .run();
 }
+
+#[cargo_test]
+fn cdylib_both_forms() {
+    // Cargo accepts two different forms for the cdylib link instruction,
+    // which have the same meaning.
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+                [package]
+                name = "foo"
+                version = "0.1.0"
+                edition = "2015"
+
+                [lib]
+                crate-type = ["cdylib"]
+            "#,
+        )
+        .file("src/lib.rs", "")
+        .file(
+            "build.rs",
+            r#"
+                fn main() {
+                    println!("cargo::rustc-cdylib-link-arg=--bogus-flag-one");
+                    println!("cargo::rustc-link-arg-cdylib=--bogus-flag-two");
+                }
+            "#,
+        )
+        .build();
+    p.cargo("build -v")
+        .without_status()
+        .with_stderr_data(str![[r#"
+[COMPILING] foo v0.1.0 ([ROOT]/foo)
+[RUNNING] `rustc --crate-name build_script_build [..]
+[RUNNING] `[ROOT]/foo/target/debug/build/foo-[HASH]/build-script-build`
+[RUNNING] `rustc --crate-name foo [..]--crate-type cdylib [..]-C link-arg=--bogus-flag-one -C link-arg=--bogus-flag-two[..]
+...
+"#]])
+        .run();
+}