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.

1 files changed, 85 insertions, 1 deletions

diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md
index f0498eac5b19..b77c41e9b229 100644
--- a/doc/languages-frameworks/rust.section.md
+++ b/doc/languages-frameworks/rust.section.md
@@ -16,6 +16,12 @@ cargo
 into the `environment.systemPackages` or bring them into
 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
 nixpkgs or use the [Rust nightlies
 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)
       Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs
     $ 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:
 
@@ -276,6 +282,84 @@ features, we would write:
 
 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
 
 Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope.