input-output-hk · rvl · Jun 12, 2019 · Jun 7, 2019 · Jun 12, 2019
diff --git a/docs/dev-architecture.md → docs/dev/dev-architecture.md b/docs/dev-architecture.md → docs/dev/dev-architecture.md
diff --git a/docs/maintainer-scripts.md → docs/dev/maintainer-scripts.md b/docs/maintainer-scripts.md → docs/dev/maintainer-scripts.md
diff --git a/docs/dev/nixpkgs-pin.md b/docs/dev/nixpkgs-pin.md
@@ -0,0 +1,21 @@
+# Haskell.nix Nixpkgs Pin
+
+Haskell.nix contains a Nixpkgs pin in
+[`nixpkgs/github.json`](https://github.com/input-output-hk/haskell.nix/blob/master/nixpkgs/github.json).
+This is the version of Nixpkgs used for builds of `nix-tools` and
+running the tests.
+
+Users should pass their own version of Nixpkgs to Haskell.nix,
+although things might not work for them if their Nixpkgs version is
+too different.
+
+We aim to keep this pin somewhere on the channel of the **NixOS latest
+stable release**. That is currently 19.03. So:
+
+```
+nix-prefetch-git https://github.com/NixOS/nixpkgs-channels refs/heads/nixos-19.03
+```
+
+Keep the URL in `github.json` pointing at
+<https://github.com/NixOS/nixpkgs>. Case matters because the Hydra
+trusted URL whitelist is case-sensitive.
diff --git a/docs/removing-with-package-wrapper.md → docs/dev/removing-with-package-wrapper.md b/docs/removing-with-package-wrapper.md → docs/dev/removing-with-package-wrapper.md
diff --git a/docs/reference/library.md b/docs/reference/library.md
@@ -4,6 +4,10 @@ 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](#types) — the kinds of data that you will encounter working with [Haskell.nix][].
+ * [Top-level attributes](#top-level-attributes) — Functions and derivations defined in the Haskell.nix attrset.
+ * [Package-set functions](#package-set-functions) — Helper functions defined on the `hsPkgs` package set.
+
 # Types
 
 ## Package Set

diff --git a/docs/user-guide/cabal-projects.md b/docs/user-guide/cabal-projects.md
@@ -8,9 +8,11 @@ dependencies of your package(s).
 
 ## Generating `plan.json`
 
-To get a plan, you need Cabal and GHC. See the [Nixpkgs
-Manual](https://nixos.org/nixpkgs/manual/#how-to-install-a-compiler)
-for information about how to choose a specific compiler version.
+To get a plan, you need Cabal and GHC. See the [How to install a
+compiler section of the Nixpkgs Manual][compiler] for information
+about how to choose a specific compiler version.
+
+[compiler]: https://nixos.org/nixpkgs/manual/#how-to-install-a-compiler
 
 For this example, we will run a `nix-shell` with the default GHC
 version for Nixpkgs.
@@ -23,6 +25,12 @@ nix-shell -p haskellPackages.cabal-install haskellPackages.ghc \
 If all goes well, you should now have the file
 `dist-newstyle/cache/plan.json`.
 
+!!! tip "Specifying the GHC version"
+    To use a specific compiler version, replace `haskellPackages.ghc`
+    with something like `haskell.compiler.ghc865`. The given compiler
+    must exist in your Nixpkgs version, of course. See also the
+    [Nixpkgs Manual][compiler].
+
 ## Using `plan-to-nix`
 
 With [nix-tools installed](../user-guide.md), we can then run the

diff --git a/docs/user-guide/cross-compilation.md b/docs/user-guide/cross-compilation.md
@@ -6,7 +6,7 @@ First, understand how to cross-compile a normal package from
 Nixpkgs. Matthew Bauer's [Beginners' guide to cross compilation in
 Nixpkgs][bauer] is a useful resource.
 
-[bauer]: https://matthewbauer.us/blog/beginners-guide-to-cross.html 
+[bauer]: https://matthewbauer.us/blog/beginners-guide-to-cross.html
 
 
 Using 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
 GHC, before building all the Haskell dependencies of [Bench][]. If all
 of these dependencies compiled successfully, I would be very surprised!
 
+!!! hint
+    The above example won't build, but you can try and see, if you like.
+    It will fail on [clock-0.7.2](http://hackage.haskell.org/package/clock-0.7.2),
+    which needs a patch to build.
+
 To fix the build problems, you must add extra configuration to the
 package set. Your project will have a [`mkStackPkgSet`](../reference/library.md#mkstackpkgset) or
 [`mkCabalProjectPkgSet`](../reference/library.md#mkcabalprojectpkgset). It is there where you must add
-[module options](../reference/modules.md) for setting compiler flags and so on.
+[module options](../reference/modules.md) for setting compiler flags, adding patches, and so on.
+
 
 ### Static executables with Musl libc
 
 Another application of cross-compiling is to produce fully static
 binaries for Linux. For information about how to do that with the
 [Nixpkgs Haskell infrastructure][nixpkgs] (not [Haskell.nix][]), see
-[nh2/static‑haskell‑nix][nh2]. Vaibhav Sagar's linked [blog
-post][vaibhav] is also very informative.
+[nh2/static‑haskell‑nix][nh2]. Vaibhav Sagar's linked
+[blog post][vaibhav] is also very informative.
 
 
 ```nix
@@ -98,6 +104,76 @@ executables you must add package overrides to:
     `integer-gmp`. However, at present, [Haskell.nix][] does not provide
     an option for this.
 
+
+### How to cross-compile your project
+
+Set up your project Haskell package set.
+
+```nix
+# default.nix
+{ pkgs ? import <nixpkgs> {}
+let
+  # Import the Haskell.nix library,
+  haskell = import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {
+    inherit pkgs;
+  };
+
+  # Instantiate a package set using the generated file.
+  pkgSet = haskell.mkCabalProjectPkgSet {
+    plan-pkgs = import ./pkgs.nix;
+    pkg-def-extras = [];
+    modules = [
+      {
+        # You will need to put build fixes here.
+      }
+    ];
+  };
+in
+  pkgSet.config.hsPkgs
+```
+
+Apply that package set to the Nixpkgs cross package sets that you are
+interested in.
+
+We are going to expand the `pkgs.pkgsCross` shortcut to be more
+explicit.
+
+```nix
+let
+  pkgs = import <nixpkgs> {}
+in {
+  shortcut = pkgs.pkgsCross.SYSTEM;
+  actual = import <nixpkgs> { crossSystem = pkgs.lib.systems.examples.SYSTEM; };
+}
+```
+
+In the above example, for any `SYSTEM`, `shortcut` and `actual` are
+the same package set.
+
+```nix
+# release.nix
+let
+  myProject = import ./default.nix;
+
+  pkgsNative = import <nixpkgs> {};
+  pkgsRaspberryPi = import <nixpkgs> {
+    crossSystem = pkgsNative.lib.systems.examples.raspberryPi;
+  };
+
+  native = myProject { pkgs = pkgsNative; };
+  crossRaspberryPi = myProject { pkgs = pkgsRaspberryPi; };
+
+in {
+  my-project-native = native.my-project.components.exes.my-project;
+  my-project-raspberry-pi = crossRaspberryPi.my-project.components.exes.my-project;
+}
+```
+
+Try to build it, and apply fixes to the `modules` list, until there
+are no errors left.
+
+
+
 [nh2]: https://github.com/nh2/static-haskell-nix
 [vaibhav]: https://vaibhavsagar.com/blog/2018/01/03/static-haskell-nix/
 [haskell.nix]: https://github.com/input-output-hk/haskell.nix

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -38,7 +38,8 @@ pages:
   - 'Templates / Abstraction':
     - 'IOHKs nix library': iohk-nix.md
   - 'Dev Notes':
-    - 'Architecture': dev-architecture.md
-    - 'Removing withPackage wrapper': removing-with-package-wrapper.md
-    - 'Maintainer Scripts': maintainer-scripts.md
+    - 'Architecture': dev/dev-architecture.md
+    - 'Removing withPackage wrapper': dev/removing-with-package-wrapper.md
+    - 'Maintainer Scripts': dev/maintainer-scripts.md
+    - 'Nixpkgs Pin': dev/nixpkgs-pin.md
   - 'ChangeLog': changelog.md