fork/rules_rust

git clone https://git.julia.blue/fork/rules_rust

Daniel Wagner-HallUpdate docs on lockfiles (#1477)838e4ea8

0.8.1
12.2 KiB297 linesraw
1"""`crates_repository` rule implementation"""
2
3load("//crate_universe/private:common_utils.bzl", "get_rust_tools")
4load(
5    "//crate_universe/private:generate_utils.bzl",
6    "CRATES_REPOSITORY_ENVIRON",
7    "determine_repin",
8    "execute_generator",
9    "generate_config",
10    "get_generator",
11    "get_lockfiles",
12)
13load(
14    "//crate_universe/private:splicing_utils.bzl",
15    "create_splicing_manifest",
16    "splice_workspace_manifest",
17)
18load("//crate_universe/private:urls.bzl", "CARGO_BAZEL_SHA256S", "CARGO_BAZEL_URLS")
19load("//rust:defs.bzl", "rust_common")
20load("//rust/platform:triple.bzl", "get_host_triple")
21load("//rust/platform:triple_mappings.bzl", "SUPPORTED_PLATFORM_TRIPLES")
22
23def _crates_repository_impl(repository_ctx):
24    # Determine the current host's platform triple
25    host_triple = get_host_triple(repository_ctx)
26
27    # Locate the generator to use
28    generator, generator_sha256 = get_generator(repository_ctx, host_triple.str)
29
30    # Generate a config file for all settings
31    config_path = generate_config(repository_ctx)
32
33    # Locate the lockfiles
34    lockfiles = get_lockfiles(repository_ctx)
35
36    # Locate Rust tools (cargo, rustc)
37    tools = get_rust_tools(repository_ctx, host_triple)
38    cargo_path = repository_ctx.path(tools.cargo)
39    rustc_path = repository_ctx.path(tools.rustc)
40
41    # Create a manifest of all dependency inputs
42    splicing_manifest = create_splicing_manifest(repository_ctx)
43
44    # Determine whether or not to repin depednencies
45    repin = determine_repin(
46        repository_ctx = repository_ctx,
47        generator = generator,
48        lockfile_path = lockfiles.bazel,
49        config = config_path,
50        splicing_manifest = splicing_manifest,
51        cargo = cargo_path,
52        rustc = rustc_path,
53    )
54
55    # If re-pinning is enabled, gather additional inputs for the generator
56    kwargs = dict()
57    if repin:
58        # Generate a top level Cargo workspace and manifest for use in generation
59        metadata_path = splice_workspace_manifest(
60            repository_ctx = repository_ctx,
61            generator = generator,
62            cargo_lockfile = lockfiles.cargo,
63            splicing_manifest = splicing_manifest,
64            cargo = cargo_path,
65            rustc = rustc_path,
66        )
67
68        kwargs.update({
69            "metadata": metadata_path,
70        })
71
72    # Run the generator
73    execute_generator(
74        repository_ctx = repository_ctx,
75        generator = generator,
76        config = config_path,
77        splicing_manifest = splicing_manifest,
78        lockfile_path = lockfiles.bazel,
79        cargo_lockfile_path = lockfiles.cargo,
80        repository_dir = repository_ctx.path("."),
81        cargo = cargo_path,
82        rustc = rustc_path,
83        # sysroot = tools.sysroot,
84        **kwargs
85    )
86
87    # Determine the set of reproducible values
88    attrs = {attr: getattr(repository_ctx.attr, attr) for attr in dir(repository_ctx.attr)}
89    exclude = ["to_json", "to_proto"]
90    for attr in exclude:
91        attrs.pop(attr, None)
92
93    # Note that this is only scoped to the current host platform. Users should
94    # ensure they provide all the values necessary for the host environments
95    # they support
96    if generator_sha256:
97        attrs.update({"generator_sha256s": generator_sha256})
98
99    # Inform users that the repository rule can be made deterministic if they
100    # add a label to a lockfile path specifically for Bazel.
101    if not lockfiles.bazel:
102        attrs.update({"lockfile": repository_ctx.attr.cargo_lockfile.relative("cargo-bazel-lock.json")})
103
104    return attrs
105
106crates_repository = repository_rule(
107    doc = """\
108A rule for defining and downloading Rust dependencies (crates). This rule
109handles all the same [workflows](#workflows) `crate_universe` rules do.
110
111Environment Variables:
112
113| variable | usage |
114| --- | --- |
115| `CARGO_BAZEL_GENERATOR_SHA256` | The sha256 checksum of the file located at `CARGO_BAZEL_GENERATOR_URL` |
116| `CARGO_BAZEL_GENERATOR_URL` | The URL of a cargo-bazel binary. This variable takes precedence over attributes and can use `file://` for local paths |
117| `CARGO_BAZEL_ISOLATED` | An authorative flag as to whether or not the `CARGO_HOME` environment variable should be isolated from the host configuration |
118| `CARGO_BAZEL_REPIN` | An indicator that the dependencies represented by the rule should be regenerated. `REPIN` may also be used. See [Repinning / Updating Dependencies](#crates_repository_repinning_updating_dependencies) for more details. |
119
120Example:
121
122Given the following workspace structure:
123
124```text
125[workspace]/
126    WORKSPACE
127    BUILD
128    Cargo.toml
129    Cargo.Bazel.lock
130    src/
131        main.rs
132```
133
134The following is something that'd be found in the `WORKSPACE` file:
135
136```python
137load("@rules_rust//crate_universe:defs.bzl", "crates_repository", "crate")
138
139crates_repository(
140    name = "crate_index",
141    annotations = annotations = {
142        "rand": [crate.annotation(
143            default_features = False,
144            features = ["small_rng"],
145        )],
146    },
147    cargo_lockfile = "//:Cargo.Bazel.lock",
148    lockfile = "//:cargo-bazel-lock.json",
149    manifests = ["//:Cargo.toml"],
150    # Should match the version represented by the currently registered `rust_toolchain`.
151    rust_version = "1.60.0",
152)
153```
154
155The above will create an external repository which contains aliases and macros for accessing
156Rust targets found in the dependency graph defined by the given manifests.
157
158**NOTE**: The `lockfile` must be manually created. The rule unfortunately does not yet create
159it on its own. When initially setting up this rule, an empty file should be created and then
160populated by repinning dependencies.
161
162<a id="#crates_repository_repinning_updating_dependencies"></a>
163
164### Repinning / Updating Dependencies
165
166Dependency syncing and updating is done in the repository rule which means it's done during the
167analysis phase of builds. As mentioned in the environments variable table above, the `CARGO_BAZEL_REPIN`
168(or `REPIN`) environment variables can be used to force the rule to update dependencies and potentially
169render a new lockfile. Given an instance of this repository rule named `crate_index`, the easiest way to
170repin dependencies is to run:
171
172```shell
173CARGO_BAZEL_REPIN=1 bazel sync --only=crate_index
174```
175
176This will result in all dependencies being updated for a project. The `CARGO_BAZEL_REPIN` environment variable
177can also be used to customize how dependencies are updated. The following table shows translations from environment
178variable values to the equivilant [cargo update](https://doc.rust-lang.org/cargo/commands/cargo-update.html) command
179that is called behind the scenes to update dependencies.
180
181| Value | Cargo command |
182| --- | --- |
183| Any of [`true`, `1`, `yes`, `on`] | `cargo update` |
184| `workspace` | `cargo update --workspace` |
185| `package_name` | `cargo upgrade --package package_name` |
186| `package_name@1.2.3` | `cargo upgrade --package package_name --precise 1.2.3` |
187
188""",
189    implementation = _crates_repository_impl,
190    attrs = {
191        "annotations": attr.string_list_dict(
192            doc = "Extra settings to apply to crates. See [crate.annotation](#crateannotation).",
193        ),
194        "cargo_config": attr.label(
195            doc = "A [Cargo configuration](https://doc.rust-lang.org/cargo/reference/config.html) file",
196        ),
197        "cargo_lockfile": attr.label(
198            doc = (
199                "The path used to store the `crates_repository` specific " +
200                "[Cargo.lock](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html) file. " +
201                "In the case that your `crates_repository` corresponds directly with an existing " +
202                "`Cargo.toml` file which has a paired `Cargo.lock` file, that `Cargo.lock` file " +
203                "should be used here, which will keep the versions used by cargo and bazel in sync."
204            ),
205            mandatory = True,
206        ),
207        "generate_build_scripts": attr.bool(
208            doc = (
209                "Whether or not to generate " +
210                "[cargo build scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html) by default."
211            ),
212            default = True,
213        ),
214        "generator": attr.string(
215            doc = (
216                "The absolute label of a generator. Eg. `@cargo_bazel_bootstrap//:cargo-bazel`. " +
217                "This is typically used when bootstrapping"
218            ),
219        ),
220        "generator_sha256s": attr.string_dict(
221            doc = "Dictionary of `host_triple` -> `sha256` for a `cargo-bazel` binary.",
222            default = CARGO_BAZEL_SHA256S,
223        ),
224        "generator_urls": attr.string_dict(
225            doc = (
226                "URL template from which to download the `cargo-bazel` binary. `{host_triple}` and will be " +
227                "filled in according to the host platform."
228            ),
229            default = CARGO_BAZEL_URLS,
230        ),
231        "isolated": attr.bool(
232            doc = (
233                "If true, `CARGO_HOME` will be overwritten to a directory within the generated repository in " +
234                "order to prevent other uses of Cargo from impacting having any effect on the generated targets " +
235                "produced by this rule. For users who either have multiple `crate_repository` definitions in a " +
236                "WORKSPACE or rapidly re-pin dependencies, setting this to false may improve build times. This " +
237                "variable is also controled by `CARGO_BAZEL_ISOLATED` environment variable."
238            ),
239            default = True,
240        ),
241        "lockfile": attr.label(
242            doc = (
243                "The path to a file to use for reproducible renderings. " +
244                "If set, this file must exist within the workspace (but can be empty) before this rule will work."
245            ),
246        ),
247        "manifests": attr.label_list(
248            doc = "A list of Cargo manifests (`Cargo.toml` files).",
249        ),
250        "packages": attr.string_dict(
251            doc = "A set of crates (packages) specifications to depend on. See [crate.spec](#crate.spec).",
252        ),
253        "quiet": attr.bool(
254            doc = "If stdout and stderr should not be printed to the terminal.",
255            default = True,
256        ),
257        "render_config": attr.string(
258            doc = (
259                "The configuration flags to use for rendering. Use `//crate_universe:defs.bzl\\%render_config` to " +
260                "generate the value for this field. If unset, the defaults defined there will be used."
261            ),
262        ),
263        "rust_toolchain_cargo_template": attr.string(
264            doc = (
265                "The template to use for finding the host `cargo` binary. `{version}` (eg. '1.53.0'), " +
266                "`{triple}` (eg. 'x86_64-unknown-linux-gnu'), `{arch}` (eg. 'aarch64'), `{vendor}` (eg. 'unknown'), " +
267                "`{system}` (eg. 'darwin'), `{cfg}` (eg. 'exec'), and `{tool}` (eg. 'rustc.exe') will be replaced in " +
268                "the string if present."
269            ),
270            default = "@rust_{system}_{arch}__{triple}_tools//:bin/{tool}",
271        ),
272        "rust_toolchain_rustc_template": attr.string(
273            doc = (
274                "The template to use for finding the host `rustc` binary. `{version}` (eg. '1.53.0'), " +
275                "`{triple}` (eg. 'x86_64-unknown-linux-gnu'), `{arch}` (eg. 'aarch64'), `{vendor}` (eg. 'unknown'), " +
276                "`{system}` (eg. 'darwin'), `{cfg}` (eg. 'exec'), and `{tool}` (eg. 'cargo.exe') will be replaced in " +
277                "the string if present."
278            ),
279            default = "@rust_{system}_{arch}__{triple}_tools//:bin/{tool}",
280        ),
281        "rust_version": attr.string(
282            doc = "The version of Rust the currently registered toolchain is using. Eg. `1.56.0`, or `nightly-2021-09-08`",
283            default = rust_common.default_version,
284        ),
285        "splicing_config": attr.string(
286            doc = (
287                "The configuration flags to use for splicing Cargo maniests. Use `//crate_universe:defs.bzl\\%rsplicing_config` to " +
288                "generate the value for this field. If unset, the defaults defined there will be used."
289            ),
290        ),
291        "supported_platform_triples": attr.string_list(
292            doc = "A set of all platform triples to consider when generating dependencies.",
293            default = SUPPORTED_PLATFORM_TRIPLES,
294        ),
295    },
296    environ = CRATES_REPOSITORY_ENVIRON,
297)