Add a bit about creating your own expressions

README.md

@@ -74,3 +74,69 @@ To undo the last install/update/remove command
 ```sh
 nix-env --rollback
 ```
+
+# Creating an expression
+
+The best way to create a new package is to pillage existing package
+expressions.  This includes the ones in [this
+repository](https://git.sharcnet.ca/nix/nixpkgs-sharcnet) (click the
+repository tab to see the files) and all the various [upstream
+ones](https://git.sharcnet.ca/nix/nixpkgs-sharcnet/tree/master) (click
+on a package and then following the Nix expression link).  The
+[packaging manual](https://nixos.org/nixpkgs/manual/) details all the
+various options you will see in these files.
+
+## Building
+
+A package can be build by running (replace *file.nix* with the name of
+your file)
+
+
+```sh
+nix-build file.nix
+```
+
+If the build succeeds, the output will be symlinked into
+the current directory as *result*.
+
+## Debugging a build
+
+A simulated build environment can be entered by running (replace
+*file.nix* with the name of your file)
+
+```sh
+nix-shell --pure file.nix
+```
+
+which gives you a shell in the build environment described by the
+epxression.  The default build and install locations need to be
+overriden to somewhere you have write permission (this uses */tmp*)
+
+
+```sh
+NIX_BUILD_TOP=/tmp/nix-$USER
+
+mkdir "$NIX_BUILD_TOP"
+cd "$NIX_BUILD_TOP"
+mkdir out
+out=$PWD/out
+prefix=$out
+```
+
+Then you can invoke the standard nix build phases and use the fact
+that you are in a shell to diagnose whatever goes wrong (setting
+`NIX_ENFORCE_PURITY` enables various checks along the way to ensure no
+host bits get into the results as these would not be available in the
+real sandboxed build)
+
+
+```
+export NIX_ENFORCE_PURITY=1
+
+unpackPhase
+cd "$sourceRoot"
+
+configurePhase
+buildPhase
+installPhase
+```