Add -C hint-mostly-unused to tell rustc that most of a crate will go unused

compiler/rustc_interface/src/tests.rs

@@ -615,6 +615,7 @@ fn test_codegen_options_tracking_hash() {
     tracked!(embed_bitcode, false);
     tracked!(force_frame_pointers, FramePointer::Always);
     tracked!(force_unwind_tables, Some(true));
+    tracked!(hint_mostly_unused, true);
     tracked!(instrument_coverage, InstrumentCoverage::Yes);
     tracked!(link_dead_code, Some(true));
     tracked!(linker_plugin_lto, LinkerPluginLto::LinkerPluginAuto);

compiler/rustc_mir_transform/src/cross_crate_inline.rs

@@ -50,6 +50,12 @@ fn cross_crate_inlinable(tcx: TyCtxt<'_>, def_id: LocalDefId) -> bool {
         _ => {}
     }
 
+    // If the crate is likely to be mostly unused, use cross-crate inlining to defer codegen until
+    // the function is referenced, in order to skip codegen for unused functions.
+    if tcx.sess.opts.cg.hint_mostly_unused {
+        return true;
+    }
+
     let sig = tcx.fn_sig(def_id).instantiate_identity();
     for ty in sig.inputs().skip_binder().iter().chain(std::iter::once(&sig.output().skip_binder()))
     {

compiler/rustc_session/src/config.rs

@@ -2441,6 +2441,12 @@ pub fn build_session_options(early_dcx: &mut EarlyDiagCtxt, matches: &getopts::M
         }
     }
 
+    if cg.hint_mostly_unused && !unstable_opts.unstable_options {
+        early_dcx.early_fatal(
+            "`-C hint-mostly-unused` requires `-Zunstable-options` and a nightly compiler",
+        )
+    }
+
     if !nightly_options::is_unstable_enabled(matches)
         && cg.force_frame_pointers == FramePointer::NonLeaf
     {

compiler/rustc_session/src/options.rs

@@ -1620,6 +1620,8 @@ options! {
     #[rustc_lint_opt_deny_field_access("use `Session::must_emit_unwind_tables` instead of this field")]
     force_unwind_tables: Option<bool> = (None, parse_opt_bool, [TRACKED],
         "force use of unwind tables"),
+    hint_mostly_unused: bool = (false, parse_bool, [TRACKED],
+        "hint that most of this crate will go unused, to minimize work for uncalled functions"),
     incremental: Option<String> = (None, parse_opt_string, [UNTRACKED],
         "enable incremental compilation"),
     #[rustc_lint_opt_deny_field_access("documented to do nothing")]

src/doc/rustc/src/codegen-options/index.md

@@ -172,6 +172,25 @@ values:
 
 The default if not specified depends on the target.
 
+## hint-mostly-unused
+
+This flag hints to the compiler that most of the crate will probably go unused.
+The compiler can optimize its operation based on this assumption, in order to
+compile faster. This is a hint, and does not guarantee any particular behavior.
+
+This option can substantially speed up compilation if applied to a large
+dependency where the majority of the dependency does not get used. This flag
+may slow down compilation in other cases.
+
+Currently, this option makes the compiler defer as much code generation as
+possible from functions in the crate, until later crates invoke those
+functions. Functions that never get invoked will never have code generated for
+them. For instance, if a crate provides thousands of functions, but only a few
+of them will get called, this flag will result in the compiler only doing code
+generation for the called functions. (This uses the same mechanisms as
+cross-crate inlining of functions.) This does not affect `extern` functions, or
+functions marked as `#[inline(never)]`.
+
 ## incremental
 
 This flag allows you to enable incremental compilation, which allows `rustc`