Creating Shells

Similar to inputs, Nilla uses a system of builders to create shells. A builder provides a build function and settings options to configure its use. Out of the box, Nilla ships with a single builder, nixpkgs. This builder is used to create shells using Nixpkgs’ callPackage functionality. This guide will show you how to create a new shell using the nixpkgs builder, but remember that you can create your own builders as well!

Note

This guide will assume you have a Nilla project created and a Nixpkgs pin available.

Create a new shell

To create a new shell, we need to define two options: the systems that the shell will be built for and the shell function that will produce the built shell.

my-shell.nix

{
  # We declare our shell as `my-shell`.
  config.shells.my-shell = {
    # Now we set the list systems that the shell will be built for.
    systems = [ "x86_64-linux" ];

    # Finally, we need to provide a function that takes in a package set (Nixpkgs) and
    # produces a shell.
    shell = { mkShell, bun, ... }:
      # This function returns a built shell. You can use Nixpkgs-provided tools to
      # create one!
      mkShell {
        packages = [
          bun
        ];
      };
  };
}

This shell can now be built using the Nilla CLI.

nilla shell my-shell

Tip

If you name your shell default then you can run nilla shell on its own to use it!

Using a custom package set

By default, the Nixpkgs builder will use the package set produced by inputs.nixpkgs if it exists. However, we can also specify the package set manually in our shell definition.

my-shell.nix

{ config }:
{
  config.shells.my-shell = {
    systems = [ "x86_64-linux" ];

    shell = { mkShell, bun, ... }:
      mkShell {
        packages = [
          bun
        ];
      };

    # We can customize how the builder builds our shell with the `settings` option.
    settings = {
      # One option that the Nixpkgs builder provides is `pkgs` which allows us to
      # choose the package set that will be used to build our shell.
      #
      # In this example we will tell the builder to use the loaded `nixpkgs-unstable`
      # package set.
      pkgs = config.inputs.nixpkgs-unstable.result;
    };
  };
}

Customizing shell arguments

The shell function takes its arguments from Nixpkgs’ callPackage function in addition to settings. This allows us to override or provide additional configuration.

my-shell.nix

{
  config.shells.my-shell = {
    systems = [ "x86_64-linux" ];

    shell = { mkShell, enableFeatureX, ... }:
      mkShell {
        /* ... */
      };

    settings = {
      # For the Nixpkgs builder we can specify `args` which are passed to the shell function.
      args = {
        enableFeatureX = true;
      };
    };
  };
}