feat: support extra deps in rust_doc_test (#1286)

* feat: support extra deps in rust_doc_test

Currently, `rust_doc_test` (unlike `rust_test`) doesn't support adding
extra test-only dependencies, which makes it unnecessarily hard to
migrate doc tests from Cargo to rules_rust.

This change extends the `rust_doc_test` rust to support extra
test-only dependencies.

* sort dictionary items

I'm getting unnecessarily proficient in this.

* Regenerate documentation

* apply review feedback

* sort load statements

docs/flatten.md

@@ -465,7 +465,7 @@ Running `bazel build //hello_lib:hello_lib_doc` will build a zip file containing
 ## rust_doc_test
 
 <pre>
-rust_doc_test(<a href="#rust_doc_test-name">name</a>, <a href="#rust_doc_test-crate">crate</a>, <a href="#rust_doc_test-experimental_use_whole_archive_for_native_deps">experimental_use_whole_archive_for_native_deps</a>)
+rust_doc_test(<a href="#rust_doc_test-name">name</a>, <a href="#rust_doc_test-crate">crate</a>, <a href="#rust_doc_test-deps">deps</a>, <a href="#rust_doc_test-experimental_use_whole_archive_for_native_deps">experimental_use_whole_archive_for_native_deps</a>)
 </pre>
 
 Runs Rust documentation tests.
@@ -513,6 +513,7 @@ Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation t
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="rust_doc_test-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
 | <a id="rust_doc_test-crate"></a>crate |  The label of the target to generate code documentation for. <code>rust_doc_test</code> can generate HTML code documentation for the source files of <code>rust_library</code> or <code>rust_binary</code> targets.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required |  |
+| <a id="rust_doc_test-deps"></a>deps |  List of other libraries to be linked to this library target.<br><br>These can be either other <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="rust_doc_test-experimental_use_whole_archive_for_native_deps"></a>experimental_use_whole_archive_for_native_deps |  Whether to use +whole-archive linking modifier for native dependencies.<br><br>TODO: This is a stopgap feature and will be removed, see https://github.com/bazelbuild/rules_rust/issues/1268.   | Boolean | optional | False |
 
 

docs/rust_doc.md

@@ -69,7 +69,7 @@ Running `bazel build //hello_lib:hello_lib_doc` will build a zip file containing
 ## rust_doc_test
 
 <pre>
-rust_doc_test(<a href="#rust_doc_test-name">name</a>, <a href="#rust_doc_test-crate">crate</a>, <a href="#rust_doc_test-experimental_use_whole_archive_for_native_deps">experimental_use_whole_archive_for_native_deps</a>)
+rust_doc_test(<a href="#rust_doc_test-name">name</a>, <a href="#rust_doc_test-crate">crate</a>, <a href="#rust_doc_test-deps">deps</a>, <a href="#rust_doc_test-experimental_use_whole_archive_for_native_deps">experimental_use_whole_archive_for_native_deps</a>)
 </pre>
 
 Runs Rust documentation tests.
@@ -117,6 +117,7 @@ Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation t
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="rust_doc_test-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
 | <a id="rust_doc_test-crate"></a>crate |  The label of the target to generate code documentation for. <code>rust_doc_test</code> can generate HTML code documentation for the source files of <code>rust_library</code> or <code>rust_binary</code> targets.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required |  |
+| <a id="rust_doc_test-deps"></a>deps |  List of other libraries to be linked to this library target.<br><br>These can be either other <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="rust_doc_test-experimental_use_whole_archive_for_native_deps"></a>experimental_use_whole_archive_for_native_deps |  Whether to use +whole-archive linking modifier for native dependencies.<br><br>TODO: This is a stopgap feature and will be removed, see https://github.com/bazelbuild/rules_rust/issues/1268.   | Boolean | optional | False |
 
 

rust/private/rustdoc_test.bzl

@@ -15,8 +15,9 @@
 """Rules for performing `rustdoc --test` on Bazel built crates"""
 
 load("//rust/private:common.bzl", "rust_common")
+load("//rust/private:providers.bzl", "CrateInfo")
 load("//rust/private:rustdoc.bzl", "rustdoc_compile_action")
-load("//rust/private:utils.bzl", "dedent", "find_toolchain")
+load("//rust/private:utils.bzl", "dedent", "find_toolchain", "transform_deps")
 
 def _construct_writer_arguments(ctx, test_runner, action, crate_info):
     """Construct arguments and environment variables specific to `rustdoc_test_writer`.
@@ -90,8 +91,25 @@ def _rust_doc_test_impl(ctx):
 
     toolchain = find_toolchain(ctx)
 
-    crate = ctx.attr.crate
-    crate_info = crate[rust_common.crate_info]
+    crate = ctx.attr.crate[rust_common.crate_info]
+    deps = transform_deps(ctx.attr.deps)
+
+    crate_info = rust_common.create_crate_info(
+        name = crate.name,
+        type = crate.type,
+        root = crate.root,
+        srcs = crate.srcs,
+        deps = depset(deps, transitive = [crate.deps]),
+        proc_macro_deps = crate.proc_macro_deps,
+        aliases = {},
+        output = crate.output,
+        edition = crate.edition,
+        rustc_env = crate.rustc_env,
+        is_test = True,
+        compile_data = crate.compile_data,
+        wrapped_crate_type = crate.type,
+        owner = ctx.label,
+    )
 
     if toolchain.os == "windows":
         test_runner = ctx.actions.declare_file(ctx.label.name + ".rustdoc_test.bat")
@@ -127,7 +145,7 @@ def _rust_doc_test_impl(ctx):
 
     ctx.actions.run(
         mnemonic = "RustdocTestWriter",
-        progress_message = "Generating Rustdoc test runner for {}".format(crate.label),
+        progress_message = "Generating Rustdoc test runner for {}".format(ctx.attr.crate.label),
         executable = ctx.executable._test_writer,
         inputs = action.inputs,
         tools = tools,
@@ -154,6 +172,15 @@ rust_doc_test = rule(
             providers = [rust_common.crate_info],
             mandatory = True,
         ),
+        "deps": attr.label_list(
+            doc = dedent("""\
+                List of other libraries to be linked to this library target.
+
+                These can be either other `rust_library` targets or `cc_library` targets if
+                linking a native library.
+            """),
+            providers = [CrateInfo, CcInfo],
+        ),
         "experimental_use_whole_archive_for_native_deps": attr.bool(
             doc = dedent("""\
                 Whether to use +whole-archive linking modifier for native dependencies.

test/unit/rustdoc/adder.rs

@@ -0,0 +1,18 @@
+// Copyright 2022 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/// Increments the input.
+pub fn inc(n: u32) -> u32 {
+    n + 1
+}

test/unit/rustdoc/rustdoc_lib.rs

@@ -9,6 +9,11 @@ make_answer!();
 /// fn answer() -> u32 { 42 }
 /// assert_eq!(answer(), 42);
 /// ```
+///
+/// ```
+/// use adder::inc;
+/// assert_eq!(inc(41), 42);
+/// ```
 #[cfg(not(feature = "with_proc_macro"))]
 pub fn answer() -> u32 {
     42

test/unit/rustdoc/rustdoc_unit_test.bzl

@@ -74,7 +74,7 @@ rustdoc_for_lib_with_proc_macro_test = analysistest.make(_rustdoc_for_lib_with_p
 rustdoc_for_bin_with_transitive_proc_macro_test = analysistest.make(_rustdoc_for_bin_with_transitive_proc_macro_test_impl)
 rustdoc_for_lib_with_cc_lib_test = analysistest.make(_rustdoc_for_lib_with_cc_lib_test_impl)
 
-def _target_maker(rule_fn, name, **kwargs):
+def _target_maker(rule_fn, name, rustdoc_deps = [], **kwargs):
     rule_fn(
         name = name,
         **kwargs
@@ -93,9 +93,12 @@ def _target_maker(rule_fn, name, **kwargs):
     rust_doc_test(
         name = "{}_doctest".format(name),
         crate = ":{}".format(name),
+        deps = rustdoc_deps,
     )
 
 def _define_targets():
+    rust_library(name = "adder", srcs = ["adder.rs"])
+
     _target_maker(
         rust_binary,
         name = "bin",
@@ -106,6 +109,7 @@ def _define_targets():
         rust_library,
         name = "lib",
         srcs = ["rustdoc_lib.rs"],
+        rustdoc_deps = [":adder"],
     )
 
     _target_maker(
@@ -119,6 +123,7 @@ def _define_targets():
         rust_library,
         name = "lib_with_proc_macro",
         srcs = ["rustdoc_lib.rs"],
+        rustdoc_deps = [":adder"],
         proc_macro_deps = [":rustdoc_proc_macro"],
         crate_features = ["with_proc_macro"],
     )
@@ -142,6 +147,7 @@ def _define_targets():
         rust_library,
         name = "lib_with_cc",
         srcs = ["rustdoc_lib.rs"],
+        rustdoc_deps = [":adder"],
         crate_features = ["with_cc"],
         deps = [":cc_lib"],
     )