fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
6ee7c80b
0.10.0
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 = [] 67for dep in crate_info . deps . to_list (): 68dep_crate_info = getattr ( dep , "crate_info" , None ) 69dep_dep_info = getattr ( dep , "dep_info" , None ) 70if dep_crate_info : 71root = dep_crate_info . output . root . path 72if not root in roots : 73roots . append ( root ) 74if dep_dep_info : 75for direct_dep in dep_dep_info . direct_crates . to_list (): 76root = direct_dep . dep . output . root . path 77if not root in roots : 78roots . append ( root ) 79for transitive_dep in dep_dep_info . transitive_crates . to_list (): 80root = transitive_dep . output . root . path 81if not root in roots : 82roots . append ( root ) 83 84for root in roots : 85writer_args . add ( "--strip_substring={}/" . format ( root )) 86 87# Indicate that the rustdoc_test args are over. 88writer_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`. 92writer_args . add ( ctx . executable . _process_wrapper . short_path ) 93 94return ( writer_args , action . env ) 95 96def _rust_doc_test_impl ( ctx ): 97"""The implementation for the `rust_doc_test` rule 98 99Args: 100ctx (ctx): The rule's context object 101 102Returns: 103list: A list containing a DefaultInfo provider 104""" 105 106toolchain = find_toolchain ( ctx ) 107 108crate = ctx . attr . crate [ rust_common . crate_info ] 109deps = transform_deps ( ctx . attr . deps ) 110 111crate_info = rust_common . create_crate_info ( 112name = crate . name , 113type = crate . type , 114root = crate . root , 115srcs = crate . srcs , 116deps = depset ( deps , transitive = [ crate . deps ]), 117proc_macro_deps = crate . proc_macro_deps , 118aliases = {}, 119output = crate . output , 120edition = crate . edition , 121rustc_env = crate . rustc_env , 122rustc_env_files = crate . rustc_env_files , 123is_test = True , 124compile_data = crate . compile_data , 125wrapped_crate_type = crate . type , 126owner = ctx . label , 127) 128 129if toolchain . os == "windows" : 130test_runner = ctx . actions . declare_file ( ctx . label . name + ".rustdoc_test.bat" ) 131else : 132test_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 138opt_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 141rustdoc_flags = [ 142"--extern" , 143"{}={}" . format ( crate_info . name , crate_info . output . short_path ), 144"--test" , 145] 146 147action = rustdoc_compile_action ( 148ctx = ctx , 149toolchain = toolchain , 150crate_info = crate_info , 151rustdoc_flags = rustdoc_flags , 152is_test = True , 153) 154 155tools = action . tools + [ ctx . executable . _process_wrapper ] 156 157writer_args , env = _construct_writer_arguments ( 158ctx = ctx , 159test_runner = test_runner , 160opt_test_params = opt_test_params , 161action = action , 162crate_info = crate_info , 163) 164 165# Allow writer environment variables to override those from the action. 166action . env . update ( env ) 167 168ctx . actions . run ( 169mnemonic = "RustdocTestWriter" , 170progress_message = "Generating Rustdoc test runner for {}" . format ( ctx . attr . crate . label ), 171executable = ctx . executable . _test_writer , 172inputs = action . inputs , 173tools = tools , 174arguments = [ writer_args ] + action . arguments , 175env = action . env , 176outputs = [ test_runner , opt_test_params ], 177) 178 179return [ DefaultInfo ( 180files = depset ([ test_runner ]), 181runfiles = ctx . runfiles ( files = tools + [ opt_test_params ], transitive_files = action . inputs ), 182executable = test_runner , 183)] 184 185rust_doc_test = rule ( 186implementation = _rust_doc_test_impl , 187attrs = { 188"crate" : attr . label ( 189doc = ( 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), 194providers = [ rust_common . crate_info ], 195mandatory = True , 196), 197"deps" : attr . label_list ( 198doc = dedent ( """\ 199List of other libraries to be linked to this library target. 200 201These can be either other `rust_library` targets or `cc_library` targets if 202linking a native library. 203""" ), 204providers = [ CrateInfo , CcInfo ], 205), 206"_cc_toolchain" : attr . label ( 207doc = ( 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), 212default = Label ( "@bazel_tools//tools/cpp:current_cc_toolchain" ), 213), 214"_process_wrapper" : attr . label ( 215doc = "A process wrapper for running rustdoc on all platforms" , 216cfg = "exec" , 217default = Label ( "//util/process_wrapper" ), 218executable = True , 219), 220"_test_writer" : attr . label ( 221doc = "A binary used for writing script for use as the test executable." , 222cfg = "exec" , 223default = Label ( "//tools/rustdoc:rustdoc_test_writer" ), 224executable = True , 225), 226}, 227test = True , 228fragments = [ "cpp" ], 229host_fragments = [ "cpp" ], 230toolchains = [ 231str ( Label ( "//rust:toolchain_type" )), 232"@bazel_tools//tools/cpp:toolchain_type" , 233], 234incompatible_use_toolchain_transition = True , 235doc = dedent ( """\ 236Runs Rust documentation tests. 237 238Example: 239 240Suppose you have the following directory structure for a Rust library crate: 241 242```output 243[workspace]/ 244WORKSPACE 245hello_lib/ 246BUILD 247src/ 248lib.rs 249``` 250 251To run [documentation tests][doc-test] for the `hello_lib` crate, define a `rust_doc_test` \ 252target 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 257package(default_visibility = ["//visibility:public"]) 258 259load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc_test") 260 261rust_library( 262name = "hello_lib", 263srcs = ["src/lib.rs"], 264) 265 266rust_doc_test( 267name = "hello_lib_doc_test", 268crate = ":hello_lib", 269) 270``` 271 272Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation tests for the `hello_lib` library crate. 273""" ), 274)