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