fork/rules_rust

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

P1n3appl3Deploying to gh-pages from @ P1n3appl3/rules_rust@c07cb1b5e1bec3184239c28bdddd6c5a0a97d634 🚀ba7abedc

gh-pages
88.9 KiB885 linesraw
1<!DOCTYPE HTML>
2<html lang="en" class="light sidebar-visible" dir="ltr">
3    <head>
4        <!-- Book generated using mdBook -->
5        <meta charset="UTF-8">
6        <title>crate_universe (WORKSPACE) - rules_rust</title>
7
8
9        <!-- Custom HTML head -->
10
11        <meta name="description" content="">
12        <meta name="viewport" content="width=device-width, initial-scale=1">
13        <meta name="theme-color" content="#ffffff">
14
15        <link rel="icon" href="favicon.svg">
16        <link rel="shortcut icon" href="favicon.png">
17        <link rel="stylesheet" href="css/variables.css">
18        <link rel="stylesheet" href="css/general.css">
19        <link rel="stylesheet" href="css/chrome.css">
20        <link rel="stylesheet" href="css/print.css" media="print">
21
22        <!-- Fonts -->
23        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
24        <link rel="stylesheet" href="fonts/fonts.css">
25
26        <!-- Highlight.js Stylesheets -->
27        <link rel="stylesheet" href="highlight.css">
28        <link rel="stylesheet" href="tomorrow-night.css">
29        <link rel="stylesheet" href="ayu-highlight.css">
30
31        <!-- Custom theme stylesheets -->
32
33
34        <!-- Provide site root to javascript -->
35        <script>
36            var path_to_root = "";
37            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
38        </script>
39        <!-- Start loading toc.js asap -->
40        <script src="toc.js"></script>
41    </head>
42    <body>
43    <div id="body-container">
44        <!-- Work around some values being stored in localStorage wrapped in quotes -->
45        <script>
46            try {
47                var theme = localStorage.getItem('mdbook-theme');
48                var sidebar = localStorage.getItem('mdbook-sidebar');
49
50                if (theme.startsWith('"') && theme.endsWith('"')) {
51                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
52                }
53
54                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
55                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
56                }
57            } catch (e) { }
58        </script>
59
60        <!-- Set the theme before any content is loaded, prevents flash -->
61        <script>
62            var theme;
63            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
64            if (theme === null || theme === undefined) { theme = default_theme; }
65            const html = document.documentElement;
66            html.classList.remove('light')
67            html.classList.add(theme);
68            html.classList.add("js");
69        </script>
70
71        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
72
73        <!-- Hide / unhide sidebar before it is displayed -->
74        <script>
75            var sidebar = null;
76            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
77            if (document.body.clientWidth >= 1080) {
78                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
79                sidebar = sidebar || 'visible';
80            } else {
81                sidebar = 'hidden';
82            }
83            sidebar_toggle.checked = sidebar === 'visible';
84            html.classList.remove('sidebar-visible');
85            html.classList.add("sidebar-" + sidebar);
86        </script>
87
88        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
89            <!-- populated by js -->
90            <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
91            <noscript>
92                <iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
93            </noscript>
94            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
95                <div class="sidebar-resize-indicator"></div>
96            </div>
97        </nav>
98
99        <div id="page-wrapper" class="page-wrapper">
100
101            <div class="page">
102                <div id="menu-bar-hover-placeholder"></div>
103                <div id="menu-bar" class="menu-bar sticky">
104                    <div class="left-buttons">
105                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
106                            <i class="fa fa-bars"></i>
107                        </label>
108                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
109                            <i class="fa fa-paint-brush"></i>
110                        </button>
111                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
112                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
113                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
114                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
115                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
116                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
117                        </ul>
118                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
119                            <i class="fa fa-search"></i>
120                        </button>
121                    </div>
122
123                    <h1 class="menu-title">rules_rust</h1>
124
125                    <div class="right-buttons">
126                        <a href="print.html" title="Print this book" aria-label="Print this book">
127                            <i id="print-button" class="fa fa-print"></i>
128                        </a>
129                        <a href="https://github.com/bazelbuild/rules_rust" title="Git repository" aria-label="Git repository">
130                            <i id="git-repository-button" class="fa fa-github"></i>
131                        </a>
132
133                    </div>
134                </div>
135
136                <div id="search-wrapper" class="hidden">
137                    <form id="searchbar-outer" class="searchbar-outer">
138                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
139                    </form>
140                    <div id="searchresults-outer" class="searchresults-outer hidden">
141                        <div id="searchresults-header" class="searchresults-header"></div>
142                        <ul id="searchresults">
143                        </ul>
144                    </div>
145                </div>
146
147                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
148                <script>
149                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
150                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
151                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
152                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
153                    });
154                </script>
155
156                <div id="content" class="content">
157                    <main>
158                        <!-- Generated with Stardoc: http://skydoc.bazel.build -->
159<h1 id="crate-universe"><a class="header" href="#crate-universe">Crate Universe</a></h1>
160<p>Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.</p>
161<p>This doc describes using crate_universe from a WORKSPACE file.</p>
162<p>If you're using bzlmod, please see <a href="crate_universe_bzlmod.html">the bzlmod equivalent of this doc</a>.</p>
163<h2 id="setup"><a class="header" href="#setup">Setup</a></h2>
164<p>After loading <code>rules_rust</code> in your workspace, set the following to begin using <code>crate_universe</code>:</p>
165<pre><code class="language-python">load("@rules_rust//crate_universe:repositories.bzl", "crate_universe_dependencies")
166
167crate_universe_dependencies()
168</code></pre>
169<p>Note that if the current version of <code>rules_rust</code> is not a release artifact, you may need to set additional
170flags such as <a href="#crate_universe_dependencies-bootstrap"><code>bootstrap = True</code></a> on the <code>crate_universe_dependencies</code>
171call above or <a href="#crates_repository-generator_urls">crates_repository::generator_urls</a> in uses of <code>crates_repository</code>.</p>
172<h2 id="rules"><a class="header" href="#rules">Rules</a></h2>
173<ul>
174<li><a href="#crates_repository">crates_repository</a></li>
175<li><a href="#crates_vendor">crates_vendor</a></li>
176</ul>
177<h2 id="utility-macros"><a class="header" href="#utility-macros">Utility Macros</a></h2>
178<ul>
179<li><a href="#crate_universe_dependencies">crate_universe_dependencies</a></li>
180<li><a href="#crateannotation">crate.annotation</a></li>
181<li><a href="#crateselect">crate.select</a></li>
182<li><a href="#cratespec">crate.spec</a></li>
183<li><a href="#crateworkspace_member">crate.workspace_member</a></li>
184<li><a href="#render_config">render_config</a></li>
185<li><a href="#splicing_config">splicing_config</a></li>
186</ul>
187<h2 id="workflows"><a class="header" href="#workflows">Workflows</a></h2>
188<p>The <a href="#crates_repository"><code>crates_repository</code></a> rule (the primary repository rule of <code>rules_rust</code>'s cargo support) supports a number of different
189ways users can express and organize their dependencies. The most common are listed below though there are more to be found in
190the <a href="https://github.com/bazelbuild/rules_rust/tree/main/examples/crate_universe">./examples/crate_universe</a> directory.</p>
191<h3 id="cargo-workspaces"><a class="header" href="#cargo-workspaces">Cargo Workspaces</a></h3>
192<p>One of the simpler ways to wire up dependencies would be to first structure your project into a <a href="https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html">Cargo workspace</a>.
193The <code>crates_repository</code> rule can ingest a root <code>Cargo.toml</code> file and generate dependencies from there.</p>
194<pre><code class="language-python">load("@rules_rust//crate_universe:defs.bzl", "crates_repository")
195
196crates_repository(
197    name = "crate_index",
198    cargo_lockfile = "//:Cargo.lock",
199    lockfile = "//:Cargo.Bazel.lock",
200    manifests = ["//:Cargo.toml"],
201)
202
203load("@crate_index//:defs.bzl", "crate_repositories")
204
205crate_repositories()
206</code></pre>
207<p>The generated <code>crates_repository</code> contains helper macros which make collecting dependencies for Bazel targets simpler.
208Notably, the <code>all_crate_deps</code> and <code>aliases</code> macros (see <a href="#dependencies-api">Dependencies API</a>) commonly allow the
209<code>Cargo.toml</code> files to be the single source of truth for dependencies. Since these macros come from the generated
210repository, the dependencies and alias definitions they return will automatically update BUILD targets.</p>
211<pre><code class="language-python">load("@crate_index//:defs.bzl", "aliases", "all_crate_deps")
212load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
213
214rust_library(
215    name = "lib",
216    aliases = aliases(),
217    deps = all_crate_deps(
218        normal = True,
219    ),
220    proc_macro_deps = all_crate_deps(
221        proc_macro = True,
222    ),
223)
224
225rust_test(
226    name = "unit_test",
227    crate = ":lib",
228    aliases = aliases(
229        normal_dev = True,
230        proc_macro_dev = True,
231    ),
232    deps = all_crate_deps(
233        normal_dev = True,
234    ),
235    proc_macro_deps = all_crate_deps(
236        proc_macro_dev = True,
237    ),
238)
239</code></pre>
240<h3 id="direct-packages"><a class="header" href="#direct-packages">Direct Packages</a></h3>
241<p>In cases where Rust targets have heavy interractions with other Bazel targests (<a href="https://docs.bazel.build/versions/main/be/c-cpp.html">Cc</a>, <a href="https://rules-proto-grpc.com/en/latest/lang/rust.html">Proto</a>, etc.),
242maintaining <code>Cargo.toml</code> files may have deminishing returns as things like <a href="https://rust-analyzer.github.io/">rust-analyzer</a> begin to be confused
243about missing targets or environment variables defined only in Bazel. In workspaces like this, it may be desirable
244to have a "Cargo free" setup. <code>crates_repository</code> supports this through the <code>packages</code> attribute.</p>
245<pre><code class="language-python">load("@rules_rust//crate_universe:defs.bzl", "crate", "crates_repository", "render_config")
246
247crates_repository(
248    name = "crate_index",
249    cargo_lockfile = "//:Cargo.lock",
250    lockfile = "//:Cargo.Bazel.lock",
251    packages = {
252        "async-trait": crate.spec(
253            version = "0.1.51",
254        ),
255        "mockall": crate.spec(
256            version = "0.10.2",
257        ),
258        "tokio": crate.spec(
259            version = "1.12.0",
260        ),
261    },
262    # Setting the default package name to `""` forces the use of the macros defined in this repository
263    # to always use the root package when looking for dependencies or aliases. This should be considered
264    # optional as the repository also exposes alises for easy access to all dependencies.
265    render_config = render_config(
266        default_package_name = ""
267    ),
268)
269
270load("@crate_index//:defs.bzl", "crate_repositories")
271
272crate_repositories()
273</code></pre>
274<p>Consuming dependencies may be more ergonomic in this case through the aliases defined in the new repository.</p>
275<pre><code class="language-python">load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
276
277rust_library(
278    name = "lib",
279    deps = [
280        "@crate_index//:tokio",
281    ],
282    proc_macro_deps = [
283        "@crate_index//:async-trait",
284    ],
285)
286
287rust_test(
288    name = "unit_test",
289    crate = ":lib",
290    deps = [
291        "@crate_index//:mockall",
292    ],
293)
294</code></pre>
295<h3 id="binary-dependencies"><a class="header" href="#binary-dependencies">Binary dependencies</a></h3>
296<p>Neither of the above approaches supports depending on binary-only packages.</p>
297<p>In order to depend on a Cargo package that contains binaries and no library, you
298will need to do one of the following:</p>
299<ul>
300<li>
301<p>Fork the package to add an empty lib.rs, which makes the package visible to
302Cargo metadata and compatible with the above approaches;</p>
303</li>
304<li>
305<p>Or handwrite your own build target for the binary, use <code>http_archive</code> to
306import its source code, and use <code>crates_repository</code> to make build targets for
307its dependencies. This is demonstrated below using the <code>rustfilt</code> crate as an
308example.</p>
309</li>
310</ul>
311<pre><code class="language-python"># in WORKSPACE.bazel
312
313load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
314
315http_archive(
316    name = "rustfilt",
317    build_file = "//rustfilt:BUILD.rustfilt.bazel",
318    sha256 = "c8d748b182c8f95224336d20dcc5609598af612581ce60cfb29da4dc8d0091f2",
319    strip_prefix = "rustfilt-0.2.1",
320    type = "tar.gz",
321    urls = ["https://static.crates.io/crates/rustfilt/rustfilt-0.2.1.crate"],
322)
323
324load("@rules_rust//crate_universe:defs.bzl", "crates_repository")
325
326crates_repository(
327    name = "rustfilt_deps",
328    cargo_lockfile = "//rustfilt:Cargo.lock",
329    manifests = ["@rustfilt//:Cargo.toml"],
330)
331
332load("@rustfilt_deps//:defs.bzl", rustfilt_deps = "crate_repositories")
333
334rustfilt_deps()
335</code></pre>
336<pre><code class="language-python"># in rustfilt/BUILD.rustfilt.bazel
337
338load("@rules_rust//rust:defs.bzl", "rust_binary")
339
340rust_binary(
341    name = "rustfilt",
342    srcs = glob(["src/**/*.rs"]),
343    edition = "2018",
344    deps = [
345        "@rustfilt_deps//:clap",
346        "@rustfilt_deps//:lazy_static",
347        "@rustfilt_deps//:regex",
348        "@rustfilt_deps//:rustc-demangle",
349    ],
350)
351</code></pre>
352<p>If you use either <code>crates_repository</code> or <code>crates_vendor</code> to depend on a Cargo
353package that contains <em>both</em> a library crate <em>and</em> binaries, by default only the
354library gets made available to Bazel. To generate Bazel targets for the binary
355crates as well, you must opt in to it with an annotation on the package:</p>
356<pre><code class="language-python">load("@rules_rust//crate_universe:defs.bzl", "crates_repository", "crate")
357
358crates_repository(
359    name = "crate_index",
360    annotations = {
361        "thepackage": [crate.annotation(
362            gen_binaries = True,
363            # Or, to expose just a subset of the package's binaries by name:
364            gen_binaries = ["rustfilt"],
365        )],
366    },
367    # Or, to expose every binary of every package:
368    generate_binaries = True,
369    ...
370)
371</code></pre>
372<h2 id="dependencies-api"><a class="header" href="#dependencies-api">Dependencies API</a></h2>
373<p>After rendering dependencies, convenience macros may also be generated to provide
374convenient accessors to larger sections of the dependency graph.</p>
375<ul>
376<li><a href="#aliases">aliases</a></li>
377<li><a href="#crate_deps">crate_deps</a></li>
378<li><a href="#all_crate_deps">all_crate_deps</a></li>
379<li><a href="#crate_repositories">crate_repositories</a></li>
380</ul>
381<h2 id="building-crates-with-complicated-dependencies"><a class="header" href="#building-crates-with-complicated-dependencies">Building crates with complicated dependencies</a></h2>
382<p>Some crates have build.rs scripts which are complicated to run. Typically these build C++ (or other languages), or attempt to find pre-installed libraries on the build machine.</p>
383<p>There are a few approaches to making sure these run:</p>
384<h3 id="some-things-work-without-intervention"><a class="header" href="#some-things-work-without-intervention">Some things work without intervention</a></h3>
385<p>Some build scripts will happily run without any support needed.</p>
386<p>rules_rust already supplies a configured C++ toolchain as input to build script execution, and sets variables like <code>CC</code>, <code>CXX</code>, <code>LD</code>, <code>LDFLAGS</code>, etc as needed. Many crates which invoke a compiler with the default environment, or forward these env vars, will Just Work (e.g. if using <a href="https://github.com/rust-lang/cc-rs"><code>cc-rs</code></a>).</p>
387<p>rules_rust is open to PRs which make build scripts more likely to work by default with intervention assuming they're broadly applicable (e.g. setting extra widely-known env vars is probably fine, wiring up additional toolchains like <code>cmake</code> that aren't present by default for most Bazel users probably isn't).</p>
388<h3 id="supplying-extra-tools-to-build"><a class="header" href="#supplying-extra-tools-to-build">Supplying extra tools to build</a></h3>
389<p>Some build scripts can be made to work by pulling in some extra files and making them available to the build script.</p>
390<p>Commonly this is done by passing the file to the <code>build_script_data</code> annotation for the crate, and using <code>build_script_env</code> to tell the build script where the file is. That env var may often use <code>$(execroot)</code> to get the path to the label, or <code>$${pwd}/</code> as a prefix if the path given is relative to the execroot (as will frequently happen when using a toolchain).A</p>
391<p>There is an example of this in the "complicated dependencies" section of https://github.com/bazelbuild/rules_rust/blob/main/examples/crate_universe/WORKSPACE.bazel which builds libz-ng-sys.</p>
392<h3 id="building-with-bazel-and-supplying-via-an-override"><a class="header" href="#building-with-bazel-and-supplying-via-an-override">Building with Bazel and supplying via an override</a></h3>
393<p>Some build scripts have hooks to allow replacing parts that are complicated to build with output prepared by Bazel.</p>
394<p>We can use those hooks by specifying paths (generally using the <code>build_script_data</code> and <code>build_script_env</code> annotations) and pointing them at labels which Bazel will then build. These env vars may often use <code>$(execroot)</code> to get the path to the label, or <code>$${pwd}/</code> as a prefix if the path given is relative to the execroot (as will frequently happen when using a toolchain).</p>
395<p>There is an example of this in the "complicated dependencies" section of https://github.com/bazelbuild/rules_rust/blob/main/examples/crate_universe/WORKSPACE.bazel which builds boring-sys.</p>
396<hr />
397<hr />
398<p><a id="crates_vendor"></a></p>
399<h2 id="crates_vendor"><a class="header" href="#crates_vendor">crates_vendor</a></h2>
400<pre>
401crates_vendor(<a href="#crates_vendor-name">name</a>, <a href="#crates_vendor-annotations">annotations</a>, <a href="#crates_vendor-bazel">bazel</a>, <a href="#crates_vendor-buildifier">buildifier</a>, <a href="#crates_vendor-cargo_bazel">cargo_bazel</a>, <a href="#crates_vendor-cargo_config">cargo_config</a>, <a href="#crates_vendor-cargo_lockfile">cargo_lockfile</a>,
402              <a href="#crates_vendor-generate_binaries">generate_binaries</a>, <a href="#crates_vendor-generate_build_scripts">generate_build_scripts</a>, <a href="#crates_vendor-generate_target_compatible_with">generate_target_compatible_with</a>, <a href="#crates_vendor-manifests">manifests</a>,
403              <a href="#crates_vendor-mode">mode</a>, <a href="#crates_vendor-packages">packages</a>, <a href="#crates_vendor-render_config">render_config</a>, <a href="#crates_vendor-repository_name">repository_name</a>, <a href="#crates_vendor-splicing_config">splicing_config</a>,
404              <a href="#crates_vendor-supported_platform_triples">supported_platform_triples</a>, <a href="#crates_vendor-vendor_path">vendor_path</a>)
405</pre>
406<p>A rule for defining Rust dependencies (crates) and writing targets for them to the current workspace.
407This rule is useful for users whose workspaces are expected to be consumed in other workspaces as the
408rendered <code>BUILD</code> files reduce the number of workspace dependencies, allowing for easier loads. This rule
409handles all the same <a href="#workflows">workflows</a> <code>crate_universe</code> rules do.</p>
410<p>Example:</p>
411<p>Given the following workspace structure:</p>
412<pre><code class="language-text">[workspace]/
413    WORKSPACE
414    BUILD
415    Cargo.toml
416    3rdparty/
417        BUILD
418    src/
419        main.rs
420</code></pre>
421<p>The following is something that'd be found in <code>3rdparty/BUILD</code>:</p>
422<pre><code class="language-python">load("@rules_rust//crate_universe:defs.bzl", "crates_vendor", "crate")
423
424crates_vendor(
425    name = "crates_vendor",
426    annotations = {
427        "rand": [crate.annotation(
428            default_features = False,
429            features = ["small_rng"],
430        )],
431    },
432    cargo_lockfile = "//:Cargo.Bazel.lock",
433    manifests = ["//:Cargo.toml"],
434    mode = "remote",
435    vendor_path = "crates",
436    tags = ["manual"],
437)
438</code></pre>
439<p>The above creates a target that can be run to write <code>BUILD</code> files into the <code>3rdparty</code>
440directory next to where the target is defined. To run it, simply call:</p>
441<pre><code class="language-shell">bazel run //3rdparty:crates_vendor
442</code></pre>
443<p><a id="#crates_vendor_repinning_updating_dependencies"></a></p>
444<h3 id="repinning--updating-dependencies"><a class="header" href="#repinning--updating-dependencies">Repinning / Updating Dependencies</a></h3>
445<p>Repinning dependencies is controlled by both the <code>CARGO_BAZEL_REPIN</code> environment variable or the <code>--repin</code>
446flag to the <code>crates_vendor</code> binary. To update dependencies, simply add the flag ro your <code>bazel run</code> invocation.</p>
447<pre><code class="language-shell">bazel run //3rdparty:crates_vendor -- --repin
448</code></pre>
449<p>Under the hood, <code>--repin</code> will trigger a <a href="https://doc.rust-lang.org/cargo/commands/cargo-update.html">cargo update</a>
450call against the generated workspace. The following table describes how to control particular values passed to the
451<code>cargo update</code> command.</p>
452<div class="table-wrapper"><table><thead><tr><th>Value</th><th>Cargo command</th></tr></thead><tbody>
453<tr><td>Any of [<code>true</code>, <code>1</code>, <code>yes</code>, <code>on</code>, <code>workspace</code>]</td><td><code>cargo update --workspace</code></td></tr>
454<tr><td>Any of [<code>full</code>, <code>eager</code>, <code>all</code>]</td><td><code>cargo update</code></td></tr>
455<tr><td><code>package_name</code></td><td><code>cargo upgrade --package package_name</code></td></tr>
456<tr><td><code>package_name@1.2.3</code></td><td><code>cargo upgrade --package package_name --precise 1.2.3</code></td></tr>
457</tbody></table>
458</div>
459<p><strong>ATTRIBUTES</strong></p>
460<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Type</th><th style="text-align: left">Mandatory</th><th style="text-align: left">Default</th></tr></thead><tbody>
461<tr><td style="text-align: left"><a id="crates_vendor-name"></a>name</td><td style="text-align: left">A unique name for this target.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels#target-names">Name</a></td><td style="text-align: left">required</td><td style="text-align: left"></td></tr>
462<tr><td style="text-align: left"><a id="crates_vendor-annotations"></a>annotations</td><td style="text-align: left">Extra settings to apply to crates. See <a href="#crateannotation">crate.annotation</a>.</td><td style="text-align: left"><a href="https://bazel.build/rules/lib/dict">Dictionary: String -&gt; List of strings</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>{}</code></td></tr>
463<tr><td style="text-align: left"><a id="crates_vendor-bazel"></a>bazel</td><td style="text-align: left">The path to a bazel binary used to locate the output_base for the current workspace.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
464<tr><td style="text-align: left"><a id="crates_vendor-buildifier"></a>buildifier</td><td style="text-align: left">The path to a <a href="https://github.com/bazelbuild/buildtools/blob/5.0.1/buildifier/README.md">buildifier</a> binary used to format generated BUILD files.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>"@rules_rust//crate_universe/private/vendor:buildifier"</code></td></tr>
465<tr><td style="text-align: left"><a id="crates_vendor-cargo_bazel"></a>cargo_bazel</td><td style="text-align: left">The cargo-bazel binary to use for vendoring. If this attribute is not set, then a <code>CARGO_BAZEL_GENERATOR_PATH</code> action env will be used.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>"@@rules_rust~~cu~cargo_bazel_bootstrap//:binary"</code></td></tr>
466<tr><td style="text-align: left"><a id="crates_vendor-cargo_config"></a>cargo_config</td><td style="text-align: left">A <a href="https://doc.rust-lang.org/cargo/reference/config.html">Cargo configuration</a> file.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
467<tr><td style="text-align: left"><a id="crates_vendor-cargo_lockfile"></a>cargo_lockfile</td><td style="text-align: left">The path to an existing <code>Cargo.lock</code> file</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
468<tr><td style="text-align: left"><a id="crates_vendor-generate_binaries"></a>generate_binaries</td><td style="text-align: left">Whether to generate <code>rust_binary</code> targets for all the binary crates in every package. By default only the <code>rust_library</code> targets are generated.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>False</code></td></tr>
469<tr><td style="text-align: left"><a id="crates_vendor-generate_build_scripts"></a>generate_build_scripts</td><td style="text-align: left">Whether or not to generate <a href="https://doc.rust-lang.org/cargo/reference/build-scripts.html">cargo build scripts</a> by default.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
470<tr><td style="text-align: left"><a id="crates_vendor-generate_target_compatible_with"></a>generate_target_compatible_with</td><td style="text-align: left">DEPRECATED: Moved to <code>render_config</code>.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
471<tr><td style="text-align: left"><a id="crates_vendor-manifests"></a>manifests</td><td style="text-align: left">A list of Cargo manifests (<code>Cargo.toml</code> files).</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">List of labels</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
472<tr><td style="text-align: left"><a id="crates_vendor-mode"></a>mode</td><td style="text-align: left">Flags determining how crates should be vendored. <code>local</code> is where crate source and BUILD files are written to the repository. <code>remote</code> is where only BUILD files are written and repository rules used to fetch source code.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>"remote"</code></td></tr>
473<tr><td style="text-align: left"><a id="crates_vendor-packages"></a>packages</td><td style="text-align: left">A set of crates (packages) specifications to depend on. See <a href="#crate.spec">crate.spec</a>.</td><td style="text-align: left"><a href="https://bazel.build/rules/lib/dict">Dictionary: String -&gt; String</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>{}</code></td></tr>
474<tr><td style="text-align: left"><a id="crates_vendor-render_config"></a>render_config</td><td style="text-align: left">The configuration flags to use for rendering. Use <code>//crate_universe:defs.bzl\%render_config</code> to generate the value for this field. If unset, the defaults defined there will be used.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
475<tr><td style="text-align: left"><a id="crates_vendor-repository_name"></a>repository_name</td><td style="text-align: left">The name of the repository to generate for <code>remote</code> vendor modes. If unset, the label name will be used</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
476<tr><td style="text-align: left"><a id="crates_vendor-splicing_config"></a>splicing_config</td><td style="text-align: left">The configuration flags to use for splicing Cargo maniests. Use <code>//crate_universe:defs.bzl\%rsplicing_config</code> to generate the value for this field. If unset, the defaults defined there will be used.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
477<tr><td style="text-align: left"><a id="crates_vendor-supported_platform_triples"></a>supported_platform_triples</td><td style="text-align: left">A set of all platform triples to consider when generating dependencies.</td><td style="text-align: left">List of strings</td><td style="text-align: left">optional</td><td style="text-align: left"><code>["aarch64-apple-darwin", "aarch64-apple-ios", "aarch64-apple-ios-sim", "aarch64-linux-android", "aarch64-pc-windows-msvc", "aarch64-unknown-fuchsia", "aarch64-unknown-linux-gnu", "aarch64-unknown-nixos-gnu", "aarch64-unknown-nto-qnx710", "arm-unknown-linux-gnueabi", "armv7-linux-androideabi", "armv7-unknown-linux-gnueabi", "i686-apple-darwin", "i686-linux-android", "i686-pc-windows-msvc", "i686-unknown-freebsd", "i686-unknown-linux-gnu", "powerpc-unknown-linux-gnu", "riscv32imc-unknown-none-elf", "riscv64gc-unknown-none-elf", "s390x-unknown-linux-gnu", "thumbv7em-none-eabi", "thumbv8m.main-none-eabi", "wasm32-unknown-unknown", "wasm32-wasip1", "x86_64-apple-darwin", "x86_64-apple-ios", "x86_64-linux-android", "x86_64-pc-windows-msvc", "x86_64-unknown-freebsd", "x86_64-unknown-fuchsia", "x86_64-unknown-linux-gnu", "x86_64-unknown-nixos-gnu", "x86_64-unknown-none"]</code></td></tr>
478<tr><td style="text-align: left"><a id="crates_vendor-vendor_path"></a>vendor_path</td><td style="text-align: left">The path to a directory to write files into. Absolute paths will be treated as relative to the workspace root</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>"crates"</code></td></tr>
479</tbody></table>
480</div>
481<p><a id="aliases"></a></p>
482<h2 id="aliases"><a class="header" href="#aliases">aliases</a></h2>
483<pre>
484aliases(<a href="#aliases-normal">normal</a>, <a href="#aliases-normal_dev">normal_dev</a>, <a href="#aliases-proc_macro">proc_macro</a>, <a href="#aliases-proc_macro_dev">proc_macro_dev</a>, <a href="#aliases-build">build</a>, <a href="#aliases-build_proc_macro">build_proc_macro</a>, <a href="#aliases-package_name">package_name</a>)
485</pre>
486<p>Produces a map of Crate alias names to their original label</p>
487<p>If no dependency kinds are specified, <code>normal</code> and <code>proc_macro</code> are used by default.
488Setting any one flag will otherwise determine the contents of the returned dict.</p>
489<p><strong>PARAMETERS</strong></p>
490<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
491<tr><td style="text-align: left"><a id="aliases-normal"></a>normal</td><td style="text-align: left">If True, normal dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
492<tr><td style="text-align: left"><a id="aliases-normal_dev"></a>normal_dev</td><td style="text-align: left">If True, normal dev dependencies will be included in the output list..</td><td style="text-align: left"><code>False</code></td></tr>
493<tr><td style="text-align: left"><a id="aliases-proc_macro"></a>proc_macro</td><td style="text-align: left">If True, proc_macro dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
494<tr><td style="text-align: left"><a id="aliases-proc_macro_dev"></a>proc_macro_dev</td><td style="text-align: left">If True, dev proc_macro dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
495<tr><td style="text-align: left"><a id="aliases-build"></a>build</td><td style="text-align: left">If True, build dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
496<tr><td style="text-align: left"><a id="aliases-build_proc_macro"></a>build_proc_macro</td><td style="text-align: left">If True, build proc_macro dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
497<tr><td style="text-align: left"><a id="aliases-package_name"></a>package_name</td><td style="text-align: left">The package name of the set of dependencies to look up. Defaults to <code>native.package_name()</code> when unset.</td><td style="text-align: left"><code>None</code></td></tr>
498</tbody></table>
499</div>
500<p><strong>RETURNS</strong></p>
501<p>dict: The aliases of all associated packages</p>
502<p><a id="all_crate_deps"></a></p>
503<h2 id="all_crate_deps"><a class="header" href="#all_crate_deps">all_crate_deps</a></h2>
504<pre>
505all_crate_deps(<a href="#all_crate_deps-normal">normal</a>, <a href="#all_crate_deps-normal_dev">normal_dev</a>, <a href="#all_crate_deps-proc_macro">proc_macro</a>, <a href="#all_crate_deps-proc_macro_dev">proc_macro_dev</a>, <a href="#all_crate_deps-build">build</a>, <a href="#all_crate_deps-build_proc_macro">build_proc_macro</a>,
506               <a href="#all_crate_deps-package_name">package_name</a>)
507</pre>
508<p>Finds the fully qualified label of all requested direct crate dependencies     for the package where this macro is called.</p>
509<p>If no parameters are set, all normal dependencies are returned. Setting any one flag will
510otherwise impact the contents of the returned list.</p>
511<p><strong>PARAMETERS</strong></p>
512<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
513<tr><td style="text-align: left"><a id="all_crate_deps-normal"></a>normal</td><td style="text-align: left">If True, normal dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
514<tr><td style="text-align: left"><a id="all_crate_deps-normal_dev"></a>normal_dev</td><td style="text-align: left">If True, normal dev dependencies will be included in the output list..</td><td style="text-align: left"><code>False</code></td></tr>
515<tr><td style="text-align: left"><a id="all_crate_deps-proc_macro"></a>proc_macro</td><td style="text-align: left">If True, proc_macro dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
516<tr><td style="text-align: left"><a id="all_crate_deps-proc_macro_dev"></a>proc_macro_dev</td><td style="text-align: left">If True, dev proc_macro dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
517<tr><td style="text-align: left"><a id="all_crate_deps-build"></a>build</td><td style="text-align: left">If True, build dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
518<tr><td style="text-align: left"><a id="all_crate_deps-build_proc_macro"></a>build_proc_macro</td><td style="text-align: left">If True, build proc_macro dependencies are included in the output list.</td><td style="text-align: left"><code>False</code></td></tr>
519<tr><td style="text-align: left"><a id="all_crate_deps-package_name"></a>package_name</td><td style="text-align: left">The package name of the set of dependencies to look up. Defaults to <code>native.package_name()</code> when unset.</td><td style="text-align: left"><code>None</code></td></tr>
520</tbody></table>
521</div>
522<p><strong>RETURNS</strong></p>
523<p>list: A list of labels to generated rust targets (str)</p>
524<p><a id="crate.annotation"></a></p>
525<h2 id="crateannotation"><a class="header" href="#crateannotation">crate.annotation</a></h2>
526<pre>
527crate.annotation(<a href="#crate.annotation-version">version</a>, <a href="#crate.annotation-additive_build_file">additive_build_file</a>, <a href="#crate.annotation-additive_build_file_content">additive_build_file_content</a>, <a href="#crate.annotation-alias_rule">alias_rule</a>,
528                 <a href="#crate.annotation-build_script_compile_data">build_script_compile_data</a>, <a href="#crate.annotation-build_script_data">build_script_data</a>, <a href="#crate.annotation-build_script_tools">build_script_tools</a>,
529                 <a href="#crate.annotation-build_script_data_glob">build_script_data_glob</a>, <a href="#crate.annotation-build_script_deps">build_script_deps</a>, <a href="#crate.annotation-build_script_env">build_script_env</a>,
530                 <a href="#crate.annotation-build_script_proc_macro_deps">build_script_proc_macro_deps</a>, <a href="#crate.annotation-build_script_rundir">build_script_rundir</a>, <a href="#crate.annotation-build_script_rustc_env">build_script_rustc_env</a>,
531                 <a href="#crate.annotation-build_script_toolchains">build_script_toolchains</a>, <a href="#crate.annotation-compile_data">compile_data</a>, <a href="#crate.annotation-compile_data_glob">compile_data_glob</a>, <a href="#crate.annotation-crate_features">crate_features</a>, <a href="#crate.annotation-data">data</a>,
532                 <a href="#crate.annotation-data_glob">data_glob</a>, <a href="#crate.annotation-deps">deps</a>, <a href="#crate.annotation-extra_aliased_targets">extra_aliased_targets</a>, <a href="#crate.annotation-gen_binaries">gen_binaries</a>, <a href="#crate.annotation-disable_pipelining">disable_pipelining</a>,
533                 <a href="#crate.annotation-gen_build_script">gen_build_script</a>, <a href="#crate.annotation-patch_args">patch_args</a>, <a href="#crate.annotation-patch_tool">patch_tool</a>, <a href="#crate.annotation-patches">patches</a>, <a href="#crate.annotation-proc_macro_deps">proc_macro_deps</a>, <a href="#crate.annotation-rustc_env">rustc_env</a>,
534                 <a href="#crate.annotation-rustc_env_files">rustc_env_files</a>, <a href="#crate.annotation-rustc_flags">rustc_flags</a>, <a href="#crate.annotation-shallow_since">shallow_since</a>, <a href="#crate.annotation-override_targets">override_targets</a>)
535</pre>
536<p>A collection of extra attributes and settings for a particular crate</p>
537<p><strong>PARAMETERS</strong></p>
538<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
539<tr><td style="text-align: left"><a id="crate.annotation-version"></a>version</td><td style="text-align: left">The version or semver-conditions to match with a crate. The wildcard <code>*</code> matches any version, including prerelease versions.</td><td style="text-align: left"><code>"*"</code></td></tr>
540<tr><td style="text-align: left"><a id="crate.annotation-additive_build_file"></a>additive_build_file</td><td style="text-align: left">A file containing extra contents to write to the bottom of generated BUILD files.</td><td style="text-align: left"><code>None</code></td></tr>
541<tr><td style="text-align: left"><a id="crate.annotation-additive_build_file_content"></a>additive_build_file_content</td><td style="text-align: left">Extra contents to write to the bottom of generated BUILD files.</td><td style="text-align: left"><code>None</code></td></tr>
542<tr><td style="text-align: left"><a id="crate.annotation-alias_rule"></a>alias_rule</td><td style="text-align: left">Alias rule to use instead of <code>native.alias()</code>.  Overrides <a href="#render_config">render_config</a>'s 'default_alias_rule'.</td><td style="text-align: left"><code>None</code></td></tr>
543<tr><td style="text-align: left"><a id="crate.annotation-build_script_compile_data"></a>build_script_compile_data</td><td style="text-align: left">A list of labels to add to a crate's <code>cargo_build_script::compile_data</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
544<tr><td style="text-align: left"><a id="crate.annotation-build_script_data"></a>build_script_data</td><td style="text-align: left">A list of labels to add to a crate's <code>cargo_build_script::data</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
545<tr><td style="text-align: left"><a id="crate.annotation-build_script_tools"></a>build_script_tools</td><td style="text-align: left">A list of labels to add to a crate's <code>cargo_build_script::tools</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
546<tr><td style="text-align: left"><a id="crate.annotation-build_script_data_glob"></a>build_script_data_glob</td><td style="text-align: left">A list of glob patterns to add to a crate's <code>cargo_build_script::data</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
547<tr><td style="text-align: left"><a id="crate.annotation-build_script_deps"></a>build_script_deps</td><td style="text-align: left">A list of labels to add to a crate's <code>cargo_build_script::deps</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
548<tr><td style="text-align: left"><a id="crate.annotation-build_script_env"></a>build_script_env</td><td style="text-align: left">Additional environment variables to set on a crate's <code>cargo_build_script::env</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
549<tr><td style="text-align: left"><a id="crate.annotation-build_script_proc_macro_deps"></a>build_script_proc_macro_deps</td><td style="text-align: left">A list of labels to add to a crate's <code>cargo_build_script::proc_macro_deps</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
550<tr><td style="text-align: left"><a id="crate.annotation-build_script_rundir"></a>build_script_rundir</td><td style="text-align: left">An override for the build script's rundir attribute.</td><td style="text-align: left"><code>None</code></td></tr>
551<tr><td style="text-align: left"><a id="crate.annotation-build_script_rustc_env"></a>build_script_rustc_env</td><td style="text-align: left">Additional environment variables to set on a crate's <code>cargo_build_script::env</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
552<tr><td style="text-align: left"><a id="crate.annotation-build_script_toolchains"></a>build_script_toolchains</td><td style="text-align: left">A list of labels to set on a crates's <code>cargo_build_script::toolchains</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
553<tr><td style="text-align: left"><a id="crate.annotation-compile_data"></a>compile_data</td><td style="text-align: left">A list of labels to add to a crate's <code>rust_library::compile_data</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
554<tr><td style="text-align: left"><a id="crate.annotation-compile_data_glob"></a>compile_data_glob</td><td style="text-align: left">A list of glob patterns to add to a crate's <code>rust_library::compile_data</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
555<tr><td style="text-align: left"><a id="crate.annotation-crate_features"></a>crate_features</td><td style="text-align: left">A list of strings to add to a crate's <code>rust_library::crate_features</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
556<tr><td style="text-align: left"><a id="crate.annotation-data"></a>data</td><td style="text-align: left">A list of labels to add to a crate's <code>rust_library::data</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
557<tr><td style="text-align: left"><a id="crate.annotation-data_glob"></a>data_glob</td><td style="text-align: left">A list of glob patterns to add to a crate's <code>rust_library::data</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
558<tr><td style="text-align: left"><a id="crate.annotation-deps"></a>deps</td><td style="text-align: left">A list of labels to add to a crate's <code>rust_library::deps</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
559<tr><td style="text-align: left"><a id="crate.annotation-extra_aliased_targets"></a>extra_aliased_targets</td><td style="text-align: left">A list of targets to add to the generated aliases in the root crate_universe repository.</td><td style="text-align: left"><code>None</code></td></tr>
560<tr><td style="text-align: left"><a id="crate.annotation-gen_binaries"></a>gen_binaries</td><td style="text-align: left">As a list, the subset of the crate's bins that should get <code>rust_binary</code> targets produced. Or <code>True</code> to generate all, <code>False</code> to generate none.</td><td style="text-align: left"><code>None</code></td></tr>
561<tr><td style="text-align: left"><a id="crate.annotation-disable_pipelining"></a>disable_pipelining</td><td style="text-align: left">If True, disables pipelining for library targets for this crate.</td><td style="text-align: left"><code>False</code></td></tr>
562<tr><td style="text-align: left"><a id="crate.annotation-gen_build_script"></a>gen_build_script</td><td style="text-align: left">An authorative flag to determine whether or not to produce <code>cargo_build_script</code> targets for the current crate.</td><td style="text-align: left"><code>None</code></td></tr>
563<tr><td style="text-align: left"><a id="crate.annotation-patch_args"></a>patch_args</td><td style="text-align: left">The <code>patch_args</code> attribute of a Bazel repository rule. See <a href="https://docs.bazel.build/versions/main/repo/http.html#http_archive-patch_args">http_archive.patch_args</a></td><td style="text-align: left"><code>None</code></td></tr>
564<tr><td style="text-align: left"><a id="crate.annotation-patch_tool"></a>patch_tool</td><td style="text-align: left">The <code>patch_tool</code> attribute of a Bazel repository rule. See <a href="https://docs.bazel.build/versions/main/repo/http.html#http_archive-patch_tool">http_archive.patch_tool</a></td><td style="text-align: left"><code>None</code></td></tr>
565<tr><td style="text-align: left"><a id="crate.annotation-patches"></a>patches</td><td style="text-align: left">The <code>patches</code> attribute of a Bazel repository rule. See <a href="https://docs.bazel.build/versions/main/repo/http.html#http_archive-patches">http_archive.patches</a></td><td style="text-align: left"><code>None</code></td></tr>
566<tr><td style="text-align: left"><a id="crate.annotation-proc_macro_deps"></a>proc_macro_deps</td><td style="text-align: left">A list of labels to add to a crate's <code>rust_library::proc_macro_deps</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
567<tr><td style="text-align: left"><a id="crate.annotation-rustc_env"></a>rustc_env</td><td style="text-align: left">Additional variables to set on a crate's <code>rust_library::rustc_env</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
568<tr><td style="text-align: left"><a id="crate.annotation-rustc_env_files"></a>rustc_env_files</td><td style="text-align: left">A list of labels to set on a crate's <code>rust_library::rustc_env_files</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
569<tr><td style="text-align: left"><a id="crate.annotation-rustc_flags"></a>rustc_flags</td><td style="text-align: left">A list of strings to set on a crate's <code>rust_library::rustc_flags</code> attribute.</td><td style="text-align: left"><code>None</code></td></tr>
570<tr><td style="text-align: left"><a id="crate.annotation-shallow_since"></a>shallow_since</td><td style="text-align: left">An optional timestamp used for crates originating from a git repository instead of a crate registry. This flag optimizes fetching the source code.</td><td style="text-align: left"><code>None</code></td></tr>
571<tr><td style="text-align: left"><a id="crate.annotation-override_targets"></a>override_targets</td><td style="text-align: left">A dictionary of alternate targets to use when something depends on this crate to allow the parent repo to provide its own version of this dependency. Keys can be <code>proc-marco</code>, <code>custom-build</code>, <code>lib</code>, <code>bin</code>.</td><td style="text-align: left"><code>None</code></td></tr>
572</tbody></table>
573</div>
574<p><strong>RETURNS</strong></p>
575<p>string: A json encoded string containing the specified version and separately all other inputs.</p>
576<p><a id="crate.select"></a></p>
577<h2 id="crateselect"><a class="header" href="#crateselect">crate.select</a></h2>
578<pre>
579crate.select(<a href="#crate.select-common">common</a>, <a href="#crate.select-selects">selects</a>)
580</pre>
581<p>A Starlark Select for <code>crate.annotation()</code>.</p>
582<p><strong>PARAMETERS</strong></p>
583<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
584<tr><td style="text-align: left"><a id="crate.select-common"></a>common</td><td style="text-align: left">A value that applies to all configurations.</td><td style="text-align: left">none</td></tr>
585<tr><td style="text-align: left"><a id="crate.select-selects"></a>selects</td><td style="text-align: left">A dict of <code>target_triple</code> to values.</td><td style="text-align: left">none</td></tr>
586</tbody></table>
587</div>
588<p><strong>RETURNS</strong></p>
589<p>struct: A struct representing the Starlark Select.</p>
590<p><a id="crate.spec"></a></p>
591<h2 id="cratespec"><a class="header" href="#cratespec">crate.spec</a></h2>
592<pre>
593crate.spec(<a href="#crate.spec-package">package</a>, <a href="#crate.spec-version">version</a>, <a href="#crate.spec-artifact">artifact</a>, <a href="#crate.spec-lib">lib</a>, <a href="#crate.spec-default_features">default_features</a>, <a href="#crate.spec-features">features</a>, <a href="#crate.spec-git">git</a>, <a href="#crate.spec-branch">branch</a>, <a href="#crate.spec-tag">tag</a>, <a href="#crate.spec-rev">rev</a>)
594</pre>
595<p>A constructor for a crate dependency.</p>
596<p>See <a href="https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html">specifying dependencies</a> in the Cargo book for more details.</p>
597<p><strong>PARAMETERS</strong></p>
598<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
599<tr><td style="text-align: left"><a id="crate.spec-package"></a>package</td><td style="text-align: left">The explicit name of the package (used when attempting to alias a crate).</td><td style="text-align: left"><code>None</code></td></tr>
600<tr><td style="text-align: left"><a id="crate.spec-version"></a>version</td><td style="text-align: left">The exact version of the crate. Cannot be used with <code>git</code>.</td><td style="text-align: left"><code>None</code></td></tr>
601<tr><td style="text-align: left"><a id="crate.spec-artifact"></a>artifact</td><td style="text-align: left">Set to "bin" to pull in a binary crate as an artifact dependency. Requires a nightly Cargo.</td><td style="text-align: left"><code>None</code></td></tr>
602<tr><td style="text-align: left"><a id="crate.spec-lib"></a>lib</td><td style="text-align: left">If using <code>artifact = "bin"</code>, additionally setting <code>lib = True</code> declares a dependency on both the package's library and binary, as opposed to just the binary.</td><td style="text-align: left"><code>None</code></td></tr>
603<tr><td style="text-align: left"><a id="crate.spec-default_features"></a>default_features</td><td style="text-align: left">Maps to the <code>default-features</code> flag.</td><td style="text-align: left"><code>True</code></td></tr>
604<tr><td style="text-align: left"><a id="crate.spec-features"></a>features</td><td style="text-align: left">A list of features to use for the crate</td><td style="text-align: left"><code>[]</code></td></tr>
605<tr><td style="text-align: left"><a id="crate.spec-git"></a>git</td><td style="text-align: left">The Git url to use for the crate. Cannot be used with <code>version</code>.</td><td style="text-align: left"><code>None</code></td></tr>
606<tr><td style="text-align: left"><a id="crate.spec-branch"></a>branch</td><td style="text-align: left">The git branch of the remote crate. Tied with the <code>git</code> param. Only one of branch, tag or rev may be specified. Specifying <code>rev</code> is recommended for fully-reproducible builds.</td><td style="text-align: left"><code>None</code></td></tr>
607<tr><td style="text-align: left"><a id="crate.spec-tag"></a>tag</td><td style="text-align: left">The git tag of the remote crate. Tied with the <code>git</code> param. Only one of branch, tag or rev may be specified. Specifying <code>rev</code> is recommended for fully-reproducible builds.</td><td style="text-align: left"><code>None</code></td></tr>
608<tr><td style="text-align: left"><a id="crate.spec-rev"></a>rev</td><td style="text-align: left">The git revision of the remote crate. Tied with the <code>git</code> param. Only one of branch, tag or rev may be specified.</td><td style="text-align: left"><code>None</code></td></tr>
609</tbody></table>
610</div>
611<p><strong>RETURNS</strong></p>
612<p>string: A json encoded string of all inputs</p>
613<p><a id="crate.workspace_member"></a></p>
614<h2 id="crateworkspace_member"><a class="header" href="#crateworkspace_member">crate.workspace_member</a></h2>
615<pre>
616crate.workspace_member(<a href="#crate.workspace_member-version">version</a>, <a href="#crate.workspace_member-sha256">sha256</a>)
617</pre>
618<p>Define information for extra workspace members</p>
619<p><strong>PARAMETERS</strong></p>
620<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
621<tr><td style="text-align: left"><a id="crate.workspace_member-version"></a>version</td><td style="text-align: left">The semver of the crate to download. Must be an exact version.</td><td style="text-align: left">none</td></tr>
622<tr><td style="text-align: left"><a id="crate.workspace_member-sha256"></a>sha256</td><td style="text-align: left">The sha256 checksum of the <code>.crate</code> file.</td><td style="text-align: left"><code>None</code></td></tr>
623</tbody></table>
624</div>
625<p><strong>RETURNS</strong></p>
626<p>string: A json encoded string of all inputs</p>
627<p><a id="crate_deps"></a></p>
628<h2 id="crate_deps"><a class="header" href="#crate_deps">crate_deps</a></h2>
629<pre>
630crate_deps(<a href="#crate_deps-deps">deps</a>, <a href="#crate_deps-package_name">package_name</a>)
631</pre>
632<p>Finds the fully qualified label of the requested crates for the package where this macro is called.</p>
633<p><strong>PARAMETERS</strong></p>
634<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
635<tr><td style="text-align: left"><a id="crate_deps-deps"></a>deps</td><td style="text-align: left">The desired list of crate targets.</td><td style="text-align: left">none</td></tr>
636<tr><td style="text-align: left"><a id="crate_deps-package_name"></a>package_name</td><td style="text-align: left">The package name of the set of dependencies to look up. Defaults to <code>native.package_name()</code>.</td><td style="text-align: left"><code>None</code></td></tr>
637</tbody></table>
638</div>
639<p><strong>RETURNS</strong></p>
640<p>list: A list of labels to generated rust targets (str)</p>
641<p><a id="crate_repositories"></a></p>
642<h2 id="crate_repositories"><a class="header" href="#crate_repositories">crate_repositories</a></h2>
643<pre>
644crate_repositories()
645</pre>
646<p>A macro for defining repositories for all generated crates.</p>
647<p><strong>RETURNS</strong></p>
648<p>A list of repos visible to the module through the module extension.</p>
649<p><a id="crate_universe_dependencies"></a></p>
650<h2 id="crate_universe_dependencies"><a class="header" href="#crate_universe_dependencies">crate_universe_dependencies</a></h2>
651<pre>
652crate_universe_dependencies(<a href="#crate_universe_dependencies-rust_version">rust_version</a>, <a href="#crate_universe_dependencies-bootstrap">bootstrap</a>, <a href="#crate_universe_dependencies-kwargs">kwargs</a>)
653</pre>
654<p>Define dependencies of the <code>cargo-bazel</code> Rust target</p>
655<p><strong>PARAMETERS</strong></p>
656<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
657<tr><td style="text-align: left"><a id="crate_universe_dependencies-rust_version"></a>rust_version</td><td style="text-align: left">The version of rust to use when generating dependencies.</td><td style="text-align: left"><code>"1.83.0"</code></td></tr>
658<tr><td style="text-align: left"><a id="crate_universe_dependencies-bootstrap"></a>bootstrap</td><td style="text-align: left">If true, a <code>cargo_bootstrap_repository</code> target will be generated.</td><td style="text-align: left"><code>False</code></td></tr>
659<tr><td style="text-align: left"><a id="crate_universe_dependencies-kwargs"></a>kwargs</td><td style="text-align: left">Arguments to pass through to cargo_bazel_bootstrap.</td><td style="text-align: left">none</td></tr>
660</tbody></table>
661</div>
662<p><strong>RETURNS</strong></p>
663<p>list[struct(repo=str, is_dev_dep=bool)]: A list of the repositories
664defined by this macro.</p>
665<p><a id="render_config"></a></p>
666<h2 id="render_config"><a class="header" href="#render_config">render_config</a></h2>
667<pre>
668render_config(<a href="#render_config-build_file_template">build_file_template</a>, <a href="#render_config-crate_label_template">crate_label_template</a>, <a href="#render_config-crate_repository_template">crate_repository_template</a>,
669              <a href="#render_config-crates_module_template">crates_module_template</a>, <a href="#render_config-default_alias_rule">default_alias_rule</a>, <a href="#render_config-default_package_name">default_package_name</a>,
670              <a href="#render_config-generate_target_compatible_with">generate_target_compatible_with</a>, <a href="#render_config-platforms_template">platforms_template</a>, <a href="#render_config-regen_command">regen_command</a>, <a href="#render_config-vendor_mode">vendor_mode</a>,
671              <a href="#render_config-generate_rules_license_metadata">generate_rules_license_metadata</a>)
672</pre>
673<p>Various settings used to configure rendered outputs</p>
674<p>The template parameters each support a select number of format keys. A description of each key
675can be found below where the supported keys for each template can be found in the parameter docs</p>
676<div class="table-wrapper"><table><thead><tr><th>key</th><th>definition</th></tr></thead><tbody>
677<tr><td><code>name</code></td><td>The name of the crate. Eg <code>tokio</code></td></tr>
678<tr><td><code>repository</code></td><td>The rendered repository name for the crate. Directly relates to <code>crate_repository_template</code>.</td></tr>
679<tr><td><code>triple</code></td><td>A platform triple. Eg <code>x86_64-unknown-linux-gnu</code></td></tr>
680<tr><td><code>version</code></td><td>The crate version. Eg <code>1.2.3</code></td></tr>
681<tr><td><code>target</code></td><td>The library or binary target of the crate</td></tr>
682<tr><td><code>file</code></td><td>The basename of a file</td></tr>
683</tbody></table>
684</div>
685<p><strong>PARAMETERS</strong></p>
686<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
687<tr><td style="text-align: left"><a id="render_config-build_file_template"></a>build_file_template</td><td style="text-align: left">The base template to use for BUILD file names. The available format keys are [<code>{name}</code>, {version}`].</td><td style="text-align: left"><code>"//:BUILD.{name}-{version}.bazel"</code></td></tr>
688<tr><td style="text-align: left"><a id="render_config-crate_label_template"></a>crate_label_template</td><td style="text-align: left">The base template to use for crate labels. The available format keys are [<code>{repository}</code>, <code>{name}</code>, <code>{version}</code>, <code>{target}</code>].</td><td style="text-align: left"><code>"@{repository}__{name}-{version}//:{target}"</code></td></tr>
689<tr><td style="text-align: left"><a id="render_config-crate_repository_template"></a>crate_repository_template</td><td style="text-align: left">The base template to use for Crate label repository names. The available format keys are [<code>{repository}</code>, <code>{name}</code>, <code>{version}</code>].</td><td style="text-align: left"><code>"{repository}__{name}-{version}"</code></td></tr>
690<tr><td style="text-align: left"><a id="render_config-crates_module_template"></a>crates_module_template</td><td style="text-align: left">The pattern to use for the <code>defs.bzl</code> and <code>BUILD.bazel</code> file names used for the crates module. The available format keys are [<code>{file}</code>].</td><td style="text-align: left"><code>"//:{file}"</code></td></tr>
691<tr><td style="text-align: left"><a id="render_config-default_alias_rule"></a>default_alias_rule</td><td style="text-align: left">Alias rule to use when generating aliases for all crates.  Acceptable values are 'alias', 'dbg'/'fastbuild'/'opt' (transitions each crate's <code>compilation_mode</code>)  or a string representing a rule in the form '&lt;label to .bzl&gt;:<rule>' that takes a single label parameter 'actual'. See '@crate_index//:alias_rules.bzl' for an example.</td><td style="text-align: left"><code>"alias"</code></td></tr>
692<tr><td style="text-align: left"><a id="render_config-default_package_name"></a>default_package_name</td><td style="text-align: left">The default package name to use in the rendered macros. This affects the auto package detection of things like <code>all_crate_deps</code>.</td><td style="text-align: left"><code>None</code></td></tr>
693<tr><td style="text-align: left"><a id="render_config-generate_target_compatible_with"></a>generate_target_compatible_with</td><td style="text-align: left">Whether to generate <code>target_compatible_with</code> annotations on the generated BUILD files.  This catches a <code>target_triple</code>being targeted that isn't declared in <code>supported_platform_triples</code>.</td><td style="text-align: left"><code>True</code></td></tr>
694<tr><td style="text-align: left"><a id="render_config-platforms_template"></a>platforms_template</td><td style="text-align: left">The base template to use for platform names. See <a href="https://docs.bazel.build/versions/main/platforms.html">platforms documentation</a>. The available format keys are [<code>{triple}</code>].</td><td style="text-align: left"><code>"@rules_rust//rust/platform:{triple}"</code></td></tr>
695<tr><td style="text-align: left"><a id="render_config-regen_command"></a>regen_command</td><td style="text-align: left">An optional command to demonstrate how generated files should be regenerated.</td><td style="text-align: left"><code>None</code></td></tr>
696<tr><td style="text-align: left"><a id="render_config-vendor_mode"></a>vendor_mode</td><td style="text-align: left">An optional configuration for rendirng content to be rendered into repositories.</td><td style="text-align: left"><code>None</code></td></tr>
697<tr><td style="text-align: left"><a id="render_config-generate_rules_license_metadata"></a>generate_rules_license_metadata</td><td style="text-align: left">Whether to generate rules license metedata</td><td style="text-align: left"><code>False</code></td></tr>
698</tbody></table>
699</div>
700<p><strong>RETURNS</strong></p>
701<p>string: A json encoded struct to match the Rust <code>config::RenderConfig</code> struct</p>
702<p><a id="splicing_config"></a></p>
703<h2 id="splicing_config"><a class="header" href="#splicing_config">splicing_config</a></h2>
704<pre>
705splicing_config(<a href="#splicing_config-resolver_version">resolver_version</a>)
706</pre>
707<p>Various settings used to configure Cargo manifest splicing behavior.</p>
708<p><strong>PARAMETERS</strong></p>
709<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Default Value</th></tr></thead><tbody>
710<tr><td style="text-align: left"><a id="splicing_config-resolver_version"></a>resolver_version</td><td style="text-align: left">The <a href="https://doc.rust-lang.org/cargo/reference/resolver.html#resolver-versions">resolver version</a> to use in generated Cargo manifests. This flag is <strong>only</strong> used when splicing a manifest from direct package definitions. See <code>crates_repository::packages</code>.</td><td style="text-align: left"><code>"2"</code></td></tr>
711</tbody></table>
712</div>
713<p><strong>RETURNS</strong></p>
714<p>str: A json encoded string of the parameters provided</p>
715<p><a id="crates_repository"></a></p>
716<h2 id="crates_repository"><a class="header" href="#crates_repository">crates_repository</a></h2>
717<pre>
718crates_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>,
719                  <a href="#crates_repository-compressed_windows_toolchain_names">compressed_windows_toolchain_names</a>, <a href="#crates_repository-generate_binaries">generate_binaries</a>, <a href="#crates_repository-generate_build_scripts">generate_build_scripts</a>,
720                  <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>,
721                  <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-repin_instructions">repin_instructions</a>,
722                  <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>,
723                  <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>)
724</pre>
725<p>A rule for defining and downloading Rust dependencies (crates). This rule
726handles all the same <a href="#workflows">workflows</a> <code>crate_universe</code> rules do.</p>
727<p>Environment Variables:</p>
728<div class="table-wrapper"><table><thead><tr><th>variable</th><th>usage</th></tr></thead><tbody>
729<tr><td><code>CARGO_BAZEL_GENERATOR_SHA256</code></td><td>The sha256 checksum of the file located at <code>CARGO_BAZEL_GENERATOR_URL</code></td></tr>
730<tr><td><code>CARGO_BAZEL_GENERATOR_URL</code></td><td>The URL of a cargo-bazel binary. This variable takes precedence over attributes and can use <code>file://</code> for local paths</td></tr>
731<tr><td><code>CARGO_BAZEL_ISOLATED</code></td><td>An authorative flag as to whether or not the <code>CARGO_HOME</code> environment variable should be isolated from the host configuration</td></tr>
732<tr><td><code>CARGO_BAZEL_REPIN</code></td><td>An indicator that the dependencies represented by the rule should be regenerated. <code>REPIN</code> may also be used. See <a href="#repinning--updating-dependencies">Repinning / Updating Dependencies</a> for more details.</td></tr>
733<tr><td><code>CARGO_BAZEL_REPIN_ONLY</code></td><td>A comma-delimited allowlist for rules to execute repinning. Can be useful if multiple instances of the repository rule are used in a Bazel workspace, but repinning should be limited to one of them.</td></tr>
734</tbody></table>
735</div>
736<p>Example:</p>
737<p>Given the following workspace structure:</p>
738<pre><code class="language-text">[workspace]/
739    WORKSPACE.bazel
740    BUILD.bazel
741    Cargo.toml
742    Cargo.Bazel.lock
743    src/
744        main.rs
745</code></pre>
746<p>The following is something that'd be found in the <code>WORKSPACE</code> file:</p>
747<pre><code class="language-python">load("@rules_rust//crate_universe:defs.bzl", "crates_repository", "crate")
748
749crates_repository(
750    name = "crate_index",
751    annotations = {
752        "rand": [crate.annotation(
753            default_features = False,
754            features = ["small_rng"],
755        )],
756    },
757    cargo_lockfile = "//:Cargo.Bazel.lock",
758    lockfile = "//:cargo-bazel-lock.json",
759    manifests = ["//:Cargo.toml"],
760    # Should match the version represented by the currently registered `rust_toolchain`.
761    rust_version = "1.60.0",
762)
763</code></pre>
764<p>The above will create an external repository which contains aliases and macros for accessing
765Rust targets found in the dependency graph defined by the given manifests.</p>
766<p><strong>NOTE</strong>: The <code>cargo_lockfile</code> and <code>lockfile</code> must be manually created. The rule unfortunately does not yet create
767it on its own. When initially setting up this rule, an empty file should be created and then
768populated by repinning dependencies.</p>
769<h3 id="repinning--updating-dependencies-1"><a class="header" href="#repinning--updating-dependencies-1">Repinning / Updating Dependencies</a></h3>
770<p>Dependency syncing and updating is done in the repository rule which means it's done during the
771analysis phase of builds. As mentioned in the environments variable table above, the <code>CARGO_BAZEL_REPIN</code>
772(or <code>REPIN</code>) environment variables can be used to force the rule to update dependencies and potentially
773render a new lockfile. Given an instance of this repository rule named <code>crate_index</code>, the easiest way to
774repin dependencies is to run:</p>
775<pre><code class="language-shell">CARGO_BAZEL_REPIN=1 bazel sync --only=crate_index
776</code></pre>
777<p>This will result in all dependencies being updated for a project. The <code>CARGO_BAZEL_REPIN</code> environment variable
778can also be used to customize how dependencies are updated. The following table shows translations from environment
779variable values to the equivilant <a href="https://doc.rust-lang.org/cargo/commands/cargo-update.html">cargo update</a> command
780that is called behind the scenes to update dependencies.</p>
781<div class="table-wrapper"><table><thead><tr><th>Value</th><th>Cargo command</th></tr></thead><tbody>
782<tr><td>Any of [<code>true</code>, <code>1</code>, <code>yes</code>, <code>on</code>, <code>workspace</code>]</td><td><code>cargo update --workspace</code></td></tr>
783<tr><td>Any of [<code>full</code>, <code>eager</code>, <code>all</code>]</td><td><code>cargo update</code></td></tr>
784<tr><td><code>package_name</code></td><td><code>cargo upgrade --package package_name</code></td></tr>
785<tr><td><code>package_name@1.2.3</code></td><td><code>cargo upgrade --package package_name@1.2.3</code></td></tr>
786<tr><td><code>package_name@1.2.3=4.5.6</code></td><td><code>cargo upgrade --package package_name@1.2.3 --precise=4.5.6</code></td></tr>
787</tbody></table>
788</div>
789<p>If the <code>crates_repository</code> is used multiple times in the same Bazel workspace (e.g. for multiple independent
790Rust workspaces), it may additionally be useful to use the <code>CARGO_BAZEL_REPIN_ONLY</code> environment variable, which
791limits execution of the repinning to one or multiple instances of the <code>crates_repository</code> rule via a comma-delimited
792allowlist:</p>
793<pre><code class="language-shell">CARGO_BAZEL_REPIN=1 CARGO_BAZEL_REPIN_ONLY=crate_index bazel sync --only=crate_index
794</code></pre>
795<p><strong>ATTRIBUTES</strong></p>
796<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Type</th><th style="text-align: left">Mandatory</th><th style="text-align: left">Default</th></tr></thead><tbody>
797<tr><td style="text-align: left"><a id="crates_repository-name"></a>name</td><td style="text-align: left">A unique name for this repository.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels#target-names">Name</a></td><td style="text-align: left">required</td><td style="text-align: left"></td></tr>
798<tr><td style="text-align: left"><a id="crates_repository-annotations"></a>annotations</td><td style="text-align: left">Extra settings to apply to crates. See <a href="#crateannotation">crate.annotation</a>.</td><td style="text-align: left"><a href="https://bazel.build/rules/lib/dict">Dictionary: String -&gt; List of strings</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>{}</code></td></tr>
799<tr><td style="text-align: left"><a id="crates_repository-cargo_config"></a>cargo_config</td><td style="text-align: left">A <a href="https://doc.rust-lang.org/cargo/reference/config.html">Cargo configuration</a> file</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
800<tr><td style="text-align: left"><a id="crates_repository-cargo_lockfile"></a>cargo_lockfile</td><td style="text-align: left">The path used to store the <code>crates_repository</code> specific <a href="https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html">Cargo.lock</a> 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.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">required</td><td style="text-align: left"></td></tr>
801<tr><td style="text-align: left"><a id="crates_repository-compressed_windows_toolchain_names"></a>compressed_windows_toolchain_names</td><td style="text-align: left">Wether or not the toolchain names of windows toolchains are expected to be in a <code>compressed</code> format.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
802<tr><td style="text-align: left"><a id="crates_repository-generate_binaries"></a>generate_binaries</td><td style="text-align: left">Whether to generate <code>rust_binary</code> targets for all the binary crates in every package. By default only the <code>rust_library</code> targets are generated.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>False</code></td></tr>
803<tr><td style="text-align: left"><a id="crates_repository-generate_build_scripts"></a>generate_build_scripts</td><td style="text-align: left">Whether or not to generate <a href="https://doc.rust-lang.org/cargo/reference/build-scripts.html">cargo build scripts</a> by default.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
804<tr><td style="text-align: left"><a id="crates_repository-generate_target_compatible_with"></a>generate_target_compatible_with</td><td style="text-align: left">DEPRECATED: Moved to <code>render_config</code>.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
805<tr><td style="text-align: left"><a id="crates_repository-generator"></a>generator</td><td style="text-align: left">The absolute label of a generator. Eg. <code>@cargo_bazel_bootstrap//:cargo-bazel</code>. This is typically used when bootstrapping</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
806<tr><td style="text-align: left"><a id="crates_repository-generator_sha256s"></a>generator_sha256s</td><td style="text-align: left">Dictionary of <code>host_triple</code> -&gt; <code>sha256</code> for a <code>cargo-bazel</code> binary.</td><td style="text-align: left"><a href="https://bazel.build/rules/lib/dict">Dictionary: String -&gt; String</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>{}</code></td></tr>
807<tr><td style="text-align: left"><a id="crates_repository-generator_urls"></a>generator_urls</td><td style="text-align: left">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.</td><td style="text-align: left"><a href="https://bazel.build/rules/lib/dict">Dictionary: String -&gt; String</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>{}</code></td></tr>
808<tr><td style="text-align: left"><a id="crates_repository-isolated"></a>isolated</td><td style="text-align: left">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.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
809<tr><td style="text-align: left"><a id="crates_repository-lockfile"></a>lockfile</td><td style="text-align: left">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.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
810<tr><td style="text-align: left"><a id="crates_repository-manifests"></a>manifests</td><td style="text-align: left">A list of Cargo manifests (<code>Cargo.toml</code> files).</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">List of labels</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
811<tr><td style="text-align: left"><a id="crates_repository-packages"></a>packages</td><td style="text-align: left">A set of crates (packages) specifications to depend on. See <a href="#crate.spec">crate.spec</a>.</td><td style="text-align: left"><a href="https://bazel.build/rules/lib/dict">Dictionary: String -&gt; String</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>{}</code></td></tr>
812<tr><td style="text-align: left"><a id="crates_repository-quiet"></a>quiet</td><td style="text-align: left">If stdout and stderr should not be printed to the terminal.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
813<tr><td style="text-align: left"><a id="crates_repository-render_config"></a>render_config</td><td style="text-align: left">The configuration flags to use for rendering. Use <code>//crate_universe:defs.bzl\%render_config</code> to generate the value for this field. If unset, the defaults defined there will be used.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
814<tr><td style="text-align: left"><a id="crates_repository-repin_instructions"></a>repin_instructions</td><td style="text-align: left">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.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
815<tr><td style="text-align: left"><a id="crates_repository-repo_mapping"></a>repo_mapping</td><td style="text-align: left">In <code>WORKSPACE</code> 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 <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>).<br><br>This attribute is <em>not</em> supported in <code>MODULE.bazel</code> context (when invoking a repository rule inside a module extension's implementation function).</td><td style="text-align: left"><a href="https://bazel.build/rules/lib/dict">Dictionary: String -&gt; String</a></td><td style="text-align: left">optional</td><td style="text-align: left"></td></tr>
816<tr><td style="text-align: left"><a id="crates_repository-rust_toolchain_cargo_template"></a>rust_toolchain_cargo_template</td><td style="text-align: left">The template to use for finding the host <code>cargo</code> binary. <code>{version}</code> (eg. '1.53.0'), <code>{triple}</code> (eg. 'x86_64-unknown-linux-gnu'), <code>{arch}</code> (eg. 'aarch64'), <code>{vendor}</code> (eg. 'unknown'), <code>{system}</code> (eg. 'darwin'), <code>{cfg}</code> (eg. 'exec'), <code>{channel}</code> (eg. 'stable'), and <code>{tool}</code> (eg. 'rustc.exe') will be replaced in the string if present.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>"@rust_{system}_{arch}__{triple}__{channel}_tools//:bin/{tool}"</code></td></tr>
817<tr><td style="text-align: left"><a id="crates_repository-rust_toolchain_rustc_template"></a>rust_toolchain_rustc_template</td><td style="text-align: left">The template to use for finding the host <code>rustc</code> binary. <code>{version}</code> (eg. '1.53.0'), <code>{triple}</code> (eg. 'x86_64-unknown-linux-gnu'), <code>{arch}</code> (eg. 'aarch64'), <code>{vendor}</code> (eg. 'unknown'), <code>{system}</code> (eg. 'darwin'), <code>{cfg}</code> (eg. 'exec'), <code>{channel}</code> (eg. 'stable'), and <code>{tool}</code> (eg. 'cargo.exe') will be replaced in the string if present.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>"@rust_{system}_{arch}__{triple}__{channel}_tools//:bin/{tool}"</code></td></tr>
818<tr><td style="text-align: left"><a id="crates_repository-rust_version"></a>rust_version</td><td style="text-align: left">The version of Rust the currently registered toolchain is using. Eg. <code>1.56.0</code>, or <code>nightly/2021-09-08</code></td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>"1.83.0"</code></td></tr>
819<tr><td style="text-align: left"><a id="crates_repository-splicing_config"></a>splicing_config</td><td style="text-align: left">The configuration flags to use for splicing Cargo maniests. Use <code>//crate_universe:defs.bzl\%rsplicing_config</code> to generate the value for this field. If unset, the defaults defined there will be used.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
820<tr><td style="text-align: left"><a id="crates_repository-supported_platform_triples"></a>supported_platform_triples</td><td style="text-align: left">A set of all platform triples to consider when generating dependencies.</td><td style="text-align: left">List of strings</td><td style="text-align: left">optional</td><td style="text-align: left"><code>["aarch64-apple-darwin", "aarch64-apple-ios", "aarch64-apple-ios-sim", "aarch64-linux-android", "aarch64-pc-windows-msvc", "aarch64-unknown-fuchsia", "aarch64-unknown-linux-gnu", "aarch64-unknown-nixos-gnu", "aarch64-unknown-nto-qnx710", "arm-unknown-linux-gnueabi", "armv7-linux-androideabi", "armv7-unknown-linux-gnueabi", "i686-apple-darwin", "i686-linux-android", "i686-pc-windows-msvc", "i686-unknown-freebsd", "i686-unknown-linux-gnu", "powerpc-unknown-linux-gnu", "riscv32imc-unknown-none-elf", "riscv64gc-unknown-none-elf", "s390x-unknown-linux-gnu", "thumbv7em-none-eabi", "thumbv8m.main-none-eabi", "wasm32-unknown-unknown", "wasm32-wasip1", "x86_64-apple-darwin", "x86_64-apple-ios", "x86_64-linux-android", "x86_64-pc-windows-msvc", "x86_64-unknown-freebsd", "x86_64-unknown-fuchsia", "x86_64-unknown-linux-gnu", "x86_64-unknown-nixos-gnu", "x86_64-unknown-none"]</code></td></tr>
821</tbody></table>
822</div>
823<p><strong>ENVIRONMENT VARIABLES</strong></p>
824<p>This repository rule depends on the following environment variables:</p>
825<ul>
826<li><code>CARGO_BAZEL_GENERATOR_URL</code></li>
827<li><code>CARGO_BAZEL_GENERATOR_SHA256</code></li>
828<li><code>CARGO_BAZEL_REPIN</code></li>
829<li><code>REPIN</code></li>
830<li><code>CARGO_BAZEL_REPIN_ONLY</code></li>
831<li><code>CARGO_BAZEL_ISOLATED</code></li>
832<li><code>CARGO_BAZEL_DEBUG</code></li>
833</ul>
834
835                    </main>
836
837                    <nav class="nav-wrapper" aria-label="Page navigation">
838                        <!-- Mobile navigation buttons -->
839                            <a rel="prev" href="crate_universe_bzlmod.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
840                                <i class="fa fa-angle-left"></i>
841                            </a>
842
843                            <a rel="next prefetch" href="upstream_tooling.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
844                                <i class="fa fa-angle-right"></i>
845                            </a>
846
847                        <div style="clear: both"></div>
848                    </nav>
849                </div>
850            </div>
851
852            <nav class="nav-wide-wrapper" aria-label="Page navigation">
853                    <a rel="prev" href="crate_universe_bzlmod.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
854                        <i class="fa fa-angle-left"></i>
855                    </a>
856
857                    <a rel="next prefetch" href="upstream_tooling.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
858                        <i class="fa fa-angle-right"></i>
859                    </a>
860            </nav>
861
862        </div>
863
864
865
866
867        <script>
868            window.playground_copyable = true;
869        </script>
870
871
872        <script src="elasticlunr.min.js"></script>
873        <script src="mark.min.js"></script>
874        <script src="searcher.js"></script>
875
876        <script src="clipboard.min.js"></script>
877        <script src="highlight.js"></script>
878        <script src="book.js"></script>
879
880        <!-- Custom JS scripts -->
881
882
883    </div>
884    </body>
885</html>