e15f235 · haskell.nix · git.iko.soy

.buildkite/pipeline.yml−1

compare with iko/ghcjs-patch-master

unifiedsplit

@@ -15,6 +15,5 @@ steps:

15 command:

16 - nix-build build.nix -A maintainer-scripts.update-docs -o update-docs.sh

17 - ./update-docs.sh

18− branches: master

19 agents:

18 agents:

20 system: x86_64-linux

19 system: x86_64-linux

.gitignore+1

@@ -1,5 +1,6 @@

1# The output of "mkdocs build"

2/site/

3+docs/reference/modules.md

3

4

4# Nix build results

5# Nix build results

5result*

6result*

build.nix+13−1

@@ -24,7 +24,19 @@ in {

24 update-hackage = haskell.callPackage ./scripts/update-hackage.nix {};

25 update-stackage = haskell.callPackage ./scripts/update-stackage.nix {};

26 update-pins = haskell.callPackage ./scripts/update-pins.nix {};

27− update-docs = haskell.callPackage ./scripts/update-docs.nix {};

27+ update-docs = haskell.callPackage ./scripts/update-docs.nix {

28+ generatedOptions = import ./scripts/options-doc.nix {

29+ # nixpkgs unstable changes "Option has no description" from an

30+ # error into a warning. That is quite helpful when hardly any

31+ # of our options are documented, thanks @oxij.

32+ pkgs = import (pkgs.fetchFromGitHub {

33+ owner = "NixOS";

34+ repo = "nixpkgs";

35+ rev = "4ab1c14714fc97a27655f3a6877386da3cb237bc";

36+ sha256 = "16lcj9552q2jfxc27j6116qkf2vl2dcj7vhg5gdq4qi51d891yhn";

37+ }) {};

38+ };

39+ };

28 check-hydra = haskell.callPackage ./scripts/check-hydra.nix {};

40 check-hydra = haskell.callPackage ./scripts/check-hydra.nix {};

29 };

41 };

30}

42}

docs/reference/commands.md+8−3

@@ -23,8 +23,10 @@ output directory, it will create a basic one with a

23

24!!! note

25 If you find that there are missing files which should have been

26− generated, remove `.stack-to-nix.cache`. (There's an open issue for

26+ generated, remove `.stack-to-nix.cache`

27− this).

