feat(crates_repository): customizable repin instructions (#2756)

Add customizable instructions to re-pin the repository if required. Many
people have wrapper scripts for keeping dependencies up to date, and
would like to point users to that instead of the default.

This follows the logic of
bazel-contrib/rules_jvm_external#1000

---------

Co-authored-by: Daniel Wagner-Hall <[email protected]>

Author: stevebarrau

crate_universe/private/crates_repository.bzl

@@ -50,6 +50,7 @@ def _crates_repository_impl(repository_ctx):
         splicing_manifest = splicing_manifest,
         cargo = cargo_path,
         rustc = rustc_path,
+        repin_instructions = repository_ctx.attr.repin_instructions,
     )
 
     # If re-pinning is enabled, gather additional inputs for the generator
@@ -281,6 +282,9 @@ CARGO_BAZEL_REPIN=1 CARGO_BAZEL_REPIN_ONLY=crate_index bazel sync --only=crate_i
                 "generate the value for this field. If unset, the defaults defined there will be used."
             ),
         ),
+        "repin_instructions": attr.string(
+            doc = "Instructions to re-pin the repository if required. Many people have wrapper scripts for keeping dependencies up to date, and would like to point users to that instead of the default.",
+        ),
         "rust_toolchain_cargo_template": attr.string(
             doc = (
                 "The template to use for finding the host `cargo` binary. `{version}` (eg. '1.53.0'), " +

crate_universe/private/generate_utils.bzl

@@ -336,7 +336,7 @@ def get_lockfiles(repository_ctx):
         bazel = repository_ctx.path(repository_ctx.attr.lockfile) if repository_ctx.attr.lockfile else None,
     )
 
-def determine_repin(repository_ctx, generator, lockfile_path, config, splicing_manifest, cargo, rustc):
+def determine_repin(repository_ctx, generator, lockfile_path, config, splicing_manifest, cargo, rustc, repin_instructions = None):
     """Use the `cargo-bazel` binary to determine whether or not dpeendencies need to be re-pinned
 
     Args:
@@ -347,6 +347,7 @@ def determine_repin(repository_ctx, generator, lockfile_path, config, splicing_m
         lockfile_path (path): The path to a "lock" file for reproducible outputs.
         cargo (path): The path to a Cargo binary.
         rustc (path): The path to a Rustc binary.
+        repin_instructions (optional string): Instructions to re-pin dependencies in your repository. Will be shown when re-pinning is required.
 
     Returns:
         bool: True if dependencies need to be re-pinned
@@ -403,14 +404,22 @@ def determine_repin(repository_ctx, generator, lockfile_path, config, splicing_m
     # flag indicating repinning was requested, an error is raised
     # since repinning should be an explicit action
     if result.return_code:
-        fail(("\n".join([
-            result.stderr,
-            (
-                "The current `lockfile` is out of date for '{}'. Please re-run " +
-                "bazel using `CARGO_BAZEL_REPIN=true` if this is expected " +
-                "and the lockfile should be updated."
-            ).format(repository_ctx.name),
-        ])))
+        if repin_instructions:
+            msg = ("\n".join([
+                result.stderr,
+                "The current `lockfile` is out of date for '{}'.".format(repository_ctx.name),
+                repin_instructions,
+            ]))
+        else:
+            msg = ("\n".join([
+                result.stderr,
+                (
+                    "The current `lockfile` is out of date for '{}'. Please re-run " +
+                    "bazel using `CARGO_BAZEL_REPIN=true` if this is expected " +
+                    "and the lockfile should be updated."
+                ).format(repository_ctx.name),
+            ]))
+        fail(msg)
 
     return False
 

docs/crate_universe.md

@@ -752,7 +752,7 @@ str: A json encoded string of the parameters provided
 crates_repository(<a href="#crates_repository-name">name</a>, <a href="#crates_repository-annotations">annotations</a>, <a href="#crates_repository-cargo_config">cargo_config</a>, <a href="#crates_repository-cargo_lockfile">cargo_lockfile</a>, <a href="#crates_repository-generate_binaries">generate_binaries</a>,
                   <a href="#crates_repository-generate_build_scripts">generate_build_scripts</a>, <a href="#crates_repository-generate_target_compatible_with">generate_target_compatible_with</a>, <a href="#crates_repository-generator">generator</a>,
                   <a href="#crates_repository-generator_sha256s">generator_sha256s</a>, <a href="#crates_repository-generator_urls">generator_urls</a>, <a href="#crates_repository-isolated">isolated</a>, <a href="#crates_repository-lockfile">lockfile</a>, <a href="#crates_repository-manifests">manifests</a>, <a href="#crates_repository-packages">packages</a>, <a href="#crates_repository-quiet">quiet</a>,
-                  <a href="#crates_repository-render_config">render_config</a>, <a href="#crates_repository-repo_mapping">repo_mapping</a>, <a href="#crates_repository-rust_toolchain_cargo_template">rust_toolchain_cargo_template</a>,
+                  <a href="#crates_repository-render_config">render_config</a>, <a href="#crates_repository-repin_instructions">repin_instructions</a>, <a href="#crates_repository-repo_mapping">repo_mapping</a>, <a href="#crates_repository-rust_toolchain_cargo_template">rust_toolchain_cargo_template</a>,
                   <a href="#crates_repository-rust_toolchain_rustc_template">rust_toolchain_rustc_template</a>, <a href="#crates_repository-rust_version">rust_version</a>, <a href="#crates_repository-splicing_config">splicing_config</a>,
                   <a href="#crates_repository-supported_platform_triples">supported_platform_triples</a>)
 </pre>
@@ -867,6 +867,7 @@ CARGO_BAZEL_REPIN=1 CARGO_BAZEL_REPIN_ONLY=crate_index bazel sync --only=crate_i
 | <a id="crates_repository-packages"></a>packages |  A set of crates (packages) specifications to depend on. See [crate.spec](#crate.spec).   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional |  `{}`  |
 | <a id="crates_repository-quiet"></a>quiet |  If stdout and stderr should not be printed to the terminal.   | Boolean | optional |  `True`  |
 | <a id="crates_repository-render_config"></a>render_config |  The configuration flags to use for rendering. Use `//crate_universe:defs.bzl\%render_config` to generate the value for this field. If unset, the defaults defined there will be used.   | String | optional |  `""`  |
+| <a id="crates_repository-repin_instructions"></a>repin_instructions |  Instructions to re-pin the repository if required. Many people have wrapper scripts for keeping dependencies up to date, and would like to point users to that instead of the default.   | String | optional |  `""`  |
 | <a id="crates_repository-repo_mapping"></a>repo_mapping |  In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<br><br>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).<br><br>This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional |  |
 | <a id="crates_repository-rust_toolchain_cargo_template"></a>rust_toolchain_cargo_template |  The template to use for finding the host `cargo` binary. `{version}` (eg. '1.53.0'), `{triple}` (eg. 'x86_64-unknown-linux-gnu'), `{arch}` (eg. 'aarch64'), `{vendor}` (eg. 'unknown'), `{system}` (eg. 'darwin'), `{cfg}` (eg. 'exec'), `{channel}` (eg. 'stable'), and `{tool}` (eg. 'rustc.exe') will be replaced in the string if present.   | String | optional |  `"@rust_{system}_{arch}__{triple}__{channel}_tools//:bin/{tool}"`  |
 | <a id="crates_repository-rust_toolchain_rustc_template"></a>rust_toolchain_rustc_template |  The template to use for finding the host `rustc` binary. `{version}` (eg. '1.53.0'), `{triple}` (eg. 'x86_64-unknown-linux-gnu'), `{arch}` (eg. 'aarch64'), `{vendor}` (eg. 'unknown'), `{system}` (eg. 'darwin'), `{cfg}` (eg. 'exec'), `{channel}` (eg. 'stable'), and `{tool}` (eg. 'cargo.exe') will be replaced in the string if present.   | String | optional |  `"@rust_{system}_{arch}__{triple}__{channel}_tools//:bin/{tool}"`  |