HORIZON HASKELLDocsSearch packagesCtrl K
Theme: |

9 sites

QuickStart

There are two ways to build a Haskell project with a Horizon package set:

  • Generate the project's Nix from a short horizon.vx file with horizon-gen-nix. This is how Horizon's own projects are built, and it gives you a development shell.
  • Write a flake.nix by hand that uses a set as an input. This needs no extra tools.

Both build against horizon-platform for GHC 10.0.

Generate the project's Nix

At the top of your project's repository, write horizon.vx. Replace the first hello with your package's name, and the second with the directory that holds its .cabal file:

do
  name "hello"
  compiler "ghc-10.0.0.20260917"
  on (toolchain (forge "nixlab.openfp.net/package-sets/haskell/horizon-platform") (branch "refs/tags/snapshots/lts/ghc-10.0.x/9"))
  flake Generated
  local "hello" "hello"
  root "hello"
  devShell

flake Generated lets horizon-gen-nix write flake.nix. Generate the Nix files, lock the flake, then build the package:

git init
git add -A
nix run 'git+https://nixlab.openfp.net/horizon/horizon-gen-nix?ref=refs/tags/0.26.0' -- update horizon.vx
git add -A
nix flake lock
git add flake.lock
nix build .#hello

horizon-gen-nix update writes flake.nix, horizon.lock, cabal.project and the files under nix/. Nix reads only files that git tracks, so add them before building. Commit them all, with flake.lock. The build has succeeded when ./result/bin/hello runs.

After changing horizon.vx or a .cabal file, run update again. To confirm, for example in CI, that the committed files match horizon.vx:

nix run 'git+https://nixlab.openfp.net/horizon/horizon-gen-nix?ref=refs/tags/0.26.0' -- check horizon.vx

It prints Horizon snapshot is consistent, or says what differs and how to fix it. It fails if flake.nix has been edited or flake.lock is missing.

For a shell with GHC and cabal-install:

nix develop
cabal build all

Keep your own flake.nix

To add your own inputs or outputs, write flake Manual in place of flake Generated. horizon-gen-nix then never writes or checks flake.nix; you write it. It must load the modules under nix/, and declare the set named by on as an input of the same name, on the same tag:

{
  inputs = {
    horizon-platform.url = "git+https://nixlab.openfp.net/package-sets/haskell/horizon-platform?ref=refs/tags/snapshots/lts/ghc-10.0.x/9";
    horizon-flake-parts.url = "git+https://nixlab.openfp.net/nix/horizon-flake-parts?ref=refs/tags/0.35.2";
    nixpkgs.follows = "horizon-platform/nixpkgs";
    horizon-ghc.follows = "horizon-platform/horizon-ghc";
  };

  outputs =
    inputs:
    inputs.horizon-flake-parts.inputs.nixica.lib.mkFlake {
      inputs = inputs.horizon-platform.inputs // inputs // { inherit (inputs.horizon-flake-parts.inputs) nixica; };
      modules = ./nix;
    };
}

The commands are the same as above. If the input is missing or on another branch, check prints the line to put in flake.nix. Configuration describes both options and every statement horizon.vx can contain.

Write a flake by hand

A set's legacyPackages has the same interface as nixpkgs' haskellPackages. Put this flake.nix next to your project's .cabal file, replacing hello with your package's name:

{
  inputs.horizon-platform.url = "git+https://nixlab.openfp.net/package-sets/haskell/horizon-platform?ref=refs/tags/snapshots/lts/ghc-10.0.x/9";

  outputs = { self, horizon-platform }:
    let
      system = "x86_64-linux";
      haskellPackages = horizon-platform.legacyPackages.${system};
    in
    {
      packages.${system}.default = haskellPackages.callCabal2nix "hello" ./. { };
      devShells.${system}.default = haskellPackages.shellFor {
        packages = _: [ self.packages.${system}.default ];
        nativeBuildInputs = [ haskellPackages.cabal-install ];
      };
    };
}

Then:

git add flake.nix
nix build
nix develop

Pin a snapshot

Each release of a set's branch is tagged snapshots/<branch>/<N>; these examples pin snapshots/lts/ghc-10.0.x/9. Pin a snapshot tag rather than the branch, because the branch moves.

Use the binary cache

CI-built packages are cached at https://cache.openfp.net. Add it to nix.conf so Nix downloads them instead of building them:

extra-substituters = https://cache.openfp.net
extra-trusted-public-keys = cache.openfp.net-1:ThN0P23SdgO8mRfZDCr0FZICFv9f2Llv1wqpfDoaMY4=

Choose another set

Each set's page on this site lists its branches. The FAQ lists the sets. A set built on top of another is generated the same way: the on (toolchain ...) line names the set it is built on.