mkShell vs. buildEnv?

akavel · August 16, 2018, 7:43pm

I’ve seen examples of nix-shell environments, sometimes based on buildEnv, sometimes on mkShell; are there some important differences? Which one should I use and why?

manveru · August 17, 2018, 8:23am

Let’s first take a look at buildEnv:

github.com

NixOS/nixpkgs/blob/master/pkgs/build-support/buildenv/default.nix

# buildEnv creates a tree of symlinks to the specified paths.  This is
# a fork of the hardcoded buildEnv in the Nix distribution.

{ buildPackages, runCommand, lib, substituteAll }:

let
  builder = substituteAll {
    src = ./builder.pl;
    inherit (builtins) storeDir;
  };
in

lib.makeOverridable
({ name

, # The manifest file (if any).  A symlink $out/manifest will be
  # created to it.
  manifest ? ""

, # The paths to symlink.

This file has been truncated. show original

This is basically a wrapper around the builder.pl, and simply provides you with a bunch of symlinks. I’m not sure why you’d use it for a nix-shell, but it seems like some people like to put all their buildInputs through buildEnv to get a reference to all their dependencies within a single directory.

mkShell

github.com

NixOS/nixpkgs/blob/master/pkgs/build-support/mkshell/default.nix

{ lib, stdenv, buildEnv }:

# A special kind of derivation that is only meant to be consumed by the
# nix-shell.
{ name ? "nix-shell"
, # a list of packages to add to the shell environment
  packages ? [ ]
, # propagate all the inputs from the given derivations
  inputsFrom ? [ ]
, buildInputs ? [ ]
, nativeBuildInputs ? [ ]
, propagatedBuildInputs ? [ ]
, propagatedNativeBuildInputs ? [ ]
, ...
}@attrs:
let
  mergeInputs = name:
    (attrs.${name} or [ ]) ++
    # 1. get all `{build,nativeBuild,...}Inputs` from the elements of `inputsFrom`
    # 2. since that is a list of lists, `flatten` that into a regular list

This file has been truncated. show original

This one is super simple compared to buildEnv and the one I use every day, all it does is provide some defaults for a stdenv.mkDerivation. So you don’t need to give it a src or name, all you really need is buildInputs, maybe a shellHook that runs when you enter the nix-shell, and any env variables you want.

toraritte · July 15, 2019, 4:00pm

See also Nixpkgs issue 58624, " mkShell needs more documentation in the manual" for more info.