Split rust_library and add //rust:defs.bzl

This PR splits rust_library into multiple smaller rules:

* rust_library: rust_library will represent a non-transitive library
  similar to how cc_library, java_library and others behave. It will
  always provide CrateInfo, and depending on it will always mean you can
  access the crate from source. Once we support dynamic linking we can
  consider producing both rlib and dylib from rust_library, but let's
  leave that for another discussion.
* rust_static_library: this will only provide CcInfo and it will
  represent an archive of all transitive objects, both Rustc-made and
  native.
* rust_shared_library: this will only provide CcInfo and it will
  represent an shared library of all transitive objects, both Rustc-made
  and native.
* rust_proc_macro: similar to rust_library, but with different
  crate_type passed to rustc and different validation logic for its
  attributes.

I this this makes sense based on these observations:
* Right now rust_library covers all possible crate types except `bin`.
* rust_library always provides CrateInfo, rust_libraries can depend on
  other rust_libraries.
* When the crate type is `cdylib` or `staticlib`, rust_library provides
  CcInfo.
* When the crate type is `cdylib` or `staticlib`, Rust code will not be
  able to access the crate by `extern crate Foo` in the source; the
  behavior will be similar to depending on a CcInfo providing rule.

I believe smaller rules will make them less confusing and
will allow us to have more focused implementations.

This PR is mostly backwards compatible. //rust:rust.bzl#rust_library is
a macro. If the crate_type attribute is present, macro dispatches to
the right new rule. If it's not present, macro will choose the new
rust_library. New rules are added, so people can migrate at
their own pace.

