View source for Flakes

Nix flakes is some upcoming feature in the Nix package manager.
It allows to download nix expressions from other sources 
in a declarative way by specifying them a flake.nix file. 
Those sources are called flakes and also have a flake.nix 
where they can describe their own dependencies.
Sources can be tarballs, git, local directories or mercurial repositories.
It makes evaluation reproducible with providing a lock called flake.lock.
This lock file provides hashes for sources and locks the revision
of external version control system.
Nix flakes intents to replace nix channels and the nix search path (<code>NIX_PATH</code>).

== Installing nix flakes ==

Right now nix flakes are only available in the unstable nix version and need to be enabled in nix.conf as well.
=== NixOS ===
In NixOS this can be achieved with the following line in <code>configuration.nix</code>

<syntaxHighlight lang=nix>
{ pkgs, ... }: {
   nix = {
    package = pkgs.nixUnstable;
    extraOptions = ''
      experimental-features = nix-command flakes
    '';
   };
}
</syntaxHighlight>

=== Non-NixOS ===
On non-nixos system install `nixUnstable` in your environment:

<syntaxHighlight lang=console>
$ nix-env -iA nixUnstable
</syntaxHighlight>

Edit either <code>~/.config/nix/nix.conf</code> or <code>/etc/nix/nix.conf</code> and add:

<syntaxHighlight>
experimental-features = nix-command flakes 
</syntaxHighlight>

This is needed to expose the Nix 2.0 CLI and flakes support that are hidden behind feature-flags.

Finally, if the Nix installation is in multi-user mode, don’t forget to restart the nix-daemon.

