Add documentation for Flakes

- Add some beginning resources for Nix Flakes.

Author: sevanspowell

docs/code/Flakes/Explanation/Why.md

@@ -0,0 +1,46 @@
+---
+title: Why Flakes?
+date: 2021-02-10
+---
+
+Nix Flakes are a new feature of the "nix package manager". They unify the typical ways of declaring inputs and ouputs of a project under a common syntax.
+
+But why use them?
+
+## Why?
+
+  - Unify the management of inputs (make redundant tools like `niv`).
+  - Remove sources of impurity that existed in the previous model.
+  - Standardize the output format of repositories.
+    - A Nix expression typically creates a "package" for a repository, for example, the cardano-wallet expression creates a binary package which is available at "cardano-wallet". The location of the attribute in the output attribute set is completely arbitrary. Another repository might put their "package" at "packages.cardano-doohickey".
+    - Nix flakes attempt to standardize the typical output locations of a Nix expression, so that packages are always available at the same location.
+
+## Concepts
+
+From an abstract point of view, a derivation in Nix is a function from inputs to ouputs. Inputs are typically libraries and executables, and the output is typically another library or executable.
+
+Flakes extend the input/output model of derivations to the entire repository. A single file sits at the root of the repository called `flake.nix`, that might look something like this:
+
+```
+{
+  description = "Example flake";
+
+  inputs = {
+    cardano-db-sync.url = "github:input-output-hk/cardano-db-sync?ref=refs/tags/12.0.0";
+    haskellNix.url = "github:input-output-hk/haskell.nix";
+    # ... other inputs
+  };
+
+  outputs = { cardano-db-sync, haskellNix }: {
+    packages.x86_64-linux.linode-cli = pkgs.python3Packages.callPackage ./pkgs/linode-cli.nix {};
+    # ... other outputs
+  };
+}
+```
+
+It's conceptually quite simple. Given these inputs, this repository produces a set of outputs.
+
+IOHK previously made use of `niv`, `niv` was just a different method of pinning inputs that wrote to the file "sources.json". The flakes model isn't necessarily "better" than `niv`, but flakes have other benefits.
+
+By running `nix flake lock`, the inputs of the repository are pinned down to specific revisions and SHAs and written to `flake.lock`.
+

docs/code/Flakes/Reference/CommonErrors.md

@@ -0,0 +1,10 @@
+---
+title: Common Errors
+date: 2021-02-09
+---
+
+```
+error: getting status of '/nix/store/1dg75ahm07ah26phnd1jy1jq06s680ps-source/some-file.nix': No such file or directory
+```
+
+Make sure the file is staged to version control. Flakes can't see files that are not tracked by version control.

docs/code/Flakes/Reference/Invocations.md

@@ -0,0 +1,50 @@
+---
+title: Invocations and Pathing
+date: 2021-02-10
+---
+
+## Invocations
+
+`nix-build` is now `nix build`
+
+`nix-shell` is now `nix develop`
+
+`nix-repl default.nix` is now:
+
+```
+$ nix repl
+> :lf .
+# Get some information:
+> legacyPackages.x86_64-linux.pkgs.stdenv.hostPlatform.libc
+# Build cardano-wallet:
+> :b packages.x86_64-linux.cardano-wallet
+```
+
+## Pathing
+
+`nix-build -A cardano-wallet` is now `nix build .#packages.x86_64-linux.cardano-wallet`
+
+i.e.
+
+```
+nix build $FLAKE_PATH
+$FLAKE_PATH = $PATH_TO_FLAKE_FILE#$ATTRIBUTE
+$FLAKE_PATH = .#packages.x86_64-linux.cardano-cli
+```
+
+The `$PATH_TO_FLAKE_FILE` can be quite complicated:
+
+```
+  · .: The flake in the current directory.
+  · /home/alice/src/patchelf: A flake in some other directory.
+  · nixpkgs: The nixpkgs entry in the flake registry.
+  · nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293: The nixpkgs entry in the flake registry, with its Git revision overridden to a specific value.
+  · github:NixOS/nixpkgs: The master branch of the NixOS/nixpkgs repository on GitHub.
+  · github:NixOS/nixpkgs/nixos-20.09: The nixos-20.09 branch of the nixpkgs repository.
+  · github:NixOS/nixpkgs/a3a3dda3bacf61e8a39258a0ed9c924eeca8e293: A specific revision of the nixpkgs repository.
+  · github:edolstra/nix-warez?dir=blender: A flake in a subdirectory of a GitHub repository.
+  · git+https://github.com/NixOS/patchelf: A Git repository.
+  · git+https://github.com/NixOS/patchelf?ref=master: A specific branch of a Git repository.
+  · git+https://github.com/NixOS/patchelf?ref=master&rev=f34751b88bd07d7f44f5cd3200fb4122bf916c7e: A specific branch and revision of a Git repository.
+  · https://github.com/NixOS/patchelf/archive/master.tar.gz: A tarball flake.
+```

docs/code/Flakes/Reference/Schema.md

