diff options
Diffstat (limited to 'nixpkgs/doc/languages-frameworks/rust.section.md')
| -rw-r--r-- | nixpkgs/doc/languages-frameworks/rust.section.md | 206 |
1 files changed, 125 insertions, 81 deletions
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md index b2f045b11b32..56faf636df10 100644 --- a/nixpkgs/doc/languages-frameworks/rust.section.md +++ b/nixpkgs/doc/languages-frameworks/rust.section.md @@ -13,7 +13,7 @@ into your `configuration.nix` or bring them into scope with `nix-shell -p rustc For other versions such as daily builds (beta and nightly), use either `rustup` from nixpkgs (which will manage the rust installation in your home directory), -or use Mozilla's [Rust nightlies overlay](#using-the-rust-nightlies-overlay). +or use a community maintained [Rust overlay](#using-community-rust-overlays). ## Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo} @@ -186,6 +186,33 @@ added. To find the correct hash, you can first use `lib.fakeSha256` or `lib.fakeHash` as a stub hash. Building the package (and thus the vendored dependencies) will then inform you of the correct hash. +### Cargo features {#cargo-features} + +You can disable default features using `buildNoDefaultFeatures`, and +extra features can be added with `buildFeatures`. + +If you want to use different features for check phase, you can use +`checkNoDefaultFeatures` and `checkFeatures`. They are only passed to +`cargo test` and not `cargo build`. If left unset, they default to +`buildNoDefaultFeatures` and `buildFeatures`. + +For example: + +```nix +rustPlatform.buildRustPackage rec { + pname = "myproject"; + version = "1.0.0"; + + buildNoDefaultFeatures = true; + buildFeatures = [ "color" "net" ]; + + # disable network features in tests + checkFeatures = [ "color" ]; + + # ... +} +``` + ### Cross compilation {#cross-compilation} By default, Rust packages are compiled for the host platform, just like any @@ -237,22 +264,6 @@ where they are known to differ. But there are ways to customize the argument: --target /nix/store/asdfasdfsadf-thumb-crazy.json # contains {"foo":"","bar":""} ``` -Finally, as an ad-hoc escape hatch, a computed target (string or JSON file -path) can be passed directly to `buildRustPackage`: - -```nix -pkgs.rustPlatform.buildRustPackage { - /* ... */ - target = "x86_64-fortanix-unknown-sgx"; -} -``` - -This is useful to avoid rebuilding Rust tools, since they are actually target -agnostic and don't need to be rebuilt. But in the future, we should always -build the Rust tools and standard library crates separately so there is no -reason not to take the `stdenv.hostPlatform.rustc`-modifying approach, and the -ad-hoc escape hatch to `buildRustPackage` can be removed. - Note that currently custom targets aren't compiled with `std`, so `cargo test` will fail. This can be ignored by adding `doCheck = false;` to your derivation. @@ -277,12 +288,12 @@ rustPlatform.buildRustPackage { Please note that the code will be compiled twice here: once in `release` mode for the `buildPhase`, and again in `debug` mode for the `checkPhase`. -Test flags, e.g., `--features xxx/yyy`, can be passed to `cargo test` via the +Test flags, e.g., `--package foo`, can be passed to `cargo test` via the `cargoTestFlags` attribute. Another attribute, called `checkFlags`, is used to pass arguments to the test binary itself, as stated -(here)[https://doc.rust-lang.org/cargo/commands/cargo-test.html]. +[here](https://doc.rust-lang.org/cargo/commands/cargo-test.html). #### Tests relying on the structure of the `target/` directory {#tests-relying-on-the-structure-of-the-target-directory} @@ -427,7 +438,7 @@ you of the correct hash. `rustPlatform` provides the following hooks to automate Cargo builds: -* `cargoSetupHook`: configure Cargo to use depenencies vendored +* `cargoSetupHook`: configure Cargo to use dependencies vendored through `fetchCargoTarball`. This hook uses the `cargoDeps` environment variable to find the vendored dependencies. If a project already vendors its dependencies, the variable `cargoVendorDir` can @@ -437,18 +448,20 @@ you of the correct hash. * `cargoBuildHook`: use Cargo to build a crate. If the crate to be built is a crate in e.g. a Cargo workspace, the relative path to the crate to build can be set through the optional `buildAndTestSubdir` - environment variable. Additional Cargo build flags can be passed - through `cargoBuildFlags`. + environment variable. Features can be specified with + `cargoBuildNoDefaultFeatures` and `cargoBuildFeatures`. Additional + Cargo build flags can be passed through `cargoBuildFlags`. * `maturinBuildHook`: use [Maturin](https://github.com/PyO3/maturin) to build a Python wheel. Similar to `cargoBuildHook`, the optional variable `buildAndTestSubdir` can be used to build a crate in a - Cargo workspace. Additional maturin flags can be passed through + Cargo workspace. Additional Maturin flags can be passed through `maturinBuildFlags`. * `cargoCheckHook`: run tests using Cargo. The build type for checks - can be set using `cargoCheckType`. Additional flags can be passed to - the tests using `checkFlags` and `checkFlagsArray`. By default, - tests are run in parallel. This can be disabled by setting - `dontUseCargoParallelTests`. + can be set using `cargoCheckType`. Features can be specified with + `cargoCheckNoDefaultFeaatures` and `cargoCheckFeatures`. Additional + flags can be passed to the tests using `checkFlags` and + `checkFlagsArray`. By default, tests are run in parallel. This can + be disabled by setting `dontUseCargoParallelTests`. * `cargoInstallHook`: install binaries and static/shared libraries that were built using `cargoBuildHook`. @@ -463,7 +476,7 @@ dependencies. The build itself is then performed by The following example outlines how the `tokenizers` Python package is built. Since the Python package is in the `source/bindings/python` -directory of the *tokenizers* project's source archive, we use +directory of the `tokenizers` project's source archive, we use `sourceRoot` to point the tooling to this directory: ```nix @@ -688,7 +701,7 @@ Some crates require external libraries. For crates from `defaultCrateOverrides` package in nixpkgs itself. Starting from that file, one can add more overrides, to add features -or build inputs by overriding the hello crate in a seperate file. +or build inputs by overriding the hello crate in a separate file. ```nix with import <nixpkgs> {}; @@ -745,7 +758,7 @@ with import <nixpkgs> {}; Actually, the overrides introduced in the previous section are more general. A number of other parameters can be overridden: -- The version of rustc used to compile the crate: +- The version of `rustc` used to compile the crate: ```nix (hello {}).override { rust = pkgs.rust; }; @@ -758,7 +771,7 @@ general. A number of other parameters can be overridden: (hello {}).override { release = false; }; ``` -- Whether to print the commands sent to rustc when building +- Whether to print the commands sent to `rustc` when building (equivalent to `--verbose` in cargo: ```nix @@ -887,76 +900,107 @@ rustc 1.26.0-nightly (188e693b3 2018-03-26) To see that you are using nightly. -## Using the Rust nightlies overlay {#using-the-rust-nightlies-overlay} - -Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope. -This overlay can _also_ be used to install recent unstable or stable versions -of Rust, if desired. - -### Rust overlay installation {#rust-overlay-installation} - -You can use this overlay by either changing your local nixpkgs configuration, -or by adding the overlay declaratively in a nix expression, e.g. in `configuration.nix`. -For more information see [the manual on installing overlays](#sec-overlays-install). +## Using community Rust overlays {#using-community-rust-overlays} -#### Imperative rust overlay installation {#imperative-rust-overlay-installation} +There are two community maintained approaches to Rust toolchain management: +- [oxalica's Rust overlay](https://github.com/oxalica/rust-overlay) +- [fenix](https://github.com/nix-community/fenix) -Clone [nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla), -and create a symbolic link to the file -[rust-overlay.nix](https://github.com/mozilla/nixpkgs-mozilla/blob/master/rust-overlay.nix) -in the `~/.config/nixpkgs/overlays` directory. +Oxalica's overlay allows you to select a particular Rust version and components. +See [their documentation](https://github.com/oxalica/rust-overlay#rust-overlay) for more +detailed usage. -```ShellSession -$ git clone https://github.com/mozilla/nixpkgs-mozilla.git -$ mkdir -p ~/.config/nixpkgs/overlays -$ ln -s $(pwd)/nixpkgs-mozilla/rust-overlay.nix ~/.config/nixpkgs/overlays/rust-overlay.nix -``` +Fenix is an alternative to `rustup` and can also be used as an overlay. -### Declarative rust overlay installation {#declarative-rust-overlay-installation} +Both oxalica's overlay and fenix better integrate with nix and cache optimizations. +Because of this and ergonomics, either of those community projects +should be preferred to the Mozilla's Rust overlay (`nixpkgs-mozilla`). -Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar: +### How to select a specific `rustc` and toolchain version {#how-to-select-a-specific-rustc-and-toolchain-version} +You can consume the oxalica overlay and use it to grab a specific Rust toolchain version. +Here is an example `shell.nix` showing how to grab the current stable toolchain: ```nix { pkgs ? import <nixpkgs> { overlays = [ - (import (builtins.fetchTarball https://github.com/mozilla/nixpkgs-mozilla/archive/master.tar.gz)) - # Further overlays go here + (import (fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz")) ]; - }; -}; + } +}: +pkgs.mkShell { + nativeBuildInputs = with pkgs; [ + pkg-config + rust-bin.stable.latest.minimal + ]; +} ``` -Note that this will fetch the latest overlay version when rebuilding your system. +You can try this out by: +1. Saving that to `shell.nix` +2. Executing `nix-shell --pure --command 'rustc --version'` + +As of writing, this prints out `rustc 1.56.0 (09c42c458 2021-10-18)`. -### Rust overlay usage {#rust-overlay-usage} +### How to use an overlay toolchain in a derivation {#how-to-use-an-overlay-toolchain-in-a-derivation} -The overlay contains attribute sets corresponding to different versions of the rust toolchain, such as: +You can also use an overlay's Rust toolchain with `buildRustPackage`. +The below snippet demonstrates invoking `buildRustPackage` with an oxalica overlay selected Rust toolchain: +```nix +with import <nixpkgs> { + overlays = [ + (import (fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz")) + ]; +}; -* `latest.rustChannels.stable` -* `latest.rustChannels.nightly` -* a function `rustChannelOf`, called as `(rustChannelOf { date = "2018-04-11"; channel = "nightly"; })`, or... -* `(nixpkgs.rustChannelOf { rustToolchain = ./rust-toolchain; })` if you have a local `rust-toolchain` file (see https://github.com/mozilla/nixpkgs-mozilla#using-in-nix-expressions for an example) +rustPlatform.buildRustPackage rec { + pname = "ripgrep"; + version = "12.1.1"; + nativeBuildInputs = [ + rust-bin.stable.latest.minimal + ]; -Each of these contain packages such as `rust`, which contains your usual rust development tools with the respective toolchain chosen. -For example, you might want to add `latest.rustChannels.stable.rust` to the list of packages in your configuration. + src = fetchFromGitHub { + owner = "BurntSushi"; + repo = "ripgrep"; + rev = version; + sha256 = "1hqps7l5qrjh9f914r5i6kmcz6f1yb951nv4lby0cjnp5l253kps"; + }; -Imperatively, the latest stable version can be installed with the following command: + cargoSha256 = "03wf9r2csi6jpa7v5sw5lpxkrk4wfzwmzx7k3991q3bdjzcwnnwp"; -```ShellSession -$ nix-env -Ai nixpkgs.latest.rustChannels.stable.rust + meta = with lib; { + description = "A fast line-oriented regex search tool, similar to ag and ack"; + homepage = "https://github.com/BurntSushi/ripgrep"; + license = licenses.unlicense; + maintainers = [ maintainers.tailhook ]; + }; +} ``` -Or using the attribute with nix-shell: +Follow the below steps to try that snippet. +1. create a new directory +1. save the above snippet as `default.nix` in that directory +1. cd into that directory and run `nix-build` -```ShellSession -$ nix-shell -p nixpkgs.latest.rustChannels.stable.rust -``` +### Rust overlay installation {#rust-overlay-installation} + +You can use this overlay by either changing your local nixpkgs configuration, +or by adding the overlay declaratively in a nix expression, e.g. in `configuration.nix`. +For more information see [the manual on installing overlays](#sec-overlays-install). + +### Declarative Rust overlay installation {#declarative-rust-overlay-installation} + +This snippet shows how to use oxalica's Rust overlay. +Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar: -Substitute the `nixpkgs` prefix with `nixos` on NixOS. -To install the beta or nightly channel, "stable" should be substituted by -"nightly" or "beta", or -use the function provided by this overlay to pull a version based on a -build date. +```nix +{ pkgs ? import <nixpkgs> { + overlays = [ + (import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz")) + # Further overlays go here + ]; + }; +}; +``` -The overlay automatically updates itself as it uses the same source as -[rustup](https://www.rustup.rs/). +Note that this will fetch the latest overlay version when rebuilding your system. |