Flakes: Difference between revisions

<languages />

{{Cleanup}}

<!--T:182-->

'''Nix flakes''' are an [[Experimental Nix features|experimental feature]] first introduced in the 2.4 [[Nix]] release,{{Cite manual|nix|development/experimental-features|number=13.8|title=Experimental Features|subsection=xp-feature-flakes|subtitle=flakes}}{{Cite manual|nix|release-notes/rl-2.4|number=14.27|title=Release 2.4 (2021-11-01)}} aiming to address a number of areas of improvement for the Nix ecosystem: they provide a uniform structure for Nix projects, allow for pinning specific versions of each dependencies, and sharing these dependencies via lock files, and overall make it more convenient to write reproducible Nix expressions.

<!--T:185-->

== Flake file structure ==

Minimally, a flake file contains a description of the flake, a set of input dependencies and an output. You can generate a very basic flake file at any time using nix flake init. This will populate the current directory with a file called flake.nix that will contain something akin to:

{{File|3=<nowiki>{

   description = "A very basic flake";

inputs = {

     nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";

   };

outputs = { self, nixpkgs }: {

packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;

packages.x86_64-linux.default = self.packages.x86_64-linux.hello;

};

}</nowiki>|name=flake.nix|lang=nix}}

In the example above, you can see the description, the input specified as a GitHub repository with a specific branch (here <code>nixos/nixpkgs</code> on the <code>nixos-unstable</code> branch), and an output that makes use of the input. The output simply specifies that the flake contains one package for the x86_64 architecture called <code>hello</code>. Even if your flake's output wouldn't use its input (however, in practice, that is highly unlikely), the output still needs to be a Nix function.

<!--T:191-->

=== Nix configuration ===

It is possible to override the global Nix configuration set in your <code>nix.conf</code> file for the purposes of evaluating a flake. This can be useful, for example, for setting up binary caches specific to certain projects, while keeping the global configuration untouched. The flake file can contain a nixConfig attribute with any relevant configuration settings supplied. For example, enabling the nix-community binary cache would be achieved by:

