From 21d58d4f147c32b297c6da9d106e1aaed13d1119 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 18 Mar 2025 10:56:37 -0700 Subject: [PATCH 1/3] Reorder the rustc-link-arg sections This reorders these sections so they are presented in a logical order, and matches the summary at the top. --- src/doc/src/reference/build-scripts.md | 54 +++++++++++++------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index cccdd349602..6fdcb8a0d38 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/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-cdylib-link-arg=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,13 @@ linker script. [link-arg]: ../../rustc/codegen-options/index.md#link-arg +### `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::rustc-link-arg-bin=BIN=FLAG` {#rustc-link-arg-bin} The `rustc-link-arg-bin` instruction tells Cargo to pass the [`-C @@ -161,6 +168,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 +210,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 +314,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 From 9c2e8302fc31b7fcf46c47364ffb551df8023575 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 18 Mar 2025 11:06:55 -0700 Subject: [PATCH 2/3] Make rustc-link-arg-cdylib the standard form This form has the consistent pattern of `rustc-link-arg-$KIND`. The old, original `rustc-cdylib-link-arg` is just an alias. --- src/doc/src/reference/build-scripts.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index 6fdcb8a0d38..ac18b365d22 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/src/doc/src/reference/build-scripts.md @@ -105,7 +105,7 @@ 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-cdylib-link-arg=FLAG`](#rustc-cdylib-link-arg) --- Passes custom +* [`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`. @@ -147,13 +147,16 @@ linker script. [link-arg]: ../../rustc/codegen-options/index.md#link-arg -### `cargo::rustc-cdylib-link-arg=FLAG` {#rustc-cdylib-link-arg} +### `cargo::rustc-link-arg-cdylib=FLAG` {#rustc-cdylib-link-arg} -The `rustc-cdylib-link-arg` instruction tells Cargo to pass the [`-C +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 From 5516ffa1c3d7572910130d6e1d39d0cd15284853 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 18 Mar 2025 11:09:09 -0700 Subject: [PATCH 3/3] Add a test for rustc-cdylib-link-arg We didn't have any tests that included the old `rustc-cdylib-link-arg` form. --- .../testsuite/build_script_extra_link_arg.rs | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/tests/testsuite/build_script_extra_link_arg.rs b/tests/testsuite/build_script_extra_link_arg.rs index ad3a8d13b7b..ee58e309fe9 100644 --- a/tests/testsuite/build_script_extra_link_arg.rs +++ b/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(); +}