docs: extend rust docs (#35587)
- Add example for setting up nix-shell, improve rust docs - Rust docs: add gcc rust dependencies and fix carnix commands - Fix a typo with the carnix command.
This commit is contained in:
parent
5e4c376490
commit
f7342a3625
|
@ -16,6 +16,12 @@ cargo
|
||||||
into the `environment.systemPackages` or bring them into
|
into the `environment.systemPackages` or bring them into
|
||||||
scope with `nix-shell -p rustc cargo`.
|
scope with `nix-shell -p rustc cargo`.
|
||||||
|
|
||||||
|
> If you are using NixOS and you want to use rust without a nix expression you
|
||||||
|
> probably want to add the following in your `configuration.nix` to build
|
||||||
|
> crates with C dependencies.
|
||||||
|
>
|
||||||
|
> environment.systemPackages = [binutils gcc gnumake openssl pkgconfig]
|
||||||
|
|
||||||
For daily builds (beta and nightly) use either rustup from
|
For daily builds (beta and nightly) use either rustup from
|
||||||
nixpkgs or use the [Rust nightlies
|
nixpkgs or use the [Rust nightlies
|
||||||
overlay](#using-the-rust-nightlies-overlay).
|
overlay](#using-the-rust-nightlies-overlay).
|
||||||
|
@ -76,7 +82,7 @@ an example for a minimal `hello` crate:
|
||||||
Compiling hello v0.1.0 (file:///tmp/hello)
|
Compiling hello v0.1.0 (file:///tmp/hello)
|
||||||
Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs
|
Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs
|
||||||
$ carnix -o hello.nix --src ./. Cargo.lock --standalone
|
$ carnix -o hello.nix --src ./. Cargo.lock --standalone
|
||||||
$ nix-build hello.nix
|
$ nix-build hello.nix -A hello_0_1_0
|
||||||
|
|
||||||
Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:
|
Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:
|
||||||
|
|
||||||
|
@ -276,6 +282,84 @@ features, we would write:
|
||||||
|
|
||||||
Where `diesel.nix` is the file generated by Carnix, as explained above.
|
Where `diesel.nix` is the file generated by Carnix, as explained above.
|
||||||
|
|
||||||
|
|
||||||
|
## Setting Up `nix-shell`
|
||||||
|
Oftentimes you want to develop code from within `nix-shell`. Unfortunately
|
||||||
|
`buildRustCrate` does not support common `nix-shell` operations directly
|
||||||
|
(see [this issue](https://github.com/NixOS/nixpkgs/issues/37945))
|
||||||
|
so we will use `stdenv.mkDerivation` instead.
|
||||||
|
|
||||||
|
Using the example `hello` project above, we want to do the following:
|
||||||
|
- Have access to `cargo` and `rustc`
|
||||||
|
- Have the `openssl` library available to a crate through it's _normal_
|
||||||
|
compilation mechanism (`pkg-config`).
|
||||||
|
|
||||||
|
A typical `shell.nix` might look like:
|
||||||
|
|
||||||
|
```
|
||||||
|
with import <nixpkgs> {};
|
||||||
|
|
||||||
|
stdenv.mkDerivation {
|
||||||
|
name = "rust-env";
|
||||||
|
buildInputs = [
|
||||||
|
rustc cargo
|
||||||
|
|
||||||
|
# Example Additional Dependencies
|
||||||
|
pkgconfig openssl
|
||||||
|
];
|
||||||
|
|
||||||
|
# Set Environment Variables
|
||||||
|
RUST_BACKTRACE = 1;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
You should now be able to run the following:
|
||||||
|
```
|
||||||
|
$ nix-shell --pure
|
||||||
|
$ cargo build
|
||||||
|
$ cargo test
|
||||||
|
```
|
||||||
|
|
||||||
|
### Controlling Rust Version Inside `nix-shell`
|
||||||
|
To control your rust version (i.e. use nightly) from within `shell.nix` (or
|
||||||
|
other nix expressions) you can use the following `shell.nix`
|
||||||
|
|
||||||
|
```
|
||||||
|
# Latest Nightly
|
||||||
|
with import <nixpkgs> {};
|
||||||
|
let src = fetchFromGitHub {
|
||||||
|
owner = "mozilla";
|
||||||
|
repo = "nixpkgs-mozilla";
|
||||||
|
# commit from: 2018-03-27
|
||||||
|
rev = "2945b0b6b2fd19e7d23bac695afd65e320efcebe";
|
||||||
|
sha256 = "034m1dryrzh2lmjvk3c0krgip652dql46w5yfwpvh7gavd3iypyw";
|
||||||
|
};
|
||||||
|
in
|
||||||
|
with import "${src.out}/rust-overlay.nix" pkgs pkgs;
|
||||||
|
stdenv.mkDerivation {
|
||||||
|
name = "rust-env";
|
||||||
|
buildInputs = [
|
||||||
|
# Note: to use use stable, just replace `nightly` with `stable`
|
||||||
|
latest.rustChannels.nightly.rust
|
||||||
|
|
||||||
|
# Add some extra dependencies from `pkgs`
|
||||||
|
pkgconfig openssl
|
||||||
|
];
|
||||||
|
|
||||||
|
# Set Environment Variables
|
||||||
|
RUST_BACKTRACE = 1;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Now run:
|
||||||
|
```
|
||||||
|
$ rustc --version
|
||||||
|
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.
|
Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope.
|
||||||
|
|
Loading…
Reference in a new issue