mkSpagoDerivation

This flake provides an unopinionated approach to packaging PureScript projects with the Nix package manager. Leveraging PureScript’s registry and the new spago@next, this repository facilitates the creation of reproducible builds for PureScript projects with minimal complexity. This works by treating a PureScript project’s spago.lock as a single source of truth for dependencies.

Table of contents

• Examples
• Out of date registry
• Limitations
• Notes
  • Hooks
• Related
• License

Examples

The most important function that this flake provides is the mkSpagoDerivation function, exposed as both an output and via an overlay. This provides a wrapper around stdenv.mkDerivation which puts all of your project’s dependencies in the right place, making it easy for you to build your projects in a reproducible way.

Importantly, the spago.lock file is required for mkSpagoDerivation to determine your project’s dependencies. Optionally, if you provide your project’s spago.yaml file, then your project’s name will be extracted and used. You can provide a name or pname argument instead.

Here is a simple flake.nix that builds a PureScript project.

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    mkSpagoDerivation.url = "github:jeslie0/mkSpagoDerivation";
    ps-overlay.url = "github:thomashoneyman/purescript-overlay";
  };

  outputs = { self, nixpkgs, flake-utils, mkSpagoDerivation }:
    flake-utils.lib.eachDefaultSystem (
      system:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [ mkSpagoDerivation.overlays.default
                       ps-overlay.overlays.default ];
        };
      in
        {
          packages.default =
            pkgs.mkSpagoDerivation {
              spagoYaml = ./spago.yaml;
              spagoLock = ./spago.lock;
              src = ./.;
              nativeBuildInputs = [ pkgs.purs-unstable pkgs.spago-unstable pkgs.esbuild ];
              version = "0.1.0";
              buildPhase = "spago bundle";
              installPhase = "mkdir $out; cp index.js $out";
            };
        }
    );
}

The only attribute mkSpagoDerivation requires is src. The spagoYaml attribute will default to ${src}/spago.yaml and likewise, spagoLock defaults to ${src}/spago.lock. Everything else is passed into mkDerivation. There are no assumptions about the which version of the compiler is used - you must specify which copy of Spago and PureScript you want to use. Dependencies can be added through buildInputs or nativeBuildInputs. The following example demonstrates this, by using purescript-backend-optimizer and using the unstable PureScript compiler from the PureScript Overlay.

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    ps-overlay.url = "github:thomashoneyman/purescript-overlay";
    mkSpagoDerivation.url = "github:jeslie0/mkSpagoDerivation";
  };

  outputs = { self, nixpkgs, flake-utils, ps-overlay, mkSpagoDerivation }:
    flake-utils.lib.eachDefaultSystem (
      system:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [ mkSpagoDerivation.overlays.default
                       ps-overlay.overlays.default
                     ];
        };
      in
        {
          packages.default =
            pkgs.mkSpagoDerivation {
              spagoYaml = ./spago.yaml;
              spagoLock = ./spago.lock;
              src = ./.;
              version = "0.1.0";
              nativeBuildInputs = [ pkgs.esbuild pkgs.purs-backend-es pkgs.purs-unstable pkgs.spago-unstable ];
              buildPhase = "spago build && purs-backend-es bundle-app --no-build --minify --to=main.min.js";
              installPhase = "mkdir $out; cp -r main.min.js $out";
            };
        }
    );
}

Some other useful functions are exposed. One is buildDotSpago, which builds a project’s .spago directory. It takes an attribute set { spagoLock, src }, which respectively are the paths to the project’s spago.lock and the root of the project. Another useful function is buildSpagoNodeJs, which builds the spago-nodejs directory, typically located in the user’s .cache directory.

Out of date registry

It is possible for this repository to not have the most up-to-date registry set. If you cant wait for the GitHub action to update this repository, you can override the registry and registry-index inputs to this flake.

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    ps-overlay.url = "github:thomashoneyman/purescript-overlay";
    mkSpagoDerivation = {
      url = "github:jeslie0/mkSpagoDerivation";
      inputs = {
        registry.url = "github:purescript/registry/066f77d3b668fd7916e0af493d8d8ec7a850d774";
        registry-index.url = "github:purescript/registry-index/53cfacb3b1677120eb5e6c11a1f2449d1049c2ce";
      };
    };
  };

  outputs = { self, nixpkgs, flake-utils, ps-overlay, mkSpagoDerivation }:
  ...

Limitations

At the time of writing, this project only supports PureScript projects that make use of the newer spago@next releases. In particular, the project needs a spago.yaml file and a spago.lock file is required too.

Notes

Hooks

The buildPhase and installPhase always run pre and post hooks, even if the commands provided by the user don’t specify them.

Related

• purifix A different tool to package PureScript programs with Nix.
• spago2nix Another tool for packaging PureScript programs with Nix.
• easy-purescript-nix A repository and Nix flake that provides lots of PureScript tools.
• purs-nix A tool for Nix based PureScript development.
• mkElmDerivation A similar tool (that I created) to package Elm applications with Nix.

License

All of this repository is under the MIT license.