27+ (The open issue is [#57][cache-issue]).

28+

29+[cache-issue]: https://github.com/input-output-hk/haskell.nix/issues/57

28

30

29# plan-to-nix

31# plan-to-nix

30

32

@@ -58,7 +60,10 @@ Inside the output directory, there will be another directory

58generated by `cabal-to-nix`. The output file `pkgs.nix` refers to

60generated by `cabal-to-nix`. The output file `pkgs.nix` refers to

59these files.

61these files.

60

62

61−Same note as above applies about the cache file.

63+!!! note

64+ If you find that there are missing files which should have been

65+ generated, remove `.nix-tools.cache`

66+ (The open issue is [#57][cache-issue]).

62

67

63# cabal-to-nix

68# cabal-to-nix

64

69

docs/reference/library.md+73−9

@@ -42,18 +42,27 @@ system.

42

43## Haskell Package description

44

45+The _Haskell package descriptions_ are values of the

46+`pkgSet.config.packages` attrset. These are not derivations, but just

45−Options for building a package. (todo: more info)

47+the configuration for building an individual package. The

48+configuration options are described under `packages.<name>` in [Module

49+options](./modules.md).

46

50

47## Component description

51## Component description

48

52

49−Options for building a component. (todo: more info)

53+The _component descriptions_ are values of the

54+`pkgSet.config.packages.<package>.components` attrset. These are not

55+derivations, but just the configuration for building an individual

56+component. The configuration options are described under

57+`packages.<name>.components.*` in [Module options](./modules.md).

58+

50

59

51## Haskell Package

60## Haskell Package

52

61

62+In [Haskell.nix][], a _Haskell package_ is a derivation which has a

53−A derivation which has a `components` attribute. This derivation is

63+`components` attribute. This derivation is actually just for the

54−actually just for the package `Setup.hs` script, and isn't very

64+package `Setup.hs` script, and isn't very interesting. To actually use

55−interesting. To actually use the package, look within the components

65+the package, look within the components structure.

56−structure.

57

66

58```

67```

59components = {

68components = {

@@ -67,14 +76,44 @@ components = {

67

76

68## Component

77## Component

69

78

79+In [Haskell.nix][], a _component_ is a derivation corresponding to a

80+[Cabal component](https://www.haskell.org/cabal/users-guide/developing-packages.html)

81+of a package.

82+

83+[Haskell.nix][] also defines a special `all` component, which is the

84+union of all components in the package.

85+

70## Identifier

86## Identifier

71

87

72A package identifier is an attrset pair of `name` and `version`.

88A package identifier is an attrset pair of `name` and `version`.

73

89

74## Extras

90## Extras

75

91

92+Extras allow adding more packages to the package set. These will be

93+functions taking a single parameter `hackage`. They should return an

94+attrset of package descriptions.

95+

76## Modules

96## Modules

77

97

98+Modules are the primary method of configuring building of the package

99+set. They are either:

100+

101+1. an attrset containing [option declarations](./options.md), or

102+2. a function that returns an attrset containing option declarations.

103+

104+If using the function form of a module, the following named parameters

105+will be passed to it:

106+

107+| Argument | Type | Description |

108+|------------------|------|---------------------|

109+| `haskellLib` | attrset | The [haskellLib](#haskelllib) utility functions. |

110+| `pkgs` | | The Nixpkgs collection. |

111+| `pkgconfPkgs` | | A mapping of cabal build-depends names to Nixpkgs packages. (TODO: more information about this) |

112+| `buildModules` | | |

113+| `config` | | |

114+| `options` | | |

115+

116+

78# Top-level attributes

117# Top-level attributes

79

118

80## mkStackPkgSet

119## mkStackPkgSet

@@ -126,7 +165,11 @@ This is an attrset of `hsPkgs` packages from Stackage.

126

165

127## haskellPackages

166## haskellPackages

128

167

129−A `hsPkgs` package set

168+A `hsPkgs` package set, which is one of the recent LTS Haskell

169+releases from [`snapshots`](#snapshots).

170+

171+The chosen LTS is updated occasionally in [Haskell.nix][], though a

172+manual process.

130

173

131## nix-tools

174## nix-tools

132

175

@@ -145,6 +188,10 @@ A derivation containing the `nix-tools` [command-line tools](commands.md).

145

188

146## haskellLib

189## haskellLib

147

190

191+Assorted functions for operating on [Haskell.nix][] data. This is

192+distinct from `pkgs.haskell.lib` in the current Nixpkgs Haskell

193+Infrastructure.

194+

148# Package-set functions

195# Package-set functions

149

196

150These functions exist within the `hsPkgs` package set.

197These functions exist within the `hsPkgs` package set.

@@ -152,8 +199,8 @@ These functions exist within the `hsPkgs` package set.

152## shellFor

199## shellFor

153

200

154Create a `nix-shell` [development

201Create a `nix-shell` [development

155−environment](../user-guide/development.md) *for* developing one or

202+environment](../user-guide/development.md) for developing one or more

156−more packages.

203+packages.

157

204

158```

205```

159shellFor =

206shellFor =

@@ -171,7 +218,24 @@ shellFor =

171

218

172## ghcWithPackages

219## ghcWithPackages

173

220

221+Creates a `nix-shell` [development

222+environment](../user-guide/development.md) including the given

223+packages selected from this package set.

224+

225+**Parameter**: a package selection function.

226+

227+**Return value**: a derivation

228+

229+**Example**:

230+

231+```

232+haskell.haskellPackages.ghcWithPackages (ps: with ps; [ lens conduit ])

233+```

234+

174## ghcWithHoogle

235## ghcWithHoogle

175

236

237+The same as `ghcWithPackages`, except, a `hoogle` command with a

238+Hoogle documentation index of the packages will be included in the

239+shell.

176

240

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

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

docs/reference/modules-preamble.mdnew file+10

@@ -0,0 +1,10 @@

1+Haskell.nix modules options for packages and components.

2+

3+!!! note "Undocumented"

4+ Please help write me.

5+

6+ This documentation is generated from Nix sources in the

7+ [`modules`](https://github.com/input-output-hk/haskell.nix/tree/master/modules)

8+ subdirectory.

9+

10+ The Markdown generation script could also be improved.

docs/reference/modules.mddeleted−4

@@ -1,4 +0,0 @@

1−Haskell.nix modules options for packages and components.

2−

3−!!! note "Undocumented"

4− Please help write me.

docs/user-guide/cabal-projects.md+4

@@ -14,6 +14,10 @@ about how to choose a specific compiler version.

14

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

16

17+!!! note "Cabal version"

18+ The minimum Cabal version is 2.4. This version is available

19+ in the NixOS 19.03 release.

20+

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

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

18version for Nixpkgs.

22version for Nixpkgs.

19

23

scripts/options-doc.nixnew file+29

@@ -0,0 +1,29 @@

1+{ pkgs ? import <nixpkgs> {}

2+, lib ? pkgs.lib

3+}:

4+let

5+ # Provide a dummy pkg-def for the package set function

6+ pkg-def = hackage: {

7+ packages = {};

8+ compiler = {

9+ version = "";

10+ nix-name = "";

11+ packages = {};

12+ };

13+ };

14+

15+ # Apply the package set function to get NixOS options.

16+ inherit (import ../package-set.nix { hackage = null; inherit pkgs pkg-def; }) options;

17+

18+ # Use code from the NixOS manual to generate Docbook XML options list.

19+ manual = import (pkgs.path + /nixos/doc/manual) {

20+ inherit pkgs options;

21+ config.meta.doc = [];

22+ version = "testing";

23+ revision = "testing";

24+ };

25+in

26+ # Convert docbook options list to markdown

27+ pkgs.runCommand "options.md" {} ''

28+ ${pkgs.buildPackages.pandoc}/bin/pandoc -s -f docbook -t markdown_strict ${manual.generatedSources}/options-db.xml -o $out

29+ ''

scripts/update-docs.nix+6−1

@@ -1,4 +1,5 @@

1−{ stdenv, writeScript, coreutils, glibc, git, openssh, gnused, mkdocs }:

1+{ stdenv, writeScript, coreutils, glibc, git, openssh, gnused, mkdocs

2+, generatedOptions }:

2

3

3with stdenv.lib;

4with stdenv.lib;

4

5

@@ -15,6 +16,9 @@ in

15

16

16 source ${./git.env}

17 source ${./git.env}

17

18

19+ echo "Preprocessing..."

20+ cat docs/reference/modules-preamble.md ${generatedOptions} > docs/reference/modules.md

21+

18 echo "Building..."

22 echo "Building..."

19 rm -rf site

23 rm -rf site

20 mkdocs build

24 mkdocs build

@@ -23,6 +27,7 @@ in

23 sed -i -e '/lastmod/d' site/sitemap.xml

27 sed -i -e '/lastmod/d' site/sitemap.xml

24 rm -f site/sitemap.xml.gz

28 rm -f site/sitemap.xml.gz

25 rev=$(git rev-parse --short HEAD)

29 rev=$(git rev-parse --short HEAD)

30+ rm docs/reference/modules.md

26

31

27 echo "Updating git index..."

32 echo "Updating git index..."

28 git fetch origin

33 git fetch origin