README.md

PureScript Overlay

Pure and reproducible overlay for the standard PureScript toolchain, including support for Nix flakes. The toolchain is auto-updated every day. Currently supported tools:

• purs, the compiler
• spago, the package manager
• purs-tidy, the code formatter
• purs-backend-es, the optimizer
• purescript-language-server, the language server protocol

⚠️ This library is unstable and may be reorganized. Use at your own risk!

The overlay is tested on the following architectures:

• x86_64-linux
• x86_64-darwin (Intel Mac)
• aarch64-darwin (M1 Mac)
• aarch64-linux

The included overlay inserts the latest stable and unstable executables into your packages (ie. purs, purs-unstable, and so on). You can see all specific versions in the named.json file. It also provides many versions of each executable under a -bin namespace (ie. purs-bin, spago-bin, and so on) so you can access specific versions of a tool. For example, you can use purs-bin.purs-0_15_8 to get the 0.15.8 PureScript compiler. These are tracked in the manifests directory.

If you're looking for a way to build your spago@next-based projects using Nix, take a look at https://github.com/jeslie0/mkSpagoDerivation.

Usage

In a Nix flake, use the provided overlay when importing nixpkgs to get access to tools like purs and spago and functions like buildSpagoLock. For example, the below flake creates a development shell with recent versions of the PureScript compiler and Spago package manager:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05";
    purescript-overlay = {
      url = "github:thomashoneyman/purescript-overlay";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, ... }@inputs:
    let
      supportedSystems = ["x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin"];

      forAllSystems = nixpkgs.lib.genAttrs supportedSystems;

      nixpkgsFor = forAllSystems (system: import nixpkgs {
        inherit system;
        config = { };
        overlays = builtins.attrValues self.overlays;
      });
    in {
      overlays = {
        purescript = inputs.purescript-overlay.overlays.default;
      };

      packages = forAllSystems (system:
        let pkgs = nixpkgsFor.${system}; in {
          default = pkgs.hello; # your package here
        });

      devShells = forAllSystems (system:
        # pkgs now has access to the standard PureScript toolchain
        let pkgs = nixpkgsFor.${system}; in {
          default = pkgs.mkShell {
            name = "my-purescript-project";
            inputsFrom = builtins.attrValues self.packages.${system};
            buildInputs = with pkgs; [
              purs
              spago-unstable
              purs-tidy-bin.purs-tidy-0_10_0
              purs-backend-es
            ];
          };
        });
  };
}

The latest versions of all the supported tools are including in the default development shell of this flake. To enter a nix develop shell environment with all of the supported tools:

nix develop github:thomashoneyman/purescript-overlay

You can also run individual packages from the flake, e.g. to format your src directory:

nix run github:thomashoneyman/purescript-overlay#purs-tidy format-in-place src

You can run a nix shell with purs and spago-unstable selected from this flake:

nix shell github:thomashoneyman/purescript-overlay#purs github:thomashoneyman/purescript-overlay#spago-unstable

Tests

You can run the repository tests using a combination of nix eval .#lib (to run the unit tests in Nix) and nix flake check (to run the derivation-based tests). Both are executed in CI.