Flakes: Difference between revisions

'''Nix flakes''' is an [https://nixos.org/manual/nix/stable/contributing/experimental-Features.html experimental feature] that was introduced with Nix 2.4 ([https://nixos.org/manual/nix/unstable/release-notes/rl-2.4.html see release notes]).

====Introduction==== <!--T:2-->

<!--T:3-->

Nix flakes enforce a uniform structure for Nix projects, pin versions of their dependencies in a lock file, and make it more convenient to write reproducible Nix expressions.

<!--T:4-->

* A [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html#description flake] refers to a file-system tree whose root directory contains the Nix file specification called <code>flake.nix</code>.

<!--T:141-->

* The contents of <code>flake.nix</code> file follow a uniform naming schema for declaring packages and their dependencies in the Nix language.

<!--T:142-->

*  Flakes introduce a [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references URL-like syntax] for specifying remote sources.

<!--T:143-->

* To simplify the long URL syntax with shorter names, [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-registry.html flakes uses a registry] of symbolic identifiers.

<!--T:144-->

* Flakes also allow for locking references and versions that can then be queried and updated programmatically.

<!--T:145-->

====Enable flakes temporarily==== <!--T:5-->

When using any <code>nix</code> command, add the following command-line options:

====Enable flakes permanently in NixOS==== <!--T:7-->

====Other Distros, with Home-Manager==== <!--T:10-->

Add the following to your home-manager config:

====Other Distros, without Home-Manager==== <!--T:13-->

===Basic Usage of Flake=== <!--T:17-->

<!--T:18-->

Before running any nix commands at this point, please note the two warnings below: one for encryption and the other for git.

====Encryption WARNING==== <!--T:19-->

<!--T:20-->

{{Warning | Since contents of flake files are copied to the world-readable Nix store folder, do not put any unencrypted secrets in flake files. You should instead use a [[Comparison of secret managing schemes|secret managing scheme]].}}

====Git WARNING==== <!--T:21-->

<!--T:146-->

For flakes in git repos, only files in the working tree will be copied to the store.

<!--T:22-->

Therefore, if you use <code>git</code> for your flake, ensure to <code>git add</code> any project files after you first create them.

<!--T:23-->

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

====Generate flake.nix file==== <!--T:24-->

<!--T:25-->

To start the basic usage of flake, run the flake command in the project directory:

</translate>

<syntaxHighlight lang=text>

nix flake init

<translate>

* <code>nixConfig</code> is an attribute set of values which reflect the [https://nixos.org/manual/nix/stable/command-ref/conf-file.html values given to nix.conf]. This can extend the normal behavior of a user's nix experience by adding flake-specific configuration, such as a binary cache.

Nixpkgs can be defined using the following code:

Using curly brackets({}), we can shorten all of this and put it in a table. The code will look something like this:

==== nix run ==== <!--T:49-->

 

 

 

 

<!--T:52-->

 

 

 

 

 

 

 

== Making your evaluations pure == <!--T:60-->

Nix flakes run in pure evaluation mode, which is underdocumented. Some tips for now:

* fetchurl and fetchtar [https://github.com/NixOS/nix/blob/36c4d6f59247826dde32ad2e6b5a9471a9a1c911/src/libexpr/primops/fetchTree.cc#L201 require] a sha256 argument to be considered pure.

* builtins.currentSystem is non-hermetic and impure. This can usually be avoided by passing the system (i.e., x86_64-linux) explicitly to derivations requiring it.

 

 

 

 

 

 

== Using nix flakes with NixOS == <!--T:68-->

<!--T:69-->

{{Ic|nixos-rebuild switch}} will read its configuration from <code>/etc/nixos/flake.nix</code> if it is present.

<!--T:70-->

A basic nixos flake.nix could look like this:

</translate>

   inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;

<!--T:158-->

If you want to pass on the flake inputs to external configuration files, you can use the <code>specialArgs</code> attribute:

 

<syntaxhighlight lang="nix">

{

  inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;

 

    };

</translate>

<syntaxhighlight lang="nix">

{ inputs, ... }:

{

nix.registry = {

     nixpkgs.flake = inputs.nixpkgs;

<!--T:86-->

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

<syntaxhighlight lang="nix">

  pkgs ? import <nixpkgs> { },

    # ...

<!--T:89-->

<!--T:90-->

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

</translate>

   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";

 

   outputs =

    { nixpkgs, ... }:

     {

       /*

        This example assumes your system is x86_64-linux

       devShells.x86_64-linux =

          pkgs = nixpkgs.legacyPackages.x86_64-linux;

        in

        {

          default = pkgs.mkShell {

            packages = [ pkgs.hello ];

</syntaxhighlight>

<translate>

<!--T:93-->

<!--T:94-->

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

<!--T:95-->

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

<!--T:96-->

=== Automatically switch nix shells with nix-direnv === <!--T:97-->

You can easily switch nix shells when you cd into different projects with [https://github.com/nix-community/nix-direnv nix-direnv].

== Pushing Flakes to Cachix == <!--T:99-->

<!--T:101-->

== Build specific attributes in a flake repository == <!--T:102-->

<!--T:103-->

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.

<!--T:104-->

</translate>

<syntaxHighlight lang=console>

$ nix build .#hello

</syntaxHighlight>

<translate>

=== Building flakes from a Git repo url with submodules === <!--T:106-->

<!--T:107-->

As per nix 2.9.1, git submodules in package <code>src</code>'s won't get copied to the nix store, this may cause the build to fail.  To workaround this, use:

 

nix build '.?submodules=1#hello'

 

See: https://github.com/NixOS/nix/pull/5434

 

 

<!--T:111-->

A NixOS config flake could be as follows:

 

 

 

 

  # ...

 

<!--T:160-->

If the variable <code>nixpkgs</code> points to the flake, you can also define <code>pkgs</code> with overlays with:

 

pkgs = import nixpkgs { system = "x86_64-linux"; overlays = [ /*the overlay in question*/ ]; };

 

 

 

 

Added 18 variables.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

When a git folder exists, flake will only copy files added in git to maximize reproducibility (this way if you forgot to add a local file in your repo, you will directly get an error when you try to compile it). However, for development purpose you may want to create an alternative flake file, for instance containing configuration for your preferred editors as described [https://discourse.nixos.org/t/local-personal-development-tools-with-flakes/22714/8 here]… of course without committing this file since it contains only your own preferred tools. You can do so by doing something like that (say for a file called <code>extra/flake.nix</code>):

* [https://www.youtube.com/watch?v=QXUlhnhuRX4&list=PLgknCdxP89RcGPTjngfNR9WmBgvD_xW0l Nix flakes 101: Introduction to nix flakes] (Jörg Thalheim, 2020)

<!--T:178-->

* [https://github.com/numtide/flake-utils flake-utils: Library to avoid some boiler-code when writing flakes]

<!--T:180-->

* [https://zimbatm.com/NixFlakes/#direnv-integration zimbat's direnv article]