fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
67e204ff
0.9.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 , 122is_test = True , 123compile_data = crate . compile_data , 124wrapped_crate_type = crate . type , 125owner = ctx . label , 126) 127 128if toolchain . os == "windows" : 129test_runner = ctx . actions . declare_file ( ctx . label . name + ".rustdoc_test.bat" ) 130else : 131test_runner = ctx . actions . declare_file ( ctx . label . name + ".rustdoc_test.sh" ) 132 133# Bazel will auto-magically spill params to a file, if they are too many for a given OSes shell 134# (e.g. Windows ~32k, Linux ~2M). The executable script (aka test_runner) that gets generated, 135# is run from the runfiles, which is separate from the params_file Bazel generates. To handle 136# this case, we declare our own params file, that the test_writer will populate, if necessary 137opt_test_params = ctx . actions . declare_file ( ctx . label . name + ".rustdoc_opt_params" , sibling = test_runner ) 138 139# Add the current crate as an extern for the compile action 140rustdoc_flags = [ 141"--extern" , 142"{}={}" . format ( crate_info . name , crate_info . output . short_path ), 143"--test" , 144] 145 146action = rustdoc_compile_action ( 147ctx = ctx , 148toolchain = toolchain , 149crate_info = crate_info , 150rustdoc_flags = rustdoc_flags , 151is_test = True , 152) 153 154tools = action . tools + [ ctx . executable . _process_wrapper ] 155 156writer_args , env = _construct_writer_arguments ( 157ctx = ctx , 158test_runner = test_runner , 159opt_test_params = opt_test_params , 160action = action , 161crate_info = crate_info , 162) 163 164# Allow writer environment variables to override those from the action. 165action . env . update ( env ) 166 167ctx . actions . run ( 168mnemonic = "RustdocTestWriter" , 169progress_message = "Generating Rustdoc test runner for {}" . format ( ctx . attr . crate . label ), 170executable = ctx . executable . _test_writer , 171inputs = action . inputs , 172tools = tools , 173arguments = [ writer_args ] + action . arguments , 174env = action . env , 175outputs = [ test_runner , opt_test_params ], 176) 177 178return [ DefaultInfo ( 179files = depset ([ test_runner ]), 180runfiles = ctx . runfiles ( files = tools + [ opt_test_params ], transitive_files = action . inputs ), 181executable = test_runner , 182)] 183 184rust_doc_test = rule ( 185implementation = _rust_doc_test_impl , 186attrs = { 187"crate" : attr . label ( 188doc = ( 189"The label of the target to generate code documentation for. " + 190"`rust_doc_test` can generate HTML code documentation for the " + 191"source files of `rust_library` or `rust_binary` targets." 192), 193providers = [ rust_common . crate_info ], 194mandatory = True , 195), 196"deps" : attr . label_list ( 197doc = dedent ( """\ 198List of other libraries to be linked to this library target. 199 200These can be either other `rust_library` targets or `cc_library` targets if 201linking a native library. 202""" ), 203providers = [ CrateInfo , CcInfo ], 204), 205"_cc_toolchain" : attr . label ( 206doc = ( 207"In order to use find_cc_toolchain, your rule has to depend " + 208"on C++ toolchain. See @rules_cc//cc:find_cc_toolchain.bzl " + 209"docs for details." 210), 211default = Label ( "@bazel_tools//tools/cpp:current_cc_toolchain" ), 212), 213"_process_wrapper" : attr . label ( 214doc = "A process wrapper for running rustdoc on all platforms" , 215cfg = "exec" , 216default = Label ( "//util/process_wrapper" ), 217executable = True , 218), 219"_test_writer" : attr . label ( 220doc = "A binary used for writing script for use as the test executable." , 221cfg = "exec" , 222default = Label ( "//tools/rustdoc:rustdoc_test_writer" ), 223executable = True , 224), 225}, 226test = True , 227fragments = [ "cpp" ], 228host_fragments = [ "cpp" ], 229toolchains = [ 230str ( Label ( "//rust:toolchain_type" )), 231"@bazel_tools//tools/cpp:toolchain_type" , 232], 233incompatible_use_toolchain_transition = True , 234doc = dedent ( """\ 235Runs Rust documentation tests. 236 237Example: 238 239Suppose you have the following directory structure for a Rust library crate: 240 241```output 242[workspace]/ 243WORKSPACE 244hello_lib/ 245BUILD 246src/ 247lib.rs 248``` 249 250To run [documentation tests][doc-test] for the `hello_lib` crate, define a `rust_doc_test` \ 251target that depends on the `hello_lib` `rust_library` target: 252 253[doc-test]: https://doc.rust-lang.org/book/documentation.html#documentation-as-tests 254 255```python 256package(default_visibility = ["//visibility:public"]) 257 258load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc_test") 259 260rust_library( 261name = "hello_lib", 262srcs = ["src/lib.rs"], 263) 264 265rust_doc_test( 266name = "hello_lib_doc_test", 267crate = ":hello_lib", 268) 269``` 270 271Running `bazel test //hello_lib:hello_lib_doc_test` will run all documentation tests for the `hello_lib` library crate. 272""" ), 273)