fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
66bcafef
main
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 25This is largely solving for the fact that tests run from a runfiles directory 26where actions run in an execroot. But it also tracks what environment variables 27were explicitly added to the action. 28 29Args: 30ctx (ctx): The rule's context object. 31test_runner (File): The test_runner output file declared by `rustdoc_test`. 32opt_test_params (File): An output file we can optionally use to store params for `rustdoc`. 33action (struct): Action arguments generated by `rustdoc_compile_action`. 34crate_info (CrateInfo): The provider of the crate who's docs are being tested. 35 36Returns: 37tuple: A tuple of `rustdoc_test_writer` specific inputs 38- Args: Arguments for the test writer 39- dict: Required environment variables 40""" 41 42writer_args = ctx . actions . args () 43 44# Track the output path where the test writer should write the test 45writer_args . add ( "--output={}" . format ( test_runner . path )) 46 47# Track where the test writer should move "spilled" Args to 48writer_args . add ( "--optional_test_params={}" . format ( opt_test_params . path )) 49 50# Track what environment variables should be written to the test runner 51writer_args . add ( "--action_env=DEVELOPER_DIR" ) 52writer_args . add ( "--action_env=PATHEXT" ) 53writer_args . add ( "--action_env=SDKROOT" ) 54writer_args . add ( "--action_env=SYSROOT" ) 55for var in action . env . keys (): 56writer_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 66roots = [] 67root = crate_info . output . root . path 68if not root in roots : 69roots . append ( root ) 70for dep in crate_info . deps . to_list () + crate_info . proc_macro_deps . to_list (): 71dep_crate_info = getattr ( dep , "crate_info" , None ) 72dep_dep_info = getattr ( dep , "dep_info" , None ) 73if dep_crate_info : 74root = dep_crate_info . output . root . path 75if not root in roots : 76roots . append ( root ) 77if dep_dep_info : 78for direct_dep in dep_dep_info . direct_crates . to_list (): 79root = direct_dep . dep . output . root . path 80if not root in roots : 81roots . append ( root ) 82for transitive_dep in dep_dep_info . transitive_crates . to_list (): 83root = transitive_dep . output . root . path 84if not root in roots : 85roots . append ( root ) 86 87for root in roots : 88writer_args . add ( "--strip_substring={}/" . format ( root )) 89 90# Indicate that the rustdoc_test args are over. 91writer_args . add ( "--" ) 92 93# Prepare for the process runner to ingest the rest of the arguments 94# to match the expectations of `rustc_compile_action`. 95writer_args . add ( ctx . executable . _process_wrapper . short_path ) 96 97return ( writer_args , action . env ) 98 99def _rust_doc_test_impl ( ctx ): 100"""The implementation for the `rust_doc_test` rule 101 102Args: 103ctx (ctx): The rule's context object 104 105Returns: 106list: A list containing a DefaultInfo provider 107""" 108 109toolchain = find_toolchain ( ctx ) 110 111crate = ctx . attr . crate [ rust_common . crate_info ] 112deps = transform_deps ( ctx . attr . deps ) 113proc_macro_deps = transform_deps ( ctx . attr . proc_macro_deps ) 114 115crate_info = rust_common . create_crate_info ( 116name = crate . name , 117type = crate . type , 118root = crate . root , 119srcs = crate . srcs , 120deps = depset ( deps , transitive = [ crate . deps ]), 121proc_macro_deps = depset ( proc_macro_deps , transitive = [ crate . proc_macro_deps ]), 122aliases = crate . aliases , 123output = crate . output , 124edition = crate . edition , 125rustc_env = crate . rustc_env , 126rustc_env_files = crate . rustc_env_files , 127is_test = True , 128compile_data = crate . compile_data , 129compile_data_targets = crate . compile_data_targets , 130wrapped_crate_type = crate . type , 131owner = ctx . label , 132) 133 134if toolchain . target_os == "windows" : 135test_runner = ctx . actions . declare_file ( ctx . label . name + ".rustdoc_test.bat" ) 136else : 137test_runner = ctx . actions . declare_file ( ctx . label . name + ".rustdoc_test.sh" ) 138 139# Bazel will auto-magically spill params to a file, if they are too many for a given OSes shell 140# (e.g. Windows ~32k, Linux ~2M). The executable script (aka test_runner) that gets generated, 141# is run from the runfiles, which is separate from the params_file Bazel generates. To handle 142# this case, we declare our own params file, that the test_writer will populate, if necessary 143opt_test_params = ctx . actions . declare_file ( ctx . label . name + ".rustdoc_opt_params" , sibling = test_runner ) 144 145# Add the current crate as an extern for the compile action 146rustdoc_flags = [ 147"--extern" , 148"{}={}" . format ( crate_info . name , crate_info . output . short_path ), 149"--test" , 150] 151 152action = rustdoc_compile_action ( 153ctx = ctx , 154toolchain = toolchain , 155crate_info = crate_info , 156rustdoc_flags = rustdoc_flags , 157is_test = True , 158) 159 160tools = action . tools + [ ctx . executable . _process_wrapper ] 161 162writer_args , env = _construct_writer_arguments ( 163ctx = ctx , 164test_runner = test_runner , 165opt_test_params = opt_test_params , 166action = action , 167crate_info = crate_info , 168) 169 170# Allow writer environment variables to override those from the action. 171action . env . update ( env ) 172 173ctx . actions . run ( 174mnemonic = "RustdocTestWriter" , 175progress_message = "Generating Rustdoc test runner for {}" . format ( ctx . attr . crate . label ), 176executable = ctx . executable . _test_writer , 177inputs = action . inputs , 178tools = tools , 179arguments = [ writer_args ] + action . arguments , 180env = action . env , 181outputs = [ test_runner , opt_test_params ], 182) 183 184return [ DefaultInfo ( 185files = depset ([ test_runner ]), 186runfiles = ctx . runfiles ( files = tools + [ opt_test_params ], transitive_files = action . inputs ), 187executable = test_runner , 188)] 189 190rust_doc_test = rule ( 191implementation = _rust_doc_test_impl , 192attrs = { 193"crate" : attr . label ( 194doc = ( 195"The label of the target to generate code documentation for. " + 196"`rust_doc_test` can generate HTML code documentation for the " + 197"source files of `rust_library` or `rust_binary` targets." 198), 199providers = [ rust_common . crate_info ], 200mandatory = True , 201), 202"deps" : attr . label_list ( 203doc = dedent ( """\ 204List of other libraries to be linked to this library target. 205 206These can be either other `rust_library` targets or `cc_library` targets if 207linking a native library. 208""" ), 209providers = [[ CrateInfo ], [ CcInfo ]], 210), 211"proc_macro_deps" : attr . label_list ( 212doc = dedent ( """\ 213List of `rust_proc_macro` targets used to help build this library target. 214""" ), 215cfg = "exec" , 216providers = [ rust_common . crate_info ], 217), 218"_cc_toolchain" : attr . label ( 219doc = ( 220"In order to use find_cc_toolchain, your rule has to depend " + 221"on C++ toolchain. See @rules_cc//cc:find_cc_toolchain.bzl " + 222"docs for details." 223), 224default = Label ( "@bazel_tools//tools/cpp:current_cc_toolchain" ), 225), 226"_process_wrapper" : attr . label ( 227doc = "A process wrapper for running rustdoc on all platforms" , 228cfg = "exec" , 229default = Label ( "//util/process_wrapper" ), 230executable = True , 231), 232"_test_writer" : attr . label ( 233doc = "A binary used for writing script for use as the test executable." , 234cfg = "exec" , 235default = Label ( "//tools/rustdoc:rustdoc_test_writer" ), 236executable = True , 237), 238}, 239test = True , 240fragments = [ "cpp" ], 241toolchains = [ 242str ( Label ( "//rust:toolchain_type" )), 243"@bazel_tools//tools/cpp:toolchain_type" , 244], 245doc = dedent ( """\ 246Runs Rust documentation tests. 247 248Example: 249 250Suppose you have the following directory structure for a Rust library crate: 251 252```output 253[workspace]/ 254WORKSPACE 255hello_lib/ 256BUILD 257src/ 258lib.rs 259``` 260 261To run [documentation tests][doc-test] for the `hello_lib` crate, define a `rust_doc_test` \ 262target that depends on the `hello_lib` `rust_library` target: 263 264[doc-test]: https://doc.rust-lang.org/book/documentation.html#documentation-as-tests 265 266```python 267package(default_visibility = ["//visibility:public"]) 268 269load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc_test") 270 271rust_library( 272name = "hello_lib", 273srcs = ["src/lib.rs"], 274) 275 276rust_doc_test( 277name = "hello_lib_doc_test", 278crate = ":hello_lib", 279) 280``` 281 282Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation tests for the `hello_lib` library crate. 283""" ), 284)