b4b18ed · haskell.nix · git.iko.soy

git.iko.soy/haskell.nix

on iko/ghcjs-patch-master help sign in

Docs improvements (#171)

b4b18edRodney Lorrimar7 years ago

docs/dev-architecture.md → docs/dev/dev-architecture.mdrenamed

compare with iko/ghcjs-patch-master

unifiedsplit

The content is the same.

docs/maintainer-scripts.md → docs/dev/maintainer-scripts.mdrenamed

The content is the same.

docs/dev/nixpkgs-pin.mdnew file+21

@@ -0,0 +1,21 @@

1+# Haskell.nix Nixpkgs Pin

3+Haskell.nix contains a Nixpkgs pin in

4+[`nixpkgs/github.json`](https://github.com/input-output-hk/haskell.nix/blob/master/nixpkgs/github.json).

5+This is the version of Nixpkgs used for builds of `nix-tools` and

6+running the tests.

8+Users should pass their own version of Nixpkgs to Haskell.nix,

9+although things might not work for them if their Nixpkgs version is

10+too different.

11+

12+We aim to keep this pin somewhere on the channel of the **NixOS latest

13+stable release**. That is currently 19.03. So:

14+

15+```

16+nix-prefetch-git https://github.com/NixOS/nixpkgs-channels refs/heads/nixos-19.03

17+```

18+

19+Keep the URL in `github.json` pointing at

20+<https://github.com/NixOS/nixpkgs>. Case matters because the Hydra

21+trusted URL whitelist is case-sensitive.

docs/removing-with-package-wrapper.md → docs/dev/removing-with-package-wrapper.mdrenamed

The content is the same.

docs/reference/library.md+4

@@ -4,6 +4,10 @@ what you get when importing [Haskell.nix][]. It might be helpful to

4load the library in the [Nix REPL](../user-guide.md#using-nix-repl) to

5test things.

7+ * [Types](#types) — the kinds of data that you will encounter working with [Haskell.nix][].

8+ * [Top-level attributes](#top-level-attributes) — Functions and derivations defined in the Haskell.nix attrset.

9+ * [Package-set functions](#package-set-functions) — Helper functions defined on the `hsPkgs` package set.

10+

7# Types

11# Types

9## Package Set

13## Package Set

docs/user-guide/cabal-projects.md+11−3

@@ -8,9 +8,11 @@ dependencies of your package(s).

9## Generating `plan.json`

11−To get a plan, you need Cabal and GHC. See the [Nixpkgs

11+To get a plan, you need Cabal and GHC. See the [How to install a

12+compiler section of the Nixpkgs Manual][compiler] for information

13+about how to choose a specific compiler version.

14+

12−Manual](https://nixos.org/nixpkgs/manual/#how-to-install-a-compiler)

15+[compiler]: https://nixos.org/nixpkgs/manual/#how-to-install-a-compiler

13−for information about how to choose a specific compiler version.

15For this example, we will run a `nix-shell` with the default GHC

17For this example, we will run a `nix-shell` with the default GHC

16version for Nixpkgs.

18version for Nixpkgs.

@@ -23,6 +25,12 @@ nix-shell -p haskellPackages.cabal-install haskellPackages.ghc \

23If all goes well, you should now have the file

25If all goes well, you should now have the file

24`dist-newstyle/cache/plan.json`.

26`dist-newstyle/cache/plan.json`.

28+!!! tip "Specifying the GHC version"

29+ To use a specific compiler version, replace `haskellPackages.ghc`

30+ with something like `haskell.compiler.ghc865`. The given compiler

31+ must exist in your Nixpkgs version, of course. See also the

32+ [Nixpkgs Manual][compiler].

33+

26## Using `plan-to-nix`

34## Using `plan-to-nix`

28With [nix-tools installed](../user-guide.md), we can then run the

36With [nix-tools installed](../user-guide.md), we can then run the

docs/user-guide/cross-compilation.md+80−4

@@ -6,7 +6,7 @@ First, understand how to cross-compile a normal package from

6Nixpkgs. Matthew Bauer's [Beginners' guide to cross compilation in

7Nixpkgs][bauer] is a useful resource.

9−[bauer]: https://matthewbauer.us/blog/beginners-guide-to-cross.html

9+[bauer]: https://matthewbauer.us/blog/beginners-guide-to-cross.html

12Using an example from the guide, this builds GNU Hello for a Raspberry

@@ -47,18 +47,24 @@ You should be prepared for a long wait because it first needs to build

47GHC, before building all the Haskell dependencies of [Bench][]. If all

48of these dependencies compiled successfully, I would be very surprised!

50+!!! hint

51+ The above example won't build, but you can try and see, if you like.

52+ It will fail on [clock-0.7.2](http://hackage.haskell.org/package/clock-0.7.2),

53+ which needs a patch to build.

54+

50To fix the build problems, you must add extra configuration to the

55To fix the build problems, you must add extra configuration to the

51package set. Your project will have a [`mkStackPkgSet`](../reference/library.md#mkstackpkgset) or

56package set. Your project will have a [`mkStackPkgSet`](../reference/library.md#mkstackpkgset) or

52[`mkCabalProjectPkgSet`](../reference/library.md#mkcabalprojectpkgset). It is there where you must add

57[`mkCabalProjectPkgSet`](../reference/library.md#mkcabalprojectpkgset). It is there where you must add

53−[module options](../reference/modules.md) for setting compiler flags and so on.

58+[module options](../reference/modules.md) for setting compiler flags, adding patches, and so on.

59+

55### Static executables with Musl libc

61### Static executables with Musl libc

57Another application of cross-compiling is to produce fully static

63Another application of cross-compiling is to produce fully static

58binaries for Linux. For information about how to do that with the

64binaries for Linux. For information about how to do that with the

59[Nixpkgs Haskell infrastructure][nixpkgs] (not [Haskell.nix][]), see

65[Nixpkgs Haskell infrastructure][nixpkgs] (not [Haskell.nix][]), see

60−[nh2/static‑haskell‑nix][nh2]. Vaibhav Sagar's linked [blog

66+[nh2/static‑haskell‑nix][nh2]. Vaibhav Sagar's linked

61−post][vaibhav] is also very informative.

67+[blog post][vaibhav] is also very informative.

64```nix

70```nix

@@ -98,6 +104,76 @@ executables you must add package overrides to:

98 `integer-gmp`. However, at present, [Haskell.nix][] does not provide

104 `integer-gmp`. However, at present, [Haskell.nix][] does not provide

99 an option for this.

105 an option for this.

100

106

107+

108+### How to cross-compile your project

109+

110+Set up your project Haskell package set.

111+

112+```nix

113+# default.nix

114+{ pkgs ? import <nixpkgs> {}

115+let

116+ # Import the Haskell.nix library,

117+ haskell = import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {

118+ inherit pkgs;

119+ };

120+

121+ # Instantiate a package set using the generated file.

122+ pkgSet = haskell.mkCabalProjectPkgSet {

123+ plan-pkgs = import ./pkgs.nix;

124+ pkg-def-extras = [];

125+ modules = [

126+ {

127+ # You will need to put build fixes here.

128+ }

129+ ];

130+ };

131+in

132+ pkgSet.config.hsPkgs

133+```

134+

135+Apply that package set to the Nixpkgs cross package sets that you are

136+interested in.

137+

138+We are going to expand the `pkgs.pkgsCross` shortcut to be more

139+explicit.

140+

141+```nix

142+let

143+ pkgs = import <nixpkgs> {}

144+in {

145+ shortcut = pkgs.pkgsCross.SYSTEM;

146+ actual = import <nixpkgs> { crossSystem = pkgs.lib.systems.examples.SYSTEM; };

147+}

148+```

149+

150+In the above example, for any `SYSTEM`, `shortcut` and `actual` are

151+the same package set.

152+

153+```nix

154+# release.nix

155+let

156+ myProject = import ./default.nix;

157+

158+ pkgsNative = import <nixpkgs> {};

159+ pkgsRaspberryPi = import <nixpkgs> {

160+ crossSystem = pkgsNative.lib.systems.examples.raspberryPi;

161+ };

162+

163+ native = myProject { pkgs = pkgsNative; };

164+ crossRaspberryPi = myProject { pkgs = pkgsRaspberryPi; };

165+

166+in {

167+ my-project-native = native.my-project.components.exes.my-project;

168+ my-project-raspberry-pi = crossRaspberryPi.my-project.components.exes.my-project;

169+}

170+```

171+

172+Try to build it, and apply fixes to the `modules` list, until there

173+are no errors left.

174+

175+

176+

101[nh2]: https://github.com/nh2/static-haskell-nix

177[nh2]: https://github.com/nh2/static-haskell-nix

102[vaibhav]: https://vaibhavsagar.com/blog/2018/01/03/static-haskell-nix/

178[vaibhav]: https://vaibhavsagar.com/blog/2018/01/03/static-haskell-nix/

103[haskell.nix]: https://github.com/input-output-hk/haskell.nix

179[haskell.nix]: https://github.com/input-output-hk/haskell.nix

mkdocs.yml+4−3

@@ -38,7 +38,8 @@ pages:

38 - 'Templates / Abstraction':

39 - 'IOHKs nix library': iohk-nix.md

40 - 'Dev Notes':

41− - 'Architecture': dev-architecture.md

41+ - 'Architecture': dev/dev-architecture.md

42− - 'Removing withPackage wrapper': removing-with-package-wrapper.md

42+ - 'Removing withPackage wrapper': dev/removing-with-package-wrapper.md

43− - 'Maintainer Scripts': maintainer-scripts.md

43+ - 'Maintainer Scripts': dev/maintainer-scripts.md

44+ - 'Nixpkgs Pin': dev/nixpkgs-pin.md

44 - 'ChangeLog': changelog.md

45 - 'ChangeLog': changelog.md