Update build script docs

0xPoe · 0xPoe · commit bd230e810cbf · 2023-12-23T13:17:55.000+08:00
Signed-off-by: hi-rustin &lt;rustin.liu@gmail.com&gt;
diff --git a/src/doc/src/reference/build-script-examples.md b/src/doc/src/reference/build-script-examples.md
@@ -71,7 +71,7 @@ fn main() {
         }
         "
     ).unwrap();
-    println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo::rerun-if-changed=build.rs");
 }
 ```
 
@@ -173,9 +173,9 @@ fn main() {
                       .current_dir(&Path::new(&out_dir))
                       .status().unwrap();
 
-    println!("cargo:rustc-link-search=native={}", out_dir);
-    println!("cargo:rustc-link-lib=static=hello");
-    println!("cargo:rerun-if-changed=src/hello.c");
+    println!("cargo::rustc-link-search=native={}", out_dir);
+    println!("cargo::rustc-link-lib=static=hello");
+    println!("cargo::rerun-if-changed=src/hello.c");
 }
 ```
 
@@ -214,7 +214,7 @@ fn main() {
     cc::Build::new()
         .file("src/hello.c")
         .compile("hello");
-    println!("cargo:rerun-if-changed=src/hello.c");
+    println!("cargo::rerun-if-changed=src/hello.c");
 }
 ```
 
@@ -316,7 +316,7 @@ The build script is fairly simple:
 
 fn main() {
     pkg_config::Config::new().probe("zlib").unwrap();
-    println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo::rerun-if-changed=build.rs");
 }
 ```
 
@@ -344,9 +344,9 @@ Run `cargo build -vv` to see the output from the build script. On a system
 with `libz` already installed, it may look something like this:
 
 ```text
-[libz-sys 0.1.0] cargo:rustc-link-search=native=/usr/lib
-[libz-sys 0.1.0] cargo:rustc-link-lib=z
-[libz-sys 0.1.0] cargo:rerun-if-changed=build.rs
+[libz-sys 0.1.0] cargo::rustc-link-search=native=/usr/lib
+[libz-sys 0.1.0] cargo::rustc-link-lib=z
+[libz-sys 0.1.0] cargo::rerun-if-changed=build.rs
 ```
 
 Nice! `pkg-config` did all the work of finding the library and telling Cargo
@@ -408,7 +408,7 @@ fn main() {
         cfg.include(include);
     }
     cfg.compile("zuser");
-    println!("cargo:rerun-if-changed=src/zuser.c");
+    println!("cargo::rerun-if-changed=src/zuser.c");
 }
 ```
 
@@ -440,7 +440,7 @@ script looks something [like
 this](https://github.com/sfackler/rust-openssl/blob/dc72a8e2c429e46c275e528b61a733a66e7877fc/openssl-sys/build/main.rs#L216):
 
 ```rust,ignore
-println!("cargo:version_number={:x}", openssl_version);
+println!("cargo::version_number={:x}", openssl_version);
 ```
 
 This instruction causes the `DEP_OPENSSL_VERSION_NUMBER` environment variable
@@ -460,19 +460,19 @@ if let Ok(version) = env::var("DEP_OPENSSL_VERSION_NUMBER") {
     let version = u64::from_str_radix(&version, 16).unwrap();
 
     if version >= 0x1_00_01_00_0 {
-        println!("cargo:rustc-cfg=ossl101");
+        println!("cargo::rustc-cfg=ossl101");
     }
     if version >= 0x1_00_02_00_0 {
-        println!("cargo:rustc-cfg=ossl102");
+        println!("cargo::rustc-cfg=ossl102");
     }
     if version >= 0x1_01_00_00_0 {
-        println!("cargo:rustc-cfg=ossl110");
+        println!("cargo::rustc-cfg=ossl110");
     }
     if version >= 0x1_01_00_07_0 {
-        println!("cargo:rustc-cfg=ossl110g");
+        println!("cargo::rustc-cfg=ossl110g");
     }
     if version >= 0x1_01_01_00_0 {
-        println!("cargo:rustc-cfg=ossl111");
+        println!("cargo::rustc-cfg=ossl111");
     }
 }
 ```
diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md
@@ -15,7 +15,7 @@ that script and execute it just before building the package.
 // Example custom build script.
 fn main() {
     // Tell Cargo that if the given file changes, to rerun this build script.
-    println!("cargo:rerun-if-changed=src/hello.c");
+    println!("cargo::rerun-if-changed=src/hello.c");
     // Use the `cc` crate to build a C file and statically link it.
     cc::Build::new()
         .file("src/hello.c")
@@ -42,7 +42,7 @@ scripts.
 Just before a package is built, Cargo will compile a build script into an
 executable (if it has not already been built). It will then run the script,
 which may perform any number of tasks. The script may communicate with Cargo
-by printing specially formatted commands prefixed with `cargo:` to stdout.
+by printing specially formatted commands prefixed with `cargo::` to stdout.
 
 The build script will be rebuilt if any of its source files or dependencies
 change.
@@ -74,16 +74,23 @@ directory specified in the [`OUT_DIR` environment variable][build-env]. Scripts
 should not modify any files outside of that directory.
 
 Build scripts communicate with Cargo by printing to stdout. Cargo will
-interpret each line that starts with `cargo:` as an instruction that 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*
+> **Note:** The old invocation prefix `cargo:` (one colon only) is deprecated
+> and won't get any new features. To migrate, use two-colons prefix `cargo::`,
+> which was added in Rust 1.77. If you were using `cargo:KEY=VALUE` for
+> arbitrary links manifest key-value pairs, it is encouraged to switch to
+> `cargo::metadata=KEY=VALUE`. Stick to `cargo:` only if the support of Rust
+> version older than 1.77 is required.
+
+> 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*
+> [`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
@@ -99,40 +106,39 @@ configuration). The stderr output is also saved in that same directory.
 The following is a summary of the instructions that Cargo recognizes, with each
 one detailed below.
 
-* [`cargo:rerun-if-changed=PATH`](#rerun-if-changed) --- Tells Cargo when to
+* [`cargo::rerun-if-changed=PATH`](#rerun-if-changed) --- Tells Cargo when to
   re-run the script.
-* [`cargo:rerun-if-env-changed=VAR`](#rerun-if-env-changed) --- Tells Cargo when
+* [`cargo::rerun-if-env-changed=VAR`](#rerun-if-env-changed) --- Tells Cargo when
   to re-run the script.
-* [`cargo:rustc-link-arg=FLAG`](#rustc-link-arg) --- Passes custom flags to a
+* [`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-bin=BIN=FLAG`](#rustc-link-arg-bin) --- Passes custom
+* [`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
+* [`cargo::rustc-link-arg-bins=FLAG`](#rustc-link-arg-bins) --- Passes custom
   flags to a linker for binaries.
-* [`cargo:rustc-link-arg-tests=FLAG`](#rustc-link-arg-tests) --- Passes custom
+* [`cargo::rustc-link-arg-tests=FLAG`](#rustc-link-arg-tests) --- Passes custom
   flags to a linker for tests.
-* [`cargo:rustc-link-arg-examples=FLAG`](#rustc-link-arg-examples) --- Passes custom
+* [`cargo::rustc-link-arg-examples=FLAG`](#rustc-link-arg-examples) --- Passes custom
   flags to a linker for examples.
-* [`cargo:rustc-link-arg-benches=FLAG`](#rustc-link-arg-benches) --- Passes custom
+* [`cargo::rustc-link-arg-benches=FLAG`](#rustc-link-arg-benches) --- Passes custom
   flags to a linker for benchmarks.
-* [`cargo:rustc-link-lib=LIB`](#rustc-link-lib) --- Adds a library to
+* [`cargo::rustc-link-lib=LIB`](#rustc-link-lib) --- Adds a library to
   link.
-* [`cargo:rustc-link-search=[KIND=]PATH`](#rustc-link-search) --- Adds to the
+* [`cargo::rustc-link-search=[KIND=]PATH`](#rustc-link-search) --- Adds to the
   library search path.
-* [`cargo:rustc-flags=FLAGS`](#rustc-flags) --- Passes certain flags to the
+* [`cargo::rustc-flags=FLAGS`](#rustc-flags) --- Passes certain flags to the
   compiler.
-* [`cargo:rustc-cfg=KEY[="VALUE"]`](#rustc-cfg) --- Enables compile-time `cfg`
+* [`cargo::rustc-cfg=KEY[="VALUE"]`](#rustc-cfg) --- Enables compile-time `cfg`
   settings.
-* [`cargo:rustc-env=VAR=VALUE`](#rustc-env) --- Sets an environment variable.
-* [`cargo:rustc-cdylib-link-arg=FLAG`](#rustc-cdylib-link-arg) --- Passes custom
+* [`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:warning=MESSAGE`](#cargo-warning) --- Displays a warning on the
+* [`cargo::warning=MESSAGE`](#cargo-warning) --- Displays a warning on the
   terminal.
-* [`cargo:KEY=VALUE`](#the-links-manifest-key) --- Metadata, used by `links`
+* [`cargo::metadata=KEY=VALUE`](#the-links-manifest-key) --- Metadata, used by `links`
   scripts.
 
-
-### `cargo:rustc-link-arg=FLAG` {#rustc-link-arg}
+### `cargo::rustc-link-arg=FLAG` {#rustc-link-arg}
 
 The `rustc-link-arg` instruction tells Cargo to pass the [`-C link-arg=FLAG`
 option][link-arg] to the compiler, but only when building supported targets
@@ -142,23 +148,21 @@ linker script.
 
 [link-arg]: ../../rustc/codegen-options/index.md#link-arg
 
-### `cargo:rustc-link-arg-bin=BIN=FLAG` {#rustc-link-arg-bin}
+### `cargo::rustc-link-arg-bin=BIN=FLAG` {#rustc-link-arg-bin}
 
 The `rustc-link-arg-bin` instruction tells Cargo to pass the [`-C
 link-arg=FLAG` option][link-arg] to the compiler, but only when building
 the binary target with name `BIN`. Its usage is highly platform specific. It is useful
 to set a linker script or other linker options.
 
-
-### `cargo:rustc-link-arg-bins=FLAG` {#rustc-link-arg-bins}
+### `cargo::rustc-link-arg-bins=FLAG` {#rustc-link-arg-bins}
 
 The `rustc-link-arg-bins` instruction tells Cargo to pass the [`-C
 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-lib=LIB` {#rustc-link-lib}
+### `cargo::rustc-link-lib=LIB` {#rustc-link-lib}
 
 The `rustc-link-lib` instruction tells Cargo to link the given library using
 the compiler's [`-l` flag][option-link]. This is typically used to link a
@@ -182,27 +186,25 @@ 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}
+### `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}
+### `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}
+### `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}
+### `cargo::rustc-link-search=[KIND=]PATH` {#rustc-link-search}
 
 The `rustc-link-search` instruction tells Cargo to pass the [`-L`
 flag][option-search] to the compiler to add a directory to the library search
@@ -220,14 +222,14 @@ is fine).
 
 [option-search]: ../../rustc/command-line-arguments.md#option-l-search-path
 
-### `cargo:rustc-flags=FLAGS` {#rustc-flags}
+### `cargo::rustc-flags=FLAGS` {#rustc-flags}
 
 The `rustc-flags` instruction tells Cargo to pass the given space-separated
 flags to the compiler. This only allows the `-l` and `-L` flags, and is
 equivalent to using [`rustc-link-lib`](#rustc-link-lib) and
 [`rustc-link-search`](#rustc-link-search).
 
-### `cargo:rustc-cfg=KEY[="VALUE"]` {#rustc-cfg}
+### `cargo::rustc-cfg=KEY[="VALUE"]` {#rustc-cfg}
 
 The `rustc-cfg` instruction tells Cargo to pass the given value to the
 [`--cfg` flag][option-cfg] to the compiler. This may be used for compile-time
@@ -239,16 +241,16 @@ used to enable an optional dependency, or enable other Cargo features.
 Be aware that [Cargo features] use the form `feature="foo"`. `cfg` values
 passed with this flag are not restricted to that form, and may provide just a
 single identifier, or any arbitrary key/value pair. For example, emitting
-`cargo:rustc-cfg=abc` will then allow code to use `#[cfg(abc)]` (note the lack
+`cargo::rustc-cfg=abc` will then allow code to use `#[cfg(abc)]` (note the lack
 of `feature=`). Or an arbitrary key/value pair may be used with an `=` symbol
-like `cargo:rustc-cfg=my_component="foo"`. The key should be a Rust
+like `cargo::rustc-cfg=my_component="foo"`. The key should be a Rust
 identifier, the value should be a string.
 
 [cargo features]: features.md
 [conditional compilation]: ../../reference/conditional-compilation.md
 [option-cfg]: ../../rustc/command-line-arguments.md#option-cfg
 
-### `cargo:rustc-env=VAR=VALUE` {#rustc-env}
+### `cargo::rustc-env=VAR=VALUE` {#rustc-env}
 
 The `rustc-env` instruction tells Cargo to set the given environment variable
 when compiling the package. The value can be then retrieved by the [`env!`
@@ -268,15 +270,14 @@ 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}
+### `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:warning=MESSAGE` {#cargo-warning}
+### `cargo::warning=MESSAGE` {#cargo-warning}
 
 The `warning` instruction tells Cargo to display a warning after the build
 script has finished running. Warnings are only shown for `path` dependencies
@@ -321,7 +322,7 @@ FAQ](../faq.md#why-is-cargo-rebuilding-my-code).
 
 [`exclude` and `include` fields]: manifest.md#the-exclude-and-include-fields
 
-### `cargo:rerun-if-changed=PATH` {#rerun-if-changed}
+### `cargo::rerun-if-changed=PATH` {#rerun-if-changed}
 
 The `rerun-if-changed` instruction tells Cargo to re-run the build script if
 the file at the given path has changed. Currently, Cargo only uses the
@@ -333,14 +334,14 @@ If the path points to a directory, it will scan the entire directory for
 any modifications.
 
 If the build script inherently does not need to re-run under any circumstance,
-then emitting `cargo:rerun-if-changed=build.rs` is a simple way to prevent it
+then emitting `cargo::rerun-if-changed=build.rs` is a simple way to prevent it
 from being re-run (otherwise, the default if no `rerun-if` instructions are
 emitted is to scan the entire package directory for changes). Cargo
 automatically handles whether or not the script itself needs to be recompiled,
 and of course the script will be re-run after it has been recompiled.
 Otherwise, specifying `build.rs` is redundant and unnecessary.
 
-### `cargo:rerun-if-env-changed=NAME` {#rerun-if-env-changed}
+### `cargo::rerun-if-env-changed=NAME` {#rerun-if-env-changed}
 
 The `rerun-if-env-changed` instruction tells Cargo to re-run the build script
 if the value of an environment variable of the given name has changed.
@@ -351,7 +352,6 @@ variables like `TARGET` that [Cargo sets for build scripts][build-env]. The
 environment variables in use are those received by `cargo` invocations, not
 those received by the executable of the build script.
 
-
 ## The `links` Manifest Key
 
 The `package.links` key may be set in the `Cargo.toml` manifest to declare
