Skip to content

Commit ea18912

Browse files
oxalicaoxalica
committed
Reorganize docs
1 parent 825a993 commit ea18912

File tree

3 files changed

+119
-96
lines changed

3 files changed

+119
-96
lines changed

‎README.md

+29-96
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,20 @@
44
![sync-channels](https://github.com/oxalica/rust-overlay/workflows/sync-channels/badge.svg)
55

66
*Pure and reproducible* overlay for binary distributed rust toolchains.
7-
A compatible but better replacement for rust overlay of [mozilla/nixpkgs-mozilla][mozilla].
7+
A compatible but better replacement for rust overlay of [nixpkgs-mozilla].
88

9-
Hashes of toolchain components are pre-fetched (and compressed) in tree (`manifests` directory),
10-
so the evaluation is *pure* and no need to have network (but [nixpkgs-mozilla][mozilla] does).
11-
It also works well with [Nix Flakes](https://nixos.wiki/wiki/Flakes).
9+
Hashes of toolchain components are pre-fetched in tree, so the evaluation is *pure* and
10+
no need to have network access. It also works well with [Nix Flakes](https://nixos.wiki/wiki/Flakes).
1211

1312
- The toolchain hashes are auto-updated daily using GitHub Actions.
1413
- Current oldest supported version is stable 1.29.0 and beta/nightly 2018-09-13
15-
(which are randomly chosen).
14+
(which are randomly picked and may change over time).
1615

17-
## Use as a classic Nix overlay
16+
For migration from [nixpkgs-mozilla], see [this section](#migration-from-nixpkgs-mozilla).
17+
18+
## Installation
19+
20+
### Classic Nix overlay
1821

1922
You can put the code below into your `~/.config/nixpkgs/overlays.nix`.
2023
```nix
@@ -33,7 +36,7 @@ $ nix-channel --update
3336
And then feel free to use it anywhere like
3437
`import <nixpkgs> { overlays = [ (import <rust-overlay>) ]; }` in your nix shell environment.
3538

36-
## Use with Nix Flakes
39+
### Nix Flakes
3740

3841
This repository already has flake support.
3942

@@ -50,7 +53,7 @@ $ cargo --version
5053
cargo 1.49.0 (d00d64df9 2020-12-05)
5154
```
5255

53-
### Flake example: NixOS Configuration
56+
#### Use in NixOS Configuration
5457

5558
Here's an example of using it in nixos configuration.
5659
```nix
@@ -79,7 +82,7 @@ Here's an example of using it in nixos configuration.
7982
}
8083
```
8184

82-
### Flake example: Using `devShell` and `nix develop`
85+
#### Use in `devShell` for `nix develop`
8386

8487
Running `nix develop` will create a shell with the default nightly Rust toolchain installed:
8588

@@ -123,7 +126,17 @@ Running `nix develop` will create a shell with the default nightly Rust toolchai
123126
124127
```
125128

126-
## Usage Examples
129+
### Migration from [nixpkgs-mozilla]
130+
131+
1. Change the channel URL to `https://github.com/oxalica/rust-overlay/archive/master.tar.gz`,
132+
or flake URL to `github:oxalica/rust-overlay` for Nix Flakes.
133+
2. Good to go! `latest.*`, `rustChannel*.*` and friends are made compatible with [nixpkgs-mozilla].
134+
You don't necessary need to change anything.
135+
3. You can also optionally change to [the `rust-bin` interface](#cheat-sheet-common-usage-of-rust-bin),
136+
which provides more functionality like "latest nightly with specific components available" or
137+
"from `rust-toolchain` file". It also has nix-aware cross-compilation support.
138+
139+
## Cheat sheet: common usage of `rust-bin`
127140

128141
- Latest stable or beta rust profile.
129142

@@ -186,8 +199,6 @@ Running `nix develop` will create a shell with the default nightly Rust toolchai
186199

187200
- Toolchain with specific rustc git revision.
188201

189-
**Warning: This may not always work (including the example below) since upstream CI periodly purges old artifacts.**
190-
191202
This is useful for development of rust components like [MIRI][miri], which requires a specific revision of rust.
192203
```nix
193204
rust-bin.fromRustcRev {
@@ -199,94 +210,16 @@ Running `nix develop` will create a shell with the default nightly Rust toolchai
199210
}
200211
```
201212

202-
- There also an cross-compilation example in [`examples/cross-aarch64`].
203-
204-
## Reference: All attributes provided by the overlay
205-
206-
```nix
207-
{
208-
rust-bin = {
209-
# The default dist url for fetching.
210-
# Override it if you want to use a mirror server.
211-
distRoot = "https://static.rust-lang.org/dist";
212-
213-
# Select a toolchain and aggregate components by rustup's `rust-toolchain` file format.
214-
# See: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
215-
fromRustupToolchain = { channel, components ? [], targets ? [] }: «derivation»;
216-
# Same as `fromRustupToolchain` but read from a `rust-toolchain` file (legacy one-line string or in TOML).
217-
fromRustupToolchainFile = rust-toolchain-file-path: «derivation»;
218-
219-
# Select the latest nightly toolchain which have specific components or profile available.
220-
# This helps nightly users in case of latest nightly may not contains all components they want.
221-
#
222-
# `selectLatestNightlyWith (toolchain: toolchain.default)` selects the latest nightly toolchain
223-
# with all `default` components (rustc, cargo, rustfmt, ...) available.
224-
selectLatestNightlyWith = selector: «derivation»;
225-
226-
# Custom toolchain from a specific rustc git revision.
227-
# This does almost the same thing as `rustup-toolchain-install-master`. (https://crates.io/crates/rustup-toolchain-install-master)
228-
# Parameter `components` should be an attrset with component name as key and its SRI hash as value.
229-
fromRustcRev = { pname ? …, rev, components, target ? … }: «derivation»;
230-
231-
stable = {
232-
# The latest stable toolchain.
233-
latest = {
234-
# Profiles, predefined component sets.
235-
# See: https://rust-lang.github.io/rustup/concepts/profiles.html
236-
minimal = «derivation»; # Only `cargo`, `rustc` and `rust-std`.
237-
default = «derivation»; # The default profile of `rustup`. Good for general use.
238-
complete = «derivation»; # Do not use it. It almost always fails.
239-
240-
# Pre-aggregated package provided by upstream, the most commonly used package in `mozilla-overlay`.
241-
# It consists of an uncertain number of components, usually more than the `default` profile of `rustup`
242-
# but less than `complete` profile.
243-
rust = «derivation»;
244-
245-
# Individial components.
246-
rustc = «derivation»;
247-
cargo = «derivation»;
248-
rust-std = «derivation»;
249-
# ... other components
250-
};
251-
"1.49.0" = { /* toolchain */ };
252-
"1.48.0" = { /* toolchain */ };
253-
# ... other versions.
254-
};
255-
256-
beta = {
257-
# The latest beta toolchain.
258-
latest = { /* toolchain */ };
259-
"2021-01-01" = { /* toolchain */ };
260-
"2020-12-30" = { /* toolchain */ };
261-
# ... other versions.
262-
};
263-
264-
nightly = {
265-
# The latest nightly toolchain.
266-
# It is preferred to use `selectLatestNightlyWith` instead of this since
267-
# nightly toolchain may have components (like `rustfmt` or `rls`) missing,
268-
# making `default` profile unusable.
269-
latest = { /* toolchain */ };
270-
"2020-12-31" = { /* toolchain */ };
271-
"2020-12-30" = { /* toolchain */ };
272-
# ... other versions.
273-
};
213+
*Warning: This may not always work (including the example below) since upstream CI periodly purges old artifacts.*
274214

275-
# ... Some internal attributes omitted.
276-
};
215+
- There also an cross-compilation example in [`examples/cross-aarch64`].
277216

278-
# These are for compatibility with nixpkgs-mozilla and
279-
# provide same toolchains as `rust-bin.*`.
280-
latest.rustChannels = /* ... */;
281-
rustChannelOf = /* ... */;
282-
rustChannelOfTargets = /* ... */;
283-
rustChannels = /* ... */;
284-
}
285-
```
217+
## More documentations
286218

287-
For more details, see also the source code of `./rust-overlay.nix`.
219+
- [Reference of all public attributes](docs/reference.md)
220+
- [Cross compilation](docs/cross_compilation.md)
288221

289-
[mozilla]: https://github.com/mozilla/nixpkgs-mozilla
222+
[nixpkgs-mozilla]: https://github.com/mozilla/nixpkgs-mozilla
290223
[rust-toolchain]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
291224
[rust-profiles]: https://rust-lang.github.io/rustup/concepts/profiles.html
292225
[miri]: https://github.com/rust-lang/miri

‎docs/cross_compilation.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Cross compilation with `rust-overlay`
2+
3+
There an example for cross compilation to `aarch64-linux` in
4+
[`example/cross-aarch64`](../examples/cross-aarch64).

‎docs/reference.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# `rust-overlay` reference
2+
3+
All public attributes provided by the overlay are below. Fields not defined here are for internal usage.
4+
5+
```nix
6+
{
7+
rust-bin = {
8+
# The default dist url for fetching.
9+
# Override it if you want to use a mirror server.
10+
distRoot = "https://static.rust-lang.org/dist";
11+
12+
# Select a toolchain and aggregate components by rustup's `rust-toolchain` file format.
13+
# See: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
14+
fromRustupToolchain = { channel, components ? [], targets ? [] }: «derivation»;
15+
# Same as `fromRustupToolchain` but read from a `rust-toolchain` file (legacy one-line string or in TOML).
16+
fromRustupToolchainFile = rust-toolchain-file-path: «derivation»;
17+
18+
# Select the latest nightly toolchain which have specific components or profile available.
19+
# This helps nightly users in case of latest nightly may not contains all components they want.
20+
#
21+
# `selectLatestNightlyWith (toolchain: toolchain.default)` selects the latest nightly toolchain
22+
# with all `default` components (rustc, cargo, rustfmt, ...) available.
23+
selectLatestNightlyWith = selector: «derivation»;
24+
25+
# Custom toolchain from a specific rustc git revision.
26+
# This does almost the same thing as `rustup-toolchain-install-master`. (https://crates.io/crates/rustup-toolchain-install-master)
27+
# Parameter `components` should be an attrset with component name as key and its SRI hash as value.
28+
fromRustcRev = { pname ? …, rev, components, target ? … }: «derivation»;
29+
30+
stable = {
31+
# The latest stable toolchain.
32+
latest = {
33+
# Profiles, predefined component sets.
34+
# See: https://rust-lang.github.io/rustup/concepts/profiles.html
35+
minimal = «derivation»; # Only `cargo`, `rustc` and `rust-std`.
36+
default = «derivation»; # The default profile of `rustup`. Good for general use.
37+
complete = «derivation»; # Do not use it. It almost always fails.
38+
39+
# Pre-aggregated package provided by upstream, the most commonly used package in `mozilla-overlay`.
40+
# It consists of an uncertain number of components, usually more than the `default` profile of `rustup`
41+
# but less than `complete` profile.
42+
rust = «derivation»;
43+
44+
# Individial components.
45+
rustc = «derivation»;
46+
cargo = «derivation»;
47+
rust-std = «derivation»;
48+
# ... other components
49+
};
50+
"1.49.0" = { /* toolchain */ };
51+
"1.48.0" = { /* toolchain */ };
52+
# ... other versions.
53+
};
54+
55+
beta = {
56+
# The latest beta toolchain.
57+
latest = { /* toolchain */ };
58+
"2021-01-01" = { /* toolchain */ };
59+
"2020-12-30" = { /* toolchain */ };
60+
# ... other versions.
61+
};
62+
63+
nightly = {
64+
# The latest nightly toolchain.
65+
# It is preferred to use `selectLatestNightlyWith` instead of this since
66+
# nightly toolchain may have components (like `rustfmt` or `rls`) missing,
67+
# making `default` profile unusable.
68+
latest = { /* toolchain */ };
69+
"2020-12-31" = { /* toolchain */ };
70+
"2020-12-30" = { /* toolchain */ };
71+
# ... other versions.
72+
};
73+
74+
# ... Some internal attributes omitted.
75+
};
76+
77+
# These are for compatibility with nixpkgs-mozilla and
78+
# provide same toolchains as `rust-bin.*`.
79+
latest.rustChannels = /* ... */;
80+
rustChannelOf = /* ... */;
81+
rustChannelOfTargets = /* ... */;
82+
rustChannels = /* ... */;
83+
}
84+
```
85+
86+
For more details, see also the source code of [`rust-overlay.nix`](../rust-overlay.nix).

0 commit comments

Comments
 (0)