Haskell: Difference between revisions

(24 intermediate revisions by 10 users not shown)

Line 1:

~~== FAQ and resources ==~~

[https://www.haskell.org/ Haskell] is a statically-typed, purely functional programming language with strong support for type inference and lazy evaluation.

* '''Official Docs:''' [https://~~nixos~~.org/~~manual/nixpkgs/unstable/#haskell '''The~~ Haskell ~~section in the nixpkgs manual'''~~]

* [https://www.srid.ca/haskell-~~nix '''Nix recipes~~ for ~~Haskellers'''] aims to get a beginner comfortable managing simple Haskell programs~~ and ~~projects using Nix~~.

* [https://github.com/mhwombat/nix-for-numbskulls/blob/78bcc186f79931c0e4a1e445e2f6b1f12f6d46be/Haskell/ss-haskell-dev.md '''Super-Simple Haskell Development with Nix'''] (and [https://discourse.nixos.org/t/super-simple-haskell-development-with-nix/14287/2 discussion] that provides interesting alternative methods together with there pro and cons)

For detailed information on Haskell support in Nixpkgs, refer to the official {{Nixpkgs Manual|name=Nixpkgs Manual: Chapter - Haskell|anchor=#haskell}}.

* [https:~~//discourse.nixos.org/t/nix-haskell~~-~~development-2020/6170 '''Nix~~ Haskell ~~Development (2020)''']~~

* [https://discourse.nixos.org/t/haskellpackages-stm-containers-fails-to-build/5416/4?u=~~srid '''How are Haskell packages managed in nixpkgs?''']~~

* [https://www.~~youtube.com/watch?v=KLhkAEk8I20 '''How to fix broken Haskell packages?''' (video)]~~

== How to develop with Haskell and Nix ==

~~There are multiples ways to develop in Haskell on Nix depending on~~ the ~~simplicity~~ of the ~~project and on whether one want~~ to ~~benefit from~~ the ~~reproducibility offered by nix or not. Below is an image to help you in your choice~~:

{{Note|{{nixos:package|haskellPackages}} is a synonym of <code>haskell.packages.ghcXYZ</code> where <code>XYZ</code> is the current default version of GHC in nixpkgs. However you can use a different version by replacing <code>haskellPackages</code> with the wanted package, for instance use <code>haskell.compiler.ghc884</code> to use GHC 8.8.4. You can get the full list of available GHC versions using:

~~[[File:haskell_choice.png]]~~

Note that in the following, <code>haskellPackages</code> is a synonym of <code>haskell.packages.ghcXYZ</code> where <code>XYZ</code> is the current default version of GHC in nixpkgs. However you can use a different version by replacing <code>haskellPackages</code> with the wanted package, for instance use <code>haskell.compiler.ghc884</code> to use GHC 8.8.4. You can get the full list of available GHC versions using:

$ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler

haskell.compiler.ghc8107 ghc-8.10.7

Line 31:

Line 17:

…

</syntaxhighlight>

}}

=== Scripting ===

For ~~simple~~ scripts, you can ~~directly~~ use nix-shell ~~to get a redistributable Haskell script that you can run on any Nix system with <code>./my-script~~.~~hs</code>:~~

For redistributable Haskell scripts on any Nix system, you can use a nix-shell shebang.

<~~pre~~>

<syntaxhighlight lang="haskell">#!/usr/bin/env nix-shell

#!/usr/bin/env nix-shell

#! nix-shell --pure -i runghc -p "ghc.withPackages (pkgs: [ pkgs.turtle ])"

#!nix-shell --pure -i runghc -p "~~haskellPackages~~.~~ghcWithPackages~~ (pkgs: [ pkgs.turtle ])"

{-# LANGUAGE OverloadedStrings #-}

import Turtle

main = do

-- do stuff

echo "Hello world from a distributable Haskell script!"</syntaxhighlight>

To remove the additional latency overhead of a nix-shell, add GHC to <code>environment.systemPackages</code> and call <code>runghc</code> in the shebang.<syntaxhighlight lang="nix">

environment.systemPackages = with pkgs; [

...

(ghc.withPackages (hsPkgs: with hsPkgs; [

turtle # Faster startup time with all external shell commands

shh # Piping operators and other goodies

shh-extras # Try shh as an interactive shell

... # ...anything else you want!

])

];

</syntaxhighlight>Here's a basic example using the Shh module rather than Turtle, so it can use the pipe operator:<syntaxhighlight lang="haskell">

#!/usr/bin/env runghc

{-# LANGUAGE TemplateHaskell #-}

{-# LANGUAGE ExtendedDefaultRules #-}

{-# LANGUAGE OverloadedStrings #-}

import Shh

-- $(loadEnv SearchPath) -- Loads entire PATH, may be slow

load SearchPath [ "dd", "sha512sum" ]

main = do

~~# do stuff~~

dd "if=/dev/urandom" "bs=4K" "count=1" |> sha512sum

~~putStrLn~~ "~~Hello world from a distributable Haskell script!~~"

</syntaxhighlight>To write inline Haskell scripts in nix-code, refer to [[Nix-writers#Haskell]].

</~~pre~~>

Read ~~below~~ if some packages are broken.

Read [[#Overrides]] if some packages are broken.

=== Directly using cabal (no nix caching/reproducibility) ===

~~Note that~~ cabal is the basic Haskell tool used to configure builds and is internally used by all the Haskell's packaging methods (including stack and nix). If one does not care about the reproducibility/caching offered by nix, it is always possible to use cabal like in a normal system:

<~~pre~~>

[https://www.haskell.org/cabal/ Cabal] is the basic Haskell tool used to configure builds and is internally used by all the Haskell's packaging methods (including stack and nix). If one does not care about the reproducibility/caching offered by nix, it is always possible to use cabal like in a normal system:

$ nix-shell -p "~~haskellPackages~~.~~ghcWithPackages~~ (pkgs: ~~with~~ pkgs~~; [~~ cabal-install ])"

$ nix-shell -p "ghc.withPackages (pkgs: [ pkgs.cabal-install ])"

$ cabal init

…

Line 55:

Line 67:

Up to date

Hello, Haskell!

</~~pre~~>

</syntaxhighlight>

~~Notes:~~

{{note|Some packages may need additional libraries/programs, notably <code>zlib</code>, you should be able to add them as additional programs in the nix-shell option.}}

* some packages may need additional libraries/programs, notably <code>zlib</code>, you should be able to add them as additional programs in the nix-shell option

{{note|Since Cabal 2.0, cabal has acquired caching similar to nix (but not as powerful) and reproducibility (via the cabal.project file and the index-state option). See [https://cabal.readthedocs.io/en/latest/cabal-project-description-file.html#cfg-field-index-state] for more information.}}

* since Cabal 2.0, cabal has acquired caching similar to nix (but not as powerful) and reproducibility (via the cabal.project file and the index-state option). See [https://cabal.readthedocs.io/en/~~stable~~/cabal-project.html#cfg-field-index-state] for more information.

=== Using Stack (no nix caching) ===

Similarly you can use ~~stack~~ that let you find the appropriate version of the libraries for you if you do not want the caching offered by nix (stack will build all the dependencies):

Similarly you can use [https://docs.haskellstack.org/en/stable/ Stack] that let you find the appropriate version of the libraries for you if you do not want the caching offered by nix (stack will build all the dependencies):

<~~pre~~>

$ nix-shell -p "~~haskellPackages~~.~~ghcWithPackages~~ (pkgs: ~~with~~ pkgs~~; [~~ stack ])"

$ nix-shell -p "ghc.withPackages (pkgs: [ pkgs.stack ])"

$ stack new my-project

$ cd my-project

$ stack build

$ stack exec my-project-exe

</~~pre~~>

</syntaxhighlight>

You can also use the features offered by stack to enable nix integration in order to use nix to install the non-haskell dependencies. You can read more [https://docs.haskellstack.org/en/stable/nix_integration/ here].

You can also use the features offered by stack to enable nix integration in order to use nix to install the non-haskell dependencies. You can read more [https://docs.haskellstack.org/en/stable/topics/nix_integration/ here].

If you want to package your program using stack in nix, you can actually use <code>haskell.lib.buildStackProject</code> that is a wrapper around <code>stdenv.mkDerivation</code> that will [https://github.com/NixOS/nixpkgs/blob/350fd0044447ae8712392c6b212a18bdf2433e71/pkgs/development/haskell-modules/generic-stack-builder.nix#L56 call <code>stack build</code> for you]… However because stack needs to download stuff you need to disable the sandbox using <code>nix-build --option sandbox false</code>. For instance if you want to compile a stack project that needs R, zeromq and zlib you can put the following into <code>default.nix</code>:

Line 83:

Line 94:

}

</syntaxhighlight>

{{note|For users of a stable version of NixOS there could be a problem where Stack tries to use a GHC version that is not yet in the given channel of Nixpkgs. Example at the time of writing: When using NixOS 23.05, Stack defaults to using the LTS-21.10 resolver, which uses <code>ghc-9.4.6</code>. However, the newest version of GHC in the 23.05 channel is <code>ghc-9.4.4</code>, thus Stack fails to execute some commands.<br/>

As a solution, [https://docs.haskellstack.org/en/stable/yaml_configuration/#resolver-or-snapshot specify a resolver in your <code>stack.yaml</code>] file that uses a GHC version available for your channel. You can find a list of snapshots on https://www.stackage.org/snapshots. Or alternatively, set the resolver as a command line argument, which is required for running commands such as <code>stack new</code>.}}

=== Using developPackage (use the nix packages set for haskell) ===

You can use ~~also~~ nix in place of stack to keep track of the dependencies in a reproducible way (note that while stack uses a solver to find a working set of dependencies, nix uses a fixed set of packages). Additionally you can benefit from the caching system offered by Nix. To that end, first create a cabal repository (nix also uses cabal internally):

You can also use nix in place of stack to keep track of the dependencies in a reproducible way (note that while stack uses a solver to find a working set of dependencies, nix uses a fixed set of packages). Additionally you can benefit from the caching system offered by Nix. To that end, first create a cabal repository (nix also uses cabal internally):

$ nix-shell -p "~~haskellPackages~~.~~ghcWithPackages~~ (pkgs: ~~with~~ pkgs~~; [~~ cabal-install ])" --run "cabal init"

$ nix-shell -p "ghc.withPackages (pkgs: [ pkgs.cabal-install ])" --run "cabal init"

…

</syntaxhighlight>

Line 105:

Line 119:

Then you can build and run the program using:

<~~pre~~>

$ nix-build

$ ./result/bin/yourprogram

</~~pre~~>

</syntaxhighlight>

or run a nix-shell to use the standard development tools provided by cabal:

<~~pre~~>

$ nix-~~build~~

$ nix-shell

$ ~~./result/bin/yourprogram~~

$ cabal run

</~~pre~~>

</syntaxhighlight>

Nix will automatically read the <code>build-depends</code> field in the <code>*.cabal</code> file to get the name of the dependencies and use the haskell packages provided in the configured package set provided by nix. Note that some of the packages present in the nix repository are broken (for instance because a package requires an older version of a library while nix only provides a recent version). For this reason it may be necessary to override some packages present in the nix package set as described below using the <code>overrides</code> and <code>source-overrides</code> attribute. Note that the <code>source-overrides</code> attribute can also turn out to be useful to load local libraries:

Line 147:

Line 161:

You can also get more details ~~in [https://srid.ca/haskell-nix this tutorial] or~~ in [https://github.com/NixOS/nixpkgs/blob/0ba44a03f620806a2558a699dba143e6cf9858db/pkgs/development/haskell-modules/make-package-set.nix#L230 pkgs/development/haskell-modules/make-package-set.nix].

You can also get more details in [https://github.com/NixOS/nixpkgs/blob/0ba44a03f620806a2558a699dba143e6cf9858db/pkgs/development/haskell-modules/make-package-set.nix#L230 pkgs/development/haskell-modules/make-package-set.nix].

=== Using shellFor (multiple packages) ===

~~<code>~~shellFor~~</code>~~ is similar to <code>developPackage</code> but (slightly) more complicated to also allow you to develop multiples packages at the same time (~~similar to <code>~~cabal.project~~</code>~~). Note that contrary to <code>developPackage</code> I don't think that <code>shellFor</code> can output a derivation.

[https://nixos.org/manual/nixpkgs/stable/#haskell-shellFor shellFor] is similar to <code>developPackage</code> but (slightly) more complicated to also allow you to develop multiples packages at the same time (it can work in conjuction with [https://cabal.readthedocs.io/en/stable/cabal-project-description-file.html cabal.project]). Note that contrary to <code>developPackage</code> I don't think that <code>shellFor</code> can output a derivation.

The idea is to first extend/override the set of haskell packages in order to add your projects as additional haskell packages (for instance using <code>haskellPackages.extend</code> and <code>packageSourceOverrides</code> that just need a the path of the project to compile it), and then to use `haskellPackages.shellFor {packages= p: [p.myproject1 p.myproject2]}` to create a shell with all wanted packages.

The idea is to first extend/override the set of haskell packages in order to add your projects as additional haskell packages (for instance using <code>haskellPackages.extend</code> and <code>packageSourceOverrides</code> that just need the path of the project to compile it), and then to use <code>haskellPackages.shellFor {packages= p: [p.myproject1 p.myproject2]}</code> to create a shell with all wanted packages.

For instance you can define your various projects in subfolders <code>./frontend</code> and <code>./backend</code> (you can use cabal init to create the content in each folder), then create a file <code>cabal.project</code> containing:

<~~syntaxhighlight~~>

{{file|cabal.project|nix|

packages:

frontend/

backend/

</~~syntaxhighlight~~>

</nowiki>

}}

Finally ~~create~~ a ~~file~~ <code>shell.nix</code> containing:

Finally you define a nix shell in <code>shell.nix</code> containing:

<~~syntaxhighlight lang="nix"~~>

{{file|shell.nix|nix|

with import <nixpkgs> {};

with import </nowiki><<nowiki>nixpkgs</nowiki>><nowiki> {};

# We add our packages to the haskell package set

(haskellPackages.extend (haskell.lib.compose.packageSourceOverrides {

Line 178:

Line 195:

buildInputs = [ pkgs.python pkgs.cabal-install ];

}

</~~syntaxhighlight~~>

</nowiki>

}}

then you can use cabal to develop incrementally your projects using for instance:

$ nix-shell

$ cabal ~~new-~~build all

$ cabal build all

</syntaxhighlight>

If you want to be able to compile a project non-incrementally with <code>nix-build</code> (say the backend in the above example) you can put in <code>default.nix</code>:

<~~syntaxhighlight lang="nix"~~>

with import <nixpkgs> {};

{{file|default.nix|nix|

with import </nowiki><<nowiki>nixpkgs</nowiki>><nowiki> {};

# We add our packages to the haskell package set

(haskellPackages.extend (haskell.lib.compose.packageSourceOverrides {

Line 195:

Line 215:

backend = ./backend;

})).backend

</~~syntaxhighlight~~>

</nowiki>

}}

or if you want to create a single derivation file, you can use <code>if pkgs.lib.inNixShell then … else …</code> to output the shell when we start a shell and the packages when we want to build them. You can find [https://github.com/kowainik/summoner/blob/60de4f2f087e5bd2beaad9253e7eded731cfbaaf/default.nix here] an example.

Line 204:

Line 226:

=== Using haskell-flake (flake-parts) ===

[https://~~haskell~~.flake.~~page~~/ haskell-flake] aims to simplify writing Nix for Haskell development through use of flake-parts module system. It uses <code>callCabal2nix</code> and <code>shellFor</code> under the hood while exposing friendly module options API.

[https://community.flake.parts/haskell-flake haskell-flake] is a project that aims to simplify writing Nix for Haskell development through use of [[Flake Parts|flake-parts module system]]. It uses <code>callCabal2nix</code> and <code>shellFor</code> under the hood while exposing friendly module options API. For an overview of Flakes, see the [[Flakes]] wiki page.

* For existing Haskell projects, initialize with:

nix flake init -t github:srid/haskell-flake

</syntaxhighlight>

* For new Haskell projects, use the example template:

mkdir example && cd ./example

nix flake init -t github:srid/haskell-flake#example

</syntaxhighlight>

This command will generate a project template with additional configuration details, comments, and examples. Below is an example minimal flake definition for a simple project:

{{file|flake.nix|nix|

{

inputs = {

nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";

flake-parts.url = "github:hercules-ci/flake-parts";

haskell-flake.url = "github:srid/haskell-flake";

};

outputs = inputs@{ self, nixpkgs, flake-parts, ... }:

flake-parts.lib.mkFlake { inherit inputs; } {

systems = nixpkgs.lib.systems.flakeExposed;

imports = [ inputs.haskell-flake.flakeModule ];

perSystem = { self', pkgs, ... }: {

haskellProjects.default = {

# Project configurations such as GHC version and package overrides are defined here

# See: https://flake.parts/options/haskell-flake

};

# haskell-flake doesn't set the default package, but you can do it here.

packages.default = self'.packages.example;

};

}

</nowiki>

}}

Once configured, you can build and run the project with:

$ nix build # Build the project; the binary will be placed in ./result/bin

$ ./result/bin/example

$ nix run # Alternatively, run the default executable directly

</syntaxhighlight>

or enter a development shell to use the standard development tools provided by the flake:

$ nix develop

$ cabal run

</syntaxhighlight>

The build process will use the <code>example.cabal</code> file and run the executable defined within it. A current limitation is that if your Cabal file contains multiple <code>executable</code> blocks, you can only assign one as the default package. This limitation also applies when using a <code>cabal.project</code>. To run a specific executable by name, use the following command <code>nix run .#another-example</code>. Below is an example cabal file defining two executables:

{{file|example.cabal|haskell|

executable example

main-is: Main.hs

...

executable another-example

main-is: AnotherMain.hs

...

</nowiki>

}}

==== Further reading ====

* [https://github.com/srid/haskell-template/tree/master Example Haskell project with a development environment]

* [https://github.com/srid/haskell-multi-nix/tree/master Example cabal.project multi-package Haskell project]

* [https://community.flake.parts/haskell-flake/start Getting started with haskell-flake].

* [https://community.flake.parts/haskell-flake/dependency Overriding dependencies in a haskell-flake]

* [https://flake.parts/options/haskell-flake haskell-flake haskell-flake options reference]

== Overrides ==

Line 299:

Line 403:

== Limitations ==

~~When using the <code>~~cabal2nix</code> tool, Nix does not pull a cabal package by respecting the constraint specified in the cabal file (see [https://github.com/chrissound/Cabal2NixLimitationExample example]). Issue is discussed [https://stackoverflow.com/questions/57441156/pulling-in-specific-haskell-packages-cabal-dependencies-with-nix here]. You should be using `callCabal2nix` anyway.

=== cabal2nix ===

~~== IFD and Haskell ==~~

When using the <code>cabal2nix</code> tool, Nix does not pull a cabal package by respecting the constraint specified in the cabal file (see [https://github.com/chrissound/Cabal2NixLimitationExample example]). Issue is discussed [https://stackoverflow.com/questions/57441156/pulling-in-specific-haskell-packages-cabal-dependencies-with-nix here]. You should be using <code>callCabal2nix</code> anyway.

<code>callCabal2nix</code>, which is implicitly used for building Haskell projects, uses IFD.[https://github.com/NixOS/templates/issues/28][https://discourse.nixos.org/t/another-simple-flake-for-haskell-development/18164/6]. This means that since IFD is disabled by default in certain nix commands,[https://github.com/NixOS/nix/pull/5253] the following commands will be broken for Haskell projects whose flake output specifies multiple system attributes:

=== IFD and Haskell ===

<code>callCabal2nix</code>, which is implicitly used for building Haskell projects, uses IFD. Refer to this [https://github.com/NixOS/templates/issues/28 github issue] and [https://discourse.nixos.org/t/another-simple-flake-for-haskell-development/18164/6 discourse thread] for additional context. This means that since IFD is disabled by default in certain nix commands,[https://github.com/NixOS/nix/pull/5253] the following commands will be broken for Haskell projects whose flake output specifies multiple system attributes:

* <code>nix flake show</code>

* <code>nix flake check</code>

=== GHCup ===

[https://www.haskell.org/ghcup/ GHCup] does not work properly on NixOS out of the box. NixOS cannot run dynamically linked executables built for generic Linux environments due to its runtime linker setup. For details and a workaround, see [https://nix.dev/guides/faq#how-to-run-non-nix-executables nix.dev's explanation of stub-ld].

In most cases there is little reason to use GHCup when working within a Nix-based system, as Nixpkgs can achieve the same goals such as managing multiple GHC versions and other Haskell tooling.

== FAQ and resources ==

* '''Official Docs:''' [https://nixos.org/manual/nixpkgs/unstable/#haskell '''The Haskell section in the nixpkgs manual''']

* [https://nixos.asia/en/nixify-haskell-nixpkgs '''Nixifying a Haskell project using nixpkgs'''] explains how to use Nix to package and develop Haskell projects using nothing but nixpkgs.

* [https://github.com/mhwombat/nix-for-numbskulls/blob/78bcc186f79931c0e4a1e445e2f6b1f12f6d46be/Haskell/ss-haskell-dev.md '''Super-Simple Haskell Development with Nix'''] (and [https://discourse.nixos.org/t/super-simple-haskell-development-with-nix/14287/2 discussion] that provides interesting alternative methods together with there pro and cons)

* [https://discourse.nixos.org/t/nix-haskell-development-2020/6170 '''Nix Haskell Development (2020)''']

* [https://discourse.nixos.org/t/haskellpackages-stm-containers-fails-to-build/5416/4 '''How are Haskell packages managed in nixpkgs?''']

* [https://www.youtube.com/watch?v=KLhkAEk8I20 '''How to fix broken Haskell packages?''' (video)]

[[Category:Languages]]

[[Category:~~Applications~~]]

[[Category:Haskell]]

@@ Line 1: / Line 1: @@
-== FAQ and resources ==
+[https://www.haskell.org/ Haskell] is a statically-typed, purely functional programming language with strong support for type inference and lazy evaluation.
-* '''Official Docs:''' [https://nixos.org/manual/nixpkgs/unstable/#haskell '''The Haskell section in the nixpkgs manual''']
-* [https://www.srid.ca/haskell-nix '''Nix recipes for Haskellers'''] aims to get a beginner comfortable managing simple Haskell programs and projects using Nix.
-* [https://github.com/mhwombat/nix-for-numbskulls/blob/78bcc186f79931c0e4a1e445e2f6b1f12f6d46be/Haskell/ss-haskell-dev.md '''Super-Simple Haskell Development with Nix'''] (and [https://discourse.nixos.org/t/super-simple-haskell-development-with-nix/14287/2 discussion] that provides interesting alternative methods together with there pro and cons)
+For detailed information on Haskell support in Nixpkgs, refer to the official {{Nixpkgs Manual|name=Nixpkgs Manual: Chapter - Haskell|anchor=#haskell}}.
-* [https://discourse.nixos.org/t/nix-haskell-development-2020/6170 '''Nix Haskell Development (2020)''']
-* [https://discourse.nixos.org/t/haskellpackages-stm-containers-fails-to-build/5416/4?u=srid '''How are Haskell packages managed in nixpkgs?''']
-* [https://www.youtube.com/watch?v=KLhkAEk8I20 '''How to fix broken Haskell packages?''' (video)]
 == How to develop with Haskell and Nix ==
-There are multiples ways to develop in Haskell on Nix depending on the simplicity of the project and on whether one want to benefit from the reproducibility offered by nix or not. Below is an image to help you in your choice:
+{{Note|{{nixos:package|haskellPackages}} is a synonym of <code>haskell.packages.ghcXYZ</code> where <code>XYZ</code> is the current default version of GHC in nixpkgs. However you can use a different version by replacing <code>haskellPackages</code> with the wanted package, for instance use <code>haskell.compiler.ghc884</code> to use GHC 8.8.4. You can get the full list of available GHC versions using:
-[[File:haskell_choice.png]]
+<syntaxhighlight lang="console">
-Note that in the following, <code>haskellPackages</code> is a synonym of <code>haskell.packages.ghcXYZ</code> where <code>XYZ</code> is the current default version of GHC in nixpkgs. However you can use a different version by replacing <code>haskellPackages</code> with the wanted package, for instance use <code>haskell.compiler.ghc884</code> to use GHC 8.8.4. You can get the full list of available GHC versions using:
-<syntaxhighlight lang="bash">
 $ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler
 haskell.compiler.ghc8107                 ghc-8.10.7
@@ Line 31: / Line 17: @@
 …
 </syntaxhighlight>
+}}
 === Scripting ===
-For simple scripts, you can directly use nix-shell to get a redistributable Haskell script that you can run on any Nix system with <code>./my-script.hs</code>:
+For redistributable Haskell scripts on any Nix system, you can use a nix-shell shebang.
-<pre>
+<syntaxhighlight lang="haskell">#!/usr/bin/env nix-shell
-#!/usr/bin/env nix-shell
+#!  nix-shell --pure -i runghc -p "ghc.withPackages (pkgs: [ pkgs.turtle ])"
-#!nix-shell --pure -i runghc -p "haskellPackages.ghcWithPackages (pkgs: [ pkgs.turtle ])"
+{-# LANGUAGE OverloadedStrings #-}
+import Turtle
+main = do
+  -- do stuff
+  echo "Hello world from a distributable Haskell script!"</syntaxhighlight>
+To remove the additional latency overhead of a nix-shell, add GHC to <code>environment.systemPackages</code> and call <code>runghc</code> in the shebang.<syntaxhighlight lang="nix">
+  environment.systemPackages = with pkgs; [
+    ...
+    (ghc.withPackages (hsPkgs: with hsPkgs; [
+      turtle      # Faster startup time with all external shell commands
+      shh         # Piping operators and other goodies
+      shh-extras  # Try shh as an interactive shell
+      ...         # ...anything else you want!
+    ])
+  ];
+</syntaxhighlight>Here's a basic example using the Shh module rather than Turtle, so it can use the pipe operator:<syntaxhighlight lang="haskell">
+#!/usr/bin/env runghc
+{-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE ExtendedDefaultRules #-}
+{-# LANGUAGE OverloadedStrings #-}
+import Shh
+-- $(loadEnv SearchPath) -- Loads entire PATH, may be slow
+load SearchPath [ "dd", "sha512sum" ]
 main = do
-   # do stuff
+   dd "if=/dev/urandom" "bs=4K" "count=1" |> sha512sum
-  putStrLn "Hello world from a distributable Haskell script!"
+</syntaxhighlight>To write inline Haskell scripts in nix-code, refer to [[Nix-writers#Haskell]].
-</pre>
-Read below if some packages are broken.
+Read [[#Overrides]] if some packages are broken.
 === Directly using cabal (no nix caching/reproducibility) ===
-Note that cabal is the basic Haskell tool used to configure builds and is internally used by all the Haskell's packaging methods (including stack and nix). If one does not care about the reproducibility/caching offered by nix, it is always possible to use cabal like in a normal system:
-<pre>
+[https://www.haskell.org/cabal/ Cabal] is the basic Haskell tool used to configure builds and is internally used by all the Haskell's packaging methods (including stack and nix). If one does not care about the reproducibility/caching offered by nix, it is always possible to use cabal like in a normal system:
-$  nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [ cabal-install ])"
+<syntaxhighlight lang="console">
+$  nix-shell -p "ghc.withPackages (pkgs: [ pkgs.cabal-install ])"
 $ cabal init
 …
@@ Line 55: / Line 67: @@
 Up to date
 Hello, Haskell!
-</pre>
+</syntaxhighlight>
-Notes:
+{{note|Some packages may need additional libraries/programs, notably <code>zlib</code>, you should be able to add them as additional programs in the nix-shell option.}}
-* some packages may need additional libraries/programs, notably <code>zlib</code>, you should be able to add them as additional programs in the nix-shell option
+{{note|Since Cabal 2.0, cabal has acquired caching similar to nix (but not as powerful) and reproducibility (via the cabal.project file and the index-state option). See [https://cabal.readthedocs.io/en/latest/cabal-project-description-file.html#cfg-field-index-state] for more information.}}
-* since Cabal 2.0, cabal has acquired caching similar to nix (but not as powerful) and reproducibility (via the cabal.project file and the index-state option). See [https://cabal.readthedocs.io/en/stable/cabal-project.html#cfg-field-index-state] for more information.
 === Using Stack (no nix caching) ===
-Similarly you can use stack that let you find the appropriate version of the libraries for you if you do not want the caching offered by nix (stack will build all the dependencies):
+Similarly you can use [https://docs.haskellstack.org/en/stable/ Stack] that let you find the appropriate version of the libraries for you if you do not want the caching offered by nix (stack will build all the dependencies):
-<pre>
+<syntaxhighlight lang="console">
-$ nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [ stack ])"
+$ nix-shell -p "ghc.withPackages (pkgs: [ pkgs.stack ])"
 $ stack new my-project
 $ cd my-project
 $ stack build
 $ stack exec my-project-exe
-</pre>
+</syntaxhighlight>
-You can also use the features offered by stack to enable nix integration in order to use nix to install the non-haskell dependencies. You can read more [https://docs.haskellstack.org/en/stable/nix_integration/ here].
+You can also use the features offered by stack to enable nix integration in order to use nix to install the non-haskell dependencies. You can read more [https://docs.haskellstack.org/en/stable/topics/nix_integration/ here].
 If you want to package your program using stack in nix, you can actually use <code>haskell.lib.buildStackProject</code> that is a wrapper around <code>stdenv.mkDerivation</code> that will [https://github.com/NixOS/nixpkgs/blob/350fd0044447ae8712392c6b212a18bdf2433e71/pkgs/development/haskell-modules/generic-stack-builder.nix#L56 call <code>stack build</code> for you]… However because stack needs to download stuff you need to disable the sandbox using <code>nix-build --option sandbox false</code>. For instance if you want to compile a stack project that needs R, zeromq and zlib you can put the following into <code>default.nix</code>:
@@ Line 83: / Line 94: @@
 }
 </syntaxhighlight>
+{{note|For users of a stable version of NixOS there could be a problem where Stack tries to use a GHC version that is not yet in the given channel of Nixpkgs. Example at the time of writing: When using NixOS 23.05, Stack defaults to using the LTS-21.10 resolver, which uses <code>ghc-9.4.6</code>. However, the newest version of GHC in the 23.05 channel is <code>ghc-9.4.4</code>, thus Stack fails to execute some commands.<br/>
+As a solution, [https://docs.haskellstack.org/en/stable/yaml_configuration/#resolver-or-snapshot specify a resolver in your <code>stack.yaml</code>] file that uses a GHC version available for your channel. You can find a list of snapshots on https://www.stackage.org/snapshots. Or alternatively, set the resolver as a command line argument, which is required for running commands such as <code>stack new</code>.}}
 ===  Using developPackage (use the nix packages set for haskell) ===
-You can use also nix in place of stack to keep track of the dependencies in a reproducible way (note that while stack uses a solver to find a working set of dependencies, nix uses a fixed set of packages). Additionally you can benefit from the caching system offered by Nix. To that end, first create a cabal repository (nix also uses cabal internally):
+You can also use nix in place of stack to keep track of the dependencies in a reproducible way (note that while stack uses a solver to find a working set of dependencies, nix uses a fixed set of packages). Additionally you can benefit from the caching system offered by Nix. To that end, first create a cabal repository (nix also uses cabal internally):
-<syntaxhighlight lang="nix">
+<syntaxhighlight lang="console">
-$ nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [ cabal-install ])" --run "cabal init"
+$ nix-shell -p "ghc.withPackages (pkgs: [ pkgs.cabal-install ])" --run "cabal init"
 …
 </syntaxhighlight>
@@ Line 105: / Line 119: @@
 Then you can build and run the program using:
-<pre>
+<syntaxhighlight lang="console">
 $ nix-build
 $ ./result/bin/yourprogram
-</pre>
+</syntaxhighlight>
 or run a nix-shell to use the standard development tools provided by cabal:
-<pre>
+<syntaxhighlight lang="console">
-$ nix-build
+$ nix-shell
-$ ./result/bin/yourprogram
+$ cabal run
-</pre>
+</syntaxhighlight>
 Nix will automatically read the <code>build-depends</code> field in the <code>*.cabal</code> file to get the name of the dependencies and use the haskell packages provided in the configured package set provided by nix. Note that some of the packages present in the nix repository are broken (for instance because a package requires an older version of a library while nix only provides a recent version). For this reason it may be necessary to override some packages present in the nix package set as described below using the <code>overrides</code> and <code>source-overrides</code> attribute. Note that the <code>source-overrides</code> attribute can also turn out to be useful to load local libraries:
@@ Line 147: / Line 161: @@
-You can also get more details in [https://srid.ca/haskell-nix this tutorial] or in [https://github.com/NixOS/nixpkgs/blob/0ba44a03f620806a2558a699dba143e6cf9858db/pkgs/development/haskell-modules/make-package-set.nix#L230 pkgs/development/haskell-modules/make-package-set.nix].
+You can also get more details in [https://github.com/NixOS/nixpkgs/blob/0ba44a03f620806a2558a699dba143e6cf9858db/pkgs/development/haskell-modules/make-package-set.nix#L230 pkgs/development/haskell-modules/make-package-set.nix].
 ===  Using shellFor (multiple packages) ===
-<code>shellFor</code> is similar to <code>developPackage</code> but (slightly) more complicated to also allow you to develop multiples packages at the same time (similar to <code>cabal.project</code>). Note that contrary to <code>developPackage</code> I don't think that <code>shellFor</code> can output a derivation.
+[https://nixos.org/manual/nixpkgs/stable/#haskell-shellFor shellFor] is similar to <code>developPackage</code> but (slightly) more complicated to also allow you to develop multiples packages at the same time (it can work in conjuction with [https://cabal.readthedocs.io/en/stable/cabal-project-description-file.html cabal.project]). Note that contrary to <code>developPackage</code> I don't think that <code>shellFor</code> can output a derivation.
-The idea is to first extend/override the set of haskell packages in order to add your projects as additional haskell packages (for instance using <code>haskellPackages.extend</code> and <code>packageSourceOverrides</code> that just need a the path of the project to compile it), and then to use `haskellPackages.shellFor {packages= p: [p.myproject1 p.myproject2]}` to create a shell with all wanted packages.
+The idea is to first extend/override the set of haskell packages in order to add your projects as additional haskell packages (for instance using <code>haskellPackages.extend</code> and <code>packageSourceOverrides</code> that just need the path of the project to compile it), and then to use <code>haskellPackages.shellFor {packages= p: [p.myproject1 p.myproject2]}</code> to create a shell with all wanted packages.
 For instance you can define your various projects in subfolders <code>./frontend</code> and <code>./backend</code> (you can use cabal init to create the content in each folder), then create a file <code>cabal.project</code> containing:
-<syntaxhighlight>
+{{file|cabal.project|nix|
+<nowiki>
 packages:
    frontend/
    backend/
-</syntaxhighlight>
+</nowiki>
+}}
-Finally create a file <code>shell.nix</code> containing:
+Finally you define a nix shell in <code>shell.nix</code> containing:
-<syntaxhighlight lang="nix">
+{{file|shell.nix|nix|
-with import <nixpkgs> {};
+<nowiki>
+with import </nowiki><<nowiki>nixpkgs</nowiki>><nowiki> {};
 # We add our packages to the haskell package set
 (haskellPackages.extend (haskell.lib.compose.packageSourceOverrides {
@@ Line 178: / Line 195: @@
      buildInputs = [ pkgs.python pkgs.cabal-install ];
    }
-</syntaxhighlight>
+</nowiki>
+}}
 then you can use cabal to develop incrementally your projects using for instance:
-<syntaxhighlight lang="bash">
+<syntaxhighlight lang="console">
 $ nix-shell
-$ cabal new-build all
+$ cabal build all
 </syntaxhighlight>
 If you want to be able to compile a project non-incrementally with <code>nix-build</code> (say the backend in the above example) you can put in <code>default.nix</code>:
-<syntaxhighlight lang="nix">
-with import <nixpkgs> {};
+{{file|default.nix|nix|
+<nowiki>
+with import </nowiki><<nowiki>nixpkgs</nowiki>><nowiki> {};
 # We add our packages to the haskell package set
 (haskellPackages.extend (haskell.lib.compose.packageSourceOverrides {
@@ Line 195: / Line 215: @@
    backend = ./backend;
 })).backend
-</syntaxhighlight>
+</nowiki>
+}}
 or if you want to create a single derivation file, you can use <code>if pkgs.lib.inNixShell then … else …</code> to output the shell when we start a shell and the packages when we want to build them. You can find [https://github.com/kowainik/summoner/blob/60de4f2f087e5bd2beaad9253e7eded731cfbaaf/default.nix here] an example.
@@ Line 204: / Line 226: @@
 === Using haskell-flake (flake-parts) ===
-[https://haskell.flake.page/ haskell-flake] aims to simplify writing Nix for Haskell development through use of flake-parts module system. It uses <code>callCabal2nix</code> and <code>shellFor</code> under the hood while exposing friendly module options API.
+[https://community.flake.parts/haskell-flake haskell-flake] is a project that aims to simplify writing Nix for Haskell development through use of [[Flake Parts|flake-parts module system]]. It uses <code>callCabal2nix</code> and <code>shellFor</code> under the hood while exposing friendly module options API. For an overview of Flakes, see the [[Flakes]] wiki page.
+* For existing Haskell projects, initialize with:
+<syntaxhighlight lang="bash">
+nix flake init -t github:srid/haskell-flake
+</syntaxhighlight>
+* For new Haskell projects, use the example template:
+<syntaxhighlight lang="bash">
+mkdir example && cd ./example
+nix flake init -t github:srid/haskell-flake#example
+</syntaxhighlight>
+This command will generate a project template with additional configuration details, comments, and examples. Below is an example minimal flake definition for a simple project:
+{{file|flake.nix|nix|
+<nowiki>
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    haskell-flake.url = "github:srid/haskell-flake";
+  };
+  outputs = inputs@{ self, nixpkgs, flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = nixpkgs.lib.systems.flakeExposed;
+      imports = [ inputs.haskell-flake.flakeModule ];
+      perSystem = { self', pkgs, ... }: {
+        haskellProjects.default = {
+          # Project configurations such as GHC version and package overrides are defined here
+          # See: https://flake.parts/options/haskell-flake
+        };
+        # haskell-flake doesn't set the default package, but you can do it here.
+        packages.default = self'.packages.example;
+      };
+    };
+}
+</nowiki>
+}}
+Once configured, you can build and run the project with:
+<syntaxhighlight lang="console">
+$ nix build # Build the project; the binary will be placed in ./result/bin
+$ ./result/bin/example
+$ nix run # Alternatively, run the default executable directly
+</syntaxhighlight>
+or enter a development shell to use the standard development tools provided by the flake:
+<syntaxhighlight lang="console">
+$ nix develop
+$ cabal run
+</syntaxhighlight>
+The build process will use the <code>example.cabal</code> file and run the executable defined within it. A current limitation is that if your Cabal file contains multiple <code>executable</code> blocks, you can only assign one as the default package. This limitation also applies when using a <code>cabal.project</code>. To run a specific executable by name, use the following command <code>nix run .#another-example</code>. Below is an example cabal file defining two executables:
+{{file|example.cabal|haskell|
+<nowiki>
+executable example
+    main-is: Main.hs
+    ...
+executable another-example
+    main-is: AnotherMain.hs
+    ...
+</nowiki>
+}}
+==== Further reading ====
+* [https://github.com/srid/haskell-template/tree/master Example Haskell project with a development environment]
+* [https://github.com/srid/haskell-multi-nix/tree/master Example cabal.project multi-package Haskell project]
+* [https://community.flake.parts/haskell-flake/start Getting started with haskell-flake].
+* [https://community.flake.parts/haskell-flake/dependency Overriding dependencies in a haskell-flake]
+* [https://flake.parts/options/haskell-flake haskell-flake haskell-flake options reference]
 == Overrides ==
@@ Line 299: / Line 403: @@
 == Limitations ==
-When using the <code>cabal2nix</code> tool, Nix does not pull a cabal package by respecting the constraint specified in the cabal file (see [https://github.com/chrissound/Cabal2NixLimitationExample example]). Issue is discussed [https://stackoverflow.com/questions/57441156/pulling-in-specific-haskell-packages-cabal-dependencies-with-nix here]. You should be using `callCabal2nix` anyway.
+=== cabal2nix ===
-== IFD and Haskell ==
+When using the <code>cabal2nix</code> tool, Nix does not pull a cabal package by respecting the constraint specified in the cabal file (see [https://github.com/chrissound/Cabal2NixLimitationExample example]). Issue is discussed [https://stackoverflow.com/questions/57441156/pulling-in-specific-haskell-packages-cabal-dependencies-with-nix here]. You should be using <code>callCabal2nix</code> anyway.
-<code>callCabal2nix</code>, which is implicitly used for building Haskell projects, uses IFD.[https://github.com/NixOS/templates/issues/28][https://discourse.nixos.org/t/another-simple-flake-for-haskell-development/18164/6]. This means that since IFD is disabled by default in certain nix commands,[https://github.com/NixOS/nix/pull/5253] the following commands will be broken for Haskell projects whose flake output specifies multiple system attributes:
+=== IFD and Haskell ===
+<code>callCabal2nix</code>, which is implicitly used for building Haskell projects, uses IFD. Refer to this [https://github.com/NixOS/templates/issues/28 github issue] and [https://discourse.nixos.org/t/another-simple-flake-for-haskell-development/18164/6 discourse thread] for additional context. This means that since IFD is disabled by default in certain nix commands,[https://github.com/NixOS/nix/pull/5253] the following commands will be broken for Haskell projects whose flake output specifies multiple system attributes:
 * <code>nix flake show</code>
 * <code>nix flake check</code>
+=== GHCup ===
+[https://www.haskell.org/ghcup/ GHCup] does not work properly on NixOS out of the box. NixOS cannot run dynamically linked executables built for generic Linux environments due to its runtime linker setup. For details and a workaround, see [https://nix.dev/guides/faq#how-to-run-non-nix-executables nix.dev's explanation of stub-ld].
+In most cases there is little reason to use GHCup when working within a Nix-based system, as Nixpkgs can achieve the same goals such as managing multiple GHC versions and other Haskell tooling.
+== FAQ and resources ==
+* '''Official Docs:''' [https://nixos.org/manual/nixpkgs/unstable/#haskell '''The Haskell section in the nixpkgs manual''']
+* [https://nixos.asia/en/nixify-haskell-nixpkgs '''Nixifying a Haskell project using nixpkgs'''] explains how to use Nix to package and develop Haskell projects using nothing but nixpkgs.
+* [https://github.com/mhwombat/nix-for-numbskulls/blob/78bcc186f79931c0e4a1e445e2f6b1f12f6d46be/Haskell/ss-haskell-dev.md '''Super-Simple Haskell Development with Nix'''] (and [https://discourse.nixos.org/t/super-simple-haskell-development-with-nix/14287/2 discussion] that provides interesting alternative methods together with there pro and cons)
+* [https://discourse.nixos.org/t/nix-haskell-development-2020/6170 '''Nix Haskell Development (2020)''']
+* [https://discourse.nixos.org/t/haskellpackages-stm-containers-fails-to-build/5416/4 '''How are Haskell packages managed in nixpkgs?''']
+* [https://www.youtube.com/watch?v=KLhkAEk8I20 '''How to fix broken Haskell packages?''' (video)]
 [[Category:Languages]]
-[[Category:Applications]]
+[[Category:Haskell]]