Skip to content

Commit 0c74f0e

Browse files
UebelAndreUebelAndre
authored
Moved crate_universe documentation from README into docs (#826)
* Move `crate_universe` documentation from README to docs * Regenerate documentation
1 parent 4979207 commit 0c74f0e

File tree

4 files changed

+232
-104
lines changed

4 files changed

+232
-104
lines changed

‎crate_universe/README.md

+2-104
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,12 @@
11
# Crate Universe
22

3-
## Experimental!
4-
5-
**Note**: `crate_universe` is experimental, and may have breaking API changes at any time. These instructions may also change without notice.
6-
7-
## What is it?
8-
93
Crate Universe is akin to a modified version of cargo-raze that can be run as
104
part of a Bazel build. Instead of generating BUILD files in advance with
115
cargo-raze, the BUILD files can be created automatically at build time. It can
126
expose crates gathered from Cargo.toml files like cargo-raze does, and also
137
supports declaring crates directly in BUILD files, for cases where compatibility
148
with Cargo is not required.
159

16-
## Workspace installation
17-
18-
To avoid having to build a Rust binary, pre-made releases are made
19-
available.
20-
21-
1. Find the most up-to-date `crate_universe` release at https://github.com/bazelbuild/rules_rust/releases.
22-
2. Copy and paste the text into a file like `crate_universe_defaults.bzl` in your repo.
23-
3. Add something like the following to your `WORKSPACE.bazel` file:
24-
25-
```python
26-
load("//3rdparty/rules_rust:crate_universe_defaults.bzl", "DEFAULT_URL_TEMPLATE", "DEFAULT_SHA256_CHECKSUMS")
27-
28-
load("@rules_rust//crate_universe:defs.bzl", "crate", "crate_universe")
29-
30-
crate_universe(
31-
name = "crates",
32-
cargo_toml_files = [
33-
"//some_crate:Cargo.toml",
34-
"//some_other:Cargo.toml",
35-
],
36-
resolver_download_url_template = DEFAULT_URL_TEMPLATE,
37-
resolver_sha256s = DEFAULT_SHA256_CHECKSUMS,
38-
# leave unset for default multi-platform support
39-
supported_targets = [
40-
"x86_64-apple-darwin",
41-
"x86_64-unknown-linux-gnu",
42-
],
43-
# [package.metadata.raze.xxx] lines in Cargo.toml files are ignored;
44-
# the overrides need to be declared in the repo rule instead.
45-
overrides = {
46-
"example-sys": crate.override(
47-
extra_build_script_env_vars = {"PATH": "/usr/bin"},
48-
),
49-
},
50-
# to use a lockfile, uncomment the following line,
51-
# create an empty file in the location, and then build
52-
# with REPIN=1 bazel build ...
53-
#lockfile = "//:crate_universe.lock",
54-
)
55-
56-
load("@crates//:defs.bzl", "pinned_rust_install")
57-
58-
pinned_rust_install()
59-
```
60-
61-
In the above example, two separate Cargo.toml files have been
62-
provided. Multiple Cargo.toml can be provided, and crate_universe
63-
will combine them together to ensure each crate uses a common version.
64-
65-
This is similar to a Cargo workspace, and can be used with an existing
66-
workspace. But some things to note:
67-
68-
- the top level workspace Cargo.toml, if one exists, should not be
69-
included in cargo_toml_files, as it does not list any dependencies by itself
70-
- presently any existing Cargo.lock file is ignored, as crate_universe does its
71-
own resolution and locking. You can uncomment the lockfile line above to
72-
enable a separate lockfile for crate_universe; if left disabled, versions will
73-
float, like if you were to remove the Cargo.lock file each time you updated a
74-
Cargo.toml file in a Cargo workspace. Currently the lockfile is in a custom
75-
format; in the future, the Cargo.lock file may be used instead.
76-
77-
## Build file usage
78-
79-
With the crates declared in the workspace, they can now be referenced in BUILD
80-
files. For example:
81-
82-
```python
83-
load("@crates//:defs.bzl", "build_crates_from", "crates_from")
84-
85-
cargo_build_script(
86-
name = "build",
87-
srcs = ["build.rs"],
88-
deps = build_crates_from("//some_crate:Cargo.toml"),
89-
)
90-
91-
rust_library(
92-
name = "some_crate",
93-
srcs = [
94-
"lib.rs",
95-
],
96-
deps = crates_from("//some_crate:Cargo.toml") + [":build"]
97-
)
98-
```
99-
100-
If you prefer, you can also list out each crate individually, eg:
101-
102-
```python
103-
load("@crates//:defs.bzl", "crate")
104-
105-
rust_library(
106-
name = "some_crate",
107-
srcs = [
108-
"lib.rs",
109-
],
110-
deps = [crate("serde"), crate("log"), ":build"]
111-
)
112-
```
10+
**Note**: `crate_universe` is experimental, and may have breaking API changes at any time. These instructions may also change without notice.
11311

114-
See [some more examples](../examples/crate_universe) and the [API docs](https://bazelbuild.github.io/rules_rust/crate_universe.html) for more info.
12+
More information can be found in the [rules_rust documentation](https://bazelbuild.github.io/rules_rust/crate_universe.html).

‎docs/BUILD.bazel

+1
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ PAGES = dict([
3939
),
4040
page(
4141
name = "crate_universe",
42+
header_template = ":crate_universe.vm",
4243
symbols = [
4344
"crate_universe",
4445
"crate",

‎docs/crate_universe.md

+115
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,121 @@
44
* [crate_universe](#crate_universe)
55
* [crate](#crate)
66

7+
8+
## Experimental!
9+
10+
**Note**: `crate_universe` is experimental, and may have breaking API changes at any time. These instructions may also change without notice.
11+
12+
## What is it?
13+
14+
Crate Universe is akin to a modified version of cargo-raze that can be run as
15+
part of a Bazel build. Instead of generating BUILD files in advance with
16+
cargo-raze, the BUILD files can be created automatically at build time. It can
17+
expose crates gathered from Cargo.toml files like cargo-raze does, and also
18+
supports declaring crates directly in BUILD files, for cases where compatibility
19+
with Cargo is not required.
20+
21+
## Workspace installation
22+
23+
To avoid having to build a Rust binary, pre-made releases are made
24+
available.
25+
26+
1. Find the most up-to-date `crate_universe` release at https://github.com/bazelbuild/rules_rust/releases.
27+
2. Copy and paste the text into a file like `crate_universe_defaults.bzl` in your repo.
28+
3. Add something like the following to your `WORKSPACE.bazel` file:
29+
30+
```python
31+
load("//3rdparty/rules_rust:crate_universe_defaults.bzl", "DEFAULT_URL_TEMPLATE", "DEFAULT_SHA256_CHECKSUMS")
32+
33+
load("@rules_rust//crate_universe:defs.bzl", "crate", "crate_universe")
34+
35+
crate_universe(
36+
name = "crates",
37+
cargo_toml_files = [
38+
"//some_crate:Cargo.toml",
39+
"//some_other:Cargo.toml",
40+
],
41+
resolver_download_url_template = DEFAULT_URL_TEMPLATE,
42+
resolver_sha256s = DEFAULT_SHA256_CHECKSUMS,
43+
# leave unset for default multi-platform support
44+
supported_targets = [
45+
"x86_64-apple-darwin",
46+
"x86_64-unknown-linux-gnu",
47+
],
48+
# [package.metadata.raze.xxx] lines in Cargo.toml files are ignored;
49+
# the overrides need to be declared in the repo rule instead.
50+
overrides = {
51+
"example-sys": crate.override(
52+
extra_build_script_env_vars = {"PATH": "/usr/bin"},
53+
),
54+
},
55+
# to use a lockfile, uncomment the following line,
56+
# create an empty file in the location, and then build
57+
# with REPIN=1 bazel build ...
58+
#lockfile = "//:crate_universe.lock",
59+
)
60+
61+
load("@crates//:defs.bzl", "pinned_rust_install")
62+
63+
pinned_rust_install()
64+
```
65+
66+
In the above example, two separate Cargo.toml files have been
67+
provided. Multiple Cargo.toml can be provided, and crate_universe
68+
will combine them together to ensure each crate uses a common version.
69+
70+
This is similar to a Cargo workspace, and can be used with an existing
71+
workspace. But some things to note:
72+
73+
- the top level workspace Cargo.toml, if one exists, should not be
74+
included in cargo_toml_files, as it does not list any dependencies by itself
75+
- presently any existing Cargo.lock file is ignored, as crate_universe does its
76+
own resolution and locking. You can uncomment the lockfile line above to
77+
enable a separate lockfile for crate_universe; if left disabled, versions will
78+
float, like if you were to remove the Cargo.lock file each time you updated a
79+
Cargo.toml file in a Cargo workspace. Currently the lockfile is in a custom
80+
format; in the future, the Cargo.lock file may be used instead.
81+
82+
## Build file usage
83+
84+
With the crates declared in the workspace, they can now be referenced in BUILD
85+
files. For example:
86+
87+
```python
88+
load("@crates//:defs.bzl", "build_crates_from", "crates_from")
89+
90+
cargo_build_script(
91+
name = "build",
92+
srcs = ["build.rs"],
93+
deps = build_crates_from("//some_crate:Cargo.toml"),
94+
)
95+
96+
rust_library(
97+
name = "some_crate",
98+
srcs = [
99+
"lib.rs",
100+
],
101+
deps = crates_from("//some_crate:Cargo.toml") + [":build"]
102+
)
103+
```
104+
105+
If you prefer, you can also list out each crate individually, eg:
106+
107+
```python
108+
load("@crates//:defs.bzl", "crate")
109+
110+
rust_library(
111+
name = "some_crate",
112+
srcs = [
113+
"lib.rs",
114+
],
115+
deps = [crate("serde"), crate("log"), ":build"]
116+
)
117+
```
118+
119+
See [some more examples](../examples/crate_universe) and the documentation below for more info.
120+
121+
7122
<a id="#crate_universe"></a>
8123

9124
## crate_universe

‎docs/crate_universe.vm

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
#[[
2+
## Experimental!
3+
4+
**Note**: `crate_universe` is experimental, and may have breaking API changes at any time. These instructions may also change without notice.
5+
6+
## What is it?
7+
8+
Crate Universe is akin to a modified version of cargo-raze that can be run as
9+
part of a Bazel build. Instead of generating BUILD files in advance with
10+
cargo-raze, the BUILD files can be created automatically at build time. It can
11+
expose crates gathered from Cargo.toml files like cargo-raze does, and also
12+
supports declaring crates directly in BUILD files, for cases where compatibility
13+
with Cargo is not required.
14+
15+
## Workspace installation
16+
17+
To avoid having to build a Rust binary, pre-made releases are made
18+
available.
19+
20+
1. Find the most up-to-date `crate_universe` release at https://github.com/bazelbuild/rules_rust/releases.
21+
2. Copy and paste the text into a file like `crate_universe_defaults.bzl` in your repo.
22+
3. Add something like the following to your `WORKSPACE.bazel` file:
23+
24+
```python
25+
load("//3rdparty/rules_rust:crate_universe_defaults.bzl", "DEFAULT_URL_TEMPLATE", "DEFAULT_SHA256_CHECKSUMS")
26+
27+
load("@rules_rust//crate_universe:defs.bzl", "crate", "crate_universe")
28+
29+
crate_universe(
30+
name = "crates",
31+
cargo_toml_files = [
32+
"//some_crate:Cargo.toml",
33+
"//some_other:Cargo.toml",
34+
],
35+
resolver_download_url_template = DEFAULT_URL_TEMPLATE,
36+
resolver_sha256s = DEFAULT_SHA256_CHECKSUMS,
37+
# leave unset for default multi-platform support
38+
supported_targets = [
39+
"x86_64-apple-darwin",
40+
"x86_64-unknown-linux-gnu",
41+
],
42+
# [package.metadata.raze.xxx] lines in Cargo.toml files are ignored;
43+
# the overrides need to be declared in the repo rule instead.
44+
overrides = {
45+
"example-sys": crate.override(
46+
extra_build_script_env_vars = {"PATH": "/usr/bin"},
47+
),
48+
},
49+
# to use a lockfile, uncomment the following line,
50+
# create an empty file in the location, and then build
51+
# with REPIN=1 bazel build ...
52+
#lockfile = "//:crate_universe.lock",
53+
)
54+
55+
load("@crates//:defs.bzl", "pinned_rust_install")
56+
57+
pinned_rust_install()
58+
```
59+
60+
In the above example, two separate Cargo.toml files have been
61+
provided. Multiple Cargo.toml can be provided, and crate_universe
62+
will combine them together to ensure each crate uses a common version.
63+
64+
This is similar to a Cargo workspace, and can be used with an existing
65+
workspace. But some things to note:
66+
67+
- the top level workspace Cargo.toml, if one exists, should not be
68+
included in cargo_toml_files, as it does not list any dependencies by itself
69+
- presently any existing Cargo.lock file is ignored, as crate_universe does its
70+
own resolution and locking. You can uncomment the lockfile line above to
71+
enable a separate lockfile for crate_universe; if left disabled, versions will
72+
float, like if you were to remove the Cargo.lock file each time you updated a
73+
Cargo.toml file in a Cargo workspace. Currently the lockfile is in a custom
74+
format; in the future, the Cargo.lock file may be used instead.
75+
76+
## Build file usage
77+
78+
With the crates declared in the workspace, they can now be referenced in BUILD
79+
files. For example:
80+
81+
```python
82+
load("@crates//:defs.bzl", "build_crates_from", "crates_from")
83+
84+
cargo_build_script(
85+
name = "build",
86+
srcs = ["build.rs"],
87+
deps = build_crates_from("//some_crate:Cargo.toml"),
88+
)
89+
90+
rust_library(
91+
name = "some_crate",
92+
srcs = [
93+
"lib.rs",
94+
],
95+
deps = crates_from("//some_crate:Cargo.toml") + [":build"]
96+
)
97+
```
98+
99+
If you prefer, you can also list out each crate individually, eg:
100+
101+
```python
102+
load("@crates//:defs.bzl", "crate")
103+
104+
rust_library(
105+
name = "some_crate",
106+
srcs = [
107+
"lib.rs",
108+
],
109+
deps = [crate("serde"), crate("log"), ":build"]
110+
)
111+
```
112+
113+
See [some more examples](../examples/crate_universe) and the documentation below for more info.
114+
]]#

0 commit comments

Comments
 (0)