da9c5b9 · haskell.nix · git.iko.soy

git.iko.soy/haskell.nix

on iko/ghcjs-patch-master help sign in

Improve docs, mention pinning Hackage and Stackage (#668)

da9c5b9Michael Peyton Jones6 years ago

README.md+9−8

@@ -4,7 +4,7 @@

4[![](https://img.shields.io/buildkite/c8d5a20d3ff0f440f82adb9190b43c16c91e5e47e8adfa867a/master.svg?label=nightly%20updates)](https://buildkite.com/input-output-hk/haskell-dot-nix-nightly-updates)

6`haskell.nix` can automatically translate your Cabal or Stack project and

7−its dependencies into Nix code.

7+its dependencies into Nix code.

9## [Documentation](https://input-output-hk.github.io/haskell.nix/)

@@ -70,6 +70,8 @@ pkgs.haskell-nix.stackProject {

70}

71```

73+### Working with a project

74+

73To build the library component of a package in the project run:

75To build the library component of a package in the project run:

75```shell

77```shell

@@ -90,24 +92,23 @@ cabal new-build your-package-name

90cabal new-repl your-package-name:library:your-package-name

92cabal new-repl your-package-name:library:your-package-name

91```

93```

93−## Using binary Cache to speed up compilation

95+## Using a binary cache

95To use precompiled binaries you'll need:

97To use precompiled binaries you'll need:

97−- to configure a binary cache by following instructions on [iohk.cachix.org](https://iohk.cachix.org).

99+- To configure the IOHK binary cache by following the instructions on [iohk.cachix.org](https://iohk.cachix.org).

98−- to pin `nixpkgs` according to [nix/sources.json](nix/sources.json).

100+- To pin your `nixpkgs` to match one of the revisions built by our CI: these can be found inside the `sources` attribute (see the quickstart above for an example).

99−

100

101

101## Related repos

102## Related repos

102

103

103The `haskell.nix` repository contains the runtime system for building

104The `haskell.nix` repository contains the runtime system for building

104Haskell packages in Nix. It depends on other repos, which are:

105Haskell packages in Nix. It depends on other repos, which are:

105

106

106−- [nix-tools](https://github.com/input-output-hk/nix-tools) — provides the programs for generating Nix expressions from Haskell projects.

107+- [`nix-tools`](https://github.com/input-output-hk/nix-tools) — provides the programs for generating Nix expressions from Haskell projects.

107

108

108−- [hackage.nix](https://github.com/input-output-hk/hackage.nix) — the latest contents of the [Hackage](https://hackage.haskell.org/) databases, converted to Nix expressions.

109+- [`hackage.nix`](https://github.com/input-output-hk/hackage.nix) — the latest contents of the [Hackage](https://hackage.haskell.org/) databases, converted to Nix expressions.

109

110

110−- [stackage.nix](https://github.com/input-output-hk/stackage.nix) — all of the [Stackage](https://www.stackage.org/) snapshots, converted to Nix expressions.

111+- [`stackage.nix`](https://github.com/input-output-hk/stackage.nix) — all of the [Stackage](https://www.stackage.org/) snapshots, converted to Nix expressions.

111

112

112## IRC Channel

113## IRC Channel

113

114

docs/user-guide/hackage-stackage.mdnew file+34

@@ -0,0 +1,34 @@

1+# Hackage and Stackage

3+`haskell.nix` relies on some generated data providing information about packages in Hackage and Stackage snapshots.

4+These are kept in [`hackage.nix`](https://github.com/input-output-hk/hackage.nix) and [`stackage.nix`](https://github.com/input-output-hk/stackage.nix) respectively.

5+If your project depends on a Hackage package, then the `hackage.nix` revision used must be new enough to contain that, and likewise for Stackage snaphots and `stackage.nix`.

7+## Updating and pinning `hackage.nix` and `stackage.nix`

9+`haskell.nix` pins particular revisions of these repositories internally, both for our own usage in testing, and so that users have a sensible default when getting started.

10+These revisions are updated nightly, so you can get newer revisions of `hackage.nix` and `stackage.nix` by updating your revision of `haskell.nix` itself.

11+

12+However, this exposes you to changes in `haskell.nix` which you may not want, such as changes that force compiler rebuilds, or the occasional bug.

13+Instead, you can pin `hackage.nix` and `stackage.nix` independently. For example:

14+

15+```

16+let

17+ # You can use a tool like `niv` to manage this boilerplate

18+ hackageSrc = builtins.fetchTarball https://github.com/input-output-hk/hackage.nix/archive/master.tar.gz;

19+ stackageSrc = builtins.fetchTarball https://github.com/input-output-hk/stackage.nix/archive/master.tar.gz;

20+ haskellSrc = builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz;

21+

22+ haskellNix = import haskellSrc {

23+ # This allows you to override the pins used by `haskell.nix` internally

24+ sourcesOverride = {

25+ hackage = hackageSrc;

26+ stackage = stackageSrc;

27+ };

28+ };

29+in ...

30+```

31+

32+You can then change the revisions that `hackage.nix` and `stackage.nix` are fetched from without changing `haskell.nix`.

33+

34+However, bear in mind that Stackage refers to Hackage, so your Stackage should never be newer than Hackage.

mkdocs.yml+1

@@ -31,6 +31,7 @@ pages:

31 - 'Creating Nix builds for your projects': user-guide/projects.md

32 - 'Stack Projects': user-guide/stack-projects.md

33 - 'Cabal Projects': user-guide/cabal-projects.md

34+ - 'Hackage and Stackage': user-guide/hackage-and-stackage.md

34 - 'How to create a development environment': user-guide/development.md

35 - 'How to create a development environment': user-guide/development.md

35 - 'How to cross-compile your project': user-guide/cross-compilation.md

36 - 'How to cross-compile your project': user-guide/cross-compilation.md

36 - 'Reference':

37 - 'Reference':