18979e4 · haskell.nix · git.iko.soy

git.iko.soy/haskell.nix

on iko/ghcjs-patch-master help sign in

Update getting started guide and shellFor (#951)

18979e4Hamish Mackenzie6 years ago

docs/tutorials/development.md+15−13

compare with iko/ghcjs-patch-master

unifiedsplit

@@ -34,13 +34,14 @@ themselves. This is what the [`shellFor`][shellFor] function does.

35```nix

36# shell.nix

37−{ pkgs ? import <nixpkgs> {} }:

38−

39let

37let

40− hsPkgs = import ./default.nix { };

38+ project = import ./default.nix;

41in

39in

42− hsPkgs.shellFor {

40+ project.shellFor {

43− # Include only the *local* packages of your project.

41+ # ALL of these arguments are optional.

42+

43+ # List of packages from the project you want to work on in

44+ # the shell (default is all the projects local packages).

44 packages = ps: with ps; [

45 packages = ps: with ps; [

45 pkga

46 pkga

46 pkgb

47 pkgb

@@ -50,15 +51,16 @@ in

50 # and provides a "hoogle" command to search the index.

51 # and provides a "hoogle" command to search the index.

51 withHoogle = true;

52 withHoogle = true;

53− # You might want some extra tools in the shell (optional).

54−

55 # Some common tools can be added with the `tools` argument

54 # Some common tools can be added with the `tools` argument

55+ tools = {

56− tools = { cabal = "3.2.0.0"; hlint = "2.2.11"; };

56+ cabal = "3.2.0.0";

57+ hlint = "latest"; # Selects the latest version in the hackage.nix snapshot

58+ haskell-language-server = "latest";

59+ };

57 # See overlays/tools.nix for more details

60 # See overlays/tools.nix for more details

59 # Some you may need to get some other way.

62 # Some you may need to get some other way.

60− buildInputs = with pkgs.haskellPackages;

63+ buildInputs = [ (import <nixpkgs> {}).git ];

61− [ ghcid ];

63 # Prevents cabal from choosing alternate plans, so that

65 # Prevents cabal from choosing alternate plans, so that

64 # *all* dependencies are provided by Nix.

66 # *all* dependencies are provided by Nix.

@@ -77,15 +79,15 @@ If you need a local Hoogle for all the dependencies of your project create this

77```nix

79```nix

78# shell-hoogle.nix

80# shell-hoogle.nix

79let

81let

80− hsPkgs = import ./default.nix {};

82+ project = import ./default.nix {};

81in

83in

82− hsPkgs.shellFor {

84+ project.shellFor {

83 packages = ps: [ps.my-package];

85 packages = ps: [ps.my-package];

84 withHoogle = true;

86 withHoogle = true;

85 }

87 }

86```

88```

88−and run `nix-shell shell-hoogle.nix --run "hoogle server --local"`.

90+and run `nix-shell shell-hoogle.nix --run "hoogle server --local"`.

89This will open a local Hoogle server at `http://127.0.0.1:8080`.

91This will open a local Hoogle server at `http://127.0.0.1:8080`.

docs/tutorials/getting-started.md+77−24

@@ -35,6 +35,33 @@ nix.binaryCaches = [

36This can be tricky to get setup properly. If you're still having trouble getting cache hits, consult the corresponding [troubleshooting section](../../troubleshooting#why-am-i-building-ghc).

38+## Niv

39+

40+[Niv](https://github.com/nmattia/niv) is a command line tool for keeping tack of Nix project dependencies.

41+

42+This guide assumes that the `sources.haskellNix` will be set to point

43+a pinned copy of the haskell.nix github repo. One easy way to do this

44+is to use Niv. If you prefer not to use Niv another option is described

45+in the in the "Using haskell.nix without niv" section of this document.

46+

47+If you want to use Nix Flakes to pin your dependencies then you should

48+consider following the [Getting started with flakes](./getting-started-flakes.md)

49+document instead of this one.

50+

51+After installing niv you can initialize niv and pin the latest haskell.nix

52+commit by running the following in the root directory of the project:

53+

54+```

55+niv init

56+niv add input-output-hk/haskell.nix -n haskellNix

57+```

58+

59+Then when you want to update to the latest version of haskellNix use:

60+

61+```

62+niv update haskellNix

63+```

64+

38## Scaffolding

65## Scaffolding

40The following work with `stack.yaml` and `cabal.project` based

67The following work with `stack.yaml` and `cabal.project` based

@@ -43,21 +70,28 @@ projects.

43Add `default.nix`:

70Add `default.nix`:

45```nix

72```nix

73+let

74+ # Read in the Niv sources

75+ sources = import ./nix/sources.nix {};

76+ # If ./nix/sources.nix file is not found run:

77+ # niv init

78+ # niv add input-output-hk/haskell.nix -n haskellNix

79+

46−{ # Fetch the latest haskell.nix and import its default.nix

80+ # Fetch the haskell.nix commit we have pinned with Niv

47− haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}

81+ haskellNix = import sources.haskellNix {};

48−

82+ # If haskellNix is not found run:

83+ # niv add input-output-hk/haskell.nix -n haskellNix

84+

85+ # Import nixpkgs and pass the haskell.nix provided nixpkgsArgs

86+ pkgs = import

49−# haskell.nix provides access to the nixpkgs pins which are used by our CI,

87+ # haskell.nix provides access to the nixpkgs pins which are used by our CI,

50−# hence you will be more likely to get cache hits when using these.

88+ # hence you will be more likely to get cache hits when using these.

51−# But you can also just use your own, e.g. '<nixpkgs>'.

89+ # But you can also just use your own, e.g. '<nixpkgs>'.

52−, nixpkgsSrc ? haskellNix.sources.nixpkgs-2009

90+ haskellNix.sources.nixpkgs-2009

53−

54−# haskell.nix provides some arguments to be passed to nixpkgs, including some

91+ # These arguments passed to nixpkgs, include some patches and also

55−# patches and also the haskell.nix functionality itself as an overlay.

92+ # the haskell.nix functionality itself as an overlay.

56−, nixpkgsArgs ? haskellNix.nixpkgsArgs

93+ haskellNix.nixpkgsArgs;

57−

58−# import nixpkgs with overlays

59−, pkgs ? import nixpkgsSrc nixpkgsArgs

60−}: pkgs.haskell-nix.project {

94+in pkgs.haskell-nix.project {

61 # 'cleanGit' cleans a source directory based on the files known by git

95 # 'cleanGit' cleans a source directory based on the files known by git

62 src = pkgs.haskell-nix.haskellLib.cleanGit {

96 src = pkgs.haskell-nix.haskellLib.cleanGit {

63 name = "haskell-nix-project";

97 name = "haskell-nix-project";

@@ -96,20 +130,40 @@ nix-build -A projectCross.ghcjs.hsPkgs.your-package-name.components.exes.your-ex

96nix-build -A projectCross.mingwW64.hsPkgs.your-package-name.components.exes.your-exe-name

130nix-build -A projectCross.mingwW64.hsPkgs.your-package-name.components.exes.your-exe-name

97```

131```

132

99−To open a shell for use with `cabal` run:

133+To open a shell for use with `cabal`, `hlint` and `haskell-language-server` add `shell.nix`:

134+

135+```nix

136+(import ./default.nix).shellFor {

137+ tools = {

138+ cabal = "3.2.0.0";

139+ hlint = "latest";

140+ haskell-language-server = "latest";

141+ };

142+}

143+```

144+

145+Then run:

100

146

101```shell

147```shell

102−nix-shell -A shellFor

148+nix-shell

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

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

104cabal new-build your-package-name

150cabal new-build your-package-name

105```

151```

106

152

107To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).

153To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).

108

154

109−### Pinning the [haskell.nix][] version

155+## Using haskell.nix without Niv

110

156

111−For simplicity's sake we will use `fetchTarball` for the examples in

157+If you would prefer not to use niv you can replace

158+`sources = import ./nix/sources.nix {};` in the examples with:

159+

160+```nix

161+let sources = {

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

163+ };

164+```

165+

112−this documentation. This will always get the latest version, and is

166+The `fetchTarball` call above will always get the latest version, and is

113similar to an auto-updating Nix channel.

167similar to an auto-updating Nix channel.

114

168

115However, in your own project, you may wish to pin [haskell.nix][] (as

169However, in your own project, you may wish to pin [haskell.nix][] (as

@@ -119,10 +173,9 @@ predictable, and faster (because the fixed version is cached).

119Straightforward way of doing this is to change the branch name to a revision.

173Straightforward way of doing this is to change the branch name to a revision.

120

174

121```nix

175```nix

122−{ # Fetch a specific haskell.nix and import its default.nix

176+let sources = {

123− haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {}

177+ haskellNix = import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {};

124−

178+ };

125−...

126```

179```

127

180

128There are other possible schemes for pinning. See

181There are other possible schemes for pinning. See