bazel
/
rules_rust
mirror of https://github.com/bazelbuild/rules_rust
2
0
Fork 0
Code Issues Releases Activity

Added `crate` attribute to `rustdoc` rules (deprecated `dep`) (#799)

This commit is contained in:
UebelAndre 2021-07-06 14:00:37 -07:00 committed by GitHub
parent 6df87d6227
commit dd1c73e232
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 92 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/flatten.md
View File

@ -430,7 +430,7 @@ rust_clippy(
## rust_doc
<pre>
rust_doc(<a href="#rust_doc-name">name</a>, <a href="#rust_doc-dep">dep</a>, <a href="#rust_doc-html_after_content">html_after_content</a>, <a href="#rust_doc-html_before_content">html_before_content</a>, <a href="#rust_doc-html_in_header">html_in_header</a>, <a href="#rust_doc-markdown_css">markdown_css</a>)
rust_doc(<a href="#rust_doc-name">name</a>, <a href="#rust_doc-crate">crate</a>, <a href="#rust_doc-dep">dep</a>, <a href="#rust_doc-html_after_content">html_after_content</a>, <a href="#rust_doc-html_before_content">html_before_content</a>, <a href="#rust_doc-html_in_header">html_in_header</a>, <a href="#rust_doc-markdown_css">markdown_css</a>)
</pre>
Generates code documentation.
@ -463,7 +463,7 @@ Example:
rust_doc(
name = "hello_lib_doc",
dep = ":hello_lib",
crate = ":hello_lib",
)
```
@ -476,7 +476,8 @@ Example:
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="rust_doc-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-dep"></a>dep | The label of the target to generate code documentation for.<br><br><code>rust_doc</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-crate"></a>crate | The label of the target to generate code documentation for.<br><br><code>rust_doc</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> | optional | None |
| <a id="rust_doc-dep"></a>dep | __deprecated__: use <code>crate</code> | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_doc-html_after_content"></a>html_after_content | File to add in <code>&lt;body&gt;</code>, after content. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_doc-html_before_content"></a>html_before_content | File to add in <code>&lt;body&gt;</code>, before content. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_doc-html_in_header"></a>html_in_header | File to add to <code>&lt;head&gt;</code>. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
@ -488,7 +489,7 @@ Example:
## rust_doc_test
<pre>
rust_doc_test(<a href="#rust_doc_test-name">name</a>, <a href="#rust_doc_test-dep">dep</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-dep">dep</a>)
</pre>
Runs Rust documentation tests.
@ -522,7 +523,7 @@ rust_library(
rust_doc_test(
name = "hello_lib_doc_test",
dep = ":hello_lib",
crate = ":hello_lib",
)
```
@ -535,7 +536,8 @@ Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation t
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <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-dep"></a>dep | The label of the target to run documentation tests for.<br><br><code>rust_doc_test</code> can run documentation tests 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-crate"></a>crate | The label of the target to generate code documentation for.<br><br><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> | optional | None |
| <a id="rust_doc_test-dep"></a>dep | __deprecated__: use <code>crate</code> | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
<a id="#rust_grpc_library"></a>

14
docs/rust_doc.md
View File

@ -9,7 +9,7 @@
## rust_doc
<pre>
rust_doc(<a href="#rust_doc-name">name</a>, <a href="#rust_doc-dep">dep</a>, <a href="#rust_doc-html_after_content">html_after_content</a>, <a href="#rust_doc-html_before_content">html_before_content</a>, <a href="#rust_doc-html_in_header">html_in_header</a>, <a href="#rust_doc-markdown_css">markdown_css</a>)
rust_doc(<a href="#rust_doc-name">name</a>, <a href="#rust_doc-crate">crate</a>, <a href="#rust_doc-dep">dep</a>, <a href="#rust_doc-html_after_content">html_after_content</a>, <a href="#rust_doc-html_before_content">html_before_content</a>, <a href="#rust_doc-html_in_header">html_in_header</a>, <a href="#rust_doc-markdown_css">markdown_css</a>)
</pre>
Generates code documentation.
@ -42,7 +42,7 @@ Example:
rust_doc(
name = "hello_lib_doc",
dep = ":hello_lib",
crate = ":hello_lib",
)
```
@ -55,7 +55,8 @@ Example:
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="rust_doc-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-dep"></a>dep | The label of the target to generate code documentation for.<br><br><code>rust_doc</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-crate"></a>crate | The label of the target to generate code documentation for.<br><br><code>rust_doc</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> | optional | None |
| <a id="rust_doc-dep"></a>dep | __deprecated__: use <code>crate</code> | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_doc-html_after_content"></a>html_after_content | File to add in <code>&lt;body&gt;</code>, after content. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_doc-html_before_content"></a>html_before_content | File to add in <code>&lt;body&gt;</code>, before content. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_doc-html_in_header"></a>html_in_header | File to add to <code>&lt;head&gt;</code>. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
@ -67,7 +68,7 @@ Example:
## rust_doc_test
<pre>
rust_doc_test(<a href="#rust_doc_test-name">name</a>, <a href="#rust_doc_test-dep">dep</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-dep">dep</a>)
</pre>
Runs Rust documentation tests.
@ -101,7 +102,7 @@ rust_library(
rust_doc_test(
name = "hello_lib_doc_test",
dep = ":hello_lib",
crate = ":hello_lib",
)
```
@ -114,6 +115,7 @@ Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation t
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <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-dep"></a>dep | The label of the target to run documentation tests for.<br><br><code>rust_doc_test</code> can run documentation tests 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-crate"></a>crate | The label of the target to generate code documentation for.<br><br><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> | optional | None |
| <a id="rust_doc_test-dep"></a>dep | __deprecated__: use <code>crate</code> | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |

4
examples/ffi/rust_calling_c/BUILD.bazel
View File

@ -21,7 +21,7 @@ rust_test(
rust_doc(
name = "matrix_doc",
dep = ":matrix",
crate = ":matrix",
)
## Do the same as above, but with a dynamic c library.
@ -46,5 +46,5 @@ rust_test(
rust_doc(
name = "matrix_dylib_doc",
dep = ":matrix_dynamically_linked",
crate = ":matrix_dynamically_linked",
)

4
examples/fibonacci/BUILD.bazel
View File

@ -29,10 +29,10 @@ rust_benchmark(
rust_doc(
name = "fibonacci_doc",
dep = ":fibonacci",
crate = ":fibonacci",
)
rust_doc_test(
name = "fibonacci_doc_test",
dep = ":fibonacci",
crate = ":fibonacci",
)

4
examples/hello_lib/BUILD.bazel
View File

@ -79,12 +79,12 @@ rust_test(
rust_doc(
name = "hello_lib_doc",
dep = ":hello_lib",
crate = ":hello_lib",
)
rust_doc_test(
name = "hello_lib_doc_test",
dep = ":hello_lib",
crate = ":hello_lib",
)
rust_analyzer(

2
examples/hello_world/BUILD.bazel
View File

@ -14,5 +14,5 @@ rust_binary(
rust_doc(
name = "hello_world_doc",
dep = ":hello_world",
crate = ":hello_world",
)

4
examples/proc_macro/BUILD.bazel
View File

@ -38,10 +38,10 @@ rust_test(
rust_doc(
name = "proc_macro_lib_doc",
dep = ":proc_macro_lib",
crate = ":proc_macro_lib",
)
rust_doc_test(
name = "doc_test",
dep = ":proc_macro_lib",
crate = ":proc_macro_lib",
)

43
rust/private/rustdoc.bzl
View File

@ -48,7 +48,7 @@ Example:
rust_doc(
name = "hello_lib_doc",
dep = ":hello_lib",
crate = ":hello_lib",
)
```
@ -62,11 +62,18 @@ def _rust_doc_impl(ctx):
Args:
ctx (ctx): The rule's context object
"""
if rust_common.crate_info not in ctx.attr.dep:
fail("Expected rust_library or rust_binary.", "dep")
crate = ctx.attr.dep[rust_common.crate_info]
dep_info = ctx.attr.dep[rust_common.dep_info]
if ctx.attr.crate and ctx.attr.dep:
fail("{} should only use the `crate` attribute. `dep` is deprecated".format(
ctx.label,
))
crate = ctx.attr.crate or ctx.attr.dep
if not crate:
fail("{} is missing the `crate` attribute".format(ctx.label))
crate_info = crate[rust_common.crate_info]
dep_info = crate[rust_common.dep_info]
toolchain = find_toolchain(ctx)
@ -74,7 +81,7 @@ def _rust_doc_impl(ctx):
[c.output for c in dep_info.transitive_crates.to_list()] +
[toolchain.rust_doc],
transitive = [
crate.srcs,
crate_info.srcs,
toolchain.rustc_lib.files,
toolchain.rust_lib.files,
],
@ -82,14 +89,14 @@ def _rust_doc_impl(ctx):
output_dir = ctx.actions.declare_directory(ctx.label.name)
args = ctx.actions.args()
args.add(crate.root.path)
args.add("--crate-name", crate.name)
args.add("--crate-type", crate.type)
if crate.type == "proc-macro":
args.add(crate_info.root.path)
args.add("--crate-name", crate_info.name)
args.add("--crate-type", crate_info.type)
if crate_info.type == "proc-macro":
args.add("--extern")
args.add("proc_macro")
args.add("--output", output_dir.path)
add_edition_flags(args, crate)
add_edition_flags(args, crate_info)
# nb. rustdoc can't do anything with native link flags; we must omit them.
add_crate_link_flags(args, dep_info)
@ -108,7 +115,10 @@ def _rust_doc_impl(ctx):
outputs = [output_dir],
arguments = [args],
mnemonic = "Rustdoc",
progress_message = "Generating rustdoc for {} ({} files)".format(crate.name, len(crate.srcs.to_list())),
progress_message = "Generating rustdoc for {} ({} files)".format(
crate_info.name,
len(crate_info.srcs.to_list()),
),
)
# This rule does nothing without a single-file output, though the directory should've sufficed.
@ -139,14 +149,19 @@ rust_doc = rule(
doc = _rust_doc_doc,
implementation = _rust_doc_impl,
attrs = {
"dep": attr.label(
"crate": attr.label(
doc = (
"The label of the target to generate code documentation for.\n" +
"\n" +
"`rust_doc` can generate HTML code documentation for the source files of " +
"`rust_library` or `rust_binary` targets."
),
mandatory = True,
providers = [rust_common.crate_info],
# TODO: Make this attribute mandatory once `dep` is removed
),
"dep": attr.label(
doc = "__deprecated__: use `crate`",
providers = [rust_common.crate_info],
),
"html_after_content": attr.label(
doc = "File to add in `<body>`, after content.",

63
rust/private/rustdoc_test.bzl
View File

@ -25,31 +25,36 @@ def _rust_doc_test_impl(ctx):
Returns:
list: A list containing a DefaultInfo provider
"""
if rust_common.crate_info not in ctx.attr.dep:
fail("Expected rust library or binary.", "dep")
if ctx.attr.crate and ctx.attr.dep:
fail("{} should only use the `crate` attribute. `dep` is deprecated".format(
ctx.label,
))
crate = ctx.attr.dep[rust_common.crate_info]
crate = ctx.attr.crate or ctx.attr.dep
if not crate:
fail("{} is missing the `crate` attribute".format(ctx.label))
toolchain = find_toolchain(ctx)
dep_info = ctx.attr.dep[rust_common.dep_info]
crate_info = crate[rust_common.crate_info]
dep_info = crate[rust_common.dep_info]
# Construct rustdoc test command, which will be written to a shell script
# to be executed to run the test.
flags = _build_rustdoc_flags(dep_info, crate)
flags = _build_rustdoc_flags(dep_info, crate_info)
if toolchain.os != "windows":
rust_doc_test = _build_rustdoc_test_bash_script(ctx, toolchain, flags, crate)
rust_doc_test = _build_rustdoc_test_bash_script(ctx, toolchain, flags, crate_info)
else:
rust_doc_test = _build_rustdoc_test_batch_script(ctx, toolchain, flags, crate)
rust_doc_test = _build_rustdoc_test_batch_script(ctx, toolchain, flags, crate_info)
# The test script compiles the crate and runs it, so it needs both compile and runtime inputs.
compile_inputs = depset(
[crate.output] +
[crate_info.output] +
[toolchain.rust_doc] +
[toolchain.rustc] +
toolchain.crosstool_files,
transitive = [
crate.srcs,
crate_info.srcs,
dep_info.transitive_libs,
toolchain.rustc_lib.files,
toolchain.rust_lib.files,
@ -77,12 +82,12 @@ def _dirname(path_str):
"""
return "/".join(path_str.split("/")[:-1])
def _build_rustdoc_flags(dep_info, crate):
def _build_rustdoc_flags(dep_info, crate_info):
"""Constructs the rustdoc script used to test `crate`.
Args:
dep_info (DepInfo): The DepInfo provider
crate (CrateInfo): The CrateInfo provider
crate_info (CrateInfo): The CrateInfo provider
Returns:
list: A list of rustdoc flags (str)
@ -94,7 +99,7 @@ def _build_rustdoc_flags(dep_info, crate):
link_flags = []
link_search_flags = []
link_flags.append("--extern=" + crate.name + "=" + crate.output.short_path)
link_flags.append("--extern=" + crate_info.name + "=" + crate_info.output.short_path)
link_flags += ["--extern=" + c.name + "=" + c.dep.output.short_path for c in d.direct_crates.to_list()]
link_search_flags += ["-Ldependency={}".format(_dirname(c.output.short_path)) for c in d.transitive_crates.to_list()]
@ -109,10 +114,10 @@ def _build_rustdoc_flags(dep_info, crate):
link_flags.append("-Lnative={}".format(_dirname(f.short_path)))
link_search_flags.append("-Lnative={}".format(_dirname(f.short_path)))
if crate.type == "proc-macro":
if crate_info.type == "proc-macro":
link_flags.extend(["--extern", "proc_macro"])
edition_flags = ["--edition={}".format(crate.edition)] if crate.edition != "2015" else []
edition_flags = ["--edition={}".format(crate_info.edition)] if crate_info.edition != "2015" else []
return link_search_flags + link_flags + edition_flags
@ -127,14 +132,14 @@ set -e;
{flags}
"""
def _build_rustdoc_test_bash_script(ctx, toolchain, flags, crate):
def _build_rustdoc_test_bash_script(ctx, toolchain, flags, crate_info):
"""Generates a helper script for executing a rustdoc test for unix systems
Args:
ctx (ctx): The `rust_doc_test` rule's context object
toolchain (ToolchainInfo): A rustdoc toolchain
flags (list): A list of rustdoc flags (str)
crate (CrateInfo): The CrateInfo provider
crate_info (CrateInfo): The CrateInfo provider
Returns:
File: An executable containing information for a rustdoc test
@ -146,8 +151,8 @@ def _build_rustdoc_test_bash_script(ctx, toolchain, flags, crate):
output = rust_doc_test,
content = _rustdoc_test_bash_script.format(
rust_doc = toolchain.rust_doc.short_path,
crate_root = crate.root.path,
crate_name = crate.name,
crate_root = crate_info.root.path,
crate_name = crate_info.name,
# TODO: Should be possible to do this with ctx.actions.Args, but can't seem to get them as a str and into the template.
flags = " \\\n ".join(flags),
),
@ -162,14 +167,14 @@ _rustdoc_test_batch_script = """\
{flags}
"""
def _build_rustdoc_test_batch_script(ctx, toolchain, flags, crate):
def _build_rustdoc_test_batch_script(ctx, toolchain, flags, crate_info):
"""Generates a helper script for executing a rustdoc test for windows systems
Args:
ctx (ctx): The `rust_doc_test` rule's context object
toolchain (ToolchainInfo): A rustdoc toolchain
flags (list): A list of rustdoc flags (str)
crate (CrateInfo): The CrateInfo provider
crate_info (CrateInfo): The CrateInfo provider
Returns:
File: An executable containing information for a rustdoc test
@ -181,8 +186,8 @@ def _build_rustdoc_test_batch_script(ctx, toolchain, flags, crate):
output = rust_doc_test,
content = _rustdoc_test_batch_script.format(
rust_doc = toolchain.rust_doc.short_path.replace("/", "\\"),
crate_root = crate.root.path,
crate_name = crate.name,
crate_root = crate_info.root.path,
crate_name = crate_info.name,
# TODO: Should be possible to do this with ctx.actions.Args, but can't seem to get them as a str and into the template.
flags = " ^\n ".join(flags),
),
@ -193,14 +198,18 @@ def _build_rustdoc_test_batch_script(ctx, toolchain, flags, crate):
rust_doc_test = rule(
implementation = _rust_doc_test_impl,
attrs = {
"dep": attr.label(
"crate": attr.label(
doc = (
"The label of the target to run documentation tests for.\n" +
"The label of the target to generate code documentation for.\n" +
"\n" +
"`rust_doc_test` can run documentation tests for the source files of " +
"`rust_doc_test` can generate HTML code documentation for the source files of " +
"`rust_library` or `rust_binary` targets."
),
mandatory = True,
providers = [rust_common.crate_info],
# TODO: Make this attribute mandatory once `dep` is removed
),
"dep": attr.label(
doc = "__deprecated__: use `crate`",
providers = [rust_common.crate_info],
),
},
@ -240,7 +249,7 @@ rust_library(
rust_doc_test(
name = "hello_lib_doc_test",
dep = ":hello_lib",
crate = ":hello_lib",
)
```

2
test/chained_direct_deps/BUILD.bazel
View File

@ -42,5 +42,5 @@ rust_test(
rust_doc_test(
name = "mod3_doc_test",
dep = ":mod3",
crate = ":mod3",
)

2
tools/runfiles/BUILD.bazel
View File

@ -19,5 +19,5 @@ rust_test(
rust_doc_test(
name = "runfiles_doc_test",
dep = ":runfiles",
crate = ":runfiles",
)