Updated documentation

cargo/cargo_build_script.bzl

@@ -1,22 +1,66 @@
 # buildifier: disable=module-docstring
+load("@bazel_tools//tools/build_defs/cc:action_names.bzl", "C_COMPILE_ACTION_NAME")
 load("@bazel_tools//tools/cpp:toolchain_utils.bzl", "find_cpp_toolchain")
-load("@io_bazel_rules_rust//rust:private/rustc.bzl", "BuildInfo", "DepInfo", "get_cc_compile_env", "get_cc_toolchain", "get_compilation_mode_opts", "get_linker_and_args")
+load("@io_bazel_rules_rust//rust:private/rustc.bzl", "BuildInfo", "DepInfo", "get_cc_toolchain", "get_compilation_mode_opts", "get_linker_and_args")
 load("@io_bazel_rules_rust//rust:private/utils.bzl", "find_toolchain")
 load("@io_bazel_rules_rust//rust:rust.bzl", "rust_binary")
 
 def _expand_location(ctx, env, data):
-    for directive in "$(execpath ", "$(location ":
+    """A trivial helper for `_expand_locations`
+
+    Args:
+        ctx (ctx): The rule's context object
+        env (str): The value possibly containing location macros to expand.
+        data (sequence of Targets): see `_expand_locations`
+
+    Returns:
+        string: The location-macro expanded version of the string.
+    """
+    for directive in ("$(execpath ", "$(location "):
         if directive in env:
             # build script runner will expand pwd to execroot for us
             env = env.replace(directive, "${pwd}/" + directive)
     return ctx.expand_location(env, data)
 
-def _expand_locations(ctx):
-    "Expand $(execpath ...) references in user-provided env vars."
-    env = ctx.attr.build_script_env
-    data = getattr(ctx.attr, "data", [])
+def _expand_locations(ctx, env, data):
+    """Performs location-macro expansion on string values.
+
+    Note that exec-root relative locations will be exposed to the build script
+    as absolute paths, rather than the ordinary exec-root relative paths,
+    because cargo build scripts do not run in the exec root.
+
+    Args:
+        ctx (ctx): The rule's context object
+        env (dict): A dict whose values we iterate over
+        data (sequence of Targets): The targets which may be referenced by
+            location macros. This is expected to be the `data` attribute of
+            the target, though may have other targets or attributes mixed in.
+
+    Returns:
+        dict: A dict of environment variables with expanded location macros
+    """
     return dict([(k, _expand_location(ctx, v, data)) for (k, v) in env.items()])
 