@@ -0,0 +1,112 @@
+---
+title: Nix Flake Schema
+date: 2021-02-09
+---
+
+The `flake.nix` has the following schema:
+
+```
+{
+  description = "A string";
+  inputs = *input_schema;
+  outputs = *output_schema:
+}
+```
+
+## Input schema
+
+An example input attrset:
+
+```
+{
+  # A GitHub repository.
+  import-cargo = {
+    type = "github";
+    owner = "edolstra";
+    repo = "import-cargo";
+  };
+
+  import-cargo-alt.url = github:edolstra/import-cargo;
+
+  nixpkgs.url = "nixpkgs";
+
+  cardano-db-sync.url = "github:input-output-hk/cardano-db-sync?ref=refs/tags/12.0.0";
+
+  nixpkgs-alt.url = "github:NixOS/nixpkgs/nixos-21.11";
+}
+```
+
+
+## Output schema
+
+There is a standard schema for the outputs of a flake:
+
+```
+{ self, cardano-db-sync, nixpkgs, import-cargo, ... } @ inputs: {
+  # Packages built by the repository.
+  #   Executed by `nix build .#<name>`
+  packages."<system>"."<name>" = derivation;
+
+  # Executed by `nix build .`
+  defaultPackage."<system>" = derivation;
+
+  # A default development shell for the project.
+  #   Used by `nix develop`.
+  devShell."<system>" = derivation;
+
+  # A development shell for the project.
+  #   Used by `nix develop .#<name>`
+  devShells."<system>"."<name>" = derivation;
+
+  # Hydra build jobs
+  hydraJobs."<attr>"."<system>" = derivation;
+
+  # Automated checks.
+  #   Executed by `nix flake check`
+  checks."<system>"."<name>" = derivation;
+
+  # Used for nixpkgs packages, also accessible via `nix build .#<name>`
+  # Typically the repository will provide the version of nixpkgs used in the repository here:
+  # E.g.
+  #   legacyPackages = import nixpkgs {
+  #     inherit system overlays;
+  #   };
+  legacyPackages."<system>"."<name>" = derivation;
+
+  # Used by `nix flake init -t <flake>#<name>`
+  templates."<name>" = { path = "<store-path>"; description = ""; };
+
+  # Default overlay, consumed by other flakes. Overlays are typically overlaid onto nixpkgs to add extra packages to the package set. Potentially for another project or for a system configuration.
+  overlay = final: prev: { };
+
+  # Same idea as overlay but a list or attrset of them.
+  overlays = {};
+
+  # Default module, consumed by other flakes. NixOS modules are used by NixOS configurations to "modularize" configuration.
+  # For example, by importing the "cardano-node.nixosModule" I can run a simple node on my computer by enabling the option: "services.cardano-node.enable = true".
+  nixosModule = { config }: { options = {}; config = {}; };
+
+  # Same idea as nixosModule but a list or attrset of them.
+  nixosModules = {};
+
+  # Used with `nixos-rebuild --flake .#<hostname>`
+  # nixosConfigurations."<hostname>".config.system.build.toplevel must be a derivation
+  nixosConfigurations."<hostname>" = {};
+
+  # Used by `nix flake init -t <flake>`
+  defaultTemplate = {
+    path = "<store-path>";
+    description = "template description goes here?";
+  };
+
+  # Executed by `nix run .#<name>`
+  apps."<system>"."<name>" = {
+    type = "app";
+    program = "<store-path>";
+  };
+
+  # Default application
+  #   Executed by `nix run . -- <args?>`
+  defaultApp."<system>" = { type = "app"; program = "..."; };
+}
+```

docs/code/Flakes/Tutorials/Hacking.md

@@ -0,0 +1,32 @@
+---
+title: 03-Create a Development Environment
+date: 2021-02-09
+---
+
+## Hacking
+
+`nix-shell` has been replaced by `nix develop`, and by default it builds the attribute `devShell.x86_64-linux`, so a simple python development environment would look like this:
+
+`flake.nix`
+```
+{
+  description = "A very basic flake";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-21.11";
+  };
+
+  outputs = { self, nixpkgs }:
+    let
+      pkgs = nixpkgs.legacyPackages.x86_64-linux
+    in {
+      devShell.x86_64-linux = pkgs.mkShell {
+        nativeBuildInputs = [
+          pkgs.python3
+        ];
+      };
+    };
+}
+```
+
+We could then run `nix develop` and we would enter a shell with access to python.

docs/code/Flakes/Tutorials/Installation.md

@@ -0,0 +1,40 @@
+---
+title: 01-Installation
+date: 2021-02-09
+---
+
+Presuming nix is already installed, Nix flakes are available from Nix version 2.4 and up.
+
+## Non-NixOS
+
+```
+$ nix-env -iA nixpkgs.nixUnstable # or nixpkgs.nix_2_4
+                                  # or nixpkgs.nix_2_5
+                                  # or nixpkgs.nix_2_6, etc.
+```
+
+Then edit either `~/.config/nix/nix.conf` or `/etc/nix/nix.conf` and add:
+
+```
+experimental-features = nix-command flakes
+```
+
+## NixOS
+
+Add the following to your NixOS configuration:
+
+`/etc/nixos/configuration.nix`
+```
+  nix = {
+    package = pkgs.nixUnstable; # or pkgs.nix_2_4
+                                # or pkgs.nix_2_5
+                                # or pkgs.nix_2_6, etc.
+    extraOptions = ''
+      experimental-features = nix-command flakes
+    '';
+  };
+```
+
+Then
+
+`nixos-rebuild switch`