Skip to content

Commit

Permalink
docs: update and document flake outputs
Browse files Browse the repository at this point in the history
  • Loading branch information
@oxalica
oxalica committed Jun 3, 2024
1 parent 305d3b0 commit 28e86b2
Show file tree
Hide file tree
Showing 2 changed files with 161 additions and 87 deletions.
35 changes: 20 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,32 @@
[![CI status](https://github.com/oxalica/rust-overlay/workflows/CI/badge.svg)](https://github.com/oxalica/rust-overlay/actions/workflows/ci.yaml)
[![sync-channels status](https://github.com/oxalica/rust-overlay/workflows/sync-channels/badge.svg)](https://github.com/oxalica/rust-overlay/actions/workflows/sync-channels.yaml)

*Pure and reproducible* overlay for binary distributed rust toolchains.
A compatible but better replacement for rust overlay of [nixpkgs-mozilla].
*Pure and reproducible* packaging of binary distributed rust toolchains.
A compatible but better replacement for rust overlay of [nixpkgs-mozilla],
with also non-overlay and [Nix Flake][flake] interfaces (despite the project name).

Hashes of toolchain components are pre-fetched in tree, so the evaluation is *pure* and
no need to have network access. It also works well with [Nix Flakes](https://nixos.wiki/wiki/Flakes).
[flake]: https://wiki.nixos.org/wiki/Flakes

For migration from [nixpkgs-mozilla], see [this section](#migration-from-nixpkgs-mozilla).

Features:

- Hashes of toolchain components are pre-fetched in tree, so the evaluation is
*pure* and no need to have network access.

- These hashes are auto-updated daily using GitHub Actions.

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

rust-overlay targets nixos-unstable and supported releases of NixOS, on x86_64-linux.
They are tested on CI. It may also work on other channels but is not guarenteed.
- We targets nixos-unstable and supported releases of NixOS, on x86\_64-linux.
They are tested on CI. Other platforms and nixpkgs channels may also work but
is not guaranteed.

For migration from [nixpkgs-mozilla], see [this section](#migration-from-nixpkgs-mozilla).
Documentations:

- [API References](docs/reference.md)
- [Cross compilation](docs/cross_compilation.md)

## Installation

Expand All @@ -41,8 +53,6 @@ And then feel free to use it anywhere like

### Nix Flakes

This repository already has flake support.

**Warning: Only the output `overlay`/`overlays` are currently stable. Use other outputs at your own risk!**

For a quick play, just use `nix shell` to bring the latest stable rust toolchain into scope.
Expand Down Expand Up @@ -218,11 +228,6 @@ Running `nix develop` will create a shell with the default beta Rust toolchain i

- There also an cross-compilation example in [`examples/cross-aarch64`].

## More documentations

- [Reference of all public attributes](docs/reference.md)
- [Cross compilation](docs/cross_compilation.md)

## License

MIT licensed.
Expand Down
213 changes: 141 additions & 72 deletions docs/reference.md
View file
Original file line number Diff line number Diff line change
@@ -1,85 +1,154 @@
# `rust-overlay` reference
# Reference

All public attributes provided by the overlay are below. Fields not defined here are for internal usage.
We provides two entry interfaces:

1. Overlay interface, via `default.nix` (non-flake) or
`rust-overlay.overlays.default` (flake).

This provides a [nixpkgs overlay][nixpkgs-overlay] to be used when
importing nixpkgs. The overlay will (try its best) not modify any existing
attributes of nixpkgs, but adds these new attributes:

- `rust-bin`,
where all main functionalities resides.
Its structure is documented in the next section.

- `latest`, `rustChannelOf`, `rustChannelOfTargets`, `rustChannels`,
for compatibility with [nixpkgs-mozilla].

They are built on top of `rust-bin` with only structure/argument
differences, and will provide the same corresponding derivations as
`rust-bin`.

[nixpkgs-overlay]: https://wiki.nixos.org/wiki/Overlays
[nixpkgs-mozilla]: https://github.com/mozilla/nixpkgs-mozilla

2. Builder interface, via `rust-overlay.lib.mkRustBin` (flake only).

It is a function with type
`{ distRoot ? ... } -> (pkgs: attrset) -> attrset`.

It returns an attrset with the same structure as `rust-bin` attribute
mentioned above, with the argument of an already imported (instantiated)
nixpkgs.

Notably, only the attrset `rust-bin` is returned, so this builder will not
give you any nixpkgs-mozilla compatible attributes.

## `rust-bin` structure

```nix
{
rust-bin = {
# The default dist url for fetching.
# Override it if you want to use a mirror server.
distRoot = "https://static.rust-lang.org/dist";
# Select a toolchain and aggregate components by rustup's `rust-toolchain` file format.
# See: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
fromRustupToolchain = { channel, components ? [], targets ? [] }: «derivation»;
# Same as `fromRustupToolchain` but read from a `rust-toolchain` file (legacy one-line string or in TOML).
fromRustupToolchainFile = rust-toolchain-file-path: «derivation»;
# Select the latest nightly toolchain which have specific components or profile available.
# This helps nightly users in case of latest nightly may not contains all components they want.
#
# `selectLatestNightlyWith (toolchain: toolchain.default)` selects the latest nightly toolchain
# with all `default` components (rustc, cargo, rustfmt, ...) available.
selectLatestNightlyWith = selector: «derivation»;
# Custom toolchain from a specific rustc git revision.
# This does almost the same thing as `rustup-toolchain-install-master`. (https://crates.io/crates/rustup-toolchain-install-master)
# Parameter `components` should be an attrset with component name as key and its SRI hash as value.
fromRustcRev = { pname ? …, rev, components, target ? … }: «derivation»;
stable = {
# The latest stable toolchain.
latest = {
# Profiles, predefined component sets.
# See: https://rust-lang.github.io/rustup/concepts/profiles.html
minimal = «derivation»; # Only `cargo`, `rustc` and `rust-std`.
default = «derivation»; # The default profile of `rustup`. Good for general use.
complete = «derivation»; # Do not use it. It almost always fails.
# Pre-aggregated package provided by upstream, the most commonly used package in `mozilla-overlay`.
# It consists of an uncertain number of components, usually more than the `default` profile of `rustup`
# but less than `complete` profile.
rust = «derivation»;
# Individial components.
rustc = «derivation»;
cargo = «derivation»;
rust-std = «derivation»;
# ... other components
};
"1.49.0" = { /* toolchain */ };
"1.48.0" = { /* toolchain */ };
# ... other versions.
};
# The default dist url for fetching.
#
# For the overlay interface, this attribute is overridable. Changing it will
# also change all dependent URLs for source derivations (FOD). Useful for
# setting mirrors.
distRoot = "https://static.rust-lang.org/dist";
beta = {
# The latest beta toolchain.
latest = { /* toolchain */ };
"2021-01-01" = { /* toolchain */ };
"2020-12-30" = { /* toolchain */ };
# ... other versions.
};
# Select a toolchain and aggregate components by rustup's `rust-toolchain` file format.
# See: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
fromRustupToolchain = { channel, components ? [], targets ? [] }: «derivation»;
# Same as `fromRustupToolchain` but read from a `rust-toolchain` file (legacy one-line string or in TOML).
fromRustupToolchainFile = rust-toolchain-file-path: «derivation»;
# Select the latest nightly toolchain which have specific components or profile available.
# This helps nightly users in case of latest nightly may not contains all components they want.
#
# `selectLatestNightlyWith (toolchain: toolchain.default)` selects the latest nightly toolchain
# with all `default` components (rustc, cargo, rustfmt, ...) available.
selectLatestNightlyWith = selector: «derivation»;
# Custom toolchain from a specific rustc git revision.
# This does almost the same thing as `rustup-toolchain-install-master`. (https://crates.io/crates/rustup-toolchain-install-master)
# Parameter `components` should be an attrset with component name as key and its SRI hash as value.
fromRustcRev = { pname ? …, rev, components, target ? … }: «derivation»;
stable = {
# The latest stable toolchain.
latest = {
# Profiles, predefined component sets.
# See: https://rust-lang.github.io/rustup/concepts/profiles.html
minimal = «derivation»; # Only `cargo`, `rustc` and `rust-std`.
default = «derivation»; # The default profile of `rustup`. Good for general use.
complete = «derivation»; # Do not use it. It almost always fails.
nightly = {
# The latest nightly toolchain.
# It is preferred to use `selectLatestNightlyWith` instead of this since
# nightly toolchain may have components (like `rustfmt` or `rls`) missing,
# making `default` profile unusable.
latest = { /* toolchain */ };
"2020-12-31" = { /* toolchain */ };
"2020-12-30" = { /* toolchain */ };
# ... other versions.
# Pre-aggregated package provided by upstream, the most commonly used package in `mozilla-overlay`.
# It consists of an uncertain number of components, usually more than the `default` profile of `rustup`
# but less than `complete` profile.
rust = «derivation»;
# Individial components.
rustc = «derivation»;
cargo = «derivation»;
rust-std = «derivation»;
# ... other components
};
"1.49.0" = { /* toolchain */ };
"1.48.0" = { /* toolchain */ };
# ... other versions.
};
beta = {
# The latest beta toolchain.
latest = { /* toolchain */ };
"2021-01-01" = { /* toolchain */ };
"2020-12-30" = { /* toolchain */ };
# ... other versions.
};
nightly = {
# The latest nightly toolchain.
# It is preferred to use `selectLatestNightlyWith` instead of this since
# nightly toolchain may have components (like `rustfmt` or `rls`) missing,
# making `default` profile unusable.
latest = { /* toolchain */ };
"2020-12-31" = { /* toolchain */ };
"2020-12-30" = { /* toolchain */ };
# ... other versions.
};
# ... Some internal attributes omitted.
}
```

## Flake output structure

```nix
{
lib.mkRustBin = { distRoot ? /*...*/ }: pkgs: «attrset rust-bin»;
overlays = {
# The overlay.
default = final: prev: «attrset»;
# Alias to `default`.
rust-overlay = final: prev: «attrset»;
};
# WARNING: The structure of `packages` here is to-be-determined and may be
# renamed or modified in the future.
packages.${system} = {
# Stable toolchain of release major.minor.patch
# The derivation is the "default" profile, and the "minimal" profile can be
# accessed via `minimal` attribute.
# This type is abbreviated as `«toolchain»` below.
"rust_${major}_${minor}_${patch}" = «derivation» // { minimal = «derivation»; };
# Alias to `rust_${latest-major-minor-patch}`.
rust = «toolchain»;
# Alias to `rust`.
default = «toolchain»;
# Nightly toolchain of a specific date.
"rust-nightly_${yyyy}-${mm}-${dd}" = «toolchain»;
# Alias to `rust-nightly_${latest-nightly-yyyy-mm-dd}`.
rust-nightly = «toolchain»;
# ... Some internal attributes omitted.
# Beta toolchain of a specific date.
"rust-beta_${yyyy}-${mm}-${dd}" = «toolchain»;
# Alias to `rust-beta_${latest-beta-yyyy-mm-dd}`.
rust-beta = «toolchain»;
};
# These are for compatibility with nixpkgs-mozilla and
# provide same toolchains as `rust-bin.*`.
latest.rustChannels = /* ... */;
rustChannelOf = /* ... */;
rustChannelOfTargets = /* ... */;
rustChannels = /* ... */;
# ... Some internal attributes omitted.
}
```

Expand Down

0 comments on commit 28e86b2

Please sign in to comment.