|
| 1 | +<!-- Generated with Stardoc: http://skydoc.bazel.build --> |
| 2 | +# Cargo |
| 3 | + |
| 4 | +* [cargo_build_script](#cargo_build_script) |
| 5 | +* [cargo_bootstrap_repository](#cargo_bootstrap_repository) |
| 6 | + |
| 7 | +<a id="#cargo_bootstrap_repository"></a> |
| 8 | + |
| 9 | +## cargo_bootstrap_repository |
| 10 | + |
| 11 | +<pre> |
| 12 | +cargo_bootstrap_repository(<a href="#cargo_bootstrap_repository-name">name</a>, <a href="#cargo_bootstrap_repository-binary">binary</a>, <a href="#cargo_bootstrap_repository-build_mode">build_mode</a>, <a href="#cargo_bootstrap_repository-cargo_lockfile">cargo_lockfile</a>, <a href="#cargo_bootstrap_repository-cargo_toml">cargo_toml</a>, <a href="#cargo_bootstrap_repository-iso_date">iso_date</a>, |
| 13 | + <a href="#cargo_bootstrap_repository-repo_mapping">repo_mapping</a>, <a href="#cargo_bootstrap_repository-rust_toolchain_repository_template">rust_toolchain_repository_template</a>, <a href="#cargo_bootstrap_repository-srcs">srcs</a>, <a href="#cargo_bootstrap_repository-version">version</a>) |
| 14 | +</pre> |
| 15 | + |
| 16 | +A rule for bootstrapping a Rust binary using [Cargo](https://doc.rust-lang.org/cargo/) |
| 17 | + |
| 18 | +**ATTRIBUTES** |
| 19 | + |
| 20 | + |
| 21 | +| Name | Description | Type | Mandatory | Default | |
| 22 | +| :------------- | :------------- | :------------- | :------------- | :------------- | |
| 23 | +| <a id="cargo_bootstrap_repository-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | |
| 24 | +| <a id="cargo_bootstrap_repository-binary"></a>binary | The binary to build (the <code>--bin</code> parameter for Cargo). If left empty, the repository name will be used. | String | optional | "" | |
| 25 | +| <a id="cargo_bootstrap_repository-build_mode"></a>build_mode | The build mode the binary should be built with | String | optional | "release" | |
| 26 | +| <a id="cargo_bootstrap_repository-cargo_lockfile"></a>cargo_lockfile | The lockfile of the crate_universe resolver | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | | |
| 27 | +| <a id="cargo_bootstrap_repository-cargo_toml"></a>cargo_toml | The path of the crate_universe resolver manifest (<code>Cargo.toml</code> file) | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | | |
| 28 | +| <a id="cargo_bootstrap_repository-iso_date"></a>iso_date | The iso_date of cargo binary the resolver should use. Note: This can only be set if <code>version</code> is <code>beta</code> or <code>nightly</code> | String | optional | "" | |
| 29 | +| <a id="cargo_bootstrap_repository-repo_mapping"></a>repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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>). | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | required | | |
| 30 | +| <a id="cargo_bootstrap_repository-rust_toolchain_repository_template"></a>rust_toolchain_repository_template | The template to use for finding the host <code>rust_toolchain</code> repository. <code>{version}</code> (eg. '1.53.0'), <code>{triple}</code> (eg. 'x86_64-unknown-linux-gnu'), <code>{system}</code> (eg. 'darwin'), and <code>{arch}</code> (eg. 'aarch64') will be replaced in the string if present. | String | optional | "rust_{system}_{arch}" | |
| 31 | +| <a id="cargo_bootstrap_repository-srcs"></a>srcs | Souces to crate to build. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | required | | |
| 32 | +| <a id="cargo_bootstrap_repository-version"></a>version | The version of cargo the resolver should use | String | optional | "1.54.0" | |
| 33 | + |
| 34 | + |
| 35 | +<a id="#cargo_build_script"></a> |
| 36 | + |
| 37 | +## cargo_build_script |
| 38 | + |
| 39 | +<pre> |
| 40 | +cargo_build_script(<a href="#cargo_build_script-name">name</a>, <a href="#cargo_build_script-crate_features">crate_features</a>, <a href="#cargo_build_script-version">version</a>, <a href="#cargo_build_script-deps">deps</a>, <a href="#cargo_build_script-build_script_env">build_script_env</a>, <a href="#cargo_build_script-data">data</a>, <a href="#cargo_build_script-links">links</a>, <a href="#cargo_build_script-rustc_env">rustc_env</a>, |
| 41 | + <a href="#cargo_build_script-kwargs">kwargs</a>) |
| 42 | +</pre> |
| 43 | + |
| 44 | +Compile and execute a rust build script to generate build attributes |
| 45 | + |
| 46 | +This rules take the same arguments as rust_binary. |
| 47 | + |
| 48 | +Example: |
| 49 | + |
| 50 | +Suppose you have a crate with a cargo build script `build.rs`: |
| 51 | + |
| 52 | +```output |
| 53 | +[workspace]/ |
| 54 | + hello_lib/ |
| 55 | + BUILD |
| 56 | + build.rs |
| 57 | + src/ |
| 58 | + lib.rs |
| 59 | +``` |
| 60 | + |
| 61 | +Then you want to use the build script in the following: |
| 62 | + |
| 63 | +`hello_lib/BUILD`: |
| 64 | +```python |
| 65 | +package(default_visibility = ["//visibility:public"]) |
| 66 | + |
| 67 | +load("@rules_rust//rust:rust.bzl", "rust_binary", "rust_library") |
| 68 | +load("@rules_rust//cargo:cargo_build_script.bzl", "cargo_build_script") |
| 69 | + |
| 70 | +# This will run the build script from the root of the workspace, and |
| 71 | +# collect the outputs. |
| 72 | +cargo_build_script( |
| 73 | + name = "build_script", |
| 74 | + srcs = ["build.rs"], |
| 75 | + # Optional environment variables passed during build.rs compilation |
| 76 | + rustc_env = { |
| 77 | + "CARGO_PKG_VERSION": "0.1.2", |
| 78 | + }, |
| 79 | + # Optional environment variables passed during build.rs execution. |
| 80 | + # Note that as the build script's working directory is not execroot, |
| 81 | + # execpath/location will return an absolute path, instead of a relative |
| 82 | + # one. |
| 83 | + build_script_env = { |
| 84 | + "SOME_TOOL_OR_FILE": "$(execpath @tool//:binary)" |
| 85 | + } |
| 86 | + # Optional data/tool dependencies |
| 87 | + data = ["@tool//:binary"], |
| 88 | +) |
| 89 | + |
| 90 | +rust_library( |
| 91 | + name = "hello_lib", |
| 92 | + srcs = [ |
| 93 | + "src/lib.rs", |
| 94 | + ], |
| 95 | + deps = [":build_script"], |
| 96 | +) |
| 97 | +``` |
| 98 | + |
| 99 | +The `hello_lib` target will be build with the flags and the environment variables declared by the build script in addition to the file generated by it. |
| 100 | + |
| 101 | + |
| 102 | +**PARAMETERS** |
| 103 | + |
| 104 | + |
| 105 | +| Name | Description | Default Value | |
| 106 | +| :------------- | :------------- | :------------- | |
| 107 | +| <a id="cargo_build_script-name"></a>name | The name for the underlying rule. This should be the name of the package being compiled, optionally with a suffix of _build_script. | none | |
| 108 | +| <a id="cargo_build_script-crate_features"></a>crate_features | A list of features to enable for the build script. | <code>[]</code> | |
| 109 | +| <a id="cargo_build_script-version"></a>version | The semantic version (semver) of the crate. | <code>None</code> | |
| 110 | +| <a id="cargo_build_script-deps"></a>deps | The dependencies of the crate. | <code>[]</code> | |
| 111 | +| <a id="cargo_build_script-build_script_env"></a>build_script_env | Environment variables for build scripts. | <code>{}</code> | |
| 112 | +| <a id="cargo_build_script-data"></a>data | Files or tools needed by the build script. | <code>[]</code> | |
| 113 | +| <a id="cargo_build_script-links"></a>links | Name of the native library this crate links against. | <code>None</code> | |
| 114 | +| <a id="cargo_build_script-rustc_env"></a>rustc_env | Environment variables to set in rustc when compiling the build script. | <code>{}</code> | |
| 115 | +| <a id="cargo_build_script-kwargs"></a>kwargs | Forwards to the underlying <code>rust_binary</code> rule. | none | |
| 116 | + |
| 117 | + |
0 commit comments