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