fork/rules_rust

git clone https://git.julia.blue/fork/rules_rust

Brian SilvermanPropagate rustc_env{,_files} from rust_test.crate (#1443)6ee7c80b

0.10.0
10.0 KiB274 linesraw
1# Copyright 2018 The Bazel Authors. All rights reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#    http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""Rules for performing `rustdoc --test` on Bazel built crates"""
16
17load("//rust/private:common.bzl", "rust_common")
18load("//rust/private:providers.bzl", "CrateInfo")
19load("//rust/private:rustdoc.bzl", "rustdoc_compile_action")
20load("//rust/private:utils.bzl", "dedent", "find_toolchain", "transform_deps")
21
22def _construct_writer_arguments(ctx, test_runner, opt_test_params, action, crate_info):
23    """Construct arguments and environment variables specific to `rustdoc_test_writer`.
24
25    This is largely solving for the fact that tests run from a runfiles directory
26    where actions run in an execroot. But it also tracks what environment variables
27    were explicitly added to the action.
28
29    Args:
30        ctx (ctx): The rule's context object.
31        test_runner (File): The test_runner output file declared by `rustdoc_test`.
32        opt_test_params (File): An output file we can optionally use to store params for `rustdoc`.
33        action (struct): Action arguments generated by `rustdoc_compile_action`.
34        crate_info (CrateInfo): The provider of the crate who's docs are being tested.
35
36    Returns:
37        tuple: A tuple of `rustdoc_test_writer` specific inputs
38            - Args: Arguments for the test writer
39            - dict: Required environment variables
40    """
41
42    writer_args = ctx.actions.args()
43
44    # Track the output path where the test writer should write the test
45    writer_args.add("--output={}".format(test_runner.path))
46
47    # Track where the test writer should move "spilled" Args to
48    writer_args.add("--optional_test_params={}".format(opt_test_params.path))
49
50    # Track what environment variables should be written to the test runner
51    writer_args.add("--action_env=DEVELOPER_DIR")
52    writer_args.add("--action_env=PATHEXT")
53    writer_args.add("--action_env=SDKROOT")
54    writer_args.add("--action_env=SYSROOT")
55    for var in action.env.keys():
56        writer_args.add("--action_env={}".format(var))
57
58    # Since the test runner will be running from a runfiles directory, the
59    # paths originally generated for the build action will not map to any
60    # files. To ensure rustdoc can find the appropriate dependencies, the
61    # file roots are identified and tracked for each dependency so it can be
62    # stripped from the test runner.
63
64    # Collect and dedupe all of the file roots in a list before appending
65    # them to args to prevent generating a large amount of identical args
66    roots = []
67    for dep in crate_info.deps.to_list():
68        dep_crate_info = getattr(dep, "crate_info", None)
69        dep_dep_info = getattr(dep, "dep_info", None)
70        if dep_crate_info:
71            root = dep_crate_info.output.root.path
72            if not root in roots:
73                roots.append(root)
74        if dep_dep_info:
75            for direct_dep in dep_dep_info.direct_crates.to_list():
76                root = direct_dep.dep.output.root.path
77                if not root in roots:
78                    roots.append(root)
79            for transitive_dep in dep_dep_info.transitive_crates.to_list():
80                root = transitive_dep.output.root.path
81                if not root in roots:
82                    roots.append(root)
83
84    for root in roots:
85        writer_args.add("--strip_substring={}/".format(root))
86
87    # Indicate that the rustdoc_test args are over.
88    writer_args.add("--")
89
90    # Prepare for the process runner to ingest the rest of the arguments
91    # to match the expectations of `rustc_compile_action`.
92    writer_args.add(ctx.executable._process_wrapper.short_path)
93
94    return (writer_args, action.env)
95
96def _rust_doc_test_impl(ctx):
97    """The implementation for the `rust_doc_test` rule
98
99    Args:
100        ctx (ctx): The rule's context object
101
102    Returns:
103        list: A list containing a DefaultInfo provider
104    """
105
106    toolchain = find_toolchain(ctx)
107
108    crate = ctx.attr.crate[rust_common.crate_info]
109    deps = transform_deps(ctx.attr.deps)
110
111    crate_info = rust_common.create_crate_info(
112        name = crate.name,
113        type = crate.type,
114        root = crate.root,
115        srcs = crate.srcs,
116        deps = depset(deps, transitive = [crate.deps]),
117        proc_macro_deps = crate.proc_macro_deps,
118        aliases = {},
119        output = crate.output,
120        edition = crate.edition,
121        rustc_env = crate.rustc_env,
122        rustc_env_files = crate.rustc_env_files,
123        is_test = True,
124        compile_data = crate.compile_data,
125        wrapped_crate_type = crate.type,
126        owner = ctx.label,
127    )
128
129    if toolchain.os == "windows":
130        test_runner = ctx.actions.declare_file(ctx.label.name + ".rustdoc_test.bat")
131    else:
132        test_runner = ctx.actions.declare_file(ctx.label.name + ".rustdoc_test.sh")
133
134    # Bazel will auto-magically spill params to a file, if they are too many for a given OSes shell
135    # (e.g. Windows ~32k, Linux ~2M). The executable script (aka test_runner) that gets generated,
136    # is run from the runfiles, which is separate from the params_file Bazel generates. To handle
137    # this case, we declare our own params file, that the test_writer will populate, if necessary
138    opt_test_params = ctx.actions.declare_file(ctx.label.name + ".rustdoc_opt_params", sibling = test_runner)
139
140    # Add the current crate as an extern for the compile action
141    rustdoc_flags = [
142        "--extern",
143        "{}={}".format(crate_info.name, crate_info.output.short_path),
144        "--test",
145    ]
146
147    action = rustdoc_compile_action(
148        ctx = ctx,
149        toolchain = toolchain,
150        crate_info = crate_info,
151        rustdoc_flags = rustdoc_flags,
152        is_test = True,
153    )
154
155    tools = action.tools + [ctx.executable._process_wrapper]
156
157    writer_args, env = _construct_writer_arguments(
158        ctx = ctx,
159        test_runner = test_runner,
160        opt_test_params = opt_test_params,
161        action = action,
162        crate_info = crate_info,
163    )
164
165    # Allow writer environment variables to override those from the action.
166    action.env.update(env)
167
168    ctx.actions.run(
169        mnemonic = "RustdocTestWriter",
170        progress_message = "Generating Rustdoc test runner for {}".format(ctx.attr.crate.label),
171        executable = ctx.executable._test_writer,
172        inputs = action.inputs,
173        tools = tools,
174        arguments = [writer_args] + action.arguments,
175        env = action.env,
176        outputs = [test_runner, opt_test_params],
177    )
178
179    return [DefaultInfo(
180        files = depset([test_runner]),
181        runfiles = ctx.runfiles(files = tools + [opt_test_params], transitive_files = action.inputs),
182        executable = test_runner,
183    )]
184
185rust_doc_test = rule(
186    implementation = _rust_doc_test_impl,
187    attrs = {
188        "crate": attr.label(
189            doc = (
190                "The label of the target to generate code documentation for. " +
191                "`rust_doc_test` can generate HTML code documentation for the " +
192                "source files of `rust_library` or `rust_binary` targets."
193            ),
194            providers = [rust_common.crate_info],
195            mandatory = True,
196        ),
197        "deps": attr.label_list(
198            doc = dedent("""\
199                List of other libraries to be linked to this library target.
200
201                These can be either other `rust_library` targets or `cc_library` targets if
202                linking a native library.
203            """),
204            providers = [CrateInfo, CcInfo],
205        ),
206        "_cc_toolchain": attr.label(
207            doc = (
208                "In order to use find_cc_toolchain, your rule has to depend " +
209                "on C++ toolchain. See @rules_cc//cc:find_cc_toolchain.bzl " +
210                "docs for details."
211            ),
212            default = Label("@bazel_tools//tools/cpp:current_cc_toolchain"),
213        ),
214        "_process_wrapper": attr.label(
215            doc = "A process wrapper for running rustdoc on all platforms",
216            cfg = "exec",
217            default = Label("//util/process_wrapper"),
218            executable = True,
219        ),
220        "_test_writer": attr.label(
221            doc = "A binary used for writing script for use as the test executable.",
222            cfg = "exec",
223            default = Label("//tools/rustdoc:rustdoc_test_writer"),
224            executable = True,
225        ),
226    },
227    test = True,
228    fragments = ["cpp"],
229    host_fragments = ["cpp"],
230    toolchains = [
231        str(Label("//rust:toolchain_type")),
232        "@bazel_tools//tools/cpp:toolchain_type",
233    ],
234    incompatible_use_toolchain_transition = True,
235    doc = dedent("""\
236        Runs Rust documentation tests.
237
238        Example:
239
240        Suppose you have the following directory structure for a Rust library crate:
241
242        ```output
243        [workspace]/
244        WORKSPACE
245        hello_lib/
246            BUILD
247            src/
248                lib.rs
249        ```
250
251        To run [documentation tests][doc-test] for the `hello_lib` crate, define a `rust_doc_test` \
252        target that depends on the `hello_lib` `rust_library` target:
253
254        [doc-test]: https://doc.rust-lang.org/book/documentation.html#documentation-as-tests
255
256        ```python
257        package(default_visibility = ["//visibility:public"])
258
259        load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc_test")
260
261        rust_library(
262            name = "hello_lib",
263            srcs = ["src/lib.rs"],
264        )
265
266        rust_doc_test(
267            name = "hello_lib_doc_test",
268            crate = ":hello_lib",
269        )
270        ```
271
272        Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation tests for the `hello_lib` library crate.
273    """),
274)