{{File|3=<nowiki>{

   ...

     ];

   }

== Setup == <!--T:192-->

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

</translate>

<syntaxhighlight lang="shell">

  --experimental-features 'nix-command flakes'

</syntaxhighlight>

<translate>

=== Enabling flakes permanently === <!--T:193-->

<!--T:8-->

Add the following to the [[Overview_of_the_NixOS_Linux_distribution#Declarative_Configuration system configuration |NixOS configuration]]:

<syntaxHighlight lang=nix>

   nix.settings.experimental-features = [ "nix-command" "flakes" ];

</syntaxHighlight>

<translate>

====Home Manager==== <!--T:10-->

<!--T:11-->

Add the following to your [[Home Manager|home manager]] config:

<syntaxhighlight lang="nix">

   nix.settings.experimental-features = [ "nix-command" "flakes" ];

</syntaxhighlight>

<translate>

====Nix standalone==== <!--T:13-->

<!--T:15-->

Add the following to <code>~/.config/nix/nix.conf</code> or <code>/etc/nix/nix.conf</code>:

<syntaxHighlight lang=text>

experimental-features = nix-command flakes

</syntaxHighlight>

<translate>

== Usage == <!--T:17-->

<!--T:64-->

=== The nix flakes command ===

{{Main|Nix (command)}}

<!--T:65-->

The {{ic|nix flake}} subcommand is described in {{Nix Manual|name=command reference page of the Nix manual|anchor=command-ref/new-cli/nix3-flake}}.

<!--T:194-->

This flake produces a single flake output <code>packages</code>. And within that, <code>x86_64-linux</code> is a system-specifc attribute set. And within that, two package [[derivations]] <code>default</code> and <code>hello</code>. You can find outputs with the {{Nix Manual|name=show command|anchor=command-ref/new-cli/nix3-flake-show}} of a flake as shown below:

<syntaxhighlight lang="console">

$ nix flake show

</syntaxhighlight>

==== Development shells ==== <!--T:196-->

<!--T:197-->

A <code>devShell</code> is a Nix-provided [[Development_environment_with_nix-shell#nix develop|development environment]] defined within a flake. It lets you declare a reproducible shell environment with the tools, libraries, and environment variables you need for the development of a specific project. This is flake equivalent to defining a <code>nix-shell</code>.

<syntaxhighlight lang="nix">

{

   description = "Example flake with a devShell";

inputs.nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";

outputs = { self, nixpkgs}:

     let

</syntaxhighlight>

<!--T:201-->

To enter the development shell environment:

<syntaxhighlight lang="console">

$ nix develop

</syntaxhighlight>

<!--T:203-->

{{note|You don’t need to define a devShell to enter a development shell using nix develop.

<!--T:103-->

Running <code>nix build</code> will look in the <code>legacyPackages</code> and <code>packages</code> output attributes for the corresponding [[derivation]] and then your system architecture and build the default output. If you want to specify a build attribute in a flake repository, you can run <code>nix build .#<attr></code>. In the example above, if you wanted to build the <code>packages.x86_64-linux.hello</code> attribute, run:

<syntaxHighlight lang=console>

$ nix build .#hello

</syntaxHighlight>

<!--T:205-->

Likewise, you can specify an attribute with the run command: <code>nix run .#hello</code> and the develop command: <code>nix develop .#hello</code>.

<!--T:34-->

[[Nixpkgs]] can be defined using the following code:

<code>inputs.nixpkgs.url = "github:NixOS/nixpkgs/<branch name>";</code>

Nixpkgs can alternatively also point to an url cached by the NixOS organization:

<code>inputs.nixpkgs.url = "<nowiki>https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz</nowiki>";</code>

In this example the input would point to the `nixpkgs-unstable` channel.

<!--T:36-->

<!--T:37-->

For example, adding [[Hyprland]] as an input would look something like this:

<code>inputs.hyprland.url = "github:hyprwm/Hyprland";</code>

<translate>

<!--T:39-->

If you want to make Hyprland follow the nixpkgs input to avoid having multiple versions of nixpkgs, this can be done using the following code:

<code>inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";</code>

<translate>

<!--T:41-->

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

<syntaxhighlight lang="nix">

inputs = {

};

</syntaxhighlight>

<translate>

<!--T:206-->

By default, Git submodules in package <code>src</code>'s won't get copied to the nix store, this may cause the build to fail. Flakes in Git repositories can declare that they need Git submodules to be enabled. Since Nix version [https://discourse.nixos.org/t/nix-2-27-0-released/62003 2.27], you can enable submodules by:

<syntaxhighlight lang="nix">

   inputs.self.submodules = true;

</syntaxhighlight>

=== Output schema === <!--T:42-->

<!--T:154-->

* <code><store-path></code> is a <code>/nix/store..</code> path

<syntaxhighlight lang="nix">

{ self, ... }@inputs:

}

</syntaxhighlight>

<translate>

<!--T:48-->

You can also define additional arbitrary attributes, but these are the outputs that Nix knows about.

<!--T:211-->

Flakes force you to specify a program for each supported architecture. An example below shows how to write a flake that targets multiple architectures.

<syntaxhighlight lang="nix">

{

   description = "A flake targeting multiple architectures";

inputs = {

     nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";

   };

outputs = { self, nixpkgs }: let

     systems = [ "x86_64-linux" "aarch64-linux" ];

</syntaxhighlight>

<!--T:215-->

You can also use third-parties projects like [[Flake Utils|flake-utils]] or [[Flake Parts|flake-parts]] that automatically provide code to avoid this boilerplate. To avoid re-defining the program multiple times, refer to [[Flake Utils#Defining a flake for multiple architectures]]

<!--T:218-->

To allow for [[Unfree software|unfree software]] in a flake project, you need to explicitly allow it by setting <code>config.allowUnree = true;</code> when importing Nixpkgs.

<syntaxhighlight lang="nix">

{

</syntaxhighlight>  

== NixOS configuration with flakes == <!--T:220-->

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

https://docs.cachix.org/pushing#flakes

<translate>

=== Flake support in projects without flakes === <!--T:50-->

=== Build a package added in a PR === <!--T:161-->

<syntaxHighlight>

nix build github:nixos/nixpkgs?ref=pull/<PR_NUMBER>/head#<PACKAGE>

</syntaxHighlight>

<translate>

<!--T:162-->

this allows building a package that has not yet been added to nixpkgs.

<!--T:132-->

note that this will download a full source tarball of nixpkgs.  if you already have a local clone, using that may be faster due to delta compression:

<syntaxHighlight>

git fetch upstream pull/<PR_NUMBER>/head && git checkout FETCH_HEAD && nix build .#PACKAGE

</syntaxHighlight>

<translate>

<!--T:163-->

this allows building a package that has not yet been added to nixpkgs.

<!--T:133-->

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>):

<syntaxHighlight>

git add --intent-to-add extra/flake.nix

git update-index --skip-worktree --assume-unchanged extra/flake.nix

</syntaxHighlight>

<translate>

=== Rapid iteration of a direct dependency === <!--T:135-->

<!--T:136-->

Consider a situation where your executable, <code>consumexe</code>, depends on a library, <code>libdep</code>. You're trying to work on both at the same time, where changes to <code>libdep</code> are reflected in real time for <code>consumexe</code>. This workflow can be achieved like so:

<syntaxHighlight lang=bash>

cd ~/libdep-src-checkout/

installPhase # install it like nix does

</syntaxHighlight>

<translate>

<!--T:166-->

Now that you've built the dependency, <code>consumexe</code> can take it as an input. '''In another terminal''':

<syntaxHighlight lang=bash>

cd ~/consumexe-src-checkout/

# Output should show ~/libdep-src-checkout/ so you know it worked

</syntaxHighlight>

<translate>

<!--T:181-->

* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]

{{references}}

</translate>