Add devshell helper (ipetkov#378)

simonzkl · Sep 3, 2023 · 7b92b59 · 7b92b59
1 parent ecf1516
commit 7b92b59
Show file tree

Hide file tree

Showing 13 changed files with 155 additions and 55 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Unreleased
 
+### Added
+* Added `devShell`, a thin wrapper around `pkgs.mkShell` which automatically
+  provides `cargo` and `rustc`.
+
 ### Changed
 * **Breaking** (technically): `buildDepsOnly`, `buildPackage`, `cargoBuild`,
   `cargoClippy`, `cargoDoc`, `cargoLlvmCov`, and `cargoTest`'s defaults have

diff --git a/checks/default.nix b/checks/default.nix
@@ -237,6 +237,14 @@ in
     src = ./various-targets;
   };
 
+  devShell = myLib.devShell {
+    checks = {
+      simple = myLib.buildPackage {
+        src = ./simple;
+      };
+    };
+  };
+
   features = callPackage ./features { };
 
   flakePackages =

diff --git a/docs/API.md b/docs/API.md
@@ -766,6 +766,55 @@ raised during evaluation.
   - Default value: `"0.0.1"` if the specified Cargo.toml file did not
     include a version
 
+### `craneLib.devShell`
+
+`devShell :: set -> drv`
+
+A thin wrapper around
+[`pkgs.mkShell`](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell) for
+creating development shells for use with `nix develop` (see [“Local
+Development”](local_development.md)). Except where noted below, all derivation
+attributes are passed straight through, so any `mkShell` behavior can be used
+as expected: namely, all key-value pairs other than those `mkShell` consumes
+will be set as environment variables in the resulting shell.
+
+#### Optional attributes
+* `checks`: A set of checks to inherit inputs from, typically
+  `self.checks.${system}`. Build inputs from the values in this attribute set
+  are added to the created shell environment for interactive use.
+* `inputsFrom`: A list of extra packages to inherit inputs from. Note that
+  these packages are _not_ added to the result environment; use
+  `packages` for that.
+* `packages`: A list of extra packages to add to the created shell environment.
+* `shellHook`: A string of bash statements that will be executed when the shell
+  is entered with `nix develop`.
+
+See the [quick start example](examples/quick-start.md) for usage in a
+`flake.nix` file.
+
+```nix
+craneLib.devShell {
+  checks = self.checks.${system};
+
+  packages = [
+    pkgs.ripgrep
+  ];
+
+  # Set a `cargo-nextest` profile:
+  NEXTEST_PROFILE = "local";
+}
+```
+
+```nix
+craneLib.devShell {
+  checks = {
+    my-package-clippy = craneLib.cargoClippy commonArgs;
+    my-package-doc = craneLib.cargoDoc commonArgs;
+    my-package-nextest = craneLib.cargoNextest commonArgs;
+  };
+}
+```
+
 ### `craneLib.downloadCargoPackage`
 
 `downloadCargoPackage :: set -> drv`

