input-output-hk · hamishmack · Jun 19, 2020 · Jun 16, 2020 · Jun 16, 2020 · Jun 17, 2020
diff --git a/README.md b/README.md
@@ -6,98 +6,10 @@
 `haskell.nix` can automatically translate your Cabal or Stack project and
 its dependencies into Nix code.
 
-## [Documentation](https://input-output-hk.github.io/haskell.nix/)
+## Documentation
 
-## Getting started
-
-### a) Using `cabal.project`
-
-Add a `default.nix`:
-
-```nix
-let 
-  # Fetch the latest haskell.nix and import its default.nix
-  haskellNix = import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {};
-
-  # haskell.nix provides access to the nixpkgs pins which are used by our CI, hence
-  # you will be more likely to get cache hits when using these.
-  # But you can also just use your own, e.g. '<nixpkgs>'
-  nixpkgsSrc = haskellNix.sources.nixpkgs-2003;
-
-  # haskell.nix provides some arguments to be passed to nixpkgs, including some patches
-  # and also the haskell.nix functionality itself as an overlay.
-  nixpkgsArgs = haskellNix.nixpkgsArgs;
-in
-{ pkgs ? import nixpkgsSrc nixpkgsArgs
-, haskellCompiler ? "ghc865"
-}:
-
-# 'cabalProject' generates a package set based on a cabal.project (and the corresponding .cabal files)
-pkgs.haskell-nix.cabalProject {
-  # 'cleanGit' cleans a source directory based on the files known by git
-  src = pkgs.haskell-nix.haskellLib.cleanGit { name = "haskell-nix-project"; src = ./.; };
-  compiler-nix-name = haskellCompiler;
-}
-```
-
-Note that you'll need to add a comment specifying the expected sha256
-output for your `source-repository-packages` in your `cabal.project`
-file:
-
-```
-source-repository-package
-  type: git
-  location: https://github.com/input-output-hk/iohk-monitoring-framework
-  subdir:   plugins/backend-editor
-  tag: 4956b32f039579a0e7e4fd10793f65b4c77d9044
-  --sha256: 03lyb2m4i6p7rpjqarnhsx21nx48fwk6rzsrx15k6274a4bv0pix
-```
-
-### b) Using `stack.yaml`
-
-Add a `default.nix`:
-
-```nix
-let 
-  haskellNix = import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {};
-  nixpkgsSrc = haskellNix.sources.nixpkgs-2003;
-  nixpkgsArgs = haskellNix.nixpkgsArgs;
-in
-{ pkgs ? import nixpkgsSrc nixpkgsArgs
-}:
-pkgs.haskell-nix.stackProject {
-  src = pkgs.haskell-nix.haskellLib.cleanGit { name = "haskell-nix-project"; src = ./.; };
-}
-```
-
-### Working with a project
-
-To build the library component of a package in the project run:
-
-```shell
-nix build -f . your-package-name.components.library
-```
-
-To build an executable:
-
-```shell
-nix build -f . your-package-name.components.exes.your-exe-name
-```
-
-To open a shell for use with `cabal` run:
-
-```shell
-nix-shell -A shellFor
-cabal new-build your-package-name
-cabal new-repl your-package-name:library:your-package-name
-```
-
-## Using a binary cache
-
-To use precompiled binaries you'll need:
-
-- To configure the IOHK binary cache by following the instructions on [iohk.cachix.org](https://iohk.cachix.org).
-- 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).
+- [Introduction](https://input-output-hk.github.io/haskell.nix/)
+- [Getting Started](https://input-output-hk.github.io/haskell.nix/getting-started/)
 
 ## Related repos
 

diff --git a/docs/index.md b/docs/index.md
@@ -4,12 +4,12 @@
 
 ## Features
 
-- autogenerate Nix expressions for Cabal project
-- autogenerate Nix expressions for Stack
-- overridable configuration
-- cross-compilation
+- Drop-in support for Cabal projects
+- Drop-in support for Stack projects
+- Build any package of specific version in Stackage or Hackage
+- Overridable configuration
+- Cross compile Haskell packages
 
-[^1]: See [Nixpkgs current Users' Guide to Haskell Infrastructure][nixpkgs] for comparison.
-[nixpkgs]: https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure
+[^1]: See [Nixpkgs current Users' Guide to Haskell Infrastructure](https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure) for comparison.
 
 
diff --git a/docs/reference/commands.md b/docs/reference/commands.md
@@ -19,7 +19,7 @@ Available options:
 
 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.
+[`mkStackPkgSet`](../manually-generating-nix-expressions#Using-Stack) function.
 
 !!! note
     If you find that there are missing files which should have been
@@ -49,7 +49,7 @@ Available options:
 
 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
+information, see [Cabal Projects](../manually-generating-nix-expressions#Using-Cabal) in the user
 guide.
 
 It will create a template `default.nix` in the output directory,

diff --git a/docs/reference/library.md b/docs/reference/library.md
@@ -1,7 +1,7 @@
 [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
+load the library in the [Nix REPL](../tutorials/development.md#using-nix-repl) to
 test things.
 
  * [Types](#types) — the kinds of data that you will encounter working with [Haskell.nix][].
@@ -98,7 +98,7 @@ attrset of package descriptions.
 Modules are the primary method of configuring building of the package
 set. They are either:
 
-1. an attrset containing [option declarations](./options.md), or
+1. an attrset containing [option declarations](./modules.md), or
 2. a function that returns an attrset containing option declarations.
 
 If using the function form of a module, the following named parameters
@@ -354,7 +354,7 @@ These functions exist within the `hsPkgs` package set.
 ## shellFor
 
 Create a `nix-shell` [development
-environment](../user-guide/development.md) for developing one or more
+environment](../tutorials/development.md) for developing one or more
 packages with `ghci` or `cabal v2-build` (but not Stack).
 
 ```
@@ -386,7 +386,7 @@ shellFor =
 ## ghcWithPackages
 
 Creates a `nix-shell` [development
-environment](../user-guide/development.md) including the given
+environment](../tutorials/development.md) including the given
 packages selected from this package set.
 
 **Parameter**: a package selection function.

diff --git a/docs/tutorials/building-package-from-stackage-hackage.md b/docs/tutorials/building-package-from-stackage-hackage.md
@@ -0,0 +1,38 @@
+
+# Build a specific package from hackage or a [stackage][] lts or nightly set.
+
+To build a package, say [lens][], from a stackage snapshot, say [lts-13.28][],
+you could run
+```bash
+nix build '(with import <nixpkgs> (import ./. {}).nixpkgsArgs; haskell-nix.snapshots."lts-13.28").lens.components.library'
+```
+which would build the [lens][] library component from the lens package as fixed
+by the [lts-13.28][] stackage snapshot.
+
+## Specific version
+
+To build any package from hackage, say [lens][], in version, say 4.17.1, you
+could run
+```bash
+nix build '(with import <nixpkgs> (import ./. {}).nixpkgsArgs; (haskell-nix.hackage-package { name = "lens"; version = "4.17.1"; })).components.library'
+```
+which would build the [lens][] library component from the [lens-4.17.1][] package
+from hackage.  
+
+## Pinning hackage index
+
+The dependencies would be solved against the most recent 
+[hackage-index-state][] that comes via the [hackage.nix][] pin with your
+[haskell.nix][] checkout.  A specific one can be specified as well:
+```bash
+nix build '(with import <nixpkgs> (import ./. {}).nixpkgsArgs; (haskell-nix.hackage-package { name = "lens"; version = "4.17.1"; index-state = "2019-07-14T00:00:00Z"; })).components.library'
+```
+which would use the hackage index as of `2019-07-14T00:00:00Z` to produce a build plan
+for the [lens-4.17.1][] package.
+
+[stackage]: https://stackage.org
+[hackage.nix]: https://github.com/input-output-hk/hackage.nix
+[lts-13.28]: https://www.stackage.org/lts-13.28
+[lens]: https://hackage.haskell.org/package/lens
+[lens-4.17.1]: https://hackage.haskell.org/package/lens-4.17.1
+[hackage-index-state]: https://github.com/input-output-hk/hackage.nix/blob/master/index-state-hashes.nix
diff --git a/docs/user-guide/clean-git.md → docs/tutorials/clean-git.md b/docs/user-guide/clean-git.md → docs/tutorials/clean-git.md
diff --git a/docs/user-guide/cross-compilation.md → docs/tutorials/cross-compilation.md b/docs/user-guide/cross-compilation.md → docs/tutorials/cross-compilation.md
diff --git a/docs/user-guide/development.md → docs/tutorials/development.md b/docs/user-guide/development.md → docs/tutorials/development.md
@@ -11,7 +11,7 @@ Every dependency will be cached in your Nix store. If you have set up
 Hydra CI, then your team can share pre-built dependencies.
 
 These examples assume that you have created your package set as
-described in [Creating Nix builds for your projects](projects.md) and
+described in [Creating Nix builds for your projects](getting-started.md) and
 it exists in a file called `default.nix`.
 
 !!! note
@@ -179,3 +179,38 @@ Emacs to use it. The way I do it is:
 4. For [`haskell‑mode`](https://github.com/haskell/haskell-mode)
    interactive Haskell, set `haskell‑process‑type` to
    `cabal‑new‑repl`.
+
+## Using `nix repl`
+
+It's sometimes useful to load [Haskell.nix][] in the REPL to explore
+attrsets and try examples. 
+
+```
+# example.nix
+{ nixpkgs ? <nixpkgs> }:
+rec {
+  haskell = import nixpkgs (import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}).nixpkgsArgs;
+  pkgNames = haskell.pkgs.lib.attrNames haskell.haskell-nix.snapshots."lts-13.18";
+}
+```
+
+Load the example file:
+
+```
+$ nix repl '<nixpkgs>' example.nix
+Welcome to Nix version 2.3pre6631_e58a7144. Type :? for help.
+
+Loading '<nixpkgs>'...
+Added 10403 variables.
+
+Loading 'example.nix'...
+Added 2 variables.
+
+nix-repl> lib.take 5 pkgNames
+[ "ALUT" "ANum" "Allure" "Boolean" "BoundedChan" ]
+
+nix-repl> 
+```
+
+Now that you have `nix-tools` and are able to import [Haskell.nix][],
+you can continue to the next chapter.