Creating Packages

Similar to inputs, Nilla uses a system of builders to create packages. 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 packages using Nixpkgs’ callPackage functionality. This guide will show you how to create a new package 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 package

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

my-package.nix

{
  # We declare our package as `my-package`.
  config.packages.my-package = {
    # Now we set the list systems that the package 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 package.
    package = { stdenv, fetchFromGitHub, waylandpp, ... }:
      # This function returns a built package. You can use Nixpkgs-provided tools to
      # create one!
      stdenv.mkDerivation {
        src = fetchFromGitHub { /* ... */ };
        buildInputs = [ waylandpp ];
      };
  };
}

This package can now be built using the Nilla CLI.

nilla build my-package

Tip

If you name your package default then you can run nilla build on its own to build 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 package definition.

my-package.nix

{ config }:
{
  config.packages.my-package = {
    systems = [ "x86_64-linux" ];

    package = { stdenv, fetchFromGitHub, waylandpp, ... }:
      stdenv.mkDerivation {
        src = fetchFromGitHub { /* ... */ };
        buildInputs = [ waylandpp ];
      };

    # We can customize how the builder builds our package 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 package.
      #
      # In this example we will tell the builder to use the loaded `nixpkgs-unstable`
      # package set.
      pkgs = config.inputs.nixpkgs-unstable.result;
    };
  };
}

Customizing package arguments

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

my-package.nix

{
  config.packages.my-package = {
    systems = [ "x86_64-linux" ];

    package = { stdenv, enableFeatureX, ... }:
      stdenv.mkDerivation {
        /* ... */
      };

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