fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
482a21cf
gh-pages
1<!DOCTYPE HTML > 2< html lang ="en "class ="light sidebar-visible "dir ="ltr "> 3< head > 4<!-- Book generated using mdBook --> 5< meta charset ="UTF-8 "> 6< title > protobuf - rules_rust</ title > 7 8 9<!-- Custom HTML head --> 10 11< meta name ="description "content =""> 12< meta name ="viewport "content ="width=device-width, initial-scale=1 "> 13< meta name ="theme-color "content ="#ffffff "> 14 15< link rel ="icon "href ="favicon.svg "> 16< link rel ="shortcut icon "href ="favicon.png "> 17< link rel ="stylesheet "href ="css/variables.css "> 18< link rel ="stylesheet "href ="css/general.css "> 19< link rel ="stylesheet "href ="css/chrome.css "> 20< link rel ="stylesheet "href ="css/print.css "media ="> 21 22<!-- Fonts --> 23< link rel ="stylesheet "href ="FontAwesome/css/font-awesome.css "> 24< link rel ="stylesheet "href ="fonts/fonts.css "> 25 26<!-- Highlight.js Stylesheets --> 27< link rel ="stylesheet "href ="highlight.css "> 28< link rel ="stylesheet "href ="tomorrow-night.css "> 29< link rel ="stylesheet "href ="ayu-highlight.css "> 30 31<!-- Custom theme stylesheets --> 32 33 34<!-- Provide site root to javascript --> 35< script > 36var path_to_root = "" ; 37var default_theme = window . matchMedia ( "(prefers-color-scheme: dark)" ). matches ?"navy" :"light" ; 38</ script > 39<!-- Start loading toc.js asap --> 40< script src ="toc.js "></ script > 41</ head > 42< body > 43< div id ="body-container "> 44<!-- Work around some values being stored in localStorage wrapped in quotes --> 45< script > 46try { 47var theme = localStorage . getItem ( 'mdbook-theme' ); 48var sidebar = localStorage . getItem ( 'mdbook-sidebar' ); 49 50if ( theme . startsWith ( '"' ) && theme . endsWith ( '"' )) { 51localStorage . setItem ( 'mdbook-theme' , theme . slice ( 1 , theme . length - 1 )); 52} 53 54if ( sidebar . startsWith ( '"' ) && sidebar . endsWith ( '"' )) { 55localStorage . setItem ( 'mdbook-sidebar' , sidebar . slice ( 1 , sidebar . length - 1 )); 56} 57} catch ( e ) { } 58</ script > 59 60<!-- Set the theme before any content is loaded, prevents flash --> 61< script > 62var theme ; 63try { theme = localStorage . getItem ( 'mdbook-theme' ); } catch ( e ) { } 64if ( theme === null || theme === undefined ) { theme = default_theme ; } 65const html = document . documentElement ; 66html . classList . remove ( 'light' ) 67html . classList . add ( theme ); 68html . classList . add ( "js" ); 69</ script > 70 71< input type ="checkbox "id ="sidebar-toggle-anchor "class ="hidden "> 72 73<!-- Hide / unhide sidebar before it is displayed --> 74< script > 75var sidebar = null ; 76var sidebar_toggle = document . getElementById ( "sidebar-toggle-anchor" ); 77if ( document . body . clientWidth >= 1080 ) { 78try { sidebar = localStorage . getItem ( 'mdbook-sidebar' ); } catch ( e ) { } 79sidebar = sidebar || 'visible' ; 80} else { 81sidebar = 'hidden' ; 82} 83sidebar_toggle . checked = sidebar === 'visible' ; 84html . classList . remove ( 'sidebar-visible' ); 85html . classList . add ( "sidebar-" + sidebar ); 86</ script > 87 88< nav id ="sidebar "class ="sidebar "aria-label ="Table of contents "> 89<!-- populated by js --> 90< mdbook-sidebar-scrollbox class ="sidebar-scrollbox "></ mdbook-sidebar-scrollbox > 91< noscript > 92< iframe class ="sidebar-iframe-outer "src ="toc.html "></ iframe > 93</ noscript > 94< div id ="sidebar-resize-handle "class ="sidebar-resize-handle "> 95< div class ="sidebar-resize-indicator "></ div > 96</ div > 97</ nav > 98 99< div id ="page-wrapper "class ="page-wrapper "> 100 101< div class ="page "> 102< div id ="menu-bar-hover-placeholder "></ div > 103< div id ="menu-bar "class ="menu-bar sticky "> 104< div class ="left-buttons "> 105< label id ="sidebar-toggle "class ="icon-button "for ="sidebar-toggle-anchor "title ="Toggle Table of Contents "aria-label ="Toggle Table of Contents "aria-controls ="sidebar "> 106< i class ="fa fa-bars "></ i > 107</ label > 108< button id ="theme-toggle "class ="icon-button "type ="button "title ="Change theme "aria-label ="Change theme "aria-haspopup ="true "aria-expanded ="false "aria-controls ="theme-list "> 109< i class ="fa fa-paint-brush "></ i > 110</ button > 111< ul id ="theme-list "class ="theme-popup "aria-label ="Themes "role ="menu "> 112< li role ="none ">< button role ="menuitem "class ="theme "id ="light "> Light</ button ></ li > 113< li role ="none ">< button role ="menuitem "class ="theme "id ="rust "> Rust</ button ></ li > 114< li role ="none ">< button role ="menuitem "class ="theme "id ="coal "> Coal</ button ></ li > 115< li role ="none ">< button role ="menuitem "class ="theme "id ="navy "> Navy</ button ></ li > 116< li role ="none ">< button role ="menuitem "class ="theme "id ="ayu "> Ayu</ button ></ li > 117</ ul > 118< button id ="search-toggle "class ="icon-button "type ="button "title ="Search. (Shortkey: s) "aria-label ="Toggle Searchbar "aria-expanded ="false "aria-keyshortcuts ="S "aria-controls ="searchbar "> 119< i class ="fa fa-search "></ i > 120</ button > 121</ div > 122 123< h1 class ="menu-title "> rules_rust</ h1 > 124 125< div class ="right-buttons "> 126< a href ="print.html "title ="Print this book "aria-label ="Print this book "> 127< i id ="print-button "class ="fa fa-print "></ i > 128</ a > 129< a href ="https://github.com/bazelbuild/rules_rust "title ="Git repository "aria-label ="Git repository "> 130< i id ="git-repository-button "class ="fa fa-github "></ i > 131</ a > 132 133</ div > 134</ div > 135 136< div id ="search-wrapper "class ="hidden "> 137< form id ="searchbar-outer "class ="searchbar-outer "> 138< input type ="search "id ="searchbar "name ="searchbar "placeholder ="Search this book ... "aria-controls ="searchresults-outer "aria-describedby ="searchresults-header "> 139</ form > 140< div id ="searchresults-outer "class ="searchresults-outer hidden "> 141< div id ="searchresults-header "class ="searchresults-header "></ div > 142< ul id ="searchresults "> 143</ ul > 144</ div > 145</ div > 146 147<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM --> 148< script > 149document . getElementById ( 'sidebar-toggle' ). setAttribute ( 'aria-expanded' , sidebar === 'visible' ); 150document . getElementById ( 'sidebar' ). setAttribute ( 'aria-hidden' , sidebar !== 'visible' ); 151Array . from ( document . querySelectorAll ( '#sidebar a' )). forEach ( function ( link ) { 152link . setAttribute ( 'tabIndex' , sidebar === 'visible' ?0 :- 1 ); 153}); 154</ script > 155 156< div id ="content "class ="content "> 157< main > 158<!-- Generated with Stardoc: http://skydoc.bazel.build --> 159< h1 id ="rules_rust_protobuf ">< a class ="header "href ="#rules_rust_protobuf "> rules_rust_protobuf</ a ></ h1 > 160< p > These build rules are used for building< a href ="https://developers.google.com/protocol-buffers/ "> protobufs</ a > /< a href ="https://grpc.io "> gRPC</ a > in< a href ="http://www.rust-lang.org/ "> Rust</ a > with Bazel 161using< a href ="https://github.com/stepancheg/rust-protobuf/ ">< code > rust-protobuf</ code ></ a > .</ p > 162< h2 id ="setup ">< a class ="header "href ="#setup "> Setup</ a ></ h2 > 163< p > To use the Rust proto rules, add the following to your< code > WORKSPACE</ code > file to add the 164external repositories for the Rust proto toolchain (in addition to the< a href =".. "> rust rules setup</ a > ):</ p > 165< pre >< code class ="language-python "> load("@rules_rust//proto/protobuf:repositories.bzl", "rust_proto_protobuf_dependencies", "rust_proto_protobuf_register_toolchains") 166 167rust_proto_protobuf_dependencies() 168 169rust_proto_protobuf_register_toolchains() 170 171load("@rules_rust//proto/protobuf:transitive_repositories.bzl", "rust_proto_protobuf_transitive_repositories") 172 173rust_proto_protobuf_transitive_repositories() 174</ code ></ pre > 175< p > This will load the required dependencies for the< a href ="https://github.com/stepancheg/rust-protobuf/ ">< code > rust-protobuf</ code ></ a > rules. It will also 176register a default toolchain for the< code > rust_proto_library</ code > and< code > rust_grpc_library</ code > rules.</ p > 177< p > To customize the< code > rust_proto_library</ code > and< code > rust_grpc_library</ code > toolchain, please see the section 178< a href ="#custom-proto-deps "> Customizing< code > rust-protobuf</ code > Dependencies</ a > .</ p > 179< p > For additional information about Bazel toolchains, see< a href ="https://docs.bazel.build/versions/master/toolchains.html "> here</ a > .</ p > 180< h4 id ="customizing-rust-protobuf-dependencies ">< a class ="header "href ="#customizing-rust-protobuf-dependencies ">< a name ="custom-proto-deps "> Customizing< code > rust-protobuf</ code > Dependencies</ a ></ h4 > 181< p > These rules depend on the< a href ="https://crates.io/crates/protobuf ">< code > protobuf</ code ></ a > and 182the< a href ="https://crates.io/crates/grpc ">< code > grpc</ code ></ a > crates in addition to the< a href ="https://github.com/google/protobuf "> protobuf 183compiler</ a > . To obtain these crates, 184< code > rust_proto_repositories</ code > imports the given crates using BUILD files generated with 185< a href ="./crate_universe.html "> crate_universe</ a > .</ p > 186< p > If you want to either change the protobuf and gRPC rust compilers, or to 187simply use< a href ="./crate_universe.html "> crate_universe</ a > in a more 188complex scenario (with more dependencies), you must redefine those 189dependencies.</ p > 190< p > To do this, once you've imported the needed dependencies (see our 191< a href ="https://github.com/bazelbuild/rules_rust/blob/main/proto/protobuf/3rdparty/BUILD.bazel "> @rules_rust//proto/protobuf/3rdparty/BUILD.bazel</ a > 192file to see the default dependencies), you need to create your own toolchain. 193To do so you can create a BUILD file with your toolchain definition, for example:</ p > 194< pre >< code class ="language-python "> load("@rules_rust//proto:toolchain.bzl", "rust_proto_toolchain") 195 196rust_proto_toolchain( 197 name = "proto-toolchain-impl", 198 # Path to the protobuf compiler. 199 protoc = "@com_google_protobuf//:protoc", 200 # Protobuf compiler plugin to generate rust gRPC stubs. 201 grpc_plugin = "//3rdparty/crates:cargo_bin_protoc_gen_rust_grpc", 202 # Protobuf compiler plugin to generate rust protobuf stubs. 203 proto_plugin = "//3rdparty/crates:cargo_bin_protoc_gen_rust", 204) 205 206toolchain( 207 name = "proto-toolchain", 208 toolchain = ":proto-toolchain-impl", 209 toolchain_type = "@rules_rust//proto/protobuf:toolchain_type", 210) 211</ code ></ pre > 212< p > Now that you have your own toolchain, you need to register it by 213inserting the following statement in your< code > WORKSPACE</ code > file:</ p > 214< pre >< code class ="language-python "> register_toolchains("//my/toolchains:proto-toolchain") 215</ code ></ pre > 216< p > Finally, you might want to set the< code > rust_deps</ code > attribute in 217< code > rust_proto_library</ code > and< code > rust_grpc_library</ code > to change the compile-time 218dependencies:</ p > 219< pre >< code class ="language-python "> rust_proto_library( 220 ... 221 rust_deps = ["//3rdparty/crates:protobuf"], 222 ... 223) 224 225rust_grpc_library( 226 ... 227 rust_deps = [ 228 "//3rdparty/crates:protobuf", 229 "//3rdparty/crates:grpc", 230 "//3rdparty/crates:tls_api", 231 "//3rdparty/crates:tls_api_stub", 232 ], 233 ... 234) 235</ code ></ pre > 236< p >< strong > Note</ strong > : Ideally, we would inject those dependencies from the toolchain, 237but due to< a href ="https://github.com/bazelbuild/bazel/issues/6889 "> bazelbuild/bazel#6889</ a > 238all dependencies added via the toolchain ends-up being in the wrong 239configuration.</ p > 240< hr /> 241< hr /> 242< p >< a id ="rust_grpc_library "></ a ></ p > 243< h2 id ="rust_grpc_library ">< a class ="header "href ="#rust_grpc_library "> rust_grpc_library</ a ></ h2 > 244< pre > 245rust_grpc_library(< a href ="#rust_grpc_library-name "> name</ a > ,< a href ="#rust_grpc_library-deps "> deps</ a > ,< a href ="#rust_grpc_library-crate_name "> crate_name</ a > ,< a href ="#rust_grpc_library-rust_deps "> rust_deps</ a > ,< a href ="#rust_grpc_library-rustc_flags "> rustc_flags</ a > ) 246</ pre > 247< p > Builds a Rust library crate from a set of< code > proto_library</ code > s suitable for gRPC.</ p > 248< p > Example:</ p > 249< pre >< code class ="language-python "> load("@rules_rust_protobuf//:defs.bzl", "rust_grpc_library") 250 251proto_library( 252 name = "my_proto", 253 srcs = ["my.proto"] 254) 255 256rust_grpc_library( 257 name = "rust", 258 deps = [":my_proto"], 259) 260 261rust_binary( 262 name = "my_service", 263 srcs = ["my_service.rs"], 264 deps = [":rust"], 265) 266</ code ></ pre > 267< p >< strong > ATTRIBUTES</ strong ></ p > 268< div class ="table-wrapper ">< table >< thead >< tr >< th style ="text-align: left "> Name</ th >< th style ="text-align: left "> Description</ th >< th style ="text-align: left "> Type</ th >< th style ="text-align: left "> Mandatory</ th >< th style ="text-align: left "> Default</ th ></ tr ></ thead >< tbody > 269< tr >< td style ="text-align: left ">< a id ="rust_grpc_library-name "></ a > name</ td >< td style ="text-align: left "> A unique name for this target.</ td >< td style ="text-align: left ">< a href ="https://bazel.build/concepts/labels#target-names "> Name</ a ></ td >< td style ="text-align: left "> required</ td >< td style ="text-align: left "></ td ></ tr > 270< tr >< td style ="text-align: left ">< a id ="rust_grpc_library-deps "></ a > deps</ td >< td style ="text-align: left "> List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding gRPC stubs.</ td >< td style ="text-align: left ">< a href ="https://bazel.build/concepts/labels "> List of labels</ a ></ td >< td style ="text-align: left "> required</ td >< td style ="text-align: left "></ td ></ tr > 271< tr >< td style ="text-align: left ">< a id ="rust_grpc_library-crate_name "></ a > crate_name</ td >< td style ="text-align: left "> Crate name to use for this target.< br >< br > This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores.</ td >< td style ="text-align: left "> String</ td >< td style ="text-align: left "> optional</ td >< td style ="text-align: left ">< code > ""</ code ></ td ></ tr > 272< tr >< td style ="text-align: left ">< a id ="rust_grpc_library-rust_deps "></ a > rust_deps</ td >< td style ="text-align: left "> The crates the generated library depends on.</ td >< td style ="text-align: left ">< a href ="https://bazel.build/concepts/labels "> List of labels</ a ></ td >< td style ="text-align: left "> optional</ td >< td style ="text-align: left ">< code > []</ code ></ td ></ tr > 273< tr >< td style ="text-align: left ">< a id ="rust_grpc_library-rustc_flags "></ a > rustc_flags</ td >< td style ="text-align: left "> List of compiler flags passed to< code > rustc</ code > .< br >< br > These strings are subject to Make variable expansion for predefined source/output path variables like< code > $location</ code > ,< code > $execpath</ code > , and< code > $rootpath</ code > . This expansion is useful if you wish to pass a generated file of arguments to rustc:< code > @$(location //package:target)</ code > .</ td >< td style ="text-align: left "> List of strings</ td >< td style ="text-align: left "> optional</ td >< td style ="text-align: left ">< code > []</ code ></ td ></ tr > 274</ tbody ></ table > 275</ div > 276< p >< a id ="rust_proto_library "></ a ></ p > 277< h2 id ="rust_proto_library ">< a class ="header "href ="#rust_proto_library "> rust_proto_library</ a ></ h2 > 278< pre > 279rust_proto_library(< a href ="#rust_proto_library-name "> name</ a > ,< a href ="#rust_proto_library-deps "> deps</ a > ,< a href ="#rust_proto_library-crate_name "> crate_name</ a > ,< a href ="#rust_proto_library-rust_deps "> rust_deps</ a > ,< a href ="#rust_proto_library-rustc_flags "> rustc_flags</ a > ) 280</ pre > 281< p > Builds a Rust library crate from a set of< code > proto_library</ code > s.</ p > 282< p > Example:</ p > 283< pre >< code class ="language-python "> load("@rules_rust_protobuf//:defs.bzl", "rust_proto_library") 284 285proto_library( 286 name = "my_proto", 287 srcs = ["my.proto"] 288) 289 290rust_proto_library( 291 name = "rust", 292 deps = [":my_proto"], 293) 294 295rust_binary( 296 name = "my_proto_binary", 297 srcs = ["my_proto_binary.rs"], 298 deps = [":rust"], 299) 300</ code ></ pre > 301< p >< strong > ATTRIBUTES</ strong ></ p > 302< div class ="table-wrapper ">< table >< thead >< tr >< th style ="text-align: left "> Name</ th >< th style ="text-align: left "> Description</ th >< th style ="text-align: left "> Type</ th >< th style ="text-align: left "> Mandatory</ th >< th style ="text-align: left "> Default</ th ></ tr ></ thead >< tbody > 303< tr >< td style ="text-align: left ">< a id ="rust_proto_library-name "></ a > name</ td >< td style ="text-align: left "> A unique name for this target.</ td >< td style ="text-align: left ">< a href ="https://bazel.build/concepts/labels#target-names "> Name</ a ></ td >< td style ="text-align: left "> required</ td >< td style ="text-align: left "></ td ></ tr > 304< tr >< td style ="text-align: left ">< a id ="rust_proto_library-deps "></ a > deps</ td >< td style ="text-align: left "> List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding stubs.</ td >< td style ="text-align: left ">< a href ="https://bazel.build/concepts/labels "> List of labels</ a ></ td >< td style ="text-align: left "> required</ td >< td style ="text-align: left "></ td ></ tr > 305< tr >< td style ="text-align: left ">< a id ="rust_proto_library-crate_name "></ a > crate_name</ td >< td style ="text-align: left "> Crate name to use for this target.< br >< br > This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores.</ td >< td style ="text-align: left "> String</ td >< td style ="text-align: left "> optional</ td >< td style ="text-align: left ">< code > ""</ code ></ td ></ tr > 306< tr >< td style ="text-align: left ">< a id ="rust_proto_library-rust_deps "></ a > rust_deps</ td >< td style ="text-align: left "> The crates the generated library depends on.</ td >< td style ="text-align: left ">< a href ="https://bazel.build/concepts/labels "> List of labels</ a ></ td >< td style ="text-align: left "> optional</ td >< td style ="text-align: left ">< code > []</ code ></ td ></ tr > 307< tr >< td style ="text-align: left ">< a id ="rust_proto_library-rustc_flags "></ a > rustc_flags</ td >< td style ="text-align: left "> List of compiler flags passed to< code > rustc</ code > .< br >< br > These strings are subject to Make variable expansion for predefined source/output path variables like< code > $location</ code > ,< code > $execpath</ code > , and< code > $rootpath</ code > . This expansion is useful if you wish to pass a generated file of arguments to rustc:< code > @$(location //package:target)</ code > .</ td >< td style ="text-align: left "> List of strings</ td >< td style ="text-align: left "> optional</ td >< td style ="text-align: left ">< code > []</ code ></ td ></ tr > 308</ tbody ></ table > 309</ div > 310</ main > 311 312< nav class ="nav-wrapper "aria-label ="Page navigation "> 313<!-- Mobile navigation buttons --> 314< a rel ="prev "href ="rust_prost.html "class ="mobile-nav-chapters previous "title ="Previous chapter "aria-label ="Previous chapter "aria-keyshortcuts ="Left "> 315< i class ="fa fa-angle-left "></ i > 316</ a > 317 318< a rel ="next prefetch "href ="rust_wasm_bindgen.html "class ="mobile-nav-chapters next "title ="Next chapter "aria-label ="Next chapter "aria-keyshortcuts ="Right "> 319< i class ="fa fa-angle-right "></ i > 320</ a > 321 322< div style ="clear: both "></ div > 323</ nav > 324</ div > 325</ div > 326 327< nav class ="nav-wide-wrapper "aria-label ="Page navigation "> 328< a rel ="prev "href ="rust_prost.html "class ="nav-chapters previous "title ="Previous chapter "aria-label ="Previous chapter "aria-keyshortcuts ="Left "> 329< i class ="fa fa-angle-left "></ i > 330</ a > 331 332< a rel ="next prefetch "href ="rust_wasm_bindgen.html "class ="nav-chapters next "title ="Next chapter "aria-label ="Next chapter "aria-keyshortcuts ="Right "> 333< i class ="fa fa-angle-right "></ i > 334</ a > 335</ nav > 336 337</ div > 338 339 340 341 342< script > 343window . playground_copyable = true ; 344</ script > 345 346 347< script src ="elasticlunr.min.js "></ script > 348< script src ="mark.min.js "></ script > 349< script src ="searcher.js "></ script > 350 351< script src ="clipboard.min.js "></ script > 352< script src ="highlight.js "></ script > 353< script src ="book.js "></ script > 354 355<!-- Custom JS scripts --> 356 357 358</ div > 359</ body > 360</ html >