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