There is no official installer yet, but you can use the [https://github.com/numtide/nix-flakes-installer nix-flake-installer]:

<syntaxHighlight lang=console>
$ sh <(curl -L https://github.com/numtide/nix-flakes-installer/releases/download/nix-3.0pre20200804_ed52cf6/install)
</syntaxHighlight>

== Basic project usage ==
{{warning|flake makes a strong assumption that the folder is a git or mercurial repository. It doesn’t work outside of them.}}

In your repo, run <code>nix flake init</code> to generate the flake.nix file. Then run <code>git add flake.nix</code> to add it to the git staging area, otherwise nix will not recognize that the file exists.

See also https://www.tweag.io/blog/2020-05-25-flakes/

== Flake schema ==

The flake.nix file is a Nix file but that has special restrictions (more on that later).

It has 3 top-level attributes:

* <code>description</code> which is self…describing
* <code>input</code> is an attribute set of all the dependencies of the flake. The schema is described below.
* <code>output</code> is a function of one argument that takes an attribute set of all the realized inputs, and outputs another attribute set which schema is described below.

== Input schema ==

This is not a complete schema but should be enough to get you started:

<syntaxHighlight lang=nix>
{
  # github example, also supported gitlab:
  inputs.nixpkgs.url = "github:Mic92/nixpkgs/master";
  # git urls
  inputs.git-example.url = "git+https://git.somehost.tld/user/path";
  # local directories (needs to be a repository?)
  inputs.directory-example.url = "/path/to/repo";
  # Use this for non-flakes
  inputs.bar.url = "github:foo/bar/branch";
  inputs.bar.flake = false;
  # Overwrite inputs in a flake
  # This is useful to use the same nixpkgs version in both flakes
  inputs.sops-nix.url = "github:Mic92/sops-nix";
  inputs.sops-nix.inputs.nixpkgs.follows = "nixpkgs";
}
</syntaxHighlight>

The bar input is then passes to the output schema

== Output schema ==

This is described in the nix package manager [https://github.com/NixOS/nix/blob/master/src/nix/flake.cc src/nix/flake.cc] in CmdFlakeCheck.

Where:
 
* <code><system></code> is something like "x86_64-linux", "aarch64-linux", "i686-linux", "x86_64-darwin"
* <code><attr></code> is an attribute name like "hello".
* <code><flake></code> is a flake name like "nixpkgs".
* <code><store-path></code> is a <code>/nix/store..</code> path

<syntaxHighlight lang=nix>
{ self, ... }@inputs:
{
  # This will be shown in `nix flake info`
  description = "A description what his flake provides";
  # Executed by `nix flake check`
  checks."<system>"."<attr>" = derivation;
  # Executed by `nix build .#<name>`
  packages."<system>"."<attr>" = derivation;
  # Executed by `nix build .`
  defaultPackage."<system>" = derivation;
  # Executed by `nix run .#<name>`
  apps."<system>"."<attr>" = {
    type = "app";
    program = "<store-path>";
  };
  # Executed by `nix run . -- <args?>`
  defaultApp."<system>" = { type = "app"; program = "..."; };
  
  # Used for nixpkgs packages, also accessible via `nix build .#<name>`
  legacyPackages."<system>"."<attr>" = derivation;
  # Default overlay, for use in dependent flakes
  overlay = final: prev: { };
  # Same idea as overlay but a list or attrset of them.
  overlays = {};
  # Default module, for use in dependent flakes
  nixosModule = { config }: { options = {}; config = {}; };
  # Same idea as nixosModule but a list or attrset of them.
  nixosModules = {};
  # Attrset of nixos configurations by hostname.
  nixosConfigurations."<hostname>" = {};
  hydraJobs."<attr>"."<system>" = derivation;
  # Used by `nix flake init -t <flake>`
  defaultTemplate = {
    path = "<store-path>";
    description = "template description goes here?";
  };
  # Used by `nix flake init -t <flake>#<attr>`
  templates."<attr>" = { path = "<store-path>"; description = ""; );
}
</syntaxHighlight>

== The nix flakes command ==

The nix flake subcommand is described [[Nix command/flake|here]].

== Using nix flakes with NixOS ==

nixos-rebuild switch will reads its configuration from <code>/etc/nixos/flake.nix</code> if is present.

A basic nixos flake.nix could look like this:

<syntaxHighlight lang=nix>
{
  outputs = { self, nixpkgs }: {
     # replace 'joes-desktop' with your hostname here.
     nixosConfigurations.joes-desktop = nixpkgs.lib.nixosSystem {
       system = "x86_64-linux";
       modules = [ ./configuration.nix ];
     }
  };
}
</syntaxHighlight>

nixos-rebuild also allows to specify different flake using the <code>--flake</code> flag (# is optional):

<syntaxHighlight lang=console>
$ sudo nixos-rebuild switch --flake '.#'
</syntaxHighlight>

By default nixos-rebuild will use the currents system hostname to lookup the right nixos configuration in <code>nixosConfigurations</code>. You can also override this by using appending it to the flake parameter:

<syntaxHighlight lang=console>
$ sudo nixos-rebuild switch --flake '/etc/nixos#joes-desktop'
</syntaxHighlight>

To switch a remote configuration, use:
<syntaxHighlight lang=console>
$ nixos-rebuild --flake .#mymachine \
  --target-host mymachine-hostname --build-host localhost \
  switch
</syntaxHighlight>
 
{{warning|Remote building seems to be broken at the moment, which is why the build host is set to “localhost”.}}

== Super fast nix-shell ==

One of the nix feature of the Flake edition is that Nix evaluations are cached.

Let’s say that your project has a <code>shell.nix</code> file that looks like this:

<syntaxHighlight lang=nix>
{ pkgs ? import <nixpkgs> { } }:
with pkgs;
mkShell {
  buildInputs = [
    nixpkgs-fmt
  ];

  shellHook = ''
    # ...
  '';
}
</syntaxHighlight>

Running nix-shell can be a bit slow and take 1-3 seconds.

Now create a <code>flake.nix</code> file in the same repository:

<syntaxHighlight lang=nix>
{
  description = "my project description";

  inputs.flake-utils.url = "github:numtide/flake-utils";

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem
      (system:
        let pkgs = nixpkgs.legacyPackages.${system}; in
        {
          devShell = import ./shell.nix { inherit pkgs; };
        }
      );
}
</syntaxHighlight>

Run git add flake.nix so that Nix recognizes it.

And finally, run <code>nix develop</code>. This is what replaces the old nix-shell invocation.

Exit and run again, this command should now be super fast.

{{warning|TODO: there is an alternative version where the defaultPackage is a pkgs.buildEnv that contains all the dependencies. And then nix shell is used to open the environment.}}

=== Direnv integration ===

Assuming that the flake defines a <code>devShell</code> output attribute and that you are using direnv. Here is how to replace the old use nix stdlib function with the faster flake version:

<syntaxHighlight lang=sh>
use_flake() {
  watch_file flake.nix
  watch_file flake.lock
  eval "$(nix print-dev-env --profile "$(direnv_layout_dir)/flake-profile")"
}
</syntaxHighlight>

Copy this in <code>~/.config/direnv/lib/use_flake.sh</code> or in <code>~/.config/direnv/direnvrc</code>
or directly in your project specific <code>.envrc</code>.

With this in place, you can now replace the use nix invocation in the <code>.envrc</code> file with <code>use flake</code>:

<syntaxHighlight>
# .envrc
use flake
</syntaxHighlight>

The nice thing about this approach is that evaluation is cached.

==== Optimize the reloads ==== 

Nix Flakes has a Nix evaluation caching mechanism. Is it possible to expose that somehow to automatically trigger direnv reloads?

With the previous solution, direnv would only reload iff the flake.nix or flake.lock files have changed. This is not completely precise as the flake.nix file might import other files in the repository.

== Pushing Flake inputs to Cachix ==

Flake inputs can also be cached in the Nix binary cache!

<syntaxHighlight lang=console>
$ nix flake archive --json \
  | jq -r '.path,(.inputs|to_entries[].value.path)' \
  | cachix push $cache_name
</syntaxHighlight>

== Build specific attributes in a flake repository ==

When in the repository top-level, run <code>nix build .#<attr></code>. It will look in the <code>legacyPackages</code> and <code>packages</code> output attributes for the corresponding derivation.

Eg, in nixpkgs:

<syntaxHighlight lang=console>
$ nix build .#hello
</syntaxHighlight>

== See also ==

* [https://github.com/numtide/flake-utils flake-utils: Library to avoid some boiler-code when writing flakes]
* [https://zimbatm.com/NixFlakes/#direnv-integration zimbat's direnv article]
* [https://www.tweag.io/blog/2020-05-25-flakes/ Nix Flakes, Part 1: An introduction and tutorial]
* [https://www.tweag.io/blog/2020-06-25-eval-cache/ Nix Flakes, Part 2: Evaluation caching]
* [https://www.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems]