minion/docs
1
0
Fork 0
forked from auxolotl/docs
Code Pull requests 5 Activity
docs/Nixpkgs/Languages-And-Frameworks/haskell.section/index.html

4318 lines
131 KiB
HTML
Raw Permalink Normal View History

Deploy cd4936a to pages...pages.gay
2024-07-24 19:14:02 +00:00
<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="Aux Documentation">
<meta name="author" content="Nixpkgs Aux, and Lix Contributors">
<link rel="canonical" href="https://docs.auxolotl.org/Nixpkgs/Languages-And-Frameworks/haskell.section/">
<link rel="prev" href="../hare.section/">
<link rel="next" href="../hy.section/">
<link rel="icon" href="../../../assets/aux-logo.svg">
<meta name="generator" content="mkdocs-1.6.0, mkdocs-material-9.5.29">
<title>Haskell - Aux Docs</title>
<link rel="stylesheet" href="../../../assets/stylesheets/main.76a95c52.min.css">
<link rel="stylesheet" href="../../../assets/stylesheets/palette.06af60db.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.bunny.net/css?family=IBM+Plex+Sans:300,300i,400,400i,700,700i%7CIBM+Plex+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"IBM Plex Sans";--md-code-font:"IBM Plex Mono"}</style>
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<meta property="og:type" content="website" >
<meta property="og:title" content="Haskell {#haskell} - Aux Docs" >
<meta property="og:description" content="Aux Documentation" >
<meta property="og:image" content="https://docs.auxolotl.org/assets/images/social/Nixpkgs/Languages-And-Frameworks/haskell.section.png" >
<meta property="og:image:type" content="image/png" >
<meta property="og:image:width" content="1200" >
<meta property="og:image:height" content="630" >
<meta property="og:url" content="https://docs.auxolotl.org/Nixpkgs/Languages-And-Frameworks/haskell.section/" >
<meta name="twitter:card" content="summary_large_image" >
<meta name="twitter:title" content="Haskell {#haskell} - Aux Docs" >
<meta name="twitter:description" content="Aux Documentation" >
<meta name="twitter:image" content="https://docs.auxolotl.org/assets/images/social/Nixpkgs/Languages-And-Frameworks/haskell.section.png" >
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="blue">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#haskell" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../../.." title="Aux Docs" class="md-header__button md-logo" aria-label="Aux Docs" data-md-component="logo">
<img src="../../../assets/aux-logo.svg" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
Aux Docs
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Haskell
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="blue" aria-label="Dark Mode" type="radio" name="__palette" id="__palette_0">
<label class="md-header__button md-icon" title="Dark Mode" for="__palette_1" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3 3.19.09m3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95 2.06.05m-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31Z"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="blue" aria-label="Light Mode" type="radio" name="__palette" id="__palette_1">
<label class="md-header__button md-icon" title="Light Mode" for="__palette_0" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5c-.84 0-1.65.15-2.39.42L12 2M3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29L3.34 7m.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14L3.36 17M20.65 7l-1.77 3.79a7.023 7.023 0 0 0-2.38-4.15l4.15.36m-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29L20.64 17M12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44L12 22Z"/></svg>
</label>
</form>
<script>var media,input,key,value,palette=__md_get("__palette");if(palette&&palette.color){"(prefers-color-scheme)"===palette.color.media&&(media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']"),palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent"));for([key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg>
</button>
</nav>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://git.auxolotl.org/auxolotl/docs" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.777 0a2.9 2.9 0 1 1-2.529 4.322H12.91a4.266 4.266 0 0 0-4.265 4.195v2.118a7.076 7.076 0 0 1 4.147-1.42l.118-.002h1.338a2.9 2.9 0 0 1 5.43 1.422 2.9 2.9 0 0 1-5.43 1.422H12.91a4.266 4.266 0 0 0-4.265 4.195v2.319A2.9 2.9 0 0 1 7.222 24 2.9 2.9 0 0 1 5.8 18.57V8.589a7.109 7.109 0 0 1 6.991-7.108l.118-.001h1.338A2.9 2.9 0 0 1 16.778 0ZM7.223 19.905a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Zm9.554-10.464a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.39Zm0-7.735a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Z"/></svg>
</div>
<div class="md-source__repository">
auxolotl/docs
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href="../../.." class="md-tabs__link">
Aux Documentation Hub
</a>
</li>
<li class="md-tabs__item">
<a href="../../../TODO/" class="md-tabs__link">
TODO
</a>
</li>
<li class="md-tabs__item">
<a href="../../../Aux/" class="md-tabs__link">
Aux
</a>
</li>
<li class="md-tabs__item">
<a href="../../../Lix/" class="md-tabs__link">
Lix
</a>
</li>
<li class="md-tabs__item">
<a href="../../../NixOS/appstream/" class="md-tabs__link">
NixOS
</a>
</li>
<li class="md-tabs__item md-tabs__item--active">
<a href="../../" class="md-tabs__link">
Nixpkgs
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../../.." title="Aux Docs" class="md-nav__button md-logo" aria-label="Aux Docs" data-md-component="logo">
<img src="../../../assets/aux-logo.svg" alt="logo">
</a>
Aux Docs
</label>
<div class="md-nav__source">
<a href="https://git.auxolotl.org/auxolotl/docs" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.777 0a2.9 2.9 0 1 1-2.529 4.322H12.91a4.266 4.266 0 0 0-4.265 4.195v2.118a7.076 7.076 0 0 1 4.147-1.42l.118-.002h1.338a2.9 2.9 0 0 1 5.43 1.422 2.9 2.9 0 0 1-5.43 1.422H12.91a4.266 4.266 0 0 0-4.265 4.195v2.319A2.9 2.9 0 0 1 7.222 24 2.9 2.9 0 0 1 5.8 18.57V8.589a7.109 7.109 0 0 1 6.991-7.108l.118-.001h1.338A2.9 2.9 0 0 1 16.778 0ZM7.223 19.905a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Zm9.554-10.464a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.39Zm0-7.735a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Z"/></svg>
</div>
<div class="md-source__repository">
auxolotl/docs
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../.." class="md-nav__link">
<span class="md-ellipsis">
Aux Documentation Hub
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../TODO/" class="md-nav__link">
<span class="md-ellipsis">
TODO
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../../Aux/" class="md-nav__link">
<span class="md-ellipsis">
Aux
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../../Lix/" class="md-nav__link">
<span class="md-ellipsis">
Lix
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../../NixOS/appstream/" class="md-nav__link">
<span class="md-ellipsis">
NixOS
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" checked>
<div class="md-nav__link md-nav__container">
<a href="../../" class="md-nav__link ">
<span class="md-ellipsis">
Nixpkgs
</span>
</a>
<label class="md-nav__link " for="__nav_6" id="__nav_6_label" tabindex="">
<span class="md-nav__icon md-icon"></span>
</label>
</div>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_6">
<span class="md-nav__icon md-icon"></span>
Nixpkgs
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../options/" class="md-nav__link">
<span class="md-ellipsis">
Options
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Build-Helpers/" class="md-nav__link">
<span class="md-ellipsis">
Build Helpers
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Development/" class="md-nav__link">
<span class="md-ellipsis">
Development
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Functions/" class="md-nav__link">
<span class="md-ellipsis">
Functions
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Hooks/" class="md-nav__link">
<span class="md-ellipsis">
Hooks
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6_7" checked>
<div class="md-nav__link md-nav__container">
<a href="../" class="md-nav__link ">
<span class="md-ellipsis">
Languages And Frameworks
</span>
</a>
<label class="md-nav__link " for="__nav_6_7" id="__nav_6_7_label" tabindex="0">
<span class="md-nav__icon md-icon"></span>
</label>
</div>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_6_7_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_6_7">
<span class="md-nav__icon md-icon"></span>
Languages And Frameworks
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../agda.section/" class="md-nav__link">
<span class="md-ellipsis">
Agda
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../android.section/" class="md-nav__link">
<span class="md-ellipsis">
Android
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../beam.section/" class="md-nav__link">
<span class="md-ellipsis">
BEAM Languages (Erlang, Elixir &amp; LFE)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../bower.section/" class="md-nav__link">
<span class="md-ellipsis">
Bower
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../chicken.section/" class="md-nav__link">
<span class="md-ellipsis">
CHICKEN
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../coq.section/" class="md-nav__link">
<span class="md-ellipsis">
Coq and coq packages
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../crystal.section/" class="md-nav__link">
<span class="md-ellipsis">
Crystal
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../cuda.section/" class="md-nav__link">
<span class="md-ellipsis">
CUDA
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../cuelang.section/" class="md-nav__link">
<span class="md-ellipsis">
Cue (Cuelang)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../dart.section/" class="md-nav__link">
<span class="md-ellipsis">
Dart
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../dhall.section/" class="md-nav__link">
<span class="md-ellipsis">
Dhall
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../dlang.section/" class="md-nav__link">
<span class="md-ellipsis">
D (Dlang)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../dotnet.section/" class="md-nav__link">
<span class="md-ellipsis">
Dotnet
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../emscripten.section/" class="md-nav__link">
<span class="md-ellipsis">
Emscripten
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../gnome.section/" class="md-nav__link">
<span class="md-ellipsis">
GNOME
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../go.section/" class="md-nav__link">
<span class="md-ellipsis">
Go
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../gradle.section/" class="md-nav__link">
<span class="md-ellipsis">
Gradle
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../hare.section/" class="md-nav__link">
<span class="md-ellipsis">
Hare
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Haskell
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Haskell
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#haskell-available-packages" class="md-nav__link">
<span class="md-ellipsis">
Available packages
</span>
</a>
<nav class="md-nav" aria-label="Available packages">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-available-versions" class="md-nav__link">
<span class="md-ellipsis">
Available package versions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-dependency-resolution" class="md-nav__link">
<span class="md-ellipsis">
Dependency resolution
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-limitations" class="md-nav__link">
<span class="md-ellipsis">
Limitations
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-mkderivation" class="md-nav__link">
<span class="md-ellipsis">
haskellPackages.mkDerivation
</span>
</a>
<nav class="md-nav" aria-label="haskellPackages.mkDerivation">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-derivation-args" class="md-nav__link">
<span class="md-ellipsis">
General arguments
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-derivation-deps" class="md-nav__link">
<span class="md-ellipsis">
Specifying dependencies
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-derivation-meta" class="md-nav__link">
<span class="md-ellipsis">
Meta attributes
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-incremental-builds" class="md-nav__link">
<span class="md-ellipsis">
Incremental builds
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-development-environments" class="md-nav__link">
<span class="md-ellipsis">
Development environments
</span>
</a>
<nav class="md-nav" aria-label="Development environments">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-shellFor" class="md-nav__link">
<span class="md-ellipsis">
shellFor
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-language-server" class="md-nav__link">
<span class="md-ellipsis">
haskell-language-server
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-overriding-haskell-packages" class="md-nav__link">
<span class="md-ellipsis">
Overriding Haskell packages
</span>
</a>
<nav class="md-nav" aria-label="Overriding Haskell packages">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-overriding-a-single-package" class="md-nav__link">
<span class="md-ellipsis">
Overriding a single package
</span>
</a>
<nav class="md-nav" aria-label="Overriding a single package">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-haskell.lib.compose" class="md-nav__link">
<span class="md-ellipsis">
haskell.lib.compose
</span>
</a>
<nav class="md-nav" aria-label="haskell.lib.compose">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-packaging-helpers" class="md-nav__link">
<span class="md-ellipsis">
Packaging Helpers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-development-helpers" class="md-nav__link">
<span class="md-ellipsis">
Development Helpers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-trivial-helpers" class="md-nav__link">
<span class="md-ellipsis">
Trivial Helpers
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-package-set-lib-functions" class="md-nav__link">
<span class="md-ellipsis">
Library functions in the Haskell package sets
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-import-from-derivation" class="md-nav__link">
<span class="md-ellipsis">
Import-from-Derivation helpers
</span>
</a>
<nav class="md-nav" aria-label="Import-from-Derivation helpers">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-cabal2nix" class="md-nav__link">
<span class="md-ellipsis">
cabal2nix
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-faq" class="md-nav__link">
<span class="md-ellipsis">
F.A.Q.
</span>
</a>
<nav class="md-nav" aria-label="F.A.Q.">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-why-not-covered" class="md-nav__link">
<span class="md-ellipsis">
Why is topic X not covered in this section? Why is section Y missing?
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-faq-override-profiling" class="md-nav__link">
<span class="md-ellipsis">
How to enable or disable profiling builds globally?
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../hy.section/" class="md-nav__link">
<span class="md-ellipsis">
Hy
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../idris.section/" class="md-nav__link">
<span class="md-ellipsis">
Idris
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../idris2.section/" class="md-nav__link">
<span class="md-ellipsis">
Idris2
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ios.section/" class="md-nav__link">
<span class="md-ellipsis">
iOS
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../java.section/" class="md-nav__link">
<span class="md-ellipsis">
Java
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../javascript.section/" class="md-nav__link">
<span class="md-ellipsis">
Javascript
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../julia.section/" class="md-nav__link">
<span class="md-ellipsis">
Julia
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../lisp.section/" class="md-nav__link">
<span class="md-ellipsis">
lisp-modules
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../lua.section/" class="md-nav__link">
<span class="md-ellipsis">
Lua
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../maven.section/" class="md-nav__link">
<span class="md-ellipsis">
Maven
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../nim.section/" class="md-nav__link">
<span class="md-ellipsis">
Nim
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ocaml.section/" class="md-nav__link">
<span class="md-ellipsis">
OCaml
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../octave.section/" class="md-nav__link">
<span class="md-ellipsis">
Octave
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../perl.section/" class="md-nav__link">
<span class="md-ellipsis">
Perl
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../php.section/" class="md-nav__link">
<span class="md-ellipsis">
PHP
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../pkg-config.section/" class="md-nav__link">
<span class="md-ellipsis">
pkg-config
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../python.section/" class="md-nav__link">
<span class="md-ellipsis">
Python
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../qt.section/" class="md-nav__link">
<span class="md-ellipsis">
Qt
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../r.section/" class="md-nav__link">
<span class="md-ellipsis">
R
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ruby.section/" class="md-nav__link">
<span class="md-ellipsis">
Ruby
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../rust.section/" class="md-nav__link">
<span class="md-ellipsis">
Rust
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../scheme.section/" class="md-nav__link">
<span class="md-ellipsis">
Scheme
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../swift.section/" class="md-nav__link">
<span class="md-ellipsis">
Swift
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../texlive.section/" class="md-nav__link">
<span class="md-ellipsis">
TeX Live
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../titanium.section/" class="md-nav__link">
<span class="md-ellipsis">
Titanium
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../vim.section/" class="md-nav__link">
<span class="md-ellipsis">
Vim
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Library-Reference/asserts/" class="md-nav__link">
<span class="md-ellipsis">
Library Reference
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Module-System/module-system.chapter/" class="md-nav__link">
<span class="md-ellipsis">
Module System
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Packages/" class="md-nav__link">
<span class="md-ellipsis">
Packages
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Standard-Environment/" class="md-nav__link">
<span class="md-ellipsis">
Standard Environment
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
<li class="md-nav__item md-nav__item--pruned md-nav__item--nested">
<a href="../../Using-Nixpkgs/" class="md-nav__link">
<span class="md-ellipsis">
Using Nixpkgs
</span>
<span class="md-nav__icon md-icon"></span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#haskell-available-packages" class="md-nav__link">
<span class="md-ellipsis">
Available packages
</span>
</a>
<nav class="md-nav" aria-label="Available packages">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-available-versions" class="md-nav__link">
<span class="md-ellipsis">
Available package versions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-dependency-resolution" class="md-nav__link">
<span class="md-ellipsis">
Dependency resolution
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-limitations" class="md-nav__link">
<span class="md-ellipsis">
Limitations
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-mkderivation" class="md-nav__link">
<span class="md-ellipsis">
haskellPackages.mkDerivation
</span>
</a>
<nav class="md-nav" aria-label="haskellPackages.mkDerivation">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-derivation-args" class="md-nav__link">
<span class="md-ellipsis">
General arguments
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-derivation-deps" class="md-nav__link">
<span class="md-ellipsis">
Specifying dependencies
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-derivation-meta" class="md-nav__link">
<span class="md-ellipsis">
Meta attributes
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-incremental-builds" class="md-nav__link">
<span class="md-ellipsis">
Incremental builds
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-development-environments" class="md-nav__link">
<span class="md-ellipsis">
Development environments
</span>
</a>
<nav class="md-nav" aria-label="Development environments">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-shellFor" class="md-nav__link">
<span class="md-ellipsis">
shellFor
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-language-server" class="md-nav__link">
<span class="md-ellipsis">
haskell-language-server
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-overriding-haskell-packages" class="md-nav__link">
<span class="md-ellipsis">
Overriding Haskell packages
</span>
</a>
<nav class="md-nav" aria-label="Overriding Haskell packages">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-overriding-a-single-package" class="md-nav__link">
<span class="md-ellipsis">
Overriding a single package
</span>
</a>
<nav class="md-nav" aria-label="Overriding a single package">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-haskell.lib.compose" class="md-nav__link">
<span class="md-ellipsis">
haskell.lib.compose
</span>
</a>
<nav class="md-nav" aria-label="haskell.lib.compose">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-packaging-helpers" class="md-nav__link">
<span class="md-ellipsis">
Packaging Helpers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-development-helpers" class="md-nav__link">
<span class="md-ellipsis">
Development Helpers
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-trivial-helpers" class="md-nav__link">
<span class="md-ellipsis">
Trivial Helpers
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-package-set-lib-functions" class="md-nav__link">
<span class="md-ellipsis">
Library functions in the Haskell package sets
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-import-from-derivation" class="md-nav__link">
<span class="md-ellipsis">
Import-from-Derivation helpers
</span>
</a>
<nav class="md-nav" aria-label="Import-from-Derivation helpers">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-cabal2nix" class="md-nav__link">
<span class="md-ellipsis">
cabal2nix
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#haskell-faq" class="md-nav__link">
<span class="md-ellipsis">
F.A.Q.
</span>
</a>
<nav class="md-nav" aria-label="F.A.Q.">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#haskell-why-not-covered" class="md-nav__link">
<span class="md-ellipsis">
Why is topic X not covered in this section? Why is section Y missing?
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#haskell-faq-override-profiling" class="md-nav__link">
<span class="md-ellipsis">
How to enable or disable profiling builds globally?
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1 id="haskell">Haskell</h1>
<p>The Haskell infrastructure in Nixpkgs has two main purposes: The primary purpose
is to provide a Haskell compiler and build tools as well as infrastructure for
packaging Haskell-based packages.</p>
<p>The secondary purpose is to provide support for Haskell development environments
including prebuilt Haskell libraries. However, in this area sacrifices have been
made due to self-imposed restrictions in Nixpkgs, to lessen the maintenance
effort and to improve performance. (More details in the subsection
<a href="#haskell-limitations">Limitations.</a>)</p>
<h2 id="haskell-available-packages">Available packages</h2>
<p>The compiler and most build tools are exposed at the top level:</p>
<ul>
<li><code>ghc</code> is the default version of GHC</li>
<li>Language specific tools: <code>cabal-install</code>, <code>stack</code>, <code>hpack</code>, …</li>
</ul>
<p>Many “normal” user facing packages written in Haskell, like <code>niv</code> or <code>cachix</code>,
are also exposed at the top level, and there is nothing Haskell specific to
installing and using them.</p>
<p>All of these packages are originally defined in the <code>haskellPackages</code> package set.
The same packages are re-exposed with a reduced dependency closure for convenience (see <code>justStaticExecutables</code> or <code>separateBinOutput</code> below).</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>See <a href="#chap-language-support"></a> for techniques to explore package sets.</p>
</div>
<p>The <code>haskellPackages</code> set includes at least one version of every package from <a href="https://hackage.haskell.org/">Hackage</a> as well as some manually injected packages.</p>
<p>The attribute names in <code>haskellPackages</code> always correspond with their name on
Hackage. Since Hackage allows names that are not valid Nix without escaping,
you need to take care when handling attribute names like <code>3dmodels</code>.</p>
<p>For packages that are part of <a href="https://www.stackage.org">Stackage</a> (a curated set of known to be
compatible packages), we use the version prescribed by a Stackage snapshot
(usually the current LTS one) as the default version. For all other packages we
use the latest version from <a href="https://hackage.org">Hackage</a> (the repository of
basically all open source Haskell packages). See <a href="#haskell-available-versions">below</a> for a few more details on this.</p>
<p>Roughly half of the 16K packages contained in <code>haskellPackages</code> don’t actually
build and are <a href="https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/broken.yaml">marked as broken semi-automatically</a>.
Most of those packages are deprecated or unmaintained, but sometimes packages
that should build, do not build. Very often fixing them is not a lot of work.</p>
<!--
TODO(@sternenseemann):
How you can help with that is
described in [Fixing a broken package](#haskell-fixing-a-broken-package).
-->
<p><code>haskellPackages</code> is built with our default compiler, but we also provide other releases of GHC and package sets built with them.
Available compilers are collected under <code>haskell.compiler</code>.</p>
<p>Each of those compiler versions has a corresponding attribute set <code>packages</code> built with
it. However, the non-standard package sets are not tested regularly and, as a
result, contain fewer working packages. The corresponding package set for GHC
9.4.5 is <code>haskell.packages.ghc945</code>. In fact <code>haskellPackages</code> is just an alias
for <code>haskell.packages.ghc964</code>:</p>
<p>Every package set also re-exposes the GHC used to build its packages as <code>haskell.packages.*.ghc</code>.</p>
<h3 id="haskell-available-versions">Available package versions</h3>
<p>We aim for a “blessed” package set which only contains one version of each
package, like <a href="https://www.stackage.org">Stackage</a>, which is a curated set of known to be compatible
packages. We use the version information from Stackage snapshots and extend it
with more packages. Normally in Nixpkgs the number of building Haskell packages
is roughly two to three times the size of Stackage. For choosing the version to
use for a certain package we use the following rules:</p>
<ol>
<li>By default, for <code>haskellPackages.foo</code> is the newest version of the package
<code>foo</code> found on <a href="https://hackage.org">Hackage</a>, which is the central registry
of all open source Haskell packages. Nixpkgs contains a reference to a pinned
Hackage snapshot, thus we use the state of Hackage as of the last time we
updated this pin.</li>
<li>If the <a href="https://www.stackage.org">Stackage</a> snapshot that we use (usually the newest LTS snapshot)
contains a package, <a href="https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/stackage.yaml">we use instead the version in the Stackage snapshot as
default version for that package.</a></li>
<li>For some packages, which are not on Stackage, we have if necessary <a href="https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/main.yaml">manual
overrides to set the default version to a version older than the newest on
Hackage.</a></li>
<li>For all packages, for which the newest Hackage version is not the default
version, there will also be a <code>haskellPackages.foo_x_y_z</code> package with the
newest version. The <code>x_y_z</code> part encodes the version with dots replaced by
underscores. When the newest version changes by a new release to Hackage the
old package will disappear under that name and be replaced by a newer one under
the name with the new version. The package name including the version will
also disappear when the default version e.g. from Stackage catches up with the
newest version from Hackage. E.g. if <code>haskellPackages.foo</code> gets updated from
1.0.0 to 1.1.0 the package <code>haskellPackages.foo_1_1_0</code> becomes obsolete and
gets dropped.</li>
<li>For some packages, we also <a href="https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/main.yaml">manually add other <code>haskellPackages.foo_x_y_z</code>
versions</a>,
if they are required for a certain build.</li>
</ol>
<p>Relying on <code>haskellPackages.foo_x_y_z</code> attributes in derivations outside
nixpkgs is discouraged because they may change or disappear with every package
set update.</p>
<!-- TODO(@maralorn) We should add a link to callHackage, etc. once we added
them to the docs. -->
<p>All <code>haskell.packages.*</code> package sets use the same package descriptions and the same sets
of versions by default. There are however GHC version specific override <code>.nix</code>
files to loosen this a bit.</p>
<h3 id="haskell-dependency-resolution">Dependency resolution</h3>
<p>Normally when you build Haskell packages with <code>cabal-install</code>, <code>cabal-install</code>
does dependency resolution. It will look at all Haskell package versions known
on Hackage and tries to pick for every (transitive) dependency of your build
exactly one version. Those versions need to satisfy all the version constraints
given in the <code>.cabal</code> file of your package and all its dependencies.</p>
<p>The <a href="#haskell-mkderivation">Haskell builder in nixpkgs</a> does no such thing.
It will take as input packages with names off the desired dependencies
and just check whether they fulfill the version bounds and fail if they don’t
(by default, see <code>jailbreak</code> to circumvent this).</p>
<p>The <code>haskellPackages.callPackage</code> function does the package resolution.
It will, e.g., use <code>haskellPackages.aeson</code>which has the default version as
described above for a package input of name <code>aeson</code>. (More general:
<code>&lt;packages&gt;.callPackage f</code> will call <code>f</code> with named inputs provided from the
package set <code>&lt;packages&gt;</code>.)
While this is the default behavior, it is possible to override the dependencies
for a specific package, see
<a href="#haskell-overriding-haskell-packages"><code>override</code> and <code>overrideScope</code></a>.</p>
<h3 id="haskell-limitations">Limitations</h3>
<p>Our main objective with <code>haskellPackages</code> is to package Haskell software in
nixpkgs. This entails some limitations, partially due to self-imposed
restrictions of nixpkgs, partially in the name of maintainability:</p>
<ul>
<li>Only the packages built with the default compiler see extensive testing of the
whole package set. For other GHC versions only a few essential packages are
tested and cached.</li>
<li>As described above we only build one version of most packages.</li>
</ul>
<p>The experience using an older or newer packaged compiler or using different
versions may be worse, because builds will not be cached on <code>cache.nixos.org</code>
or may fail.</p>
<p>Thus, to get the best experience, make sure that your project can be compiled
using the default compiler of nixpkgs and recent versions of its dependencies.</p>
<p>A result of this setup is, that getting a valid build plan for a given
package can sometimes be quite painful, and in fact this is where most of the
maintenance work for <code>haskellPackages</code> is required. Besides that, it is not
possible to get the dependencies of a legacy project from nixpkgs or to use a
specific stack solver for compiling a project.</p>
<p>Even though we couldn’t use them directly in nixpkgs, it would be desirable
to have tooling to generate working Nix package sets from build plans generated
by <code>cabal-install</code> or a specific Stackage snapshot via import-from-derivation.
Sadly we currently don’t have tooling for this. For this you might be
interested in the alternative <a href="https://input-output-hk.github.io/haskell.nix/index.html">haskell.nix</a> framework, which, be warned, is
completely incompatible with packages from <code>haskellPackages</code>.</p>
<!-- TODO(@maralorn) Link to package set generation docs in the contributors guide below. -->
<h2 id="haskell-mkderivation"><code>haskellPackages.mkDerivation</code></h2>
<p>Every haskell package set has its own haskell-aware <code>mkDerivation</code> which is used
to build its packages. Generally you won't have to interact with this builder
since <a href="#haskell-cabal2nix">cabal2nix</a> can generate packages
using it for an arbitrary cabal package definition. Still it is useful to know
the parameters it takes when you need to
<a href="#haskell-overriding-haskell-packages">override</a> a generated Nix expression.</p>
<p><code>haskellPackages.mkDerivation</code> is a wrapper around <code>stdenv.mkDerivation</code> which
re-defines the default phases to be haskell aware and handles dependency
specification, test suites, benchmarks etc. by compiling and invoking the
package's <code>Setup.hs</code>. It does <em>not</em> use or invoke the <code>cabal-install</code> binary,
but uses the underlying <code>Cabal</code> library instead.</p>
<h3 id="haskell-derivation-args">General arguments</h3>
<p><code>pname</code>
: Package name, assumed to be the same as on Hackage (if applicable)</p>
<p><code>version</code>
: Packaged version, assumed to be the same as on Hackage (if applicable)</p>
<p><code>src</code>
: Source of the package. If omitted, fetch package corresponding to <code>pname</code>
and <code>version</code> from Hackage.</p>
<p><code>sha256</code>
: Hash to use for the default case of <code>src</code>.</p>
<p><code>revision</code>
: Revision number of the updated cabal file to fetch from Hackage.
If <code>null</code> (which is the default value), the one included in <code>src</code> is used.</p>
<p><code>editedCabalFile</code>
: <code>sha256</code> hash of the cabal file identified by <code>revision</code> or <code>null</code>.</p>
<p><code>configureFlags</code>
: Extra flags passed when executing the <code>configure</code> command of <code>Setup.hs</code>.</p>
<p><code>buildFlags</code>
: Extra flags passed when executing the <code>build</code> command of <code>Setup.hs</code>.</p>
<p><code>haddockFlags</code>
: Extra flags passed to <code>Setup.hs haddock</code> when building the documentation.</p>
<p><code>doCheck</code>
: Whether to execute the package's test suite if it has one. Defaults to <code>true</code> unless cross-compiling.</p>
<p><code>doBenchmark</code>
: Whether to execute the package's benchmark if it has one. Defaults to <code>false</code>.</p>
<p><code>doHoogle</code>
: Whether to generate an index file for <a href="https://wiki.haskell.org/Hoogle">hoogle</a> as part of
<code>haddockPhase</code> by passing the <a href="https://haskell-haddock.readthedocs.io/en/latest/invoking.html#cmdoption-hoogle"><code>--hoogle</code> option</a>.
Defaults to <code>true</code>.</p>
<p><code>doHaddockQuickjump</code>
: Whether to generate an index for interactive navigation of the HTML documentation.
Defaults to <code>true</code> if supported.</p>
<p><code>doInstallIntermediates</code>
: Whether to install intermediate build products (files written to <code>dist/build</code>
by GHC during the build process). With <code>enableSeparateIntermediatesOutput</code>,
these files are instead installed to <a href="https://nixos.org/manual/nixpkgs/stable/#chap-multiple-output">a separate <code>intermediates</code>
output.</a> The output can then be passed into a future build of
the same package with the <code>previousIntermediates</code> argument to support
incremental builds. See <a href="#haskell-incremental-builds">“Incremental builds”</a> for
more information. Defaults to <code>false</code>.</p>
<p><code>enableLibraryProfiling</code>
: Whether to enable <a href="https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html">profiling</a> for libraries contained in the
package. Enabled by default if supported.</p>
<p><code>enableExecutableProfiling</code>
: Whether to enable <a href="https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html">profiling</a> for executables contained in the
package. Disabled by default.</p>
<p><code>profilingDetail</code>
: <a href="https://cabal.readthedocs.io/en/latest/cabal-project.html#cfg-field-profiling-detail">Profiling detail level</a> to set. Defaults to <code>exported-functions</code>.</p>
<p><code>enableSharedExecutables</code>
: Whether to link executables dynamically. By default, executables are linked statically.</p>
<p><code>enableSharedLibraries</code>
: Whether to build shared Haskell libraries. This is enabled by default unless we are using
<code>pkgsStatic</code> or shared libraries have been disabled in GHC.</p>
<p><code>enableStaticLibraries</code>
: Whether to build static libraries. Enabled by default if supported.</p>
<p><code>enableDeadCodeElimination</code>
: Whether to enable linker based dead code elimination in GHC.
Enabled by default if supported.</p>
<p><code>enableHsc2hsViaAsm</code>
: Whether to pass <code>--via-asm</code> to <code>hsc2hs</code>. Enabled by default only on Windows.</p>
<p><code>hyperlinkSource</code>
: Whether to render the source as well as part of the haddock documentation
by passing the <a href="https://haskell-haddock.readthedocs.io/en/latest/invoking.html#cmdoption-hyperlinked-source"><code>--hyperlinked-source</code> flag</a>.
Defaults to <code>true</code>.</p>
<p><code>isExecutable</code>
: Whether the package contains an executable.</p>
<p><code>isLibrary</code>
: Whether the package contains a library.</p>
<p><code>jailbreak</code>
: Whether to execute <a href="https://github.com/NixOS/jailbreak-cabal/">jailbreak-cabal</a> before <code>configurePhase</code>
to lift any version constraints in the cabal file. Note that this can't
lift version bounds if they are conditional, i.e. if a dependency is hidden
behind a flag.</p>
<p><code>enableParallelBuilding</code>
: Whether to use the <code>-j</code> flag to make GHC/Cabal start multiple jobs in parallel.</p>
<p><code>maxBuildCores</code>
: Upper limit of jobs to use in parallel for compilation regardless of
<code>$NIX_BUILD_CORES</code>. Defaults to 16 as Haskell compilation with GHC currently
sees a <a href="https://gitlab.haskell.org/ghc/ghc/-/issues/9221">performance regression</a>
if too many parallel jobs are used.</p>
<p><code>doCoverage</code>
: Whether to generate and install files needed for <a href="https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html#observing-code-coverage">HPC</a>.
Defaults to <code>false</code>.</p>
<p><code>doHaddock</code>
: Whether to build (HTML) documentation using <a href="https://www.haskell.org/haddock/">haddock</a>.
Defaults to <code>true</code> if supported.</p>
<p><code>testTarget</code>
: Name of the test suite to build and run. If unset, all test suites will be executed.</p>
<p><code>preCompileBuildDriver</code>
: Shell code to run before compiling <code>Setup.hs</code>.</p>
<p><code>postCompileBuildDriver</code>
: Shell code to run after compiling <code>Setup.hs</code>.</p>
<p><code>preHaddock</code>
: Shell code to run before building documentation using haddock.</p>
<p><code>postHaddock</code>
: Shell code to run after building documentation using haddock.</p>
<p><code>coreSetup</code>
: Whether to only allow core libraries to be used while building <code>Setup.hs</code>.
Defaults to <code>false</code>.</p>
<p><code>useCpphs</code>
: Whether to enable the <a href="https://Hackage.haskell.org/package/cpphs">cpphs</a> preprocessor. Defaults to <code>false</code>.</p>
<p><code>enableSeparateBinOutput</code>
: Whether to install executables to a separate <code>bin</code> output. Defaults to <code>false</code>.</p>
<p><code>enableSeparateDataOutput</code>
: Whether to install data files shipped with the package to a separate <code>data</code> output.
Defaults to <code>false</code>.</p>
<p><code>enableSeparateDocOutput</code>
: Whether to install documentation to a separate <code>doc</code> output.
Is automatically enabled if <code>doHaddock</code> is <code>true</code>.</p>
<p><code>enableSeparateIntermediatesOutput</code>
: When <code>doInstallIntermediates</code> is true, whether to install intermediate build
products to a separate <code>intermediates</code> output. See <a href="#haskell-incremental-builds">“Incremental
builds”</a> for more information. Defaults to
<code>false</code>.</p>
<p><code>allowInconsistentDependencies</code>
: If enabled, allow multiple versions of the same Haskell package in the
dependency tree at configure time. Often in such a situation compilation would
later fail because of type mismatches. Defaults to <code>false</code>.</p>
<p><code>enableLibraryForGhci</code>
: Build and install a special object file for GHCi. This improves performance
when loading the library in the REPL, but requires extra build time and
disk space. Defaults to <code>false</code>.</p>
<p><code>previousIntermediates</code>
: If non-null, intermediate build artifacts are copied from this input to
<code>dist/build</code> before performing compiling. See <a href="#haskell-incremental-builds">“Incremental
builds”</a> for more information. Defaults to <code>null</code>.</p>
<p><code>buildTarget</code>
: Name of the executable or library to build and install.
If unset, all available targets are built and installed.</p>
<h3 id="haskell-derivation-deps">Specifying dependencies</h3>
<p>Since <code>haskellPackages.mkDerivation</code> is intended to be generated from cabal
files, it reflects cabal's way of specifying dependencies. For one, dependencies
are grouped by what part of the package they belong to. This helps to reduce the
dependency closure of a derivation, for example benchmark dependencies are not
included if <code>doBenchmark == false</code>.</p>
<p><code>setup*Depends</code>
: dependencies necessary to compile <code>Setup.hs</code></p>
<p><code>library*Depends</code>
: dependencies of a library contained in the package</p>
<p><code>executable*Depends</code>
: dependencies of an executable contained in the package</p>
<p><code>test*Depends</code>
: dependencies of a test suite contained in the package</p>
<p><code>benchmark*Depends</code>
: dependencies of a benchmark contained in the package</p>
<p>The other categorization relates to the way the package depends on the dependency:</p>
<p><code>*ToolDepends</code>
: Tools we need to run as part of the build process.
They are added to the derivation's <code>nativeBuildInputs</code>.</p>
<p><code>*HaskellDepends</code>
: Haskell libraries the package depends on.
They are added to <code>propagatedBuildInputs</code>.</p>
<p><code>*SystemDepends</code>
: Non-Haskell libraries the package depends on.
They are added to <code>buildInputs</code></p>
<p><code>*PkgconfigDepends</code>
: <code>*SystemDepends</code> which are discovered using <code>pkg-config</code>.
They are added to <code>buildInputs</code> and it is additionally
ensured that <code>pkg-config</code> is available at build time.</p>
<p><code>*FrameworkDepends</code>
: Apple SDK Framework which the package depends on when compiling it on Darwin.</p>
<p>Using these two distinctions, you should be able to categorize most of the dependency
specifications that are available:
<code>benchmarkFrameworkDepends</code>,
<code>benchmarkHaskellDepends</code>,
<code>benchmarkPkgconfigDepends</code>,
<code>benchmarkSystemDepends</code>,
<code>benchmarkToolDepends</code>,
<code>executableFrameworkDepends</code>,
<code>executableHaskellDepends</code>,
<code>executablePkgconfigDepends</code>,
<code>executableSystemDepends</code>,
<code>executableToolDepends</code>,
<code>libraryFrameworkDepends</code>,
<code>libraryHaskellDepends</code>,
<code>libraryPkgconfigDepends</code>,
<code>librarySystemDepends</code>,
<code>libraryToolDepends</code>,
<code>setupHaskellDepends</code>,
<code>testFrameworkDepends</code>,
<code>testHaskellDepends</code>,
<code>testPkgconfigDepends</code>,
<code>testSystemDepends</code> and
<code>testToolDepends</code>.</p>
<p>That only leaves the following extra ways for specifying dependencies:</p>
<p><code>buildDepends</code>
: Allows specifying Haskell dependencies which are added to <code>propagatedBuildInputs</code> unconditionally.</p>
<p><code>buildTools</code>
: Like <code>*ToolDepends</code>, but are added to <code>nativeBuildInputs</code> unconditionally.</p>
<p><code>extraLibraries</code>
: Like <code>*SystemDepends</code>, but are added to <code>buildInputs</code> unconditionally.</p>
<p><code>pkg-configDepends</code>
: Like <code>*PkgconfigDepends</code>, but are added to <code>buildInputs</code> unconditionally.</p>
<p><code>testDepends</code>
: Deprecated, use either <code>testHaskellDepends</code> or <code>testSystemDepends</code>.</p>
<p><code>benchmarkDepends</code>
: Deprecated, use either <code>benchmarkHaskellDepends</code> or <code>benchmarkSystemDepends</code>.</p>
<p>The dependency specification methods in this list which are unconditional
are especially useful when writing <a href="#haskell-overriding-haskell-packages">overrides</a>
when you want to make sure that they are definitely included. However, it is
recommended to use the more accurate ones listed above when possible.</p>
<h3 id="haskell-derivation-meta">Meta attributes</h3>
<p><code>haskellPackages.mkDerivation</code> accepts the following attributes as direct
arguments which are transparently set in <code>meta</code> of the resulting derivation. See
the <a href="#chap-meta">Meta-attributes section</a> for their documentation.</p>
<ul>
<li>These attributes are populated with a default value if omitted:<ul>
<li><code>homepage</code>: defaults to the Hackage page for <code>pname</code>.</li>
<li><code>platforms</code>: defaults to <code>lib.platforms.all</code> (since GHC can cross-compile)</li>
</ul>
</li>
<li>These attributes are only set if given:<ul>
<li><code>description</code></li>
<li><code>license</code></li>
<li><code>changelog</code></li>
<li><code>maintainers</code></li>
<li><code>broken</code></li>
<li><code>hydraPlatforms</code></li>
</ul>
</li>
</ul>
<h3 id="haskell-incremental-builds">Incremental builds</h3>
<p><code>haskellPackages.mkDerivation</code> supports incremental builds for GHC 9.4 and
newer with the <code>doInstallIntermediates</code>, <code>enableSeparateIntermediatesOutput</code>,
and <code>previousIntermediates</code> arguments.</p>
<p>The basic idea is to first perform a full build of the package in question,
save its intermediate build products for later, and then copy those build
products into the build directory of an incremental build performed later.
Then, GHC will use those build artifacts to avoid recompiling unchanged
modules.</p>
<p>For more detail on how to store and use incremental build products, see
<a href="https://www.haskellforall.com/2022/12/nixpkgs-support-for-incremental-haskell.html">Gabriella Gonzalez’ blog post “Nixpkgs support for incremental Haskell
builds”.</a> motivation behind this feature.</p>
<p>An incremental build for <a href="https://hackage.haskell.org/package/turtle">the <code>turtle</code> package</a> can be performed like
so:</p>
<div class="highlight"><pre><span></span><code><span class="k">let</span>
<span class="ss">pkgs</span> <span class="o">=</span> <span class="nb">import</span> <span class="l">&lt;nixpkgs&gt;</span> <span class="p">{};</span>
<span class="k">inherit</span> <span class="p">(</span>pkgs<span class="p">)</span> haskell<span class="p">;</span>
<span class="k">inherit</span> <span class="p">(</span>haskell<span class="o">.</span>lib<span class="o">.</span>compose<span class="p">)</span> overrideCabal<span class="p">;</span>
<span class="c1"># Incremental builds work with GHC &gt;=9.4.</span>
<span class="ss">turtle</span> <span class="o">=</span> haskell<span class="o">.</span>packages<span class="o">.</span>ghc944<span class="o">.</span>turtle<span class="p">;</span>
<span class="c1"># This will do a full build of `turtle`, while writing the intermediate build products</span>
<span class="c1"># (compiled modules, etc.) to the `intermediates` output.</span>
<span class="ss">turtle-full-build-with-incremental-output</span> <span class="o">=</span> overrideCabal <span class="p">(</span>drv<span class="p">:</span> <span class="p">{</span>
<span class="ss">doInstallIntermediates</span> <span class="o">=</span> <span class="no">true</span><span class="p">;</span>
<span class="ss">enableSeparateIntermediatesOutput</span> <span class="o">=</span> <span class="no">true</span><span class="p">;</span>
<span class="p">})</span> turtle<span class="p">;</span>
<span class="c1"># This will do an incremental build of `turtle` by copying the previously</span>
<span class="c1"># compiled modules and intermediate build products into the source tree</span>
<span class="c1"># before running the build.</span>
<span class="c1">#</span>
<span class="c1"># GHC will then naturally pick up and reuse these products, making this build</span>
<span class="c1"># complete much more quickly than the previous one.</span>
<span class="ss">turtle-incremental-build</span> <span class="o">=</span> overrideCabal <span class="p">(</span>drv<span class="p">:</span> <span class="p">{</span>
<span class="ss">previousIntermediates</span> <span class="o">=</span> turtle-full-build-with-incremental-output<span class="o">.</span>intermediates<span class="p">;</span>
<span class="p">})</span> turtle<span class="p">;</span>
<span class="k">in</span>
turtle-incremental-build
</code></pre></div>
<h2 id="haskell-development-environments">Development environments</h2>
<p>In addition to building and installing Haskell software, nixpkgs can also
provide development environments for Haskell projects. This has the obvious
advantage that you benefit from <code>cache.nixos.org</code> and no longer need to compile
all project dependencies yourself. While it is often very useful, this is not
the primary use case of our package set. Have a look at the section
<a href="#haskell-available-versions">available package versions</a> to learn which
versions of packages we provide and the section
<a href="#haskell-limitations">limitations</a>, to judge whether a <code>haskellPackages</code>
based development environment for your project is feasible.</p>
<p>By default, every derivation built using
<a href="#haskell-mkderivation"><code>haskellPackages.mkDerivation</code></a> exposes an environment
suitable for building it interactively as the <code>env</code> attribute. For example, if
you have a local checkout of <code>random</code>, you can enter a development environment
for it like this (if the dependencies in the development and packaged version
match):</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span><span class="nb">cd</span><span class="w"> </span>~/src/random
<span class="gp">$ </span>nix-shell<span class="w"> </span>-A<span class="w"> </span>haskellPackages.random.env<span class="w"> </span><span class="s1">&#39;&lt;nixpkgs&gt;&#39;</span>
<span class="gp">[nix-shell:~/src/random]$ </span>ghc-pkg<span class="w"> </span>list
<span class="go">/nix/store/a8hhl54xlzfizrhcf03c1l3f6l9l8qwv-ghc-9.2.4-with-packages/lib/ghc-9.2.4/package.conf.d</span>
<span class="go"> Cabal-3.6.3.0</span>
<span class="go"> array-0.5.4.0</span>
<span class="go"> base-4.16.3.0</span>
<span class="go"> binary-0.8.9.0</span>
<span class="go"> …</span>
<span class="go"> ghc-9.2.4</span>
<span class="go"> …</span>
</code></pre></div>
<p>As you can see, the environment contains a GHC which is set up so it finds all
dependencies of <code>random</code>. Note that this environment does not mirror
the environment used to build the package, but is intended as a convenient
tool for development and simple debugging. <code>env</code> relies on the <code>ghcWithPackages</code>
wrapper which automatically injects a pre-populated package-db into every
GHC invocation. In contrast, using <code>nix-shell -A haskellPackages.random</code> will
not result in an environment in which the dependencies are in GHCs package
database. Instead, the Haskell builder will pass in all dependencies explicitly
via configure flags.</p>
<p><code>env</code> mirrors the normal derivation environment in one aspect: It does not include
familiar development tools like <code>cabal-install</code>, since we rely on plain <code>Setup.hs</code>
to build all packages. However, <code>cabal-install</code> will work as expected if in
<code>PATH</code> (e.g. when installed globally and using a <code>nix-shell</code> without <code>--pure</code>).
A declarative and pure way of adding arbitrary development tools is provided
via <a href="#haskell-shellFor"><code>shellFor</code></a>.</p>
<p>When using <code>cabal-install</code> for dependency resolution you need to be a bit
careful to achieve build purity. <code>cabal-install</code> will find and use all
dependencies installed from the packages <code>env</code> via Nix, but it will also
consult Hackage to potentially download and compile dependencies if it can’t
find a valid build plan locally. To prevent this you can either never run
<code>cabal update</code>, remove the cabal database from your <code>~/.cabal</code> folder or run
<code>cabal</code> with <code>--offline</code>. Note though, that for some usecases <code>cabal2nix</code> needs
the local Hackage db.</p>
<p>Often you won't work on a package that is already part of <code>haskellPackages</code> or
Hackage, so we first need to write a Nix expression to obtain the development
environment from. Luckily, we can generate one very easily from an already
existing cabal file using <code>cabal2nix</code>:</p>
<div class="highlight"><pre><span></span><code><span class="gp">$ </span>ls
<span class="go">my-project.cabal src …</span>
<span class="gp">$ </span>cabal2nix<span class="w"> </span>./.<span class="w"> </span>&gt;<span class="w"> </span>my-project.nix
</code></pre></div>
<p>The generated Nix expression evaluates to a function ready to be
<code>callPackage</code>-ed. For now, we can add a minimal <code>default.nix</code> which does just
that:</p>
<div class="highlight"><pre><span></span><code><span class="c1"># Retrieve nixpkgs impurely from NIX_PATH for now, you can pin it instead, of course.</span>
<span class="p">{</span> pkgs <span class="o">?</span> <span class="nb">import</span> <span class="l">&lt;nixpkgs&gt;</span> <span class="p">{}</span> <span class="p">}:</span> <span class="s2">&quot;use the nixpkgs default haskell package set</span>
<span class="s2">pkgs.haskellPackages.callPackage ./my-project.nix { }</span>
</code></pre></div>
<p>Using <code>nix-build default.nix</code> we can now build our project, but we can also
enter a shell with all the package's dependencies available using <code>nix-shell
-A env default.nix</code>. If you have <code>cabal-install</code> installed globally, it'll work
inside the shell as expected.</p>
<h3 id="haskell-shellFor">shellFor</h3>
<p>Having to install tools globally is obviously not great, especially if you want
to provide a batteries-included <code>shell.nix</code> with your project. Luckily there's a
proper tool for making development environments out of packages' build
environments: <code>shellFor</code>, a function exposed by every haskell package set. It
takes the following arguments and returns a derivation which is suitable as a
development environment inside <code>nix-shell</code>:</p>
<p><code>packages</code>
: This argument is used to select the packages for which to build the
development environment. This should be a function which takes a haskell package
set and returns a list of packages. <code>shellFor</code> will pass the used package set to
this function and include all dependencies of the returned package in the build
environment. This means you can reuse Nix expressions of packages included in
nixpkgs, but also use local Nix expressions like this: <code>hpkgs: [
(hpkgs.callPackage ./my-project.nix { }) ]</code>.</p>
<p><code>nativeBuildInputs</code>
: Expects a list of derivations to add as build tools to the build environment.
This is the place to add packages like <code>cabal-install</code>, <code>doctest</code> or <code>hlint</code>.
Defaults to <code>[]</code>.</p>
<p><code>buildInputs</code>
: Expects a list of derivations to add as library dependencies, like <code>openssl</code>.
This is rarely necessary as the haskell package expressions usually track system
dependencies as well. Defaults to <code>[]</code>. (see also
<a href="#haskell-derivation-deps">derivation dependencies</a>)</p>
<p><code>withHoogle</code>
: If this is true, <code>hoogle</code> will be added to <code>nativeBuildInputs</code>.
Additionally, its database will be populated with all included dependencies,
so you'll be able search through the documentation of your dependencies.
Defaults to <code>false</code>.</p>
<p><code>genericBuilderArgsModifier</code>
: This argument accepts a function allowing you to modify the arguments passed
to <code>mkDerivation</code> in order to create the development environment. For example,
<code>args: { doCheck = false; }</code> would cause the environment to not include any test
dependencies. Defaults to <code>lib.id</code>.</p>
<p><code>doBenchmark</code>
: This is a shortcut for enabling <code>doBenchmark</code> via <code>genericBuilderArgsModifier</code>.
Setting it to <code>true</code> will cause the development environment to include all
benchmark dependencies which would be excluded by default. Defaults to <code>false</code>.</p>
<p>One neat property of <code>shellFor</code> is that it allows you to work on multiple
packages using the same environment in conjunction with
<a href="https://cabal.readthedocs.io/en/latest/cabal-project.html">cabal.project files</a>.
Say our example above depends on <code>distribution-nixpkgs</code> and we have a project
file set up for both, we can add the following <code>shell.nix</code> expression:</p>
<div class="highlight"><pre><span></span><code><span class="p">{</span> pkgs <span class="o">?</span> <span class="nb">import</span> <span class="l">&lt;nixpkgs&gt;</span> <span class="p">{}</span> <span class="p">}:</span>
pkgs<span class="o">.</span>haskellPackages<span class="o">.</span>shellFor <span class="p">{</span>
<span class="ss">packages</span> <span class="o">=</span> hpkgs<span class="p">:</span> <span class="p">[</span>
<span class="c1"># reuse the nixpkgs for this package</span>
hpkgs<span class="o">.</span>distribution-nixpkgs
<span class="c1"># call our generated Nix expression manually</span>
<span class="p">(</span>hpkgs<span class="o">.</span>callPackage <span class="l">./my-project/my-project.nix</span> <span class="p">{</span> <span class="p">})</span>
<span class="p">];</span>
<span class="c1"># development tools we use</span>
<span class="ss">nativeBuildInputs</span> <span class="o">=</span> <span class="p">[</span>
pkgs<span class="o">.</span>cabal-install
pkgs<span class="o">.</span>haskellPackages<span class="o">.</span>doctest
pkgs<span class="o">.</span>cabal2nix
<span class="p">];</span>
<span class="c1"># Extra arguments are added to mkDerivation&#39;s arguments as-is.</span>
<span class="c1"># Since it adds all passed arguments to the shell environment,</span>
<span class="c1"># we can use this to set the environment variable the `Paths_`</span>
<span class="c1"># module of distribution-nixpkgs uses to search for bundled</span>
<span class="c1"># files.</span>
<span class="c1"># See also: https://cabal.readthedocs.io/en/latest/cabal-package.html#accessing-data-files-from-package-code</span>
<span class="ss">distribution_nixpkgs_datadir</span> <span class="o">=</span> <span class="nb">toString</span> <span class="l">./distribution-nixpkgs</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div>
<!-- TODO(@sternenseemann): deps are not included if not selected -->
<h3 id="haskell-language-server">haskell-language-server</h3>
<p>To use HLS in short: Install <code>pkgs.haskell-language-server</code> e.g. in
<code>nativeBuildInputs</code> in <code>shellFor</code> and use the <code>haskell-language-server-wrapper</code>
command to run it. See the <a href="https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor">HLS user guide</a> on how to configure your text
editor to use HLS and how to test your setup.</p>
<p>HLS needs to be compiled with the GHC version of the project you use it
on.</p>
<p><code>pkgs.haskell-language-server</code> provides
<code>haskell-language-server-wrapper</code>, <code>haskell-language-server</code>
and <code>haskell-language-server-x.x.x</code>
binaries, where <code>x.x.x</code> is the GHC version for which it is compiled. By
default, it only includes binaries for the current GHC version, to reduce
closure size. The closure size is large, because HLS needs to be dynamically
linked to work reliably. You can override the list of supported GHC versions
with e.g.</p>
<p><div class="highlight"><pre><span></span><code>pkgs<span class="o">.</span>haskell-language-server<span class="o">.</span>override <span class="p">{</span> <span class="ss">supportedGhcVersions</span> <span class="o">=</span> <span class="p">[</span> <span class="s2">&quot;90&quot;</span> <span class="s2">&quot;94&quot;</span> <span class="p">];</span> <span class="p">}</span>
</code></pre></div>
Where all strings <code>version</code> are allowed such that
<code>haskell.packages.ghc${version}</code> is an existing package set.</p>
<p>When you run <code>haskell-language-server-wrapper</code> it will detect the GHC
version used by the project you are working on (by asking e.g. cabal or
stack) and pick the appropriate versioned binary from your path.</p>
<p>Be careful when installing HLS globally and using a pinned nixpkgs for a
Haskell project in a <code>nix-shell</code>. If the nixpkgs versions deviate to much
(e.g., use different <code>glibc</code> versions) the <code>haskell-language-server-?.?.?</code>
executable will try to detect these situations and refuse to start. It is
recommended to obtain HLS via <code>nix-shell</code> from the nixpkgs version pinned in
there instead.</p>
<p>The top level <code>pkgs.haskell-language-server</code> attribute is just a convenience
wrapper to make it possible to install HLS for multiple GHC versions at the
same time. If you know, that you only use one GHC version, e.g., in a project
specific <code>nix-shell</code> you can use
<code>pkgs.haskellPackages.haskell-language-server</code> or
<code>pkgs.haskell.packages.*.haskell-language-server</code> from the package set you use.</p>
<p>If you use <code>nix-shell</code> for your development environments remember to start your
editor in that environment. You may want to use something like <code>direnv</code> and/or an
editor plugin to achieve this.</p>
<h2 id="haskell-overriding-haskell-packages">Overriding Haskell packages</h2>
<h3 id="haskell-overriding-a-single-package">Overriding a single package</h3>
<!-- TODO(@sternenseemann): we should document /somewhere/ that base == null etc. -->
<p>Like many language specific subsystems in nixpkgs, the Haskell infrastructure
also has its own quirks when it comes to overriding. Overriding of the <em>inputs</em>
to a package at least follows the standard procedure. For example, imagine you
need to build <code>nix-tree</code> with a more recent version of <code>brick</code> than the default
one provided by <code>haskellPackages</code>:</p>
<div class="highlight"><pre><span></span><code>haskellPackages<span class="o">.</span>nix-tree<span class="o">.</span>override <span class="p">{</span>
<span class="ss">brick</span> <span class="o">=</span> haskellPackages<span class="o">.</span>brick_0_67<span class="p">;</span>
<span class="p">}</span>
</code></pre></div>
<!-- TODO(@sternenseemann): This belongs in the next section
One common problem you may run into with such an override is the build failing
with “abort because of serious configure-time warning from Cabal”. When scrolling
up, you'll usually notice that Cabal noticed that more than one versions of the same
package was present in the dependency graph. This typically causes a later compilation
failure (the error message `haskellPackages.mkDerivation` produces tries to save
you the time of finding this out yourself, but if you wish to do so, you can
disable it using `allowInconsistentDependencies`). Luckily, `haskellPackages` provides
you with a tool to deal with this. `overrideScope` creates a new `haskellPackages`
instance with the override applied *globally* for this package, so the dependency
closure automatically uses a consistent version of the overridden package. E. g.
if `haskell-ci` needs a recent version of `Cabal`, but also uses other packages
that depend on that library, you may want to use:
<div class="highlight"><pre><span></span><code>haskellPackages<span class="o">.</span>haskell-ci<span class="o">.</span>overrideScope <span class="p">(</span>self<span class="p">:</span> super<span class="p">:</span> <span class="p">{</span>
<span class="ss">Cabal</span> <span class="o">=</span> self<span class="o">.</span>Cabal_3_6_2_0<span class="p">;</span>
<span class="p">})</span>
</code></pre></div>
-->
<p>The custom interface comes into play when you want to override the arguments
passed to <code>haskellPackages.mkDerivation</code>. For this, the function <code>overrideCabal</code>
from <code>haskell.lib.compose</code> is used. E.g., if you want to install a man page
that is distributed with the package, you can do something like this:</p>
<div class="highlight"><pre><span></span><code>haskell<span class="o">.</span>lib<span class="o">.</span>compose<span class="o">.</span>overrideCabal <span class="p">(</span>drv<span class="p">:</span> <span class="p">{</span>
<span class="ss">postInstall</span> <span class="o">=</span> <span class="s s-Multiline">&#39;&#39;</span>
<span class="s s-Multiline"> </span><span class="si">${</span>drv<span class="o">.</span>postInstall <span class="ow">or</span> <span class="s2">&quot;&quot;</span><span class="si">}</span>
<span class="s s-Multiline"> install -Dm644 man/pnbackup.1 -t $out/share/man/man1</span>
<span class="s s-Multiline"> &#39;&#39;</span><span class="p">;</span>
<span class="p">})</span> haskellPackages<span class="o">.</span>pnbackup
</code></pre></div>
<p><code>overrideCabal</code> takes two arguments:</p>
<ol>
<li>A function which receives all arguments passed to <code>haskellPackages.mkDerivation</code>
before and returns a set of arguments to replace (or add) with a new value.</li>
<li>The Haskell derivation to override.</li>
</ol>
<p>The arguments are ordered so that you can easily create helper functions by making
use of currying:</p>
<div class="highlight"><pre><span></span><code><span class="k">let</span>
<span class="ss">installManPage</span> <span class="o">=</span> haskell<span class="o">.</span>lib<span class="o">.</span>compose<span class="o">.</span>overrideCabal <span class="p">(</span>drv<span class="p">:</span> <span class="p">{</span>
<span class="ss">postInstall</span> <span class="o">=</span> <span class="s s-Multiline">&#39;&#39;</span>
<span class="s s-Multiline"> </span><span class="si">${</span>drv<span class="o">.</span>postInstall <span class="ow">or</span> <span class="s2">&quot;&quot;</span><span class="si">}</span>
<span class="s s-Multiline"> install -Dm644 man/</span><span class="si">${</span>drv<span class="o">.</span>pname<span class="si">}</span><span class="s s-Multiline">.1 -t &quot;$out/share/man/man1&quot;</span>
<span class="s s-Multiline"> &#39;&#39;</span><span class="p">;</span>
<span class="p">});</span>
<span class="k">in</span>
installManPage haskellPackages<span class="o">.</span>pnbackup
</code></pre></div>
<p>In fact, <code>haskell.lib.compose</code> already provides lots of useful helpers for common
tasks, detailed in the next section. They are also structured in such a way that
they can be combined using <code>lib.pipe</code>:</p>
<div class="highlight"><pre><span></span><code>lib<span class="o">.</span>pipe my-haskell-package <span class="p">[</span>
<span class="c1"># lift version bounds on dependencies</span>
haskell<span class="o">.</span>lib<span class="o">.</span>compose<span class="o">.</span>doJailbreak
<span class="c1"># disable building the haddock documentation</span>
haskell<span class="o">.</span>lib<span class="o">.</span>compose<span class="o">.</span>dontHaddock
<span class="c1"># pass extra package flag to Cabal&#39;s configure step</span>
<span class="p">(</span>haskell<span class="o">.</span>lib<span class="o">.</span>compose<span class="o">.</span>enableCabalFlag <span class="s2">&quot;myflag&quot;</span><span class="p">)</span>
<span class="p">]</span>
</code></pre></div>
<h4 id="haskell-haskell.lib.compose"><code>haskell.lib.compose</code></h4>
<p>The base interface for all overriding is the following function:</p>
<p><code>overrideCabal f drv</code>
: Takes the arguments passed to obtain <code>drv</code> to <code>f</code> and uses the resulting
attribute set to update the argument set. Then a recomputed version of <code>drv</code>
using the new argument set is returned.</p>
<!--
TODO(@sternenseemann): ideally we want to be more detailed here as well, but
I want to avoid the documentation having to be kept in sync in too many places.
We already document this stuff in the mkDerivation section and lib/compose.nix.
Ideally this section would be generated from the latter in the future.
-->
<p>All other helper functions are implemented in terms of <code>overrideCabal</code> and make
common overrides shorter and more complicate ones trivial. The simple overrides
which only change a single argument are only described very briefly in the
following overview. Refer to the
<a href="#haskell-mkderivation">documentation of <code>haskellPackages.mkDerivation</code></a>
for a more detailed description of the effects of the respective arguments.</p>
<h5 id="haskell-packaging-helpers">Packaging Helpers</h5>
<p><code>overrideSrc { src, version } drv</code>
: Replace the source used for building <code>drv</code> with the path or derivation given
as <code>src</code>. The <code>version</code> attribute is optional. Prefer this function over
overriding <code>src</code> via <code>overrideCabal</code>, since it also automatically takes care of
removing any Hackage revisions.</p>
<!-- TODO(@sternenseemann): deprecated
`generateOptparseApplicativeCompletions list drv`
: Generate and install shell completion files for the installed executables whose
names are given via `list`. The executables need to be using `optparse-applicative`
for this to work.
-->
<p><code>justStaticExecutables drv</code>
: Only build and install the executables produced by <code>drv</code>, removing everything
that may refer to other Haskell packages' store paths (like libraries and
documentation). This dramatically reduces the closure size of the resulting
derivation. Note that the executables are only statically linked against their
Haskell dependencies, but will still link dynamically against libc, GMP and
other system library dependencies.</p>
<p>If a library or its dependencies use their Cabal-generated
<code>Paths_*</code> module, this may not work as well if GHC's dead code elimination is
unable to remove the references to the dependency's store path that module
contains.
As a consequence, an unused reference may be created from the static binary to such a <em>library</em> store path.
(See <a href="https://github.com/NixOS/nixpkgs/issues/164630">nixpkgs#164630</a> for more information.)</p>
<p>Importing the <code>Paths_*</code> module may cause builds to fail with this message:</p>
<div class="highlight"><pre><span></span><code>error: output &#39;/nix/store/64k8iw0ryz76qpijsnl9v87fb26v28z8-my-haskell-package-1.0.0.0&#39; is not allowed to refer to the following paths:
/nix/store/5q5s4a07gaz50h04zpfbda8xjs8wrnhg-ghc-9.6.3
</code></pre></div>
<p>If that happens, first disable the check for GHC references and rebuild the
derivation:</p>
<div class="highlight"><pre><span></span><code>pkgs<span class="o">.</span>haskell<span class="o">.</span>lib<span class="o">.</span>overrideCabal
<span class="p">(</span>pkgs<span class="o">.</span>haskell<span class="o">.</span>lib<span class="o">.</span>justStaticExecutables my-haskell-package<span class="p">)</span>
<span class="p">(</span>drv<span class="p">:</span> <span class="p">{</span>
<span class="ss">disallowGhcReference</span> <span class="o">=</span> <span class="no">false</span><span class="p">;</span>
<span class="p">})</span>
</code></pre></div>
<p>Then use <code>strings</code> to determine which libraries are responsible:</p>
<div class="highlight"><pre><span></span><code>$ nix-build ...
$ strings result/bin/my-haskell-binary | grep /nix/store/
...
/nix/store/n7ciwdlg8yyxdhbrgd6yc2d8ypnwpmgq-hs-opentelemetry-sdk-0.0.3.6/bin
...
</code></pre></div>
<p>Finally, use <code>remove-references-to</code> to delete those store paths from the produced output:</p>
<div class="highlight"><pre><span></span><code>pkgs<span class="o">.</span>haskell<span class="o">.</span>lib<span class="o">.</span>overrideCabal
<span class="p">(</span>pkgs<span class="o">.</span>haskell<span class="o">.</span>lib<span class="o">.</span>justStaticExecutables my-haskell-package<span class="p">)</span>
<span class="p">(</span>drv<span class="p">:</span> <span class="p">{</span>
<span class="ss">postInstall</span> <span class="o">=</span> <span class="s s-Multiline">&#39;&#39;</span>
<span class="s s-Multiline"> </span><span class="si">${</span>drv<span class="o">.</span>postInstall <span class="ow">or</span> <span class="s2">&quot;&quot;</span><span class="si">}</span>
<span class="s s-Multiline"> remove-references-to -t </span><span class="si">${</span>pkgs<span class="o">.</span>haskellPackages<span class="o">.</span>hs-opentelemetry-sdk<span class="si">}</span>
<span class="s s-Multiline"> &#39;&#39;</span><span class="p">;</span>
<span class="p">})</span>
</code></pre></div>
<p><code>enableSeparateBinOutput drv</code>
: Install executables produced by <code>drv</code> to a separate <code>bin</code> output. This
has a similar effect as <code>justStaticExecutables</code>, but preserves the libraries
and documentation in the <code>out</code> output alongside the <code>bin</code> output with a
much smaller closure size.</p>
<p><code>markBroken drv</code>
: Sets the <code>broken</code> flag to <code>true</code> for <code>drv</code>.</p>
<p><code>markUnbroken drv</code>, <code>unmarkBroken drv</code>
: Set the <code>broken</code> flag to <code>false</code> for <code>drv</code>.</p>
<p><code>doDistribute drv</code>
: Updates <code>hydraPlatforms</code> so that Hydra will build <code>drv</code>. This is
sometimes necessary when working with versioned packages in
<code>haskellPackages</code> which are not built by default.</p>
<p><code>dontDistribute drv</code>
: Sets <code>hydraPlatforms</code> to <code>[]</code>, causing Hydra to skip this package
altogether. Useful if it fails to evaluate cleanly and is causing
noise in the evaluation errors tab on Hydra.</p>
<h5 id="haskell-development-helpers">Development Helpers</h5>
<p><code>sdistTarball drv</code>
: Create a source distribution tarball like those found on Hackage
instead of building the package <code>drv</code>.</p>
<p><code>documentationTarball drv</code>
: Create a documentation tarball suitable for uploading to Hackage
instead of building the package <code>drv</code>.</p>
<p><code>buildFromSdist drv</code>
: Uses <code>sdistTarball drv</code> as the source to compile <code>drv</code>. This helps to catch
packaging bugs when building from a local directory, e.g. when required files
are missing from <code>extra-source-files</code>.</p>
<p><code>failOnAllWarnings drv</code>
: Enables all warnings GHC supports and makes it fail the build if any of them
are emitted.</p>
<!-- TODO(@sternenseemann):
`checkUnusedPackages opts drv`
: Adds an extra check to `postBuild` which fails the build if any dependency
taken as an input is not used. The `opts` attribute set allows relaxing this
check.
-->
<p><code>enableDWARFDebugging drv</code>
: Compiles the package with additional debug symbols enabled, useful
for debugging with e.g. <code>gdb</code>.</p>
<p><code>doStrip drv</code>
: Sets <code>doStrip</code> to <code>true</code> for <code>drv</code>.</p>
<p><code>dontStrip drv</code>
: Sets <code>doStrip</code> to <code>false</code> for <code>drv</code>.</p>
<!-- TODO(@sternenseemann): shellAware -->
<h5 id="haskell-trivial-helpers">Trivial Helpers</h5>
<p><code>doJailbreak drv</code>
: Sets the <code>jailbreak</code> argument to <code>true</code> for <code>drv</code>.</p>
<p><code>dontJailbreak drv</code>
: Sets the <code>jailbreak</code> argument to <code>false</code> for <code>drv</code>.</p>
<p><code>doHaddock drv</code>
: Sets <code>doHaddock</code> to <code>true</code> for <code>drv</code>.</p>
<p><code>dontHaddock drv</code>
: Sets <code>doHaddock</code> to <code>false</code> for <code>drv</code>. Useful if the build of a package is
failing because of e.g. a syntax error in the Haddock documentation.</p>
<p><code>doHyperlinkSource drv</code>
: Sets <code>hyperlinkSource</code> to <code>true</code> for <code>drv</code>.</p>
<p><code>dontHyperlinkSource drv</code>
: Sets <code>hyperlinkSource</code> to <code>false</code> for <code>drv</code>.</p>
<p><code>doCheck drv</code>
: Sets <code>doCheck</code> to <code>true</code> for <code>drv</code>.</p>
<p><code>dontCheck drv</code>
: Sets <code>doCheck</code> to <code>false</code> for <code>drv</code>. Useful if a package has a broken,
flaky or otherwise problematic test suite breaking the build.</p>
<p><code>dontCheckIf condition drv</code>
: Sets <code>doCheck</code> to <code>false</code> for <code>drv</code>, but only if <code>condition</code> applies.
Otherwise it's a no-op. Useful to conditionally disable tests for a package
without interfering with previous overrides or default values.</p>
<!-- Purposefully omitting the non-list variants here. They are a bit
ugly, and we may want to deprecate them at some point. -->
<p><code>appendConfigureFlags list drv</code>
: Adds the strings in <code>list</code> to the <code>configureFlags</code> argument for <code>drv</code>.</p>
<p><code>enableCabalFlag flag drv</code>
: Makes sure that the Cabal flag <code>flag</code> is enabled in Cabal's configure step.</p>
<p><code>disableCabalFlag flag drv</code>
: Makes sure that the Cabal flag <code>flag</code> is disabled in Cabal's configure step.</p>
<p><code>appendBuildFlags list drv</code>
: Adds the strings in <code>list</code> to the <code>buildFlags</code> argument for <code>drv</code>.</p>
<!-- TODO(@sternenseemann): removeConfigureFlag -->
<p><code>appendPatches list drv</code>
: Adds the <code>list</code> of derivations or paths to the <code>patches</code> argument for <code>drv</code>.</p>
<!-- TODO(@sternenseemann): link dep section -->
<p><code>addBuildTools list drv</code>
: Adds the <code>list</code> of derivations to the <code>buildTools</code> argument for <code>drv</code>.</p>
<p><code>addExtraLibraries list drv</code>
: Adds the <code>list</code> of derivations to the <code>extraLibraries</code> argument for <code>drv</code>.</p>
<p><code>addBuildDepends list drv</code>
: Adds the <code>list</code> of derivations to the <code>buildDepends</code> argument for <code>drv</code>.</p>
<p><code>addTestToolDepends list drv</code>
: Adds the <code>list</code> of derivations to the <code>testToolDepends</code> argument for <code>drv</code>.</p>
<p><code>addPkgconfigDepends list drv</code>
: Adds the <code>list</code> of derivations to the <code>pkg-configDepends</code> argument for <code>drv</code>.</p>
<p><code>addSetupDepends list drv</code>
: Adds the <code>list</code> of derivations to the <code>setupHaskellDepends</code> argument for <code>drv</code>.</p>
<p><code>doBenchmark drv</code>
: Set <code>doBenchmark</code> to <code>true</code> for <code>drv</code>. Useful if your development
environment is missing the dependencies necessary for compiling the
benchmark component.</p>
<p><code>dontBenchmark drv</code>
: Set <code>doBenchmark</code> to <code>false</code> for <code>drv</code>.</p>
<p><code>setBuildTargets drv list</code>
: Sets the <code>buildTarget</code> argument for <code>drv</code> so that the targets specified in <code>list</code> are built.</p>
<p><code>doCoverage drv</code>
: Sets the <code>doCoverage</code> argument to <code>true</code> for <code>drv</code>.</p>
<p><code>dontCoverage drv</code>
: Sets the <code>doCoverage</code> argument to <code>false</code> for <code>drv</code>.</p>
<p><code>enableExecutableProfiling drv</code>
: Sets the <code>enableExecutableProfiling</code> argument to <code>true</code> for <code>drv</code>.</p>
<p><code>disableExecutableProfiling drv</code>
: Sets the <code>enableExecutableProfiling</code> argument to <code>false</code> for <code>drv</code>.</p>
<p><code>enableLibraryProfiling drv</code>
: Sets the <code>enableLibraryProfiling</code> argument to <code>true</code> for <code>drv</code>.</p>
<p><code>disableLibraryProfiling drv</code>
: Sets the <code>enableLibraryProfiling</code> argument to <code>false</code> for <code>drv</code>.</p>
<h4 id="haskell-package-set-lib-functions">Library functions in the Haskell package sets</h4>
<p>Some library functions depend on packages from the Haskell package sets. Thus they are
exposed from those instead of from <code>haskell.lib.compose</code> which can only access what is
passed directly to it. When using the functions below, make sure that you are obtaining them
from the same package set (<code>haskellPackages</code>, <code>haskell.packages.ghc944</code> etc.) as the packages
you are working with or – even better – from the <code>self</code>/<code>final</code> fix point of your overlay to
<code>haskellPackages</code>.</p>
<p>Note: Some functions like <code>shellFor</code> that are not intended for overriding per se, are omitted
in this section. <!-- TODO(@sternenseemann): note about ifd section --></p>
<p><code>cabalSdist { src, name ? ... }</code>
: Generates the Cabal sdist tarball for <code>src</code>, suitable for uploading to Hackage.
Contrary to <code>haskell.lib.compose.sdistTarball</code>, it uses <code>cabal-install</code> over <code>Setup.hs</code>,
so it is usually faster: No build dependencies need to be downloaded, and we can
skip compiling <code>Setup.hs</code>.</p>
<p><code>buildFromCabalSdist drv</code>
: Build <code>drv</code>, but run its <code>src</code> attribute through <code>cabalSdist</code> first. Useful for catching
files necessary for compilation that are missing from the sdist.</p>
<p><code>generateOptparseApplicativeCompletions list drv</code>
: Generate and install shell completion files for the installed executables whose
names are given via <code>list</code>. The executables need to be using <code>optparse-applicative</code>
for <a href="https://github.com/pcapriotti/optparse-applicative/blob/7726b63796aa5d0df82e926d467f039b78ca09e2/README.md#bash-zsh-and-fish-completions">this to work</a>.
Note that this feature is automatically disabled when cross-compiling, since it
requires executing the binaries in question.</p>
<h2 id="haskell-import-from-derivation">Import-from-Derivation helpers</h2>
<h3 id="haskell-cabal2nix">cabal2nix</h3>
<p><a href="https://github.com/nixos/cabal2nix"><code>cabal2nix</code></a> can generate Nix package definitions for arbitrary
Haskell packages using <a href="https://nixos.org/manual/nix/stable/language/import-from-derivation">import from derivation</a>.
<code>cabal2nix</code> will generate Nix expressions that look like this:</p>
<div class="highlight"><pre><span></span><code><span class="c1"># cabal get mtl-2.2.1 &amp;&amp; cd mtl-2.2.1 &amp;&amp; cabal2nix .</span>
<span class="p">{</span> mkDerivation<span class="p">,</span> base<span class="p">,</span> lib<span class="p">,</span> transformers <span class="p">}:</span>
mkDerivation <span class="p">{</span>
<span class="ss">pname</span> <span class="o">=</span> <span class="s2">&quot;mtl&quot;</span><span class="p">;</span>
<span class="ss">version</span> <span class="o">=</span> <span class="s2">&quot;2.2.1&quot;</span><span class="p">;</span>
<span class="ss">src</span> <span class="o">=</span> <span class="l">./.</span><span class="p">;</span>
<span class="ss">libraryHaskellDepends</span> <span class="o">=</span> <span class="p">[</span> base transformers <span class="p">];</span>
<span class="ss">homepage</span> <span class="o">=</span> <span class="s2">&quot;http://github.com/ekmett/mtl&quot;</span><span class="p">;</span>
<span class="ss">description</span> <span class="o">=</span> <span class="s2">&quot;Monad classes, using functional dependencies&quot;</span><span class="p">;</span>
<span class="ss">license</span> <span class="o">=</span> lib<span class="o">.</span>licenses<span class="o">.</span>bsd3<span class="p">;</span>
<span class="p">}</span>
</code></pre></div>
<p>This expression should be called with <code>haskellPackages.callPackage</code>, which will
supply <a href="#haskell-mkderivation"><code>haskellPackages.mkDerivation</code></a> and the Haskell
dependencies as arguments.</p>
<p><code>callCabal2nix name src args</code>
: Create a package named <code>name</code> from the source derivation <code>src</code> using
<code>cabal2nix</code>.</p>
<p><code>args</code> are extra arguments provided to <code>haskellPackages.callPackage</code>.</p>
<p><code>callCabal2nixWithOptions name src opts args</code>
: Create a package named <code>name</code> from the source derivation <code>src</code> using
<code>cabal2nix</code>.</p>
<p><code>opts</code> are extra options for calling <code>cabal2nix</code>. If <code>opts</code> is a string, it
will be used as extra command line arguments for <code>cabal2nix</code>, e.g. <code>--subpath
path/to/dir/containing/cabal-file</code>. Otherwise, <code>opts</code> should be an AttrSet
which can contain the following attributes:</p>
<p><code>extraCabal2nixOptions</code>
: Extra command line arguments for <code>cabal2nix</code>.</p>
<p><code>srcModifier</code>
: A function which is used to modify the given <code>src</code> instead of the default
filter.</p>
<div class="highlight"><pre><span></span><code>The default source filter will remove all files from `src` except for
`.cabal` files and `package.yaml` files.
</code></pre></div>
<!--
`callHackage`
: TODO
`callHackageDirect`
: TODO
`developPackage`
: TODO
-->
<!--
TODO(@NixOS/haskell): finish these planned sections
### Overriding the entire package set
## Contributing {#haskell-contributing}
### Fixing a broken package {#haskell-fixing-a-broken-package}
### Package set generation {#haskell-package-set-generation}
### Packaging a Haskell project
### Backporting {#haskell-backporting}
Backporting changes to a stable NixOS version in general is covered
in nixpkgs' `CONTRIBUTING.md` in general. In particular refer to the
[backporting policy](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#criteria-for-backporting-changes)
to check if the change you have in mind may be backported.
This section focuses on how to backport a package update (e.g. a
bug fix or security release). Fixing a broken package works like
it does for the unstable branches.
-->
<h2 id="haskell-faq">F.A.Q.</h2>
<h3 id="haskell-why-not-covered">Why is topic X not covered in this section? Why is section Y missing?</h3>
<p>We have been working on <a href="https://github.com/NixOS/nixpkgs/issues/121403">moving the nixpkgs Haskell documentation back into the
nixpkgs manual</a>. Since this
process has not been completed yet, you may find some topics missing here
covered in the old <a href="https://haskell4nix.readthedocs.io/">haskell4nix docs</a>.</p>
<p>If you feel any important topic is not documented at all, feel free to comment
on the issue linked above.</p>
<h3 id="haskell-faq-override-profiling">How to enable or disable profiling builds globally?</h3>
<p>By default, Nixpkgs builds a profiling version of each Haskell library. The
exception to this rule are some platforms where it is disabled due to concerns
over output size. You may want to…</p>
<ul>
<li>
<p>…enable profiling globally so that you can build a project you are working on
with profiling ability giving you insight in the time spent across your code
and code you depend on using <a href="https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html">GHC's profiling feature</a>.</p>
</li>
<li>
<p>…disable profiling (globally) to reduce the time spent building the profiling
versions of libraries which a significant amount of build time is spent on
(although they are not as expensive as the “normal” build of a Haskell library).</p>
</li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The method described below affects the build of all libraries in the
respective Haskell package set as well as GHC. If your choices differ from
Nixpkgs' default for your (host) platform, you will lose the ability to
substitute from the official binary cache.</p>
</div>
<p>If you are concerned about build times and thus want to disable profiling, it
probably makes sense to use <code>haskell.lib.compose.disableLibraryProfiling</code> (see
<a href="#haskell-trivial-helpers"></a>) on the packages you are building locally while
continuing to substitute their dependencies and GHC.</p>
<p>Since we need to change the profiling settings for the desired Haskell package
set <em>and</em> GHC (as the core libraries like <code>base</code>, <code>filepath</code> etc. are bundled
with GHC), it is recommended to use overlays for Nixpkgs to change them.
Since the interrelated parts, i.e. the package set and GHC, are connected
via the Nixpkgs fixpoint, we need to modify them both in a way that preserves
their connection (or else we'd have to wire it up again manually). This is
achieved by changing GHC and the package set in separate overlays to prevent
the package set from pulling in GHC from <code>prev</code>.</p>
<p>The result is two overlays like the ones shown below. Adjustable parts are
annotated with comments, as are any optional or alternative ways to achieve
the desired profiling settings without causing too many rebuilds.</p>
<!-- TODO(@sternenseemann): buildHaskellPackages != haskellPackages with this overlay,
affected by https://github.com/NixOS/nixpkgs/issues/235960 which needs to be fixed
properly still.
-->
<div class="highlight"><pre><span></span><code><span class="k">let</span>
<span class="c1"># Name of the compiler and package set you want to change. If you are using</span>
<span class="c1"># the default package set `haskellPackages`, you need to look up what version</span>
<span class="c1"># of GHC it currently uses (note that this is subject to change).</span>
<span class="ss">ghcName</span> <span class="o">=</span> <span class="s2">&quot;ghc92&quot;</span><span class="p">;</span>
<span class="c1"># Desired new setting</span>
<span class="ss">enableProfiling</span> <span class="o">=</span> <span class="no">true</span><span class="p">;</span>
<span class="k">in</span>
<span class="p">[</span>
<span class="c1"># The first overlay modifies the GHC derivation so that it does or does not</span>
<span class="c1"># build profiling versions of the core libraries bundled with it. It is</span>
<span class="c1"># recommended to only use such an overlay if you are enabling profiling on a</span>
<span class="c1"># platform that doesn&#39;t by default, because compiling GHC from scratch is</span>
<span class="c1"># quite expensive.</span>
<span class="p">(</span>final<span class="p">:</span> prev<span class="p">:</span>
<span class="k">let</span>
<span class="k">inherit</span> <span class="p">(</span>final<span class="p">)</span> lib<span class="p">;</span>
<span class="k">in</span>
<span class="p">{</span>
<span class="ss">haskell</span> <span class="o">=</span> prev<span class="o">.</span>haskell <span class="o">//</span> <span class="p">{</span>
<span class="ss">compiler</span> <span class="o">=</span> prev<span class="o">.</span>haskell<span class="o">.</span>compiler <span class="o">//</span> <span class="p">{</span>
<span class="si">${</span>ghcName<span class="si">}</span> <span class="o">=</span> prev<span class="o">.</span>haskell<span class="o">.</span>compiler<span class="o">.</span><span class="si">${</span>ghcName<span class="si">}</span><span class="o">.</span>override <span class="p">{</span>
<span class="c1"># Unfortunately, the GHC setting is named differently for historical reasons</span>
<span class="ss">enableProfiledLibs</span> <span class="o">=</span> enableProfiling<span class="p">;</span>
<span class="p">};</span>
<span class="p">};</span>
<span class="p">};</span>
<span class="p">})</span>
<span class="p">(</span>final<span class="p">:</span> prev<span class="p">:</span>
<span class="k">let</span>
<span class="k">inherit</span> <span class="p">(</span>final<span class="p">)</span> lib<span class="p">;</span>
<span class="ss">haskellLib</span> <span class="o">=</span> final<span class="o">.</span>haskell<span class="o">.</span>lib<span class="o">.</span>compose<span class="p">;</span>
<span class="k">in</span>
<span class="p">{</span>
<span class="ss">haskell</span> <span class="o">=</span> prev<span class="o">.</span>haskell <span class="o">//</span> <span class="p">{</span>
<span class="ss">packages</span> <span class="o">=</span> prev<span class="o">.</span>haskell<span class="o">.</span>packages <span class="o">//</span> <span class="p">{</span>
<span class="si">${</span>ghcName<span class="si">}</span> <span class="o">=</span> prev<span class="o">.</span>haskell<span class="o">.</span>packages<span class="o">.</span><span class="si">${</span>ghcName<span class="si">}</span><span class="o">.</span>override <span class="p">{</span>
<span class="ss">overrides</span> <span class="o">=</span> hfinal<span class="p">:</span> hprev<span class="p">:</span> <span class="p">{</span>
<span class="ss">mkDerivation</span> <span class="o">=</span> args<span class="p">:</span> hprev<span class="o">.</span>mkDerivation <span class="p">(</span>args <span class="o">//</span> <span class="p">{</span>
<span class="c1"># Since we are forcing our ideas upon mkDerivation, this change will</span>
<span class="c1"># affect every package in the package set.</span>
<span class="ss">enableLibraryProfiling</span> <span class="o">=</span> enableProfiling<span class="p">;</span>
<span class="c1"># To actually use profiling on an executable, executable profiling</span>
<span class="c1"># needs to be enabled for the executable you want to profile. You</span>
<span class="c1"># can either do this globally or…</span>
<span class="ss">enableExecutableProfiling</span> <span class="o">=</span> enableProfiling<span class="p">;</span>
<span class="p">});</span>
<span class="c1"># …only for the package that contains an executable you want to profile.</span>
<span class="c1"># That saves on unnecessary rebuilds for packages that you only depend</span>
<span class="c1"># on for their library, but also contain executables (e.g. pandoc).</span>
<span class="ss">my-executable</span> <span class="o">=</span> haskellLib<span class="o">.</span>enableExecutableProfiling hprev<span class="o">.</span>my-executable<span class="p">;</span>
<span class="c1"># If you are disabling profiling to save on build time, but want to</span>
<span class="c1"># retain the ability to substitute from the binary cache. Drop the</span>
<span class="c1"># override for mkDerivation above and instead have an override like</span>
<span class="c1"># this for the specific packages you are building locally and want</span>
<span class="c1"># to make cheaper to build.</span>
<span class="ss">my-library</span> <span class="o">=</span> haskellLib<span class="o">.</span>disableLibraryProfiling hprev<span class="o">.</span>my-library<span class="p">;</span>
<span class="p">};</span>
<span class="p">};</span>
<span class="p">};</span>
<span class="p">};</span>
<span class="p">})</span>
<span class="p">]</span>
</code></pre></div>
<!-- TODO(@sternenseemann): write overriding mkDerivation, overriding GHC, and
overriding the entire package set sections and link to them from here where
relevant.
-->
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
<div class="md-copyright__highlight">
Licenced MIT
</div>
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
<div class="md-social">
<a href="https://git.auxolotl.org/auxolotl/docs" target="_blank" rel="noopener" title="Aux Docs Repo" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.777 0a2.9 2.9 0 1 1-2.529 4.322H12.91a4.266 4.266 0 0 0-4.265 4.195v2.118a7.076 7.076 0 0 1 4.147-1.42l.118-.002h1.338a2.9 2.9 0 0 1 5.43 1.422 2.9 2.9 0 0 1-5.43 1.422H12.91a4.266 4.266 0 0 0-4.265 4.195v2.319A2.9 2.9 0 0 1 7.222 24 2.9 2.9 0 0 1 5.8 18.57V8.589a7.109 7.109 0 0 1 6.991-7.108l.118-.001h1.338A2.9 2.9 0 0 1 16.778 0ZM7.223 19.905a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Zm9.554-10.464a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.39Zm0-7.735a1.194 1.194 0 1 0 0 2.389 1.194 1.194 0 0 0 0-2.389Z"/></svg>
</a>
<a href="https://forum.aux.computer/" target="_blank" rel="noopener" title="Aux Forum" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12.103 0C18.666 0 24 5.485 24 11.997c0 6.51-5.33 11.99-11.9 11.99L0 24V11.79C0 5.28 5.532 0 12.103 0zm.116 4.563a7.395 7.395 0 0 0-6.337 3.57 7.247 7.247 0 0 0-.148 7.22L4.4 19.61l4.794-1.074a7.424 7.424 0 0 0 8.136-1.39 7.256 7.256 0 0 0 1.737-7.997 7.375 7.375 0 0 0-6.84-4.585h-.008z"/></svg>
</a>
<a href="https://wiki.auxolotl.org/" target="_blank" rel="noopener" title="Aux Wiki" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17.801 13.557c.148.098.288.202.417.313 1.854 1.6 3.127 4.656 2.582 7.311-1.091-.255-5.747-1.055-7.638-3.383-.91-1.12-1.366-2.081-1.569-2.885a5.65 5.65 0 0 0 .034-.219c.089.198.197.35.313.466.24.24.521.335.766.372.304.046.594-.006.806-.068l.001.001c.05-.015.433-.116.86-.342.325-.173 2.008-.931 3.428-1.566Zm-7.384 1.435C9.156 16.597 6.6 18.939.614 18.417c.219-1.492 1.31-3.019 2.51-4.11.379-.345.906-.692 1.506-1.009.286.168.598.332.939.486 2.689 1.221 3.903 1.001 4.89.573a1.3 1.3 0 0 0 .054-.025 6.156 6.156 0 0 0-.096.66Zm4.152-.462c.38-.341.877-.916 1.383-1.559-.389-.15-.866-.371-1.319-.591-.598-.29-1.305-.283-2.073-.315a4.685 4.685 0 0 1-.804-.103c.014-.123.027-.246.038-.369.062.104.673.057.871.057.354 0 1.621.034 3.074-.574 1.452-.608 2.55-1.706 3.022-3.225.474-1.52.22-3.091-.168-3.952-.169.709-1.453 2.381-1.926 2.871-.473.489-2.381 2.296-2.972 2.921-.7.74-.688.793-1.332 1.302-.202.19-.499.402-.563.53.027-.338.039-.675.027-.997a7.653 7.653 0 0 0-.032-.523c.322-.059.567-.522.567-.861 0-.224-.106-.247-.271-.229.075-.894.382-3.923 1.254-4.281.218.109.831.068.649-.295-.182-.364-.825-.074-1.081.266-.28.374-.956 2.046-.92 4.324-.113.014-.174.033-.322.033-.171 0-.321-.04-.433-.05.034-2.275-.714-3.772-.84-4.169-.12-.375-.491-.596-.781-.596-.146 0-.272.056-.333.179-.182.363.459.417.677.308.706.321 1.156 3.519 1.254 4.277-.125-.006-.199.035-.199.233 0 .311.17.756.452.843a.442.442 0 0 0-.007.03s-.287.99-.413 2.189a4.665 4.665 0 0 1-.718-.225c-.714-.286-1.355-.583-2.019-.566-.664.018-1.366.023-1.804-.036-.438-.058-.649-.15-.649-.15s-.234.365.257 1.075c.42.607 1.055 1.047 1.644 1.18.589.134 1.972.18 2.785-.377.16-.109.317-.228.459-.34a8.717 8.717 0 0 0-.013.626c-.289.753-.571 1.993-.268 3.338 0-.001.701-.842.787-2.958.006-.144.009-.271.01-.383.052-.248.103-.518.148-.799.072.135.151.277.234.413.511.842 1.791 1.37 2.383 1.49.091.019.187.032.285.038Zm-1.12.745c-.188.055-.445.1-.713.059-.21-.031-.45-.11-.655-.316-.169-.168-.312-.419-.401-.789a9.837 9.837 0 0 0 .039-.82l.049-.243c.563.855 1.865 1.398 2.476 1.522.036.008.072.014.109.02l-.013.009c-.579.415-.76.503-.891.558Zm6.333-2.818c-.257.114-4.111 1.822-5.246 2.363.98-.775 3.017-3.59 3.699-4.774 1.062.661 1.468 1.109 1.623 1.441.101.217.09.38.096.515a.57.57 0 0 1-.172.455Zm-9.213 1.62a1.606 1.606 0 0 1-.19.096c-.954.414-2.126.61-4.728-.571-2.023-.918-3.024-2.157-3.371-2.666.476.161 1.471.473 2.157.524.282.021.703.068 1.167.125.021.209.109.486.345.829l.001.001c.451.651 1.134 1.119 1.765 1.262.622.141 2.083.182 2.942-.407a3.12 3.12 0 0 0 .132-.093l.001.179a6.052 6.052 0 0 0-.221.721Zm5.512-1.271a17.49 17.49 0 0 1-1.326-.589c.437.042 1.054.083 1.692.108-.121.162-.244.323-.366.481Zm.932-1.26c-.12.17-.245.343-.373.517-.241.018-.478.03-.709.038a29.05 29.05 0 0 1-.741-.048c.608-.065 1.228-.252 1.823-.507Zm.22-.315c-.809.382-1.679.648-2.507.648-.472 0-.833.018-1.139.039v.001c-.324-.031-.665-.039-1.019-.054a3.555 3.555 0 0 1-.152-.009c.102-.002.192-.006.249-.006.363 0 1.662.034 3.151-.589 1.508-.632 2.645-1.773 3.136-3.351.37-1.186.31-2.402.086-3.312.458-.336.86-.651 1.147-.91.501-.451.743-.733.848-.869.199.206.714.864.685 2.138-.036 1.611-.606 3.187-1.501 4.154a9.099 9.099 0 0 1-1.321 1.132 11.978 11.978 0 0 0-.644-.422l-.089-.055-.051.091c-.184.332-.5.825-.879 1.374ZM4.763 5.817c-.157 1.144.113 2.323.652 3.099.539.776 2.088 2.29 3.614 2.505.991.14 2.055.134 2.055.134s-.593-.576-1.114-1.66c-.521-1.085-.948-2.104-1.734-2.786-.785-.681-1.601-1.416-2.045-1.945-.444-.53-.59-.86-.59-.86s-.656.175-.838 1.513Zm14.301 4.549a9.162 9.162 0 0 0 1.3-1.12c.326-.352.611-.782.845-1.265 1.315.145 2.399.371 2.791.434 0 0-.679 1.971-3.945 3.022l-.016-.035c-.121-.26-.385-.594-.975-1.036Zm-11.634.859a8.537 8.537 0 0 1-.598-.224c-1.657-.693-2.91-1.944-3.449-3.678-.498-1.601-.292-3.251.091-4.269.225.544.758 1.34 1.262 2.01a3.58 3.58 0 0 0-.172.726c-.163 1.197.123 2.428.687 3.24.416.599 1.417 1.62 2.555 2.193-.128.002-.253.003-.376.002Zm-1.758-.077c-.958-.341-1.901-.787-2.697-1.368C-.07 7.559 0 6.827 0 6.827s1.558-.005 3.088.179c.03.126.065.
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": "../../..", "features": ["content.tooltips", "search.highlight", "navigation.tabs", "navigation.indexes", "navigation.prune"], "search": "../../../assets/javascripts/workers/search.b8dbb3d2.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
<script src="../../../assets/javascripts/bundle.fe8b6f2b.min.js"></script>
</body>
</html>
Copy permalink