oxalica/rust-overlay
1
1
Fork 0
mirror of https://github.com/oxalica/rust-overlay.git synced 2024-10-03 20:57:47 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: update and document flake outputs

Browse Source
This commit is contained in:
oxalica 2024-06-03 03:50:51 -04:00
parent 305d3b088e
commit 28e86b285e
2 changed files with 158 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@ -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
@ -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.
@ -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.

207
docs/reference.md
View File

@ -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";
# 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";
# 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 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»;
# 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»;
# 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.
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»;
# 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.
# Individial components.
rustc = «derivation»;
cargo = «derivation»;
rust-std = «derivation»;
# ... other components
};
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.
"1.49.0" = { /* toolchain */ };
"1.48.0" = { /* toolchain */ };
# ... other versions.
};
# These are for compatibility with nixpkgs-mozilla and
# provide same toolchains as `rust-bin.*`.
latest.rustChannels = /* ... */;
rustChannelOf = /* ... */;
rustChannelOfTargets = /* ... */;
rustChannels = /* ... */;
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»;
# Beta toolchain of a specific date.
"rust-beta_${yyyy}-${mm}-${dd}" = «toolchain»;
# Alias to `rust-beta_${latest-beta-yyyy-mm-dd}`.
rust-beta = «toolchain»;
};
# ... Some internal attributes omitted.
}
```