diff --git a/docs/local_development.md b/docs/local_development.md
@@ -5,11 +5,13 @@ shells)](https://nix.dev/tutorials/ad-hoc-developer-environments) are extremely
 powerful when it comes to locally developing with the exact same dependencies
 used when building packages.
 
-To get started, declare a default devShell in `flake.nix` and run `nix develop`
-in the project directory. Then, you can use something like
+To get started, declare a default `devShell` in `flake.nix` using
+[`craneLib.devShell`](API.md#cranelibdevshell) and run `nix develop` in the
+project directory. Then, you can use something like
 [`direnv`](https://direnv.net) or
 [`nix-direnv`](https://github.com/nix-community/nix-direnv) to automatically
-enter and exit a development shell when you enter or exit the project directory!
+enter and exit a development shell when you enter or exit the project
+directory!
 
 Sample `flake.nix`:
 ```nix
@@ -50,21 +52,18 @@ Sample `flake.nix`:
       {
         packages.default = my-crate;
 
-        devShells.default = pkgs.mkShell {
+        devShells.default = craneLib.devShell {
           # Additional dev-shell environment variables can be set directly
           MY_CUSTOM_DEV_URL = "http://localhost:3000";
 
           # Automatically inherit any build inputs from `my-crate`
           inputsFrom = [ my-crate ];
 
           # Extra inputs (only used for interactive development)
-          # can be added here
-          nativeBuildInputs = with pkgs; [
-            cargo
-            rustc
-
-            cargo-audit
-            cargo-watch
+          # can be added here; cargo and rustc are provided by default.
+          packages = [
+            pkgs.cargo-audit
+            pkgs.cargo-watch
           ];
         };
       });

diff --git a/examples/alt-registry/flake.nix b/examples/alt-registry/flake.nix
@@ -91,13 +91,16 @@
           drv = my-crate;
         };
 
-        devShells.default = pkgs.mkShell {
-          inputsFrom = builtins.attrValues self.checks.${system};
+        devShells.default = craneLib.devShell {
+          # Inherit inputs from checks.
+          checks = self.checks.${system};
 
-          # Extra inputs can be added here
-          nativeBuildInputs = with pkgs; [
-            cargo
-            rustc
+          # Additional dev-shell environment variables can be set directly
+          # MY_CUSTOM_DEVELOPMENT_VAR = "something else";
+
+          # Extra inputs can be added here; cargo and rustc are provided by default.
+          packages = [
+            # pkgs.ripgrep
           ];
         };
       });

diff --git a/examples/build-std/flake.nix b/examples/build-std/flake.nix
@@ -78,12 +78,14 @@
 
         packages.default = my-crate;
 
-        devShells.default = pkgs.mkShell {
-          inputsFrom = builtins.attrValues self.checks.${system};
-
-          # Extra inputs can be added here
-          nativeBuildInputs = with pkgs; [
-            rustToolchain
+        devShells.default = craneLib.devShell {
+          # Inherit inputs from checks.
+          checks = self.checks.${system};
+
+          # Extra inputs can be added here; cargo and rustc are provided by default
+          # from the toolchain that was specified earlier.
+          packages = [
+            # rustToolchain
           ];
         };
       });

diff --git a/examples/custom-toolchain/flake.nix b/examples/custom-toolchain/flake.nix
@@ -68,12 +68,14 @@
           '';
         };
 
-        devShells.default = pkgs.mkShell {
-          inputsFrom = builtins.attrValues self.checks.${system};
+        devShells.default = craneLib.devShell {
+          # Inherit inputs from checks.
+          checks = self.checks.${system};
 
-          # Extra inputs can be added here
-          nativeBuildInputs = with pkgs; [
-            rustWithWasiTarget
+          # Extra inputs can be added here; cargo and rustc are provided by default
+          # from the toolchain that was specified earlier.
+          packages = [
+            # rustWithWasiTarget
           ];
         };
       });

diff --git a/examples/quick-start-simple/flake.nix b/examples/quick-start-simple/flake.nix
@@ -45,16 +45,16 @@
           drv = my-crate;
         };
 
-        devShells.default = pkgs.mkShell {
-          inputsFrom = builtins.attrValues self.checks.${system};
+        devShells.default = craneLib.devShell {
+          # Inherit inputs from checks.
+          checks = self.checks.${system};
 
           # Additional dev-shell environment variables can be set directly
           # MY_CUSTOM_DEVELOPMENT_VAR = "something else";
 
-          # Extra inputs can be added here
-          nativeBuildInputs = with pkgs; [
-            cargo
-            rustc
+          # Extra inputs can be added here; cargo and rustc are provided by default.
+          packages = [
+            # pkgs.ripgrep
           ];
         };
       });

diff --git a/examples/quick-start/flake.nix b/examples/quick-start/flake.nix
@@ -124,16 +124,16 @@
           drv = my-crate;
         };
 
-        devShells.default = pkgs.mkShell {
-          inputsFrom = builtins.attrValues self.checks.${system};
+        devShells.default = craneLib.devShell {
+          # Inherit inputs from checks.
+          checks = self.checks.${system};
 
           # Additional dev-shell environment variables can be set directly
           # MY_CUSTOM_DEVELOPMENT_VAR = "something else";
 
-          # Extra inputs can be added here
-          nativeBuildInputs = with pkgs; [
-            cargo
-            rustc
+          # Extra inputs can be added here; cargo and rustc are provided by default.
+          packages = [
+            # pkgs.ripgrep
           ];
         };
       });

diff --git a/examples/trunk-workspace/flake.nix b/examples/trunk-workspace/flake.nix
@@ -142,18 +142,17 @@
           drv = myServer;
         };
 
-        devShells.default = pkgs.mkShell {
-          inputsFrom = builtins.attrValues self.checks;
+        devShells.default = craneLib.devShell {
+          # Inherit inputs from checks.
+          checks = self.checks.${system};
 
           shellHook = ''
             export CLIENT_DIST=$PWD/client/dist;
           '';
 
-          # Extra inputs can be added here
-          nativeBuildInputs = with pkgs; [
-            cargo
-            rustc
-            trunk
+          # Extra inputs can be added here; cargo and rustc are provided by default.
+          packages = [
+            pkgs.trunk
           ];
         };
       });

diff --git a/examples/trunk/flake.nix b/examples/trunk/flake.nix
@@ -120,14 +120,16 @@
           drv = serve-app;
         };
 
-        devShells.default = pkgs.mkShell {
-          inputsFrom = builtins.attrValues self.checks;
-
-          # Extra inputs can be added here
-          nativeBuildInputs = with pkgs; [
-            cargo
-            rustc
-            trunk
+        devShells.default = craneLib.devShell {
+          # Inherit inputs from checks.
+          checks = self.checks.${system};
+
+          # Additional dev-shell environment variables can be set directly
+          # MY_CUSTOM_DEVELOPMENT_VAR = "something else";
+
+          # Extra inputs can be added here; cargo and rustc are provided by default.
+          packages = [
+            pkgs.trunk
           ];
         };
       });

diff --git a/lib/default.nix b/lib/default.nix
@@ -31,6 +31,7 @@ in
   configureCargoCommonVarsHook = callPackage ./setupHooks/configureCargoCommonVars.nix { };
   configureCargoVendoredDepsHook = callPackage ./setupHooks/configureCargoVendoredDeps.nix { };
   craneUtils = callPackage ../pkgs/crane-utils { };
+  devShell = callPackage ./devShell.nix { };
 
   crateNameFromCargoToml = callPackage ./crateNameFromCargoToml.nix {
     inherit internalCrateNameFromCargoToml;

diff --git a/lib/devShell.nix b/lib/devShell.nix
@@ -0,0 +1,31 @@
+{ lib
+, mkShell
+, rustPlatform
+, cargo
+, rustc
+}:
+
+{ checks ? { }
+, inputsFrom ? [ ]
+, packages ? [ ]
+, ...
+}@args:
+let
+  inherit (builtins) removeAttrs;
+
+  cleanedArgs = removeAttrs args [
+    "checks"
+    "inputsFrom"
+    "nativeBuildInputs"
+  ];
+in
+mkShell (cleanedArgs // {
+  inputsFrom = builtins.attrValues checks ++ inputsFrom;
+
+  packages =
+    [
+      rustc
+      cargo
+    ]
+    ++ packages;
+})