+def get_cc_compile_env(cc_toolchain, feature_configuration):
+    """Gather cc environment variables from the given `cc_toolchain`
+
+    Args:
+        cc_toolchain (cc_toolchain): The current rule's `cc_toolchain`.
+        feature_configuration (FeatureConfiguration): Class used to construct command lines from CROSSTOOL features.
+
+    Returns:
+        dict: Returns environment variables to be set for given action.
+    """
+    compile_variables = cc_common.create_compile_variables(
+        feature_configuration = feature_configuration,
+        cc_toolchain = cc_toolchain,
+    )
+    return cc_common.get_environment_variables(
+        feature_configuration = feature_configuration,
+        action_name = C_COMPILE_ACTION_NAME,
+        variables = compile_variables,
+    )
+
 def _build_script_impl(ctx):
     """The implementation for the `_build_script_run` rule.
 
@@ -101,7 +145,11 @@ def _build_script_impl(ctx):
     for f in ctx.attr.crate_features:
         env["CARGO_FEATURE_" + f.upper().replace("-", "_")] = "1"
 
-    env.update(_expand_locations(ctx))
+    env.update(_expand_locations(
+        ctx,
+        ctx.attr.build_script_env,
+        getattr(ctx.attr, "data", []),
+    ))
 
     tools = depset(
         direct = [

docs/BUILD

@@ -45,6 +45,8 @@ PAGES = {
         "rust_bindgen",
     ],
     "rust_wasm_bindgen": [
+        # This cannot be included due to https://github.com/google/cargo-raze/issues/285
+        # "rust_wasm_bindgen_repositories",
         "rust_wasm_bindgen_toolchain",
         "rust_wasm_bindgen",
     ],

docs/README.md

@@ -1 +1,3 @@
-The index.html in this directory is rendered at https://bazelbuild.github.io/rules_rust/ via [github pages](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/).
+# [docs](https://bazelbuild.github.io/rules_rust/)
+
+The index.md in this directory is rendered at https://bazelbuild.github.io/rules_rust/ via [github pages](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/).

docs/all.bzl

@@ -1,17 +1,37 @@
-# buildifier: disable=module-docstring
+"""This module provides a single place for all aspects, rules, and macros that are meant
+to have stardoc generated documentation.
+"""
+
 load(
-    "@io_bazel_rules_rust//rust:toolchain.bzl",
-    _rust_toolchain = "rust_toolchain",
+    "@io_bazel_rules_rust//:workspace.bzl",
+    _rust_workspace = "rust_workspace",
 )
 load(
-    "@io_bazel_rules_rust//proto:toolchain.bzl",
-    _rust_proto_toolchain = "rust_proto_toolchain",
+    "@io_bazel_rules_rust//bindgen:bindgen.bzl",
+    _rust_bindgen = "rust_bindgen",
+    _rust_bindgen_library = "rust_bindgen_library",
+    _rust_bindgen_toolchain = "rust_bindgen_toolchain",
+)
+load(
+    "@io_bazel_rules_rust//cargo:cargo_build_script.bzl",
+    _cargo_build_script = "cargo_build_script",
 )
 load(
     "@io_bazel_rules_rust//proto:proto.bzl",
     _rust_grpc_library = "rust_grpc_library",
     _rust_proto_library = "rust_proto_library",
 )
+load(
+    "@io_bazel_rules_rust//proto:toolchain.bzl",
+    _rust_proto_toolchain = "rust_proto_toolchain",
+)
+load(
+    "@io_bazel_rules_rust//rust:repositories.bzl",
+    _rust_repositories = "rust_repositories",
+    _rust_repository_set = "rust_repository_set",
+    _rust_toolchain_repository = "rust_toolchain_repository",
+    _rust_toolchain_repository_proxy = "rust_toolchain_repository_proxy",
+)
 load(
     "@io_bazel_rules_rust//rust:rust.bzl",
     _rust_benchmark = "rust_benchmark",
@@ -22,38 +42,20 @@ load(
     _rust_test = "rust_test",
 )
 load(
-    "@io_bazel_rules_rust//bindgen:bindgen.bzl",
-    _rust_bindgen = "rust_bindgen",
-    _rust_bindgen_library = "rust_bindgen_library",
-    _rust_bindgen_toolchain = "rust_bindgen_toolchain",
-)
-load(
-    "@io_bazel_rules_rust//cargo:cargo_build_script.bzl",
-    _cargo_build_script = "cargo_build_script",
+    "@io_bazel_rules_rust//rust:toolchain.bzl",
+    _rust_toolchain = "rust_toolchain",
 )
+# This cannot be included due to https://github.com/google/cargo-raze/issues/285
+# load(
+#     "@io_bazel_rules_rust//wasm_bindgen:repositories.bzl",
+#     _rust_wasm_bindgen_repositories = "rust_wasm_bindgen_repositories",
+# )
 load(
     "@io_bazel_rules_rust//wasm_bindgen:wasm_bindgen.bzl",
     _rust_wasm_bindgen = "rust_wasm_bindgen",
     _rust_wasm_bindgen_toolchain = "rust_wasm_bindgen_toolchain",
 )
 
-# rust_wasm_bindgen_repositories depends on raze depedencies which are not worth
-# including.
-# load("@io_bazel_rules_rust//wasm_bindgen:repositories.bzl",
-#     _rust_wasm_bindgen_repositories = "rust_wasm_bindgen_repositories",
-# )
-load(
-    "@io_bazel_rules_rust//rust:repositories.bzl",
-    _rust_repositories = "rust_repositories",
-    _rust_repository_set = "rust_repository_set",
-    _rust_toolchain_repository = "rust_toolchain_repository",
-    _rust_toolchain_repository_proxy = "rust_toolchain_repository_proxy",
-)
-load(
-    "@io_bazel_rules_rust//:workspace.bzl",
-    _rust_workspace = "rust_workspace",
-)
-
 rust_library = _rust_library
 rust_binary = _rust_binary
 rust_test = _rust_test
@@ -75,8 +77,7 @@ cargo_build_script = _cargo_build_script
 
 rust_wasm_bindgen = _rust_wasm_bindgen
 rust_wasm_bindgen_toolchain = _rust_wasm_bindgen_toolchain
-# rust_wasm_bindgen_repositories depends on raze depedencies which are not worth
-# including.
+# This cannot be included due to https://github.com/google/cargo-raze/issues/285
 # rust_wasm_bindgen_repositories = _rust_wasm_bindgen_repositories
 
 rust_repositories = _rust_repositories

docs/flatten.md

@@ -622,7 +622,7 @@ toolchain(
 )
 ```
 
-Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the "--extra_toolchains" flag for Bazel, and it will be used.
+Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the `--extra_toolchains` flag for Bazel, and it will be used.
 
 See @io_bazel_rules_rust//proto:BUILD for examples of defining the toolchain.
 

docs/rust_proto.md

@@ -128,7 +128,7 @@ toolchain(
 )
 ```
 
-Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the "--extra_toolchains" flag for Bazel, and it will be used.
+Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the `--extra_toolchains` flag for Bazel, and it will be used.
 
 See @io_bazel_rules_rust//proto:BUILD for examples of defining the toolchain.
 

proto/toolchain.bzl

@@ -187,7 +187,7 @@ toolchain(
 ```
 
 Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass \
-it to the "--extra_toolchains" flag for Bazel, and it will be used.
+it to the `--extra_toolchains` flag for Bazel, and it will be used.
 
 See @io_bazel_rules_rust//proto:BUILD for examples of defining the toolchain.
 """,

rust/private/rustc.bzl

@@ -17,11 +17,16 @@ load("@bazel_skylib//lib:versions.bzl", "versions")
 load(
     "@bazel_tools//tools/build_defs/cc:action_names.bzl",
     "CPP_LINK_EXECUTABLE_ACTION_NAME",
-    "C_COMPILE_ACTION_NAME",
 )
 load("@bazel_tools//tools/cpp:toolchain_utils.bzl", "find_cpp_toolchain")
 load("@io_bazel_rules_rust_bazel_version//:def.bzl", "BAZEL_VERSION")
-load("@io_bazel_rules_rust//rust:private/utils.bzl", "get_lib_name", "get_libs_for_static_executable", "relativize")
+load(
+    "@io_bazel_rules_rust//rust:private/utils.bzl",
+    "get_lib_name",
+    "get_libs_for_static_executable",
+    "relativize",
+    "rule_attrs",
+)
 
 CrateInfo = provider(
     doc = "A provider containing general Crate information.",
@@ -244,17 +249,6 @@ def get_cc_toolchain(ctx):
     )
     return cc_toolchain, feature_configuration
 
-def get_cc_compile_env(cc_toolchain, feature_configuration):
-    compile_variables = cc_common.create_compile_variables(
-        feature_configuration = feature_configuration,
-        cc_toolchain = cc_toolchain,
-    )
-    return cc_common.get_environment_variables(
-        feature_configuration = feature_configuration,
-        action_name = C_COMPILE_ACTION_NAME,
-        variables = compile_variables,
-    )
-
 def get_cc_user_link_flags(ctx):
     """Get the current target's linkopt flags
 
@@ -310,13 +304,22 @@ def get_linker_and_args(ctx, cc_toolchain, feature_configuration, rpaths):
 
     return ld, link_args, link_env
 
-def _expand_locations(ctx, env, aspect):
-    "Expand $(rootpath ...) references in user-provided env vars."
-    if aspect:
-        data = getattr(ctx.rule.attr, "data", [])
-    else:
-        data = getattr(ctx.attr, "data", [])
+def _expand_locations(ctx, env, data):
+    """Performs location-macro expansion on string values.
 
+    Note: Only `$(rootpath ...)` is recommended  as `$(execpath ...)` will fail
+    in the case of generated sources.
+
+    Args:
+        ctx (ctx): The rule's context object
+        env (str): The value possibly containing location macros to expand.
+        data (sequence of Targets): The targets which may be referenced by
+            location macros. This is expected to be the `data` attribute of
+            the target, though may have other targets or attributes mixed in.
+
+    Returns:
+        dict: A dict of environment variables with expanded location macros
+    """
     return dict([(k, ctx.expand_location(v, data)) for (k, v) in env.items()])
 
 def _process_build_scripts(
@@ -395,6 +398,16 @@ def collect_inputs(
     return _process_build_scripts(ctx, file, crate_info, build_info, dep_info, compile_inputs)
 
 def _exec_root_relative_path(ctx, filepath):
+    """Get the path to filepath, relative to the exec root.
+
+    Args:
+        ctx (ctx): The rule's context object
+        filepath (str): Path of the file to get. This should be relative to the root of the workspace containing the file, such as that returned by `Label.package` or `ctx.build_file_path`
+
+    Returns:
+        str: The path relative to the exec root.
+    """
+
     # Bazel 3.7.0 (commit 301b96b223b0c0) changed how file paths are returned for external packages.
     # TODO: use a proper Bazel API to determine exec-root-relative paths.
     if len(ctx.label.workspace_root) > 0 and \
@@ -569,7 +582,11 @@ def construct_arguments(
                 env["CARGO_BIN_EXE_" + dep_crate_info.output.basename] = dep_crate_info.output.short_path
 
     # Update environment with user provided variables.
-    env.update(_expand_locations(ctx, crate_info.rustc_env, aspect))
+    env.update(_expand_locations(
+        ctx,
+        crate_info.rustc_env,
+        getattr(rule_attrs(ctx, aspect), "data", []),
+    ))
 
     # This empty value satisfies Clippy, which otherwise complains about the
     # sysroot being undefined.
@@ -865,6 +882,6 @@ def _get_dirname(file):
         file (File): The target file
 
     Returns:
-        [str]: Directory name of `file`
+        str: Directory name of `file`
     """
     return file.dirname

rust/private/utils.bzl

@@ -60,10 +60,10 @@ def _path_parts(path):
     is a relative path, such as "./foo".
 
     Args:
-      path: A list containing parts of a path.
+      path (str): A string representing a unix path
 
     Returns:
-      Returns a list containing the path parts with all "." elements removed.
+      list: A list containing the path parts with all "." elements removed.
     """
     path_parts = path.split("/")
     return [part for part in path_parts if part != "."]
@@ -112,7 +112,7 @@ def _get_preferred_artifact(library_to_link):
 
     Args:
         library_to_link (LibraryToLink): See the followg links for additional details:
-          https://docs.bazel.build/versions/master/skylark/lib/LibraryToLink.html
+            https://docs.bazel.build/versions/master/skylark/lib/LibraryToLink.html
 
     Returns:
         File: Returns the first valid library type (only one is expected)
@@ -123,3 +123,20 @@ def _get_preferred_artifact(library_to_link):
         library_to_link.interface_library or
         library_to_link.dynamic_library
     )
+
+def rule_attrs(ctx, aspect):
+    """Gets a rule's attributes.
+
+    As per https://docs.bazel.build/versions/master/skylark/aspects.html when we're executing from an
+    aspect we need to get attributes of a rule differently to if we're not in an aspect.
+
+    Args:
+        ctx (ctx): A rule's context object
+        aspect (bool): Whether we're running in an aspect
+
+    Returns:
+        struct: A struct to access the values of the attributes for a
+            [rule_attributes](https://docs.bazel.build/versions/master/skylark/lib/rule_attributes.html#modules.rule_attributes)
+            object.
+    """
+    return ctx.rule.attr if aspect else ctx.attr

wasm_bindgen/repositories.bzl

@@ -17,7 +17,7 @@ load("//wasm_bindgen/raze:crates.bzl", "rules_rust_wasm_bindgen_fetch_remote_cra
 
 # buildifier: disable=unnamed-macro
 def rust_wasm_bindgen_repositories():
-    """Declare dependencies needed for bindgen."""
+    """Declare dependencies needed for wasm-bindgen."""
 
     rules_rust_wasm_bindgen_fetch_remote_crates()