[rust][build] flags from rust-lang/rfcs#3662

* Now that rust-lang/rfc#3662 the implementation PR have landed, we can
  enable this once we roll the toolchain
* Adds mergeable cross-crate info to fx rustdoc-link
* Use the `--parts-out-dir`, `--include-parts-dir`, and `--merge` flags
  from the rfc in rust_auxiliary.gni and rustdoc-link.py
* Tested change with rust toolchain defined in
  rust-lang/rust@b529e27

Bug: 360942359
Fixed: 360942359
Change-Id: Iea9b0243f96394c87c66290c58ced55d791b5495
Reviewed-on: https://fuchsia-review.googlesource.com/c/fuchsia/+/1100827
Commit-Queue: Ethan Williams <[email protected]>
Reviewed-by: Julia Ryan <[email protected]>
Reviewed-by: Jay Zhuang <[email protected]>

Author: EtomicBomb

BUILD.gn

@@ -1790,57 +1790,67 @@ group("rbe_config.metadata") {
 # Type: list(scope)
 #
 #   actual_label
-#       - Required: Label for target that invokes rustc
+#       - Description: label for target that invokes rustc
 #       - Type: label_with_toolchain
 #       - Example: //src/lib/fuchsia-async:fuchsia-async.actual(//build/toolchain:host_x64)
 #   disable_clippy
-#       - Required: whether the clippy target is put into the build graph
+#       - Description: whether the clippy target is put into the build graph
 #       - Type: boolean
 #   disable_rustdoc
-#       - Required: whether the rustdoc target is put into the build graph
+#       - Whether the rustdoc target is put into the build graph
 #       - Type: boolean
 #   clippy_label(optional)
-#       - Required: Label for target that invokes clippy
+#       - Description: Label for target that invokes clippy
 #       - Present: this field is only guaranteed for !disable_clippy
 #       - Type: label_with_toolchain
 #       - Example: //src/lib/fuchsia-async:fuchsia-async.actual.clippy(//build/toolchain:host_x64)
 #   clippy_output(optional)
-#       - Required: file that contains the clippy output
+#       - Description: file that contains the clippy output
 #       - Present: this field is only guaranteed for !disable_clippy
 #       - Type: path relative to $root_build_dir
 #       - Example: host_x64/gen/src/lib/fuchsia-async/fuchsia-async.actual.clippy
 #   original_label
-#       - Required: The original target name before a possible .actual suffix is added.
+#       - Description: The original target name before a possible .actual suffix is added.
 #         May refer to a group.
 #       - Type: label_with_toolchain
 #       - Example: //src/lib/fuchsia-async:fuchsia-async(//build/toolchain:host_x64)
 #   rustdoc_label(optional)
-#       - Required: The label of the rustdoc target
+#       - Description: The label of the rustdoc target
 #       - Present: this field is only guaranteed for !disable_rustdoc
 #       - Type: label_with_toolchain
 #       - Example: //src/lib/fuchsia-async:fuchsia-async.actual.rustdoc(//build/toolchain:host_x64)
 #   rustdoc_out_dir(optional)
-#       - Required: directory in which rustdoc output is written
+#       - Description: directory in which rustdoc output is written
 #       - Present: this field is only guaranteed for !disable_rustdoc
 #       - Type: path relative to $root_build_dir
 #       - Example: host_x64/gen/src/lib/fuchsia-async/fuchsia-async.aux.doc
+#   rustdoc_parts_dir(optional)
+#       - Description: directory in which rustdoc cross-crate linking information is written
+#       - Present: this field is only guaranteed for !disable_rustdoc
+#       - Type: path relative to $root_build_dir
+#       - Example: host_x64/gen/src/lib/fuchsia-async/fuchsia-async.aux.doc.parts
+#   target_is_fuchsia(optional)
+#       - Description: whether this is a Fuchsia target (as opposed to a host target)
+#       - Present: always
+#       - Type: boolean
+#       - Example: true
 #   rustdoc_stamp_output(optional)
-#       - Required: this file's mtime is updated when rustdoc is successfully built for a target
+#       - Description: this file's mtime is updated when rustdoc is successfully built for a target
 #       - Present: this field is only guaranteed for !disable_rustdoc
 #       - Type: path relative to $root_build_dir
 #       - Example: host_x64/gen/src/lib/fuchsia-async/fuchsia-async.aux.touch
 #   extern(optional)
-#       - Required: command line argument needed to pass to rustc to depend on this target.
+#       - Description: command line argument needed to pass to rustc to depend on this target.
 #       - Present: this field is not present on bin targets
 #       - Type: command line argument
 #       - Example: --extern=fuchsia_async=host_x64/obj/src/lib/fuchsia-async/fuchsia-async.actual/libfuchsia_async.rlib
 #   searchdir(optional)
-#       - Required: command line argument needed to pass to rustc to transitively depend on this target.
+#       - Description: command line argument needed to pass to rustc to transitively depend on this target.
 #       - Present: this field is not present on bin targets
 #       - Type: command line argument
 #       - Example: -Ldependency=host_x64/obj/src/lib/fuchsia-async/fuchsia-async.actual
 #   src(optional)
-#       - Required: list of rust source code files, relative to $root_build_dir
+#       - Description: list of rust source code files, relative to $root_build_dir
 #       - Present: this field is only guaranteed for !disable_clippy
 #       - Type: list(str)
 #       - Example: [ "../../src/lib/fuchsia-async/src/lib.rs", ... ]

build/rust/rust_auxiliary.gni

@@ -155,6 +155,11 @@ template("rust_auxiliary") {
            "clippy targets should have an original name")
     _original_target_name = target_name
   }
+  if (defined(invoker.rustdoc_parts_dir)) {
+    _rustdoc_parts_dir = invoker.rustdoc_parts_dir
+  } else {
+    _rustdoc_parts_dir = "$target_gen_dir/${target_name}.doc.parts"
+  }
 
   _define_rustdoc =
       !(defined(invoker.disable_rustdoc) && invoker.disable_rustdoc) &&
@@ -423,6 +428,13 @@ template("rust_auxiliary") {
         # rustdoc will receive remaining arguments
         rebase_path(crate_root, root_build_dir),
         "-Zunstable-options",
+
+        # Do not attempt to append to existing files in the documentation destination.
+        "--merge=none",
+
+        # Output information to be consumed by `fx rustdoc-link`.
+        "--parts-out-dir",
+        rebase_path(_rustdoc_parts_dir, root_build_dir),
         "--out-dir",
         rebase_path(_rustdoc_out_dir, root_build_dir),
         "@" + rebase_path(_transdeps_output, root_build_dir),
@@ -454,6 +466,7 @@ template("rust_auxiliary") {
     not_needed([
                  "_crate_name",
                  "_invoker_deps",
+                 "_rustdoc_parts_dir",
                  "rustflags",
                  "aliased_deps",
                ])
@@ -528,6 +541,8 @@ template("rust_auxiliary") {
             extern = "--extern=${_crate_name}=${_rlib_path}"
             searchdir = "-Ldependency=${_searchdir_path}"
           }
+          rustdoc_parts_dir = rebase_path(_rustdoc_parts_dir, root_build_dir)
+          target_is_fuchsia = is_fuchsia
           target = current_target_tuple
           clippy_output = rebase_path(_clippy_output, root_build_dir)
           src = []

build/rust/rustc_artifact.gni

@@ -206,6 +206,7 @@ template("rustc_artifact") {
                                  "sources",
                                  "testonly",
                                  "visibility",
+                                 "rustdoc_parts_dir",
                                  "zip_rustdoc_to",
                                ])
 

build/rust/rustc_library.gni

@@ -258,6 +258,7 @@ template("rustc_library") {
                              "configs",
                              "data_deps",
                              "define_rustdoc_test_override",
+                             "rustdoc_parts_dir",
                              "disable_clippy",
                              "disable_rbe",
                              "edition",

tools/devshell/contrib/lib/rust/rustdoc-link.py

@@ -38,6 +38,7 @@ class Metadata:
     rustdoc_label: str
     target: str
     rustdoc_out_dir: Path
+    rustdoc_parts_dir: Path
     touch: Path
     searchdir: str
     extern: str  # looks like --extern=CRATE_NAME=PATH
@@ -64,6 +65,7 @@ def parse(m: dict[str, Any], args: Namespace) -> Optional["Metadata"]:
             target=m["target"],
             touch=Path(f"{rustdoc_out_dir}.touch"),
             rustdoc_out_dir=rustdoc_out_dir,
+            rustdoc_parts_dir=Path(args.build_dir, m["rustdoc_parts_dir"]),
             extern=m["extern"],
             searchdir=m["searchdir"],
             disable_rustdoc=m["disable_rustdoc"],
@@ -201,13 +203,17 @@ def rustdoc_link(meta: list[Metadata], args: Namespace):
             if "fuchsia" in target
             else args.destination / "host"
         )
+
         extern = set(m.extern_arg_as_rmeta for m in meta)
 
         if not args.quiet:
             print("running rustdoc to document index for", target, file=stderr)
         with TemporaryDirectory() as tmp:
             crate_root = Path(tmp, "lib.rs")
             crate_names = [f"extern crate {m.crate_name};" for m in meta]
+            rustdoc_parts_dir = [
+                f"--include-parts-dir={m.rustdoc_parts_dir}" for m in meta
+            ]
             crate_root.write_text("\n".join(crate_names))
             argfile = Path(tmp, "argfile")
             flags = [
@@ -220,6 +226,8 @@ def rustdoc_link(meta: list[Metadata], args: Namespace):
                 f"--target={target}",
                 "-Zunstable-options",
                 f"--out-dir={dst}",
+                "--merge=finalize",
+                *rustdoc_parts_dir,
                 "--enable-index-page",
                 *extra_rustdoc_args,
             ]