git.iko.soy/haskell.nix
on iko/ghcjs-patch-master help sign in
Minor documentation fixes (#722)

* Make the haskell.nix import in the examples explicit The examples used `import ./. {}` without explaining the commands should be run from the haskell.nix repo root. To avoid confusion like this I added fetching a tarball of the repo. This is less efficient when run from the repo but works when run from anywhere and makes it clear we're importing haskell.nix. Added a couple urls and removed the urls on the lens component so as not to confuse components with packages. * Fix rephrase The phrasing was left in a partially-rewritten state. * Change wording and fix typo * Minor fixes for consistency

commit5c4a0de2a1e332d37076400773983c3c00693ca7 authorToon Nolten <toonn@toonn.io> dateTue 23 Jun 2020, 00:10 (6 years ago) parentdc7acfe
4 files changed+49−40
compare with iko/ghcjs-patch-master
unifiedsplit
docs/tutorials/building-package-from-stackage-hackage.md+25−20 docs/tutorials/getting-started.md+15−13 docs/tutorials/hackage-stackage.md+4−2 docs/tutorials/source-repository-hashes.md+5−5
docs/tutorials/building-package-from-stackage-hackage.md+25−20
@@ -1,38 +1,43 @@
11
2−# Build a specific package from hackage or a [stackage][] lts or nightly set.
2+# Build a specific package from Hackage or Stackage
33
4−To build a package, say [lens][], from a stackage snapshot, say [lts-13.28][],
5−you could run
4+## From a [Stackage][] snapshot
5+
6+To build a package, say [lens][], from a Stackage snapshot, say
7+[lts-13.28][], you could run:
68```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'
810```
9−which would build the [lens][] library component from the lens package as fixed
10−by the [lts-13.28][] stackage snapshot.
11+This would build the (public) library component of the [lens][] package as
12+fixed by the [lts-13.28][] stackage snapshot. Nightly snapshots like
13+`nightly-2020-06-21` are also available.
1114
12−## Specific version
15+## A specific version from Hackage
1316
14−To build any package from hackage, say [lens][], in version, say 4.17.1, you
15−could run
17+To build any package from hackage, say [lens][], at any version, say 4.17.1,
18+you could run:
1619```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'
1821```
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
2023from hackage.
2124
22−## Pinning hackage index
25+### Pinning hackage index
2326
24−The dependencies would be solved against the most recent
25−[hackage-index-state][] that comes via the [hackage.nix][] pin with your
26−[haskell.nix][] checkout. A specific one can be specified as well:
27+The dependencies would be resolved against the most recent
28+[hackage-index-state][] which comes with your [haskell.nix][] checkout via the
29+[hackage.nix][] pin. A specific one can be specified as well:
2730```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'
2932```
30−which would use the hackage index as of `2019-07-14T00:00:00Z` to produce a build plan
31−for the [lens-4.17.1][] package.
33+This would use the hackage index as of `2019-07-14T00:00:00Z` to produce a
34+build plan for the [lens-4.17.1][] package.
3235
33−[stackage]: https://stackage.org
36+[Stackage]: https://stackage.org
37+[Hackage]: https://hackage.haskell.org
3438[hackage.nix]: https://github.com/input-output-hk/hackage.nix
39+[haskell.nix]: https://github.com/input-output-hk/haskell.nix
3540[lts-13.28]: https://www.stackage.org/lts-13.28
3641[lens]: https://hackage.haskell.org/package/lens
3742[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 @@
55or [Stack](https://docs.haskellstack.org/en/stable/README/#quick-start-guide)
66project and its dependencies into Nix code.
77
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.
910
1011## Setting up the Cachix binary cache
1112
12−You can **avoid compiling GHC and nix-tools** by configuring [Cachix](https://cachix.org)
13−so you can benefit from the binary cache built by CI:
13+You can **avoid compiling GHC and nix-tools** by configuring
14+[Cachix](https://cachix.org) so you can benefit from the binary cache built by
15+CI:
1416
1517```bash
1618$ nix-env -iA cachix -f https://cachix.org/api/v1/install
@@ -33,13 +35,13 @@ Add `default.nix`:
3335{ # Fetch the latest haskell.nix and import its default.nix
3436 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}
3537
36−# haskell.nix provides access to the nixpkgs pins which are used by our CI, hence
37−# you will be more likely to get cache hits when using these.
38−# But you can also just use your own, e.g. '<nixpkgs>'
38+# haskell.nix provides access to the nixpkgs pins which are used by our CI,
39+# hence you will be more likely to get cache hits when using these.
40+# But you can also just use your own, e.g. '<nixpkgs>'.
3941, nixpkgsSrc ? haskellNix.sources.nixpkgs-2003
4042
41−# haskell.nix provides some arguments to be passed to nixpkgs, including some patches
42−# and also the haskell.nix functionality itself as an overlay.
43+# haskell.nix provides some arguments to be passed to nixpkgs, including some
44+# patches and also the haskell.nix functionality itself as an overlay.
4345, nixpkgsArgs ? haskellNix.nixpkgsArgs
4446
4547# import nixpkgs with overlays
@@ -84,20 +86,20 @@ cabal new-build your-package-name
8486
8587To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
8688
87−### Pinning the [Haskell.nix][] version
89+### Pinning the [haskell.nix][] version
8890
8991For simplicity's sake we will use `fetchTarball` for the examples in
9092this documentation. This will always get the latest version, and is
9193similar to an auto-updating Nix channel.
9294
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
9496you would pin Nixpkgs). This will make your builds reproducible, more
9597predictable, and faster (because the fixed version is cached).
9698
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.
98100
99101```nix
100−{ # Fetch the latest haskell.nix and import its default.nix
102+{ # Fetch a specific haskell.nix and import its default.nix
101103 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {}
102104
103105...
@@ -111,4 +113,4 @@ There are other possible schemes for pinning. See
111113
112114There are a number of things to explore further in the tutorials section.
113115
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
2929in ...
3030```
3131
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`.
3334
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:
5050 # nix-sha256: 003lm3pm024vhbfmii7xcdd9v2rczpflxf7gdl2pyxia7p014i8z
5151```
5252
53−## Avoding modifying cabal.project and stack.yaml
53+## Avoiding modifying cabal.project and stack.yaml
5454
55−In some cases we cannot modify the `cabal.project` or `stack.yaml` file
56−to add sha256 comments. As an alternative we can pass in a `sha256map`
57−For instance pandoc includes a `cabal.project` file in hackage includes a
58−`source-package-reference` to `pandoc-citeproc`:
55+In some cases we cannot modify the `cabal.project` or `stack.yaml` file to add
56+sha256 comments. As an alternative we can pass in a `sha256map`. For instance,
57+pandoc includes a `cabal.project` file on hackage which includes a
58+`source-repository-package` stanza for `pandoc-citeproc`:
5959
6060```nix
6161{ haskell-nix, testSrc } :