defs.bzl is the bzl file that we now expect people to load. Bazel docs
recommend to store public rules in defs.bzl
(https://docs.bazel.build/versions/master/skylark/deploying.html#repository-content).

This change was first socialized at
https://groups.google.com/g/rules_rust/c/kGMg6haEF44.

Regenerate documentation

Regenerate documentation

Author: hlopko

docs/BUILD

@@ -32,8 +32,11 @@ PAGES = {
         "cargo_build_script",
     ],
     "rust": [
-        "rust_library",
         "rust_binary",
+        "rust_library",
+        "rust_static_library",
+        "rust_shared_library",
+        "rust_proc_macro",
         "rust_benchmark",
         "rust_test",
     ],

docs/flatten.md

@@ -15,11 +15,14 @@
 * [rust_doc_test](#rust_doc_test)
 * [rust_grpc_library](#rust_grpc_library)
 * [rust_library](#rust_library)
+* [rust_proc_macro](#rust_proc_macro)
 * [rust_proto_library](#rust_proto_library)
 * [rust_proto_repositories](#rust_proto_repositories)
 * [rust_proto_toolchain](#rust_proto_toolchain)
 * [rust_repositories](#rust_repositories)
 * [rust_repository_set](#rust_repository_set)
+* [rust_shared_library](#rust_shared_library)
+* [rust_static_library](#rust_static_library)
 * [rust_test](#rust_test)
 * [rust_toolchain](#rust_toolchain)
 * [rust_toolchain_repository](#rust_toolchain_repository)
@@ -116,7 +119,7 @@ To build the benchmark test, add a `rust_benchmark` target:
 ```python
 package(default_visibility = ["//visibility:public"])
 
-load("@rules_rust//rust:rust.bzl", "rust_library", "rust_benchmark")
+load("@rules_rust//rust:defs.bzl", "rust_library", "rust_benchmark")
 
 rust_library(
   name = "fibonacci",
@@ -159,9 +162,9 @@ Run the benchmark test using: `bazel run //fibonacci:fibonacci_bench`.
 ## rust_binary
 
 <pre>
-rust_binary(<a href="#rust_binary-name">name</a>, <a href="#rust_binary-aliases">aliases</a>, <a href="#rust_binary-compile_data">compile_data</a>, <a href="#rust_binary-crate_features">crate_features</a>, <a href="#rust_binary-crate_root">crate_root</a>, <a href="#rust_binary-crate_type">crate_type</a>, <a href="#rust_binary-data">data</a>, <a href="#rust_binary-deps">deps</a>,
-            <a href="#rust_binary-edition">edition</a>, <a href="#rust_binary-linker_script">linker_script</a>, <a href="#rust_binary-out_binary">out_binary</a>, <a href="#rust_binary-out_dir_tar">out_dir_tar</a>, <a href="#rust_binary-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_binary-rustc_env">rustc_env</a>, <a href="#rust_binary-rustc_flags">rustc_flags</a>,
-            <a href="#rust_binary-srcs">srcs</a>, <a href="#rust_binary-version">version</a>)
+rust_binary(<a href="#rust_binary-name">name</a>, <a href="#rust_binary-aliases">aliases</a>, <a href="#rust_binary-compile_data">compile_data</a>, <a href="#rust_binary-crate_features">crate_features</a>, <a href="#rust_binary-crate_root">crate_root</a>, <a href="#rust_binary-data">data</a>, <a href="#rust_binary-deps">deps</a>, <a href="#rust_binary-edition">edition</a>,
+            <a href="#rust_binary-linker_script">linker_script</a>, <a href="#rust_binary-out_binary">out_binary</a>, <a href="#rust_binary-out_dir_tar">out_dir_tar</a>, <a href="#rust_binary-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_binary-rustc_env">rustc_env</a>, <a href="#rust_binary-rustc_flags">rustc_flags</a>, <a href="#rust_binary-srcs">srcs</a>,
+            <a href="#rust_binary-version">version</a>)
 </pre>
 
 Builds a Rust binary crate.
@@ -258,7 +261,6 @@ Hello world
 | <a id="rust_binary-compile_data"></a>compile_data |  List of files used by this rule at compile time.<br><br>This attribute can be used to specify any data files that are embedded into the library, such as via the [<code>include_str!</code>](https://doc.rust-lang.org/std/macro.include_str!.html) macro.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="rust_binary-crate_features"></a>crate_features |  List of features to enable for this crate.<br><br>Features are defined in the code using the <code>#[cfg(feature = "foo")]</code> configuration option. The features listed here will be passed to <code>rustc</code> with <code>--cfg feature="${feature_name}"</code> flags.   | List of strings | optional | [] |
 | <a id="rust_binary-crate_root"></a>crate_root |  The file that will be passed to <code>rustc</code> to be used for building this crate.<br><br>If <code>crate_root</code> is not set, then this rule will look for a <code>lib.rs</code> file (or <code>main.rs</code> for rust_binary) or the single file in <code>srcs</code> if <code>srcs</code> contains only one file.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
-| <a id="rust_binary-crate_type"></a>crate_type |  -   | String | optional | "bin" |
 | <a id="rust_binary-data"></a>data |  List of files used by this rule at compile time and runtime.<br><br>If including data at compile time with include_str!() and similar, prefer <code>compile_data</code> over <code>data</code>, to prevent the data also being included in the runfiles.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="rust_binary-deps"></a>deps |  List of other libraries to be linked to this library target.<br><br>These can be either other <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="rust_binary-edition"></a>edition |  The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.   | String | optional | "" |
@@ -528,101 +530,6 @@ rust_binary(
 | <a id="rust_grpc_library-rust_deps"></a>rust_deps |  The crates the generated library depends on.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [Label("//proto/raze:protobuf"), Label("//proto/raze:grpc"), Label("//proto/raze:tls_api"), Label("//proto/raze:tls_api_stub")] |
 
 
-<a id="#rust_library"></a>
-
-## rust_library
-
-<pre>
-rust_library(<a href="#rust_library-name">name</a>, <a href="#rust_library-aliases">aliases</a>, <a href="#rust_library-compile_data">compile_data</a>, <a href="#rust_library-crate_features">crate_features</a>, <a href="#rust_library-crate_root">crate_root</a>, <a href="#rust_library-crate_type">crate_type</a>, <a href="#rust_library-data">data</a>, <a href="#rust_library-deps">deps</a>,
-             <a href="#rust_library-edition">edition</a>, <a href="#rust_library-out_dir_tar">out_dir_tar</a>, <a href="#rust_library-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_library-rustc_env">rustc_env</a>, <a href="#rust_library-rustc_flags">rustc_flags</a>, <a href="#rust_library-srcs">srcs</a>, <a href="#rust_library-version">version</a>)
-</pre>
-
-Builds a Rust library crate.
-
-Example:
-
-Suppose you have the following directory structure for a simple Rust library crate:
-
-```output
-[workspace]/
-    WORKSPACE
-    hello_lib/
-        BUILD
-        src/
-            greeter.rs
-            lib.rs
-```
-
-`hello_lib/src/greeter.rs`:
-```rust
-pub struct Greeter {
-    greeting: String,
-}
-
-impl Greeter {
-    pub fn new(greeting: &str) -> Greeter {
-        Greeter { greeting: greeting.to_string(), }
-    }
-
-    pub fn greet(&self, thing: &str) {
-        println!("{} {}", &self.greeting, thing);
-    }
-}
-```
-
-`hello_lib/src/lib.rs`:
-
-```rust
-pub mod greeter;
-```
-
-`hello_lib/BUILD`:
-```python
-package(default_visibility = ["//visibility:public"])
-
-load("@rules_rust//rust:rust.bzl", "rust_library")
-
-rust_library(
-    name = "hello_lib",
-    srcs = [
-        "src/greeter.rs",
-        "src/lib.rs",
-    ],
-)
-```
-
-Build the library:
-```output
-$ bazel build //hello_lib
-INFO: Found 1 target...
-Target //examples/rust/hello_lib:hello_lib up-to-date:
-  bazel-bin/examples/rust/hello_lib/libhello_lib.rlib
-INFO: Elapsed time: 1.245s, Critical Path: 1.01s
-```
-
-
-**ATTRIBUTES**
-
-
-| Name  | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="rust_library-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
-| <a id="rust_library-aliases"></a>aliases |  Remap crates to a new name or moniker for linkage to this target<br><br>These are other <code>rust_library</code> targets and will be presented as the new name given.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: Label -> String</a> | optional | {} |
-| <a id="rust_library-compile_data"></a>compile_data |  List of files used by this rule at compile time.<br><br>This attribute can be used to specify any data files that are embedded into the library, such as via the [<code>include_str!</code>](https://doc.rust-lang.org/std/macro.include_str!.html) macro.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="rust_library-crate_features"></a>crate_features |  List of features to enable for this crate.<br><br>Features are defined in the code using the <code>#[cfg(feature = "foo")]</code> configuration option. The features listed here will be passed to <code>rustc</code> with <code>--cfg feature="${feature_name}"</code> flags.   | List of strings | optional | [] |
-| <a id="rust_library-crate_root"></a>crate_root |  The file that will be passed to <code>rustc</code> to be used for building this crate.<br><br>If <code>crate_root</code> is not set, then this rule will look for a <code>lib.rs</code> file (or <code>main.rs</code> for rust_binary) or the single file in <code>srcs</code> if <code>srcs</code> contains only one file.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
-| <a id="rust_library-crate_type"></a>crate_type |  The type of linkage to use for building this library. Options include <code>"lib"</code>, <code>"rlib"</code>, <code>"dylib"</code>, <code>"cdylib"</code>, <code>"staticlib"</code>, and <code>"proc-macro"</code>.<br><br>The exact output file will depend on the toolchain used.   | String | optional | "rlib" |
-| <a id="rust_library-data"></a>data |  List of files used by this rule at compile time and runtime.<br><br>If including data at compile time with include_str!() and similar, prefer <code>compile_data</code> over <code>data</code>, to prevent the data also being included in the runfiles.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="rust_library-deps"></a>deps |  List of other libraries to be linked to this library target.<br><br>These can be either other <code>rust_library</code> targets or <code>cc_library</code> targets if linking a native library.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="rust_library-edition"></a>edition |  The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.   | String | optional | "" |
-| <a id="rust_library-out_dir_tar"></a>out_dir_tar |  __Deprecated__, do not use, see [#cargo_build_script] instead.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
-| <a id="rust_library-proc_macro_deps"></a>proc_macro_deps |  List of <code>rust_library</code> targets with kind <code>proc-macro</code> used to help build this library target.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="rust_library-rustc_env"></a>rustc_env |  Dictionary of additional <code>"key": "value"</code> environment variables to set for rustc.<br><br>rust_test()/rust_binary() rules can use $(rootpath //package:target) to pass in the location of a generated file or external tool. Cargo build scripts that wish to expand locations should use cargo_build_script()'s build_script_env argument instead, as build scripts are run in a different environment - see cargo_build_script()'s documentation for more.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
-| <a id="rust_library-rustc_flags"></a>rustc_flags |  List of compiler flags passed to <code>rustc</code>.   | List of strings | optional | [] |
-| <a id="rust_library-srcs"></a>srcs |  List of Rust <code>.rs</code> source files used to build the library.<br><br>If <code>srcs</code> contains more than one file, then there must be a file either named <code>lib.rs</code>. Otherwise, <code>crate_root</code> must be set to the source file that is the root of the crate to be passed to rustc to build this crate.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-| <a id="rust_library-version"></a>version |  A version to inject in the cargo environment variable.   | String | optional | "0.0.0" |
-
-
 <a id="#rust_proto_library"></a>
 
 ## rust_proto_library
@@ -779,7 +686,7 @@ To build and run the tests, simply add a `rust_test` rule with no `srcs` and onl
 ```python
 package(default_visibility = ["//visibility:public"])
 
-load("@rules_rust//rust:rust.bzl", "rust_library", "rust_test")
+load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
 
 rust_library(
     name = "hello_lib",
@@ -842,7 +749,7 @@ with `greeting.rs` in `srcs` and a dependency on the `hello_lib` target:
 ```python
 package(default_visibility = ["//visibility:public"])
 
-load("@rules_rust//rust:rust.bzl", "rust_library", "rust_test")
+load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
 
 rust_library(
     name = "hello_lib",
@@ -1214,6 +1121,24 @@ Declare dependencies needed for bindgen.
 
 
 
+<a id="#rust_library"></a>
+
+## rust_library
+
+<pre>
+rust_library(<a href="#rust_library-args">args</a>)
+</pre>
+
+Deprecated. Use the version from "@rules_rust//rust:defs.bzl" instead.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="rust_library-args"></a>args |  args to pass to the relevant rule.   |  none |
+
+
 <a id="#rust_proto_repositories"></a>
 
 ## rust_proto_repositories