git.iko.soy/haskell.nix
on iko/ghcjs-patch-master help sign in
Minor documentation fixes (#722)
5c4a0deToon Nolten
docs/tutorials/building-package-from-stackage-hackage.md+25−20
compare with iko/ghcjs-patch-master
unifiedsplit
@@ -1,38 +1,43 @@
1
1
2−# Build a specific package from hackage or a [stackage][] lts or nightly set.
2+# Build a specific package from Hackage or Stackage
3
3
4+## From a [Stackage][] snapshot
5+
4−To build a package, say [lens][], from a stackage snapshot, say [lts-13.28][],
6+To build a package, say [lens][], from a Stackage snapshot, say
5−you could run
7+[lts-13.28][], you could run:
6```bash
8```bash
7−nix build '(with import <nixpkgs> (import ./. {}).nixpkgsArgs; haskell-nix.snapshots."lts-13.28").lens.components.library'
9+nix build '(with import <nixpkgs> (import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz")).nixpkgsArgs; haskell-nix.snapshots."lts-13.28").lens.components.library'
8```
10```
9−which would build the [lens][] library component from the lens package as fixed
11+This would build the (public) library component of the [lens][] package as
10−by the [lts-13.28][] stackage snapshot.
12+fixed by the [lts-13.28][] stackage snapshot. Nightly snapshots like
13+`nightly-2020-06-21` are also available.
11
14
12−## Specific version
15+## A specific version from Hackage
13
16
14−To build any package from hackage, say [lens][], in version, say 4.17.1, you
17+To build any package from hackage, say [lens][], at any version, say 4.17.1,
15−could run
18+you could run:
16```bash
19```bash
17−nix build '(with import <nixpkgs> (import ./. {}).nixpkgsArgs; (haskell-nix.hackage-package { name = "lens"; version = "4.17.1"; })).components.library'
20+nix build '(with import <nixpkgs> (import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz")).nixpkgsArgs; (haskell-nix.hackage-package { name = "lens"; version = "4.17.1"; })).components.library'
18```
21```
19−which would build the [lens][] library component from the [lens-4.17.1][] package
22+This would build the (public) library component of the [lens-4.17.1][] package
20from hackage.
23from hackage.
21
24
22−## Pinning hackage index
25+### Pinning hackage index
23
26
24−The dependencies would be solved against the most recent
27+The dependencies would be resolved against the most recent
25−[hackage-index-state][] that comes via the [hackage.nix][] pin with your
28+[hackage-index-state][] which comes with your [haskell.nix][] checkout via the
26−[haskell.nix][] checkout. A specific one can be specified as well:
29+[hackage.nix][] pin. A specific one can be specified as well:
27```bash
30```bash
28−nix build '(with import <nixpkgs> (import ./. {}).nixpkgsArgs; (haskell-nix.hackage-package { name = "lens"; version = "4.17.1"; index-state = "2019-07-14T00:00:00Z"; })).components.library'
31+nix build '(with import <nixpkgs> (import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz")).nixpkgsArgs; (haskell-nix.hackage-package { name = "lens"; version = "4.17.1"; index-state = "2019-07-14T00:00:00Z"; })).components.library'
29```
32```
30−which would use the hackage index as of `2019-07-14T00:00:00Z` to produce a build plan
33+This would use the hackage index as of `2019-07-14T00:00:00Z` to produce a
31−for the [lens-4.17.1][] package.
34+build plan for the [lens-4.17.1][] package.
32
35
33−[stackage]: https://stackage.org
36+[Stackage]: https://stackage.org
37+[Hackage]: https://hackage.haskell.org
34[hackage.nix]: https://github.com/input-output-hk/hackage.nix
38[hackage.nix]: https://github.com/input-output-hk/hackage.nix
39+[haskell.nix]: https://github.com/input-output-hk/haskell.nix
35[lts-13.28]: https://www.stackage.org/lts-13.28
40[lts-13.28]: https://www.stackage.org/lts-13.28
36[lens]: https://hackage.haskell.org/package/lens
41[lens]: https://hackage.haskell.org/package/lens
37[lens-4.17.1]: https://hackage.haskell.org/package/lens-4.17.1
42[lens-4.17.1]: https://hackage.haskell.org/package/lens-4.17.1
38−[hackage-index-state]: https://github.com/input-output-hk/hackage.nix/blob/master/index-state-hashes.nix
43+[hackage-index-state]: https://github.com/input-output-hk/hackage.nix/blob/master/index-state-hashes.nix
docs/tutorials/getting-started.md+15−13
@@ -5,12 +5,14 @@
5or [Stack](https://docs.haskellstack.org/en/stable/README/#quick-start-guide)
5or [Stack](https://docs.haskellstack.org/en/stable/README/#quick-start-guide)
6project and its dependencies into Nix code.
6project and its dependencies into Nix code.
7
7
8−Assuming you have [Nix installed](https://nixos.org/download.html), you can start setting up your project.
8+Assuming you have [Nix](https://nixos.org/download.html) installed, you can
9+start setting up your project.
9
10
10## Setting up the Cachix binary cache
11## Setting up the Cachix binary cache
11
12
12−You can **avoid compiling GHC and nix-tools** by configuring [Cachix](https://cachix.org)
13+You can **avoid compiling GHC and nix-tools** by configuring
13−so you can benefit from the binary cache built by CI:
14+[Cachix](https://cachix.org) so you can benefit from the binary cache built by
15+CI:
14
16
15```bash
17```bash
16$ nix-env -iA cachix -f https://cachix.org/api/v1/install
18$ nix-env -iA cachix -f https://cachix.org/api/v1/install
@@ -33,13 +35,13 @@ Add `default.nix`:
33{ # Fetch the latest haskell.nix and import its default.nix
35{ # Fetch the latest haskell.nix and import its default.nix
34 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}
36 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}
35
37
36−# haskell.nix provides access to the nixpkgs pins which are used by our CI, hence
38+# haskell.nix provides access to the nixpkgs pins which are used by our CI,
37−# you will be more likely to get cache hits when using these.
39+# hence you will be more likely to get cache hits when using these.
38−# But you can also just use your own, e.g. '<nixpkgs>'
40+# But you can also just use your own, e.g. '<nixpkgs>'.
39, nixpkgsSrc ? haskellNix.sources.nixpkgs-2003
41, nixpkgsSrc ? haskellNix.sources.nixpkgs-2003
40
42
41−# haskell.nix provides some arguments to be passed to nixpkgs, including some patches
43+# haskell.nix provides some arguments to be passed to nixpkgs, including some
42−# and also the haskell.nix functionality itself as an overlay.
44+# patches and also the haskell.nix functionality itself as an overlay.
43, nixpkgsArgs ? haskellNix.nixpkgsArgs
45, nixpkgsArgs ? haskellNix.nixpkgsArgs
44
46
45# import nixpkgs with overlays
47# import nixpkgs with overlays
@@ -84,20 +86,20 @@ cabal new-build your-package-name
84
86
85To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
87To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
86
88
87−### Pinning the [Haskell.nix][] version
89+### Pinning the [haskell.nix][] version
88
90
89For simplicity's sake we will use `fetchTarball` for the examples in
91For simplicity's sake we will use `fetchTarball` for the examples in
90this documentation. This will always get the latest version, and is
92this documentation. This will always get the latest version, and is
91similar to an auto-updating Nix channel.
93similar to an auto-updating Nix channel.
92
94
93−However, in your own project, you may wish to pin [Haskell.nix][] (as
95+However, in your own project, you may wish to pin [haskell.nix][] (as
94you would pin Nixpkgs). This will make your builds reproducible, more
96you would pin Nixpkgs). This will make your builds reproducible, more
95predictable, and faster (because the fixed version is cached).
97predictable, and faster (because the fixed version is cached).
96
98
97−Straightforward way of doing this is to change branch name to a revision.
99+Straightforward way of doing this is to change the branch name to a revision.
98
100
99```nix
101```nix
100−{ # Fetch the latest haskell.nix and import its default.nix
102+{ # Fetch a specific haskell.nix and import its default.nix
101 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {}
103 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {}
102
104
103...
105...
@@ -111,4 +113,4 @@ There are other possible schemes for pinning. See
111
113
112There are a number of things to explore further in the tutorials section.
114There are a number of things to explore further in the tutorials section.
113
115
114−[haskell.nix]: https://github.com/input-output-hk/haskell.nix
116+[haskell.nix]: https://github.com/input-output-hk/haskell.nix
docs/tutorials/hackage-stackage.md+4−2
@@ -29,6 +29,8 @@ let
29in ...
29in ...
30```
30```
31
31
32−This way you can change the revisions of `hackage.nix` and `stackage.nix` are fetched from without changing `haskell.nix`.
32+This way you can change the revisions of `hackage.nix` and `stackage.nix`
33+without changing `haskell.nix`.
33
34
34−However, bear in mind that Stackage refers to Hackage, so your Stackage should never be newer than Hackage.
35+However, bear in mind that Stackage refers to Hackage, so your Stackage pin
36+should never be newer than your Hackage pin.
docs/tutorials/source-repository-hashes.md+5−5
@@ -50,12 +50,12 @@ extra-deps:
50 # nix-sha256: 003lm3pm024vhbfmii7xcdd9v2rczpflxf7gdl2pyxia7p014i8z
50 # nix-sha256: 003lm3pm024vhbfmii7xcdd9v2rczpflxf7gdl2pyxia7p014i8z
51```
51```
52
52
53−## Avoding modifying cabal.project and stack.yaml
53+## Avoiding modifying cabal.project and stack.yaml
54
54
55−In some cases we cannot modify the `cabal.project` or `stack.yaml` file
55+In some cases we cannot modify the `cabal.project` or `stack.yaml` file to add
56−to add sha256 comments. As an alternative we can pass in a `sha256map`
56+sha256 comments. As an alternative we can pass in a `sha256map`. For instance,
57−For instance pandoc includes a `cabal.project` file in hackage includes a
57+pandoc includes a `cabal.project` file on hackage which includes a
58−`source-package-reference` to `pandoc-citeproc`:
58+`source-repository-package` stanza for `pandoc-citeproc`:
59
59
60```nix
60```nix
61{ haskell-nix, testSrc } :
61{ haskell-nix, testSrc } :