Add generated docs for crate_universe

crate_universe/BUILD.bazel

@@ -0,0 +1,9 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//visibility:public"])
+
+bzl_library(
+    name = "rules",
+    srcs = glob(["**/*.bzl"]),
+    deps = ["//crate_universe/private:bzl_srcs"],
+)

crate_universe/defs.bzl

@@ -181,7 +181,6 @@ def _crate_universe_resolve_impl(repository_ctx):
     if repository_ctx.attr.lockfile:
         lockfile_path = repository_ctx.path(repository_ctx.attr.lockfile)
 
-    # Yay hand-crafted JSON serialisation...
     input_content = _input_content_template(
         ctx = repository_ctx,
         name = repository_ctx.attr.name,
@@ -233,81 +232,61 @@ crate_universe = repository_rule(
     doc = """\
 A rule for downloading Rust dependencies (crates).
 
+__WARNING__: This rule experimental and subject to change without warning.
+
 Environment Variables:
 - `REPIN`: Re-pin the lockfile if set (useful for repinning deps from multiple rulesets).
 - `RULES_RUST_REPIN`: Re-pin the lockfile if set (useful for only repinning Rust deps).
-- `RULES_RUST_CRATE_UNIVERSE_RESOLVER_URL_OVERRIDE`: Override URL to use to download resolver binary - for local paths use a `file://` URL.
-
-`override` Example:
-
-```python
-load("@rules_rust//crate_universe:defs.bzl", "crate_universe", "crate")
-
-crate_universe(
-    name = "mylib",
-    # [...]
-    overrides = {
-        "tokio": crate.override(
-            extra_rust_env_vars = {
-                "MY_ENV_VAR": "MY_ENV_VALUE",
-            },
-            extra_build_script_env_vars = {
-                "MY_BUILD_SCRIPT_ENV_VAR": "MY_ENV_VALUE",
-            },
-            extra_bazel_deps = {
-                # Extra dependencies are per target. They are additive.
-                "cfg(unix)": ["@somerepo//:foo"],  # cfg() predicate.
-                "x86_64-apple-darwin": ["@somerepo//:bar"],  # Specific triple.
-                "cfg(all())": ["@somerepo//:baz"],  # Applies to all targets ("regular dependency").
-            },
-            extra_build_script_bazel_deps = {
-                # Extra dependencies are per target. They are additive.
-                "cfg(unix)": ["@buildscriptdep//:foo"],
-                "x86_64-apple-darwin": ["@buildscriptdep//:bar"],
-                "cfg(all())": ["@buildscriptdep//:baz"],
-            },
-            extra_bazel_data_deps = {
-                # ...
-            },
-            extra_build_script_bazel_data_deps = {
-                # ...
-            },
-        ),
-    },
-)
-```
+- `RULES_RUST_CRATE_UNIVERSE_RESOLVER_URL_OVERRIDE`: Override URL to use to download resolver binary 
+    - for local paths use a `file://` URL.
+- `RULES_RUST_CRATE_UNIVERSE_RESOLVER_URL_OVERRIDE_SHA256`: An optional sha256 value for the binary at the override url location.
 """,
     implementation = _crate_universe_resolve_impl,
     attrs = {
         "cargo_toml_files": attr.label_list(
-            doc = "",
+            doc = "A list of Cargo manifests (`Cargo.toml` files).",
+            allow_files = True,
         ),
         "crate_registry_template": attr.string(
-            doc = "A Crate registry url template. This must contain `{version}` and `{crate}` templates",
+            doc = "A template for where to download crates from for the default crate registry. This must contain `{version}` and `{crate}` templates.",
             default = DEFAULT_CRATE_REGISTRY_TEMPLATE,
         ),
         "lockfile": attr.label(
-            doc = "",
+            doc = (
+                "The path to a file which stores pinned information about the generated dependency graph. " +
+                "this target must be a file and will be updated by the repository rule when the `REPIN` " +
+                "environment variable is set. If this is not set, dependencies will be re-resolved more " +
+                "often, setting this allows caching resolves, but will error if the cache is stale."
+            ),
             allow_single_file = True,
             mandatory = False,
         ),
         "overrides": attr.string_dict(
-            doc = "Mapping of crate name to `crate.override(...)` entries)",
+            doc = (
+                "Mapping of crate name to specification overrides. See [crate.override](#crateoverride) " +
+                " for more details."
+            ),
         ),
         "packages": attr.string_list(
-            doc = "",
+            doc = "A list of crate specifications. See [crate.spec](#cratespec) for more details.",
             allow_empty = True,
         ),
         "resolver_download_url_template": attr.string(
-            doc = "URL template from which to download the resolver binary. {host_triple} and {extension} will be filled in according to the host platform.",
+            doc = (
+                "URL template from which to download the resolver binary. {host_triple} and {extension} will be " +
+                "filled in according to the host platform."
+            ),
             default = DEFAULT_URL_TEMPLATE,
         ),
         "resolver_sha256s": attr.string_dict(
             doc = "Dictionary of host_triple -> sha256 for resolver binary.",
             default = DEFAULT_SHA256_CHECKSUMS,
         ),
         "supported_targets": attr.string_list(
-            doc = "",
+            doc = (
+                "A list of supported [platform triples](https://doc.rust-lang.org/nightly/rustc/platform-support.html) " +
+                "to consider when resoliving dependencies."
+            ),
             allow_empty = False,
             default = DEFAULT_TOOLCHAIN_TRIPLES.keys(),
         ),
@@ -322,20 +301,112 @@ def _spec(
         name,
         semver,
         features = None):
+    """A simple crate definition for use in the `crate_universe` rule.
+
+    __WARNING__: This rule experimental and subject to change without warning.
+
+    Example:
+
+    ```python
+    load("@rules_rust//crate_universe:defs.bzl", "crate_universe", "crate")
+
+    crate_universe(
+        name = "spec_example",
+        packages = [
+            crate.spec(
+                name = "lazy_static",
+                semver = "=1.4",
+            ),
+        ],
+    )
+    ```
+
+    Args:
+        name (str): The name of the crate as it would appear in a crate registry.
+        semver (str): The desired version ([semver](https://semver.org/)) of the crate
+        features (list, optional): A list of desired [features](https://doc.rust-lang.org/cargo/reference/features.html).
+
+    Returns:
+        str: A json encoded struct of crate info
+    """
     return json.encode(struct(
         name = name,
         semver = semver,
-        features = features if features else [],
+        features = features or [],
     ))
 
 def _override(
-        extra_rust_env_vars = None,
-        extra_build_script_env_vars = None,
-        extra_bazel_deps = None,
-        extra_build_script_bazel_deps = None,
         extra_bazel_data_deps = None,
+        extra_bazel_deps = None,
         extra_build_script_bazel_data_deps = None,
+        extra_build_script_bazel_deps = None,
+        extra_build_script_env_vars = None,
+        extra_rustc_env_vars = None,
         features_to_remove = []):
+    """A map of overrides for a particular crate
+
+    __WARNING__: This rule experimental and subject to change without warning.
+
+    Example:
+
+    ```python
+    load("@rules_rust//crate_universe:defs.bzl", "crate_universe", "crate")
+
+    crate_universe(
+        name = "override_example",
+        # [...]
+        overrides = {
+            "tokio": crate.override(
+                extra_rustc_env_vars = {
+                    "MY_ENV_VAR": "MY_ENV_VALUE",
+                },
+                extra_build_script_env_vars = {
+                    "MY_BUILD_SCRIPT_ENV_VAR": "MY_ENV_VALUE",
+                },
+                extra_bazel_deps = {
+                    # Extra dependencies are per target. They are additive.
+                    "cfg(unix)": ["@somerepo//:foo"],  # cfg() predicate.
+                    "x86_64-apple-darwin": ["@somerepo//:bar"],  # Specific triple.
+                    "cfg(all())": ["@somerepo//:baz"],  # Applies to all targets ("regular dependency").
+                },
+                extra_build_script_bazel_deps = {
+                    # Extra dependencies are per target. They are additive.
+                    "cfg(unix)": ["@buildscriptdep//:foo"],
+                    "x86_64-apple-darwin": ["@buildscriptdep//:bar"],
+                    "cfg(all())": ["@buildscriptdep//:baz"],
+                },
+                extra_bazel_data_deps = {
+                    # ...
+                },
+                extra_build_script_bazel_data_deps = {
+                    # ...
+                },
+            ),
+        },
+    )
+    ```
+
+    Args:
+        extra_bazel_data_deps (dict, optional): Targets to add to the `data` attribute
+            of the generated target (eg: [rust_library.data](./defs.md#rust_library-data)).
+        extra_bazel_deps (dict, optional): Targets to add to the `deps` attribute
+            of the generated target (eg: [rust_library.deps](./defs.md#rust_library-data)).
+        extra_rustc_env_vars (dict, optional): Environment variables to add to the `rustc_env`
+            attribute for the generated target (eg: [rust_library.rustc_env](./defs.md#rust_library-rustc_env)).
+        extra_build_script_bazel_data_deps (dict, optional): Targets to add to the
+            [data](./cargo_build_script.md#cargo_build_script-data) attribute of the generated
+            `cargo_build_script` target.
+        extra_build_script_bazel_deps (dict, optional): Targets to add to the
+            [deps](./cargo_build_script.md#cargo_build_script-deps) attribute of the generated
+            `cargo_build_script` target.
+        extra_build_script_env_vars (dict, optional): Environment variables to add to the
+            [build_script_env](./cargo_build_script.md#cargo_build_script-build_script_env)
+            attribute of the generated `cargo_build_script` target.
+        features_to_remove (list, optional): A list of features to remove from a generated target.
+
+    Returns:
+        str: A json encoded struct of crate overrides
+    """
     for (dep_key, dep_val) in [
         (extra_bazel_deps, extra_bazel_deps),
         (extra_build_script_bazel_deps, extra_build_script_bazel_deps),
@@ -351,12 +422,12 @@ def _override(
                     fail("The {} values should be lists of strings".format(dep_key))
 
     return json.encode(struct(
-        extra_rust_env_vars = extra_rust_env_vars if extra_rust_env_vars else {},
-        extra_build_script_env_vars = extra_build_script_env_vars if extra_build_script_env_vars else {},
-        extra_bazel_deps = extra_bazel_deps if extra_bazel_deps else {},
-        extra_build_script_bazel_deps = extra_build_script_bazel_deps if extra_build_script_bazel_deps else {},
-        extra_bazel_data_deps = extra_bazel_data_deps if extra_bazel_data_deps else {},
-        extra_build_script_bazel_data_deps = extra_build_script_bazel_data_deps if extra_build_script_bazel_data_deps else {},
+        extra_rustc_env_vars = extra_rustc_env_vars or {},
+        extra_build_script_env_vars = extra_build_script_env_vars or {},
+        extra_bazel_deps = extra_bazel_deps or {},
+        extra_build_script_bazel_deps = extra_build_script_bazel_deps or {},
+        extra_bazel_data_deps = extra_bazel_data_deps or {},
+        extra_build_script_bazel_data_deps = extra_build_script_bazel_data_deps or {},
         features_to_remove = features_to_remove,
     ))
 

crate_universe/private/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//visibility:public"])
+
+bzl_library(
+    name = "bzl_srcs",
+    srcs = glob(["**/*.bzl"]),
+)

crate_universe/src/config.rs

@@ -25,7 +25,7 @@ pub struct Package {
 #[serde(deny_unknown_fields)]
 pub struct Override {
     // Mapping of environment variables key -> value.
-    pub extra_rust_env_vars: BTreeMap<String, String>,
+    pub extra_rustc_env_vars: BTreeMap<String, String>,
     // Mapping of environment variables key -> value.
     pub extra_build_script_env_vars: BTreeMap<String, String>,
     // Mapping of target triple or spec -> extra bazel target dependencies.
@@ -81,7 +81,7 @@ impl Config {
                 (
                     krate,
                     ConsolidatorOverride {
-                        extra_rust_env_vars: overryde.extra_rust_env_vars,
+                        extra_rustc_env_vars: overryde.extra_rustc_env_vars,
                         extra_build_script_env_vars: overryde.extra_build_script_env_vars,
                         extra_bazel_deps: overryde.extra_bazel_deps,
                         extra_build_script_bazel_deps: overryde.extra_build_script_bazel_deps,

crate_universe/src/consolidator.rs

@@ -17,7 +17,7 @@ use crate::{
 #[derive(Debug, Default)]
 pub struct ConsolidatorOverride {
     // Mapping of environment variables key -> value.
-    pub extra_rust_env_vars: BTreeMap<String, String>,
+    pub extra_rustc_env_vars: BTreeMap<String, String>,
     // Mapping of environment variables key -> value.
     pub extra_build_script_env_vars: BTreeMap<String, String>,
     // Mapping of target triple or spec -> extra bazel target dependencies.
@@ -239,7 +239,7 @@ impl Consolidator {
                 // Add extra environment variables.
                 pkg.raze_settings
                     .additional_env
-                    .extend(overryde.extra_rust_env_vars.into_iter());
+                    .extend(overryde.extra_rustc_env_vars.into_iter());
                 // Add extra build script environment variables.
                 pkg.raze_settings
                     .buildrs_additional_environment_variables

crate_universe/src/resolver.rs

@@ -138,7 +138,7 @@ impl Resolver {
             for (
                 crate_name,
                 ConsolidatorOverride {
-                    extra_rust_env_vars,
+                    extra_rustc_env_vars,
                     extra_build_script_env_vars,
                     extra_bazel_deps,
                     extra_bazel_data_deps,
@@ -150,7 +150,7 @@ impl Resolver {
             {
                 hasher.update(crate_name);
                 hasher.update(b"\0");
-                for (env_key, env_val) in extra_rust_env_vars {
+                for (env_key, env_val) in extra_rustc_env_vars {
                     hasher.update(env_key);
                     hasher.update(b"\0");
                     hasher.update(env_val);

docs/BUILD.bazel

@@ -21,6 +21,7 @@ bzl_library(
         "@rules_rust//:rules",
         "@rules_rust//bindgen:rules",
         "@rules_rust//cargo:rules",
+        "@rules_rust//crate_universe:rules",
         "@rules_rust//proto:rules",
         "@rules_rust//rust:rules",
         "@rules_rust//wasm_bindgen:rules",
@@ -31,6 +32,10 @@ PAGES = {
     "cargo_build_script": [
         "cargo_build_script",
     ],
+    "crate_universe": [
+        "crate_universe",
+        "crate",
+    ],
     "defs": [
         "rust_binary",
         "rust_library",

docs/all.bzl

@@ -16,6 +16,11 @@ load(
     "@rules_rust//cargo:cargo_build_script.bzl",
     _cargo_build_script = "cargo_build_script",
 )
+load(
+    "@rules_rust//crate_universe:defs.bzl",
+    _crate = "crate",
+    _crate_universe = "crate_universe",
+)
 load(
     "@rules_rust//proto:proto.bzl",
     _rust_grpc_library = "rust_grpc_library",
@@ -101,3 +106,6 @@ rust_toolchain_repository_proxy = _rust_toolchain_repository_proxy
 
 rust_clippy = _rust_clippy
 rust_analyzer = _rust_analyzer
+
+crate_universe = _crate_universe
+crate = _crate