draft day2 initial readme

1 files changed, 83 insertions, 0 deletions

diff --git a/day2/README.md b/day2/README.md
new file mode 100644
index 0000000..64f1360
--- /dev/null
+++ b/day2/README.md
@@ -0,0 +1,83 @@
+# Day 2 – BioNix workshop
+
+During Day 1 we focused on learning the basics of the Nix configuration
+language, this session will focus on putting that into practice by building and
+executing small reproducible examples. You therefore will need Nix installed, a
+terminal for interacting with it, and this git repository.
+
+## Installing and configuring Nix
+
+Nix can be installed by following the instructions at
+https://nixos.org/download.html. For WEHI Mac uses, Nix is available in the
+Software Centre for install.
+
+Nix is also available on Milton after a `module load nix`, however it is
+recommended to use a local install if available for the workshop as the Milton
+module is configured to submit jobs to the Slurm queue, so waiting times may be
+variable depending on the load. It is worth trying some of the exercises on
+Milton after completion though, to see how easily things can be shifted to
+execution on the cluster without extensive changes.
+
+This workshop also uses a couple of extensions that need to be enabled. Ensure
+you have the following line in `~/.config/nix/nix.conf`:
+
+    experimental-features = nix-command flakes
+
+## The Nix command
+
+The `nix` command is used for interacting with the Nix build system and
+requesting builds or querying the dependency graphs. To see help run
+
+    nix --help
+
+which will display a manpage detailing the subcommands that are available. For
+the most part, you will be using `nix build` to request the output for
+something, and you can see the man page for the subcommand with
+
+    nix build --help
+
+Another important command is `nix store gc`, which requests the nix store to
+clean up all unnecessary files. Nix provides it's isolation by ensuring all
+inputs and outputs are in the *Nix store* located at `/nix/store`. The store can
+grow to large sizes, especially if some of the outputs are large like with
+sequencing. Unnecessary paths are kept as a cache, it speeds up rerunning of
+builds that may depend on things that have already been computed. Running
+garbage collection removes paths in the store that are not referenced either by
+a currently used output or by a currently running build, and there are some
+configuration options for automatically triggering GC when needed (see
+`min-free` and `max-free` of the `nix.conf` manpage).
+
+The `search` command is useful as it allows searching a flake's output for
+keywords. One particularly useful example is when using Nix as a package
+manager, then the `nixpkgs` repository can easily be searched for software. As
+an example, `nix search nixpkgs genome` will output all available software with
+`genome` in the description. The software can then be accessed by dropping into
+a shell, e.g.,:
+
+    nix shell nixpkgs#{SPAdes,quast}
+
+which will provide a shell containing both SPAdes and quast.
+
+## Working through the exercises
+
+To work through the exercises, change into the directory and read the comment at
+the top of `default.nix`. The exercise can be built with
+
+    nix build
+
+in the directory. The solution is provided in `solution.nix` and can be built
+with
+
+    nix build .#solution
+
+however you should try to solve the problem yourself before looking at the
+solution.
+
+## Flakes and hermetic sealing
+
+These exercises use an extension to Nix called *flakes*, which allow for
+hermetically sealing all the input requirements such as *nixpkgs* and *BioNix*.
+How this works is beyond the scope of this workshop, however you can take a look
+at one of the `flake.nix` to see how inputs are defined followed by outputs (our
+workshop exercises) based on the inputs. The `flake.lock` is automatically
+created by Nix and pins the versions of all the inputs precisely.