input-output-hk · rvl · Jun 7, 2019 · Jun 6, 2019 · Jun 7, 2019
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,9 @@
+# The output of "mkdocs build"
+/site/
+
+# Nix build results
+result*
+/nt
 
 # Created by https://www.gitignore.io/api/haskell,emacs,vim
 

diff --git a/changelog.md b/changelog.md
@@ -1,3 +1,15 @@
+This file contains a summary of changes to Haskell.nix and `nix-tools`
+that will impact users.
+
+## June 7, 2019
+  * Several additions to the [documentation](https://input-output-hk.github.io/haskell.nix/).
+    * More information about getting nix-tools, Haskell.nix, pinning.
+    * Updates the stack-to-nix and cabal-to-nix guides.
+    * Adds a section on development environments.
+    * Adds a little information about cross compilation.
+    * Adds a (partially complete) reference section (command line manuals, library reference).
+    * Symlinks the changelog into the documentation pages.
+
 ## May 29, 2019
   * Added `shellFor` function to package set.
 
@@ -8,7 +20,7 @@
 ## May 22, 2019
   * Add the `cleanSourceHaskell` utility function to the Haskell.nix
     top-level.
-  
+
 ## May 21, 2019
   * Add the `callCabalProjectToNix` function, which uses "import from
     derivation" (IFD) so that nix-tools doesn't need to be run
@@ -23,7 +35,13 @@
   * Add the `callStackToNix` function, which uses "import from
     derivation" (IFD) so that `stack-to-nix` doesn't need to be run
     manually.
-  
+
 ## Mar 15, 2019
-  * overlays was renamed to extras (#79)
-    See docs/migration.md
+  * `overlays` was renamed to `extras` in
+    [#79](https://github.com/input-output-hk/haskell.nix/pull/79)
+    to prevent confusion between the notion of Nix overlays.
+
+    Therefore `plan-pkgs` and `stack-pkgs` as generated by `plan-to-nix` and `stack-to-nix` will
+    expose `extras` instead of `overlay`. Similarly `mkStackPkgSet`, `mkPkgSet` and `mkCabalProjectPkgSet`
+    take a `pkg-def-extras` instead of `pkg-def-overlay` argument.  If you are using `iohk-nix`, the
+    `iohk-overlay` was parameter was renamed to `iohk-extras`.
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -43,22 +43,26 @@ nix-tools is a Haskell package that provides the following tools:
 
 as well as a few other tools used to generate `hackage.nix` and `stackage.nix`.
 
-## [haskell.nix](https://github.com/input-output-hk/haskell.nix)
+## [haskell.nix][]
 
-haskell.nix is the runtime system for this Haskell infrastructure.  It
-contains the component builder, as well as the system package and
+[Haskell.nix][] is the runtime system for this Haskell infrastructure.
+It contains the component builder, as well as the system package and
 license mapping.  Without haskell.nix the expressions generated by
 either of the `nix-tools` tools make little sense on their own.
 
-## [hackage.nix](https://github.com/input-output-hk/hackage.nix)
+## [hackage.nix][]
 
-hackage.nix provides all cabal expressions from hackage as nix
+[hackage.nix][] provides all cabal expressions from hackage as nix
 expressions.  It is periodically updated to keep in sync with the set
 of packages available on hackage.
 
-## [stackage.nix](https://github.com/input-output-hk/stackage.nix)
+## [stackage.nix][]
 
-stackage.nix is similar to hackage.nix but provides all stackage
+[stackage.nix][] is similar to hackage.nix but provides all stackage
 snapshots (lts, and nightly) as nix expressions.  It naturally depends
 on hackage.nix to resolve package names, versions and revisions to the
 repsective packages from hackage.nix.
+
+[haskell.nix]: https://github.com/input-output-hk/haskell.nix
+[hackage.nix]: https://github.com/input-output-hk/hackage.nix
+[stackage.nix]: https://github.com/input-output-hk/stackage.nix
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1 @@
+../changelog.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,7 +1,11 @@
 # haskell.nix
 
 haskell.nix is an alternative Haskell infrastructure for nixpkgs. See
-[Nixpkgs current Users' Guide to Haskell Infrastructure](https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure) for comparison.
+[Nixpkgs current Users' Guide to Haskell Infrastructure][nixpkgs] for
+comparison.
+
+[nixpkgs]: https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure
+[issues]: https://github.com/input-output-hk/haskell.nix/issues
 
 ## Motivation
 

diff --git a/docs/migrations.md b/docs/migrations.md
diff --git a/docs/reference/commands.md b/docs/reference/commands.md
@@ -0,0 +1,75 @@
+# stack-to-nix
+
+```
+stack-to-nix - a stack to nix converter
+
+Usage: stack-to-nix (-o|--output DIR) [--stack-yaml FILE]
+                    [--ignore-package-yaml] [--cache FILE]
+  Generate a Nix expression for a Haskell package using Stack
+
+Available options:
+  -o,--output DIR          Generate output in DIR
+  --stack-yaml FILE        Override project stack.yaml (default: "stack.yaml")
+  --ignore-package-yaml    disable hpack run and use only cabal disregarding
+                           package.yaml existence
+  --cache FILE             Dependency cache
+                           file (default: ".stack-to-nix.cache")
+  -h,--help                Show this help text
+```
+
+Use this for stack projects. If a `default.nix` does not exist in the
+output directory, it will create a basic one with a
+[`mkStackPkgSet`](../user-guide/stack-projects.md) function.
+
+!!! note
+    If you find that there are missing files which should have been
+    generated, remove `.stack-to-nix.cache`. (There's an open issue for
+    this).
+
+# plan-to-nix
+
+```
+plan-to-nix - a stack to nix converter
+
+Usage: plan-to-nix (-o|--output DIR) [--plan-json FILE] [--cabal-project FILE]
+                   [--cache FILE]
+  Generate a Nix expression for a Haskell package using Cabal
+
+Available options:
+  -o,--output DIR          Generate output in DIR
+  --plan-json FILE         Override plan.json
+                           location (default: "dist-newstyle/cache/plan.json")
+  --cabal-project FILE     Override path to
+                           cabal.project (default: "cabal.project")
+  --cache FILE             Dependency cache file (default: ".nix-tools.cache")
+  -h,--help                Show this help text
+```
+
+Use this for Cabal new-build projects (even if you don't have a
+`cabal.project`). Before running, you need to create a plan. For more
+information, see [Cabal Projects](../user-guide/cabal-projects.md) in the user
+guide.
+
+It will create a template `default.nix` in the output directory,
+unless that file already exists.
+
+Inside the output directory, there will be another directory
+`.plan.nix`, which contains Nix expressions for all local packages,
+generated by `cabal-to-nix`. The output file `pkgs.nix` refers to
+these files.
+
+Same note as above applies about the cache file.
+
+# cabal-to-nix
+
+```
+Usage: cabal-to-nix FILE.cabal
+```
+
+This writes (to stdout) a [Haskell.nix][] Nix expression for the given
+cabal package.
+
+Normally, you do not need to run `cabal-to-nix` yourself. It is called
+by `stack-to-nix` and `plan-to-nix`.
+
+[haskell.nix]: https://github.com/input-output-hk/haskell.nix
diff --git a/docs/reference/library.md b/docs/reference/library.md
@@ -0,0 +1,173 @@
+[Haskell.nix][] contains a library of functions for creating buildable
+package sets from their Nix expression descriptions. The library is
+what you get when importing [Haskell.nix][]. It might be helpful to
+load the library in the [Nix REPL](../user-guide.md#using-nix-repl) to
+test things.
+
+# Types
+
+## Package Set
+
+The result of `mkPkgSet`. This is an application of the NixOS module
+system.
+
+```
+{
+  options = { ... };
+  config = {
+    hsPkgs = { ... };
+    packages = { ... };
+    compiler = {
+      version = "X.Y.Z";
+      nix-name = "ghcXYZ";
+      packages = { ... };
+    };
+  };
+}
+```
+
+| Attribute      | Type | Description                                         |
+|----------------|------|-----------------------------------------------------|
+| `options` | Module options | The combination of all options set through the `modules` argument passed to `mkPkgsSet`. |
+| `config` |  | The result of evaluating and applying the `options` with [Haskell.nix][] |
+| `.hsPkgs` | Attrset of [Haskell Packages](#haskell-package) | Buildable packages, created from `packages` |
+| `.packages` | Attrset of [Haskell Package descriptions](#haskell-package-descriptions) | Configuration for each package in `hsPkgs` |
+| `.compiler` | Attrset | |
+
+
+
+## Haskell Package description
+
+Options for building a package. (todo: more info)
+
+## Component description
+
+Options for building a component. (todo: more info)
+
+## Haskell Package
+
+A derivation which has a `components` attribute. This derivation is
+actually just for the package `Setup.hs` script, and isn't very
+interesting. To actually use the package, look within the components
+structure.
+
+```
+components = {
+  library = COMPONENT;
+  exes = { NAME = COMPONENT; };
+  tests = { NAME = COMPONENT; };
+  benchmarks = { NAME = COMPONENT; };
+  all = COMPONENT;
+}
+```
+
+## Component
+
+## Identifier
+
+A package identifier is an attrset pair of `name` and `version`.
+
+## Extras
+
+## Modules
+
+# Top-level attributes
+
+## mkStackPkgSet
+
+Creates a [package set](#package-set) based on the `pkgs.nix` output
+of `stack-to-nix`.
+
+```nix
+mkStackPkgSet =
+    { stack-pkgs, pkg-def-extras ? [], modules ? []}: ...
+```
+
+| Argument         | Type | Description         | 
+|------------------|------|---------------------|
+| `stack-pkgs`     |  | `import ./pkgs.nix` — The imported file generated by `stack‑to‑nix`. |
+| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
+| `modules` | List of [Modules](#modules) | For overriding the package set. |
+
+**Return value**: a [`pkgSet`](#package-set)
+
+## mkCabalProjectPkgSet
+
+Creates a [package set](#package-set) based on the `pkgs.nix` output
+of `plan-to-nix`.
+
+```nix
+mkCabalProjectPkgSet =
+    { plan-pkgs, pkg-def-extras ? [], modules ? []}: ...
+```
+
+| Argument         | Type | Description         | 
+|------------------|------|---------------------|
+| `plan-pkgs`     |  | `import ./pkgs.nix` — The imported file generated by `plan‑to‑nix`. |
+| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
+| `modules` | List of [Modules](#modules) | For overriding the package set. |
+
+**Return value**: a [`pkgSet`](#package-set)
+
+## mkPkgSet
+
+This is the base function used by both `mkStackPkgSet` and
+`mkCabalProjectPkgSet`.
+
+**Return value**: a [`pkgSet`](#package-set)
+
+## snapshots
+
+This is an attrset of `hsPkgs` packages from Stackage.
+
+## haskellPackages
+
+A `hsPkgs` package set
+
+## nix-tools
+
+A derivation containing the `nix-tools` [command-line tools](commands.md).
+
+## callStackToNix
+
+## callCabalProjectToNix
+
+## hackage
+## stackage
+
+## fetchExternal
+
+## cleanSourceHaskell
+
+## haskellLib
+
+# Package-set functions
+
+These functions exist within the `hsPkgs` package set.
+
+## shellFor
+
+Create a `nix-shell` [development
+environment](../user-guide/development.md) *for* developing one or
+more packages.
+
+```
+shellFor =
+    { packages, withHoogle ? true, ...}: ...
+```
+
+
+| Argument       | Type | Description         | 
+|----------------|------|---------------------|
+| `packages`     | Function | Package selection function. It takes a list of [Haskell packages](#haskell-package) and returns a subset of these packages. |
+| `withHoogle` | Boolean | Whether to build a Hoogle documentation index and provide the `hoogle` command. |
+| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). |
+
+**Return value**: a derivation
+
+## ghcWithPackages
+
+## ghcWithHoogle
+
+
+[haskell.nix]: https://github.com/input-output-hk/haskell.nix
diff --git a/docs/reference/modules.md b/docs/reference/modules.md
@@ -0,0 +1,4 @@
+Haskell.nix modules options for packages and components.
+
+!!! note "Undocumented"
+    Please help write me.