Update docs on lockfiles (#1477)
diff --git a/crate_universe/private/crates_repository.bzl b/crate_universe/private/crates_repository.bzl
index a440329..f429108 100644
--- a/crate_universe/private/crates_repository.bzl
+++ b/crate_universe/private/crates_repository.bzl
@@ -198,7 +198,9 @@
doc = (
"The path used to store the `crates_repository` specific " +
"[Cargo.lock](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html) file. " +
- "If set, this file must exist within the workspace (but can be empty) before this rule will work."
+ "In the case that your `crates_repository` corresponds directly with an existing " +
+ "`Cargo.toml` file which has a paired `Cargo.lock` file, that `Cargo.lock` file " +
+ "should be used here, which will keep the versions used by cargo and bazel in sync."
),
mandatory = True,
),
@@ -237,7 +239,10 @@
default = True,
),
"lockfile": attr.label(
- doc = "The path to a file to use for reproducible renderings.",
+ doc = (
+ "The path to a file to use for reproducible renderings. " +
+ "If set, this file must exist within the workspace (but can be empty) before this rule will work."
+ ),
),
"manifests": attr.label_list(
doc = "A list of Cargo manifests (`Cargo.toml` files).",
diff --git a/docs/crate_universe.md b/docs/crate_universe.md
index fb330ed..bfb4316 100644
--- a/docs/crate_universe.md
+++ b/docs/crate_universe.md
@@ -280,13 +280,13 @@
| <a id="crates_repository-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a id="crates_repository-annotations"></a>annotations | Extra settings to apply to crates. See [crate.annotation](#crateannotation). | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> List of strings</a> | optional | {} |
| <a id="crates_repository-cargo_config"></a>cargo_config | A [Cargo configuration](https://doc.rust-lang.org/cargo/reference/config.html) file | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
-| <a id="crates_repository-cargo_lockfile"></a>cargo_lockfile | The path used to store the <code>crates_repository</code> specific [Cargo.lock](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html) file. If set, this file must exist within the workspace (but can be empty) before this rule will work. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
+| <a id="crates_repository-cargo_lockfile"></a>cargo_lockfile | The path used to store the <code>crates_repository</code> specific [Cargo.lock](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html) file. In the case that your <code>crates_repository</code> corresponds directly with an existing <code>Cargo.toml</code> file which has a paired <code>Cargo.lock</code> file, that <code>Cargo.lock</code> file should be used here, which will keep the versions used by cargo and bazel in sync. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a id="crates_repository-generate_build_scripts"></a>generate_build_scripts | Whether or not to generate [cargo build scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html) by default. | Boolean | optional | True |
| <a id="crates_repository-generator"></a>generator | The absolute label of a generator. Eg. <code>@cargo_bazel_bootstrap//:cargo-bazel</code>. This is typically used when bootstrapping | String | optional | "" |
| <a id="crates_repository-generator_sha256s"></a>generator_sha256s | Dictionary of <code>host_triple</code> -> <code>sha256</code> for a <code>cargo-bazel</code> binary. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="crates_repository-generator_urls"></a>generator_urls | URL template from which to download the <code>cargo-bazel</code> binary. <code>{host_triple}</code> and will be filled in according to the host platform. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
| <a id="crates_repository-isolated"></a>isolated | If true, <code>CARGO_HOME</code> will be overwritten to a directory within the generated repository in order to prevent other uses of Cargo from impacting having any effect on the generated targets produced by this rule. For users who either have multiple <code>crate_repository</code> definitions in a WORKSPACE or rapidly re-pin dependencies, setting this to false may improve build times. This variable is also controled by <code>CARGO_BAZEL_ISOLATED</code> environment variable. | Boolean | optional | True |
-| <a id="crates_repository-lockfile"></a>lockfile | The path to a file to use for reproducible renderings. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="crates_repository-lockfile"></a>lockfile | The path to a file to use for reproducible renderings. If set, this file must exist within the workspace (but can be empty) before this rule will work. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="crates_repository-manifests"></a>manifests | A list of Cargo manifests (<code>Cargo.toml</code> files). | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <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/docs/skylark/lib/dict.html">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 |
