fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
6ee7c80b
0.11.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 generating documentation with `rustdoc` for Bazel built crates""" 16 17load ( "//rust/private:common.bzl" , "rust_common" ) 18load ( "//rust/private:rustc.bzl" , "collect_deps" , "collect_inputs" , "construct_arguments" ) 19load ( "//rust/private:utils.bzl" , "dedent" , "find_cc_toolchain" , "find_toolchain" ) 20 21def _strip_crate_info_output ( crate_info ): 22"""Set the CrateInfo.output to None for a given CrateInfo provider. 23 24Args: 25crate_info (CrateInfo): A provider 26 27Returns: 28CrateInfo: A modified CrateInfo provider 29""" 30return rust_common . create_crate_info ( 31name = crate_info . name , 32type = crate_info . type , 33root = crate_info . root , 34srcs = crate_info . srcs , 35deps = crate_info . deps , 36proc_macro_deps = crate_info . proc_macro_deps , 37aliases = crate_info . aliases , 38# This crate info should have no output 39output = None , 40metadata = None , 41edition = crate_info . edition , 42rustc_env = crate_info . rustc_env , 43rustc_env_files = crate_info . rustc_env_files , 44is_test = crate_info . is_test , 45compile_data = crate_info . compile_data , 46) 47 48def rustdoc_compile_action ( 49ctx , 50toolchain , 51crate_info , 52output = None , 53rustdoc_flags = [], 54is_test = False ): 55"""Create a struct of information needed for a `rustdoc` compile action based on crate passed to the rustdoc rule. 56 57Args: 58ctx (ctx): The rule's context object. 59toolchain (rust_toolchain): The currently configured `rust_toolchain`. 60crate_info (CrateInfo): The provider of the crate passed to a rustdoc rule. 61output (File, optional): An optional output a `rustdoc` action is intended to produce. 62rustdoc_flags (list, optional): A list of `rustdoc` specific flags. 63is_test (bool, optional): If True, the action will be configured for `rust_doc_test` targets 64 65Returns: 66struct: A struct of some `ctx.actions.run` arguments. 67""" 68 69# If an output was provided, ensure it's used in rustdoc arguments 70if output : 71rustdoc_flags = [ 72"--output" , 73output . path , 74] + rustdoc_flags 75 76cc_toolchain , feature_configuration = find_cc_toolchain ( ctx ) 77 78dep_info , build_info , linkstamps = collect_deps ( 79deps = crate_info . deps , 80proc_macro_deps = crate_info . proc_macro_deps , 81aliases = crate_info . aliases , 82) 83 84compile_inputs , out_dir , build_env_files , build_flags_files , linkstamp_outs , ambiguous_libs = collect_inputs ( 85ctx = ctx , 86file = ctx . file , 87files = ctx . files , 88linkstamps = linkstamps , 89toolchain = toolchain , 90cc_toolchain = cc_toolchain , 91feature_configuration = feature_configuration , 92crate_info = crate_info , 93dep_info = dep_info , 94build_info = build_info , 95# If this is a rustdoc test, we need to depend on rlibs rather than .rmeta. 96force_depend_on_objects = is_test , 97) 98 99# Since this crate is not actually producing the output described by the 100# given CrateInfo, this attribute needs to be stripped to allow the rest 101# of the rustc functionality in `construct_arguments` to avoid generating 102# arguments expecting to do so. 103rustdoc_crate_info = _strip_crate_info_output ( crate_info ) 104 105args , env = construct_arguments ( 106ctx = ctx , 107attr = ctx . attr , 108file = ctx . file , 109toolchain = toolchain , 110tool_path = toolchain . rust_doc . short_path if is_test else toolchain . rust_doc . path , 111cc_toolchain = cc_toolchain , 112feature_configuration = feature_configuration , 113crate_info = rustdoc_crate_info , 114dep_info = dep_info , 115linkstamp_outs = linkstamp_outs , 116ambiguous_libs = ambiguous_libs , 117output_hash = None , 118rust_flags = rustdoc_flags , 119out_dir = out_dir , 120build_env_files = build_env_files , 121build_flags_files = build_flags_files , 122emit = [], 123remap_path_prefix = None , 124force_link = True , 125force_depend_on_objects = is_test , 126) 127 128# Because rustdoc tests compile tests outside of the sandbox, the sysroot 129# must be updated to the `short_path` equivilant as it will now be 130# a part of runfiles. 131if is_test : 132if "SYSROOT" in env : 133env . update ({ "SYSROOT" : "${{pwd}}/{}" . format ( toolchain . sysroot_short_path )}) 134 135# `rustdoc` does not support the SYSROOT environment variable. To account 136# for this, the flag must be explicitly passed to the `rustdoc` binary. 137args . rustc_flags . add ( "--sysroot=${{pwd}}/{}" . format ( toolchain . sysroot_short_path )) 138 139return struct ( 140executable = ctx . executable . _process_wrapper , 141inputs = depset ([ crate_info . output ], transitive = [ compile_inputs ]), 142env = env , 143arguments = args . all , 144tools = [ toolchain . rust_doc ], 145) 146 147def _zip_action ( ctx , input_dir , output_zip , crate_label ): 148"""Creates an archive of the generated documentation from `rustdoc` 149 150Args: 151ctx (ctx): The `rust_doc` rule's context object 152input_dir (File): A directory containing the outputs from rustdoc 153output_zip (File): The location of the output archive containing generated documentation 154crate_label (Label): The label of the crate docs are being generated for. 155""" 156args = ctx . actions . args () 157args . add ( ctx . executable . _zipper ) 158args . add ( output_zip ) 159args . add ( ctx . bin_dir . path ) 160args . add_all ([ input_dir ], expand_directories = True ) 161ctx . actions . run ( 162executable = ctx . executable . _dir_zipper , 163inputs = [ input_dir ], 164outputs = [ output_zip ], 165arguments = [ args ], 166mnemonic = "RustdocZip" , 167progress_message = "Creating RustdocZip for {}" . format ( crate_label ), 168tools = [ ctx . executable . _zipper ], 169) 170 171def _rust_doc_impl ( ctx ): 172"""The implementation of the `rust_doc` rule 173 174Args: 175ctx (ctx): The rule's context object 176""" 177 178crate = ctx . attr . crate 179crate_info = crate [ rust_common . crate_info ] 180 181output_dir = ctx . actions . declare_directory ( "{}.rustdoc" . format ( ctx . label . name )) 182 183# Add the current crate as an extern for the compile action 184rustdoc_flags = [ 185"--extern" , 186"{}={}" . format ( crate_info . name , crate_info . output . path ), 187] 188 189action = rustdoc_compile_action ( 190ctx = ctx , 191toolchain = find_toolchain ( ctx ), 192crate_info = crate_info , 193output = output_dir , 194rustdoc_flags = rustdoc_flags , 195) 196 197ctx . actions . run ( 198mnemonic = "Rustdoc" , 199progress_message = "Generating Rustdoc for {}" . format ( crate . label ), 200outputs = [ output_dir ], 201executable = action . executable , 202inputs = action . inputs , 203env = action . env , 204arguments = action . arguments , 205tools = action . tools , 206) 207 208# This rule does nothing without a single-file output, though the directory should've sufficed. 209_zip_action ( ctx , output_dir , ctx . outputs . rust_doc_zip , crate . label ) 210 211return [ 212DefaultInfo ( 213files = depset ([ ctx . outputs . rust_doc_zip ]), 214), 215OutputGroupInfo ( 216rustdoc_dir = depset ([ output_dir ]), 217rustdoc_zip = depset ([ ctx . outputs . rust_doc_zip ]), 218), 219] 220 221rust_doc = rule ( 222doc = dedent ( """\ 223Generates code documentation. 224 225Example: 226Suppose you have the following directory structure for a Rust library crate: 227 228``` 229[workspace]/ 230WORKSPACE 231hello_lib/ 232BUILD 233src/ 234lib.rs 235``` 236 237To build [`rustdoc`][rustdoc] documentation for the `hello_lib` crate, define \ 238a `rust_doc` rule that depends on the the `hello_lib` `rust_library` target: 239 240[rustdoc]: https://doc.rust-lang.org/book/documentation.html 241 242```python 243package(default_visibility = ["//visibility:public"]) 244 245load("@rules_rust//rust:defs.bzl", "rust_library", "rust_doc") 246 247rust_library( 248name = "hello_lib", 249srcs = ["src/lib.rs"], 250) 251 252rust_doc( 253name = "hello_lib_doc", 254crate = ":hello_lib", 255) 256``` 257 258Running `bazel build //hello_lib:hello_lib_doc` will build a zip file containing \ 259the documentation for the `hello_lib` library crate generated by `rustdoc`. 260""" ), 261implementation = _rust_doc_impl , 262attrs = { 263"crate" : attr . label ( 264doc = ( 265 "The label of the target to generate code documentation for.\n "+ 266 "\n "+ 267"`rust_doc` can generate HTML code documentation for the source files of " + 268"`rust_library` or `rust_binary` targets." 269), 270providers = [ rust_common . crate_info ], 271mandatory = True , 272), 273"html_after_content" : attr . label ( 274doc = "File to add in `<body>`, after content." , 275allow_single_file = [ ".html" , ".md" ], 276), 277"html_before_content" : attr . label ( 278doc = "File to add in `<body>`, before content." , 279allow_single_file = [ ".html" , ".md" ], 280), 281"html_in_header" : attr . label ( 282doc = "File to add to `<head>`." , 283allow_single_file = [ ".html" , ".md" ], 284), 285"markdown_css" : attr . label_list ( 286doc = "CSS files to include via `<link>` in a rendered Markdown file." , 287allow_files = [ ".css" ], 288), 289"rustc_flags" : attr . string_list ( 290doc = dedent ( """\ 291List of compiler flags passed to `rustc`. 292 293These strings are subject to Make variable expansion for predefined 294source/output path variables like `$location`, `$execpath`, and 295`$rootpath`. This expansion is useful if you wish to pass a generated 296file of arguments to rustc: `@$(location //package:target)`. 297""" ), 298), 299"_cc_toolchain" : attr . label ( 300doc = "In order to use find_cpp_toolchain, you must define the '_cc_toolchain' attribute on your rule or aspect." , 301default = Label ( "@bazel_tools//tools/cpp:current_cc_toolchain" ), 302), 303"_dir_zipper" : attr . label ( 304doc = "A tool that orchestrates the creation of zip archives for rustdoc outputs." , 305default = Label ( "//util/dir_zipper" ), 306cfg = "exec" , 307executable = True , 308), 309"_process_wrapper" : attr . label ( 310doc = "A process wrapper for running rustdoc on all platforms" , 311default = Label ( "@rules_rust//util/process_wrapper" ), 312executable = True , 313allow_single_file = True , 314cfg = "exec" , 315), 316"_zipper" : attr . label ( 317doc = "A Bazel provided tool for creating archives" , 318default = Label ( "@bazel_tools//tools/zip:zipper" ), 319cfg = "exec" , 320executable = True , 321), 322}, 323fragments = [ "cpp" ], 324host_fragments = [ "cpp" ], 325outputs = { 326"rust_doc_zip" : "%{name}.zip" , 327}, 328toolchains = [ 329str ( Label ( "//rust:toolchain_type" )), 330"@bazel_tools//tools/cpp:toolchain_type" , 331], 332incompatible_use_toolchain_transition = True , 333)