Rollup merge of #91606 - joshtriplett:stabilize-print-link-args, r=pnkfelix

Stabilize `-Z print-link-args` as `--print link-args`

We have stable options for adding linker arguments; we should have a
stable option to help debug linker arguments.

Add documentation for the new option. In the documentation, make it clear that
the *exact* format of the output is not a stable guarantee.

Author: matthiaskrgr

compiler/rustc_codegen_ssa/src/back/link.rs

@@ -667,7 +667,7 @@ fn link_natively<'a, B: ArchiveBuilder<'a>>(
         cmd.env_remove(k);
     }
 
-    if sess.opts.debugging_opts.print_link_args {
+    if sess.opts.prints.contains(&PrintRequest::LinkArgs) {
         println!("{:?}", &cmd);
     }
 

compiler/rustc_driver/src/lib.rs

@@ -645,9 +645,9 @@ impl RustcDefaultCalls {
         temps_dir: &Option<PathBuf>,
     ) -> Compilation {
         use rustc_session::config::PrintRequest::*;
-        // PrintRequest::NativeStaticLibs is special - printed during linking
+        // NativeStaticLibs and LinkArgs are special - printed during linking
         // (empty iterator returns true)
-        if sess.opts.prints.iter().all(|&p| p == PrintRequest::NativeStaticLibs) {
+        if sess.opts.prints.iter().all(|&p| p == NativeStaticLibs || p == LinkArgs) {
             return Compilation::Continue;
         }
 
@@ -738,7 +738,8 @@ impl RustcDefaultCalls {
                     codegen_backend.print(*req, sess);
                 }
                 // Any output here interferes with Cargo's parsing of other printed output
-                PrintRequest::NativeStaticLibs => {}
+                NativeStaticLibs => {}
+                LinkArgs => {}
             }
         }
         Compilation::Stop

compiler/rustc_interface/src/tests.rs

@@ -678,7 +678,6 @@ fn test_debugging_options_tracking_hash() {
     // `pre_link_arg` is omitted because it just forwards to `pre_link_args`.
     untracked!(pre_link_args, vec![String::from("abc"), String::from("def")]);
     untracked!(profile_closures, true);
-    untracked!(print_link_args, true);
     untracked!(print_llvm_passes, true);
     untracked!(print_mono_items, Some(String::from("abc")));
     untracked!(print_type_sizes, true);

compiler/rustc_session/src/config.rs

@@ -565,6 +565,7 @@ pub enum PrintRequest {
     TargetSpec,
     NativeStaticLibs,
     StackProtectorStrategies,
+    LinkArgs,
 }
 
 #[derive(Copy, Clone)]
@@ -1187,7 +1188,8 @@ pub fn rustc_short_optgroups() -> Vec<RustcOptGroup> {
             "Compiler information to print on stdout",
             "[crate-name|file-names|sysroot|target-libdir|cfg|target-list|\
              target-cpus|target-features|relocation-models|code-models|\
-             tls-models|target-spec-json|native-static-libs|stack-protector-strategies]",
+             tls-models|target-spec-json|native-static-libs|stack-protector-strategies\
+             link-args]",
         ),
         opt::flagmulti_s("g", "", "Equivalent to -C debuginfo=2"),
         opt::flagmulti_s("O", "", "Equivalent to -C opt-level=2"),
@@ -1619,6 +1621,7 @@ fn collect_print_requests(
                 );
             }
         }
+        "link-args" => PrintRequest::LinkArgs,
         req => early_error(error_format, &format!("unknown print request `{}`", req)),
     }));
 

compiler/rustc_session/src/options.rs

@@ -1339,8 +1339,6 @@ options! {
         See #77382 and #74551."),
     print_fuel: Option<String> = (None, parse_opt_string, [TRACKED],
         "make rustc print the total optimization fuel used by a crate"),
-    print_link_args: bool = (false, parse_bool, [UNTRACKED],
-        "print the arguments passed to the linker (default: no)"),
     print_llvm_passes: bool = (false, parse_bool, [UNTRACKED],
         "print the LLVM optimization passes being run (default: no)"),
     print_mono_items: Option<String> = (None, parse_opt_string, [UNTRACKED],

src/doc/rustc/src/command-line-arguments.md

@@ -170,6 +170,12 @@ The valid types of print values are:
   include a diagnostic note that indicates the linker flags to use when
   linking the resulting static library. The note starts with the text
   `native-static-libs:` to make it easier to fetch the output.
+- `link-args` — This flag does not disable the `--emit` step. When linking,
+  this flag causes `rustc` to print the full linker invocation in a
+  human-readable form. This can be useful when debugging linker options. The
+  exact format of this debugging output is not a stable guarantee, other than
+  that it will include the linker executable and the text of each command-line
+  argument passed to the linker.
 
 [conditional compilation]: ../reference/conditional-compilation.html
 

src/test/run-make-fulldeps/codegen-options-parsing/Makefile

@@ -24,8 +24,8 @@ all:
 	$(RUSTC) -C lto dummy.rs
 
 	# Should not link dead code...
-	$(RUSTC) -Z print-link-args dummy.rs 2>&1 | \
+	$(RUSTC) --print link-args dummy.rs 2>&1 | \
 		$(CGREP) -e '--gc-sections|-z[^ ]* [^ ]*<ignore>|-dead_strip|/OPT:REF'
 	# ... unless you specifically ask to keep it
-	$(RUSTC) -Z print-link-args -C link-dead-code dummy.rs 2>&1 | \
+	$(RUSTC) --print link-args -C link-dead-code dummy.rs 2>&1 | \
 		$(CGREP) -ve '--gc-sections|-z[^ ]* [^ ]*<ignore>|-dead_strip|/OPT:REF'

src/test/run-make-fulldeps/interdependent-c-libraries/Makefile

@@ -11,4 +11,4 @@
 all: $(call NATIVE_STATICLIB,foo) $(call NATIVE_STATICLIB,bar)
 	$(RUSTC) foo.rs
 	$(RUSTC) bar.rs
-	$(RUSTC) main.rs -Z print-link-args
+	$(RUSTC) main.rs --print link-args

src/test/run-make-fulldeps/link-arg/Makefile

@@ -1,5 +1,5 @@
 -include ../tools.mk
-RUSTC_FLAGS = -C link-arg="-lfoo" -C link-arg="-lbar" -Z print-link-args
+RUSTC_FLAGS = -C link-arg="-lfoo" -C link-arg="-lbar" --print link-args
 
 all:
 	$(RUSTC) $(RUSTC_FLAGS) empty.rs | $(CGREP) lfoo lbar

src/test/run-make-fulldeps/metadata-flag-frobs-symbols/Makefile

@@ -6,5 +6,5 @@ all:
 	$(RUSTC) bar.rs \
 		--extern foo1=$(TMPDIR)/libfoo-a.rlib \
 		--extern foo2=$(TMPDIR)/libfoo-b.rlib \
-		-Z print-link-args
+		--print link-args
 	$(call RUN,bar)

src/test/run-make-fulldeps/no-builtins-lto/Makefile

@@ -6,4 +6,4 @@ all:
 	# Build an executable that depends on that crate using LTO. The no_builtins crate doesn't
 	# participate in LTO, so its rlib must be explicitly linked into the final binary. Verify this by
 	# grepping the linker arguments.
-	$(RUSTC) main.rs -C lto -Z print-link-args | $(CGREP) 'libno_builtins.rlib'
+	$(RUSTC) main.rs -C lto --print link-args | $(CGREP) 'libno_builtins.rlib'

src/test/run-make-fulldeps/redundant-libs/Makefile

@@ -16,7 +16,7 @@ RUSTC_FLAGS = \
     -l foo \
     -l static=baz \
     -l foo \
-    -Z print-link-args
+    --print link-args
 
 all: $(call DYLIB,foo) $(call STATICLIB,bar) $(call STATICLIB,baz)
 	$(RUSTC) $(RUSTC_FLAGS) main.rs

src/test/run-make-fulldeps/static-nobundle/Makefile

@@ -13,9 +13,9 @@ all: $(call NATIVE_STATICLIB,aaa)
 	nm $(TMPDIR)/libbbb.rlib | $(CGREP) -e "U _*native_func"
 
 	# Check that aaa gets linked (either as `-l aaa` or `aaa.lib`) when building ccc.
-	$(RUSTC) ccc.rs -C prefer-dynamic --crate-type=dylib -Z print-link-args | $(CGREP) -e '-l[" ]*aaa|aaa\.lib'
+	$(RUSTC) ccc.rs -C prefer-dynamic --crate-type=dylib --print link-args | $(CGREP) -e '-l[" ]*aaa|aaa\.lib'
 
 	# Check that aaa does NOT get linked when building ddd.
-	$(RUSTC) ddd.rs -Z print-link-args | $(CGREP) -ve '-l[" ]*aaa|aaa\.lib'
+	$(RUSTC) ddd.rs --print link-args | $(CGREP) -ve '-l[" ]*aaa|aaa\.lib'
 
 	$(call RUN,ddd)