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