Difference between revisions of "Flakes"

From NixOS Wiki
Jump to: navigation, search
(Add hint on installing a flake)
(Rewrite introduction paragraph.)
 
(92 intermediate revisions by 42 users not shown)
Line 1: Line 1:
'''Nix Flakes''' are an upcoming feature of the Nix package manager.
+
'''Nix flakes''' is an [https://nixos.org/manual/nix/stable/contributing/experimental-features.html experimental feature] of the Nix package manager. Flakes was introduced with Nix 2.4 ([https://nixos.org/manual/nix/unstable/release-notes/rl-2.4.html see release notes]).
  
== See also ==
+
====Introduction====
  
* [https://xeiaso.net/blog/nix-flakes-1-2022-02-21 Nix Flakes: an Introduction] 2022
+
Nix flakes provide a standard way to write Nix expressions (and therefore packages) whose dependencies are version-pinned in a lock file, improving reproducibility of Nix installations. The experimental <code>nix</code> CLI lets you evaluate or build an expression contained within a flake, install a derivation from a flake into an [[User Environment]], and operate on flake outputs much like the original nix-{build,eval,...} commands would.
* [https://serokell.io/blog/practical-nix-flakes Practical Nix Flakes] - 2021: Intro article on working with Nix and Flakes
 
* [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]
 
* [https://www.youtube.com/watch?v=QXUlhnhuRX4&list=PLgknCdxP89RcGPTjngfNR9WmBgvD_xW0l Nix flakes 101: Introduction to nix flakes]
 
* [https://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]
 
  
== Introduction ==
+
* 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>.
 +
* An installation may contain any number of flakes, independent of each other or even call each other.
 +
* The contents of <code>flake.nix</code> file follow the uniform naming schema for expressing packages and dependencies on Nix.
 +
*  Flakes use the standard Nix protocols, including the [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references URL-like syntax] for specifying repositories and package names.
 +
* 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.
 +
* Flakes also allow for locking references and versions that can then be easily queried and updated programmatically.
 +
*  [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html Nix command-line interface] accepts flake references for expressions that build, run, and deploy packages.
  
Flakes allow you to specify your code's dependencies (e.g. remote Git repositories) in a declarative way, simply by listing them inside a <code>flake.nix</code> file:
+
====Enable flakes temporarily====
  
<syntaxHighlight lang=nix>
+
When using any <code>nix</code> command, add the following command-line options:
{
+
<syntaxHighlight lang=text>
  inputs = {
+
--experimental-features 'nix-command flakes'
    home-manager.url = "github:nix-community/home-manager";
 
  };
 
}
 
 
</syntaxHighlight>
 
</syntaxHighlight>
  
Each dependency gets then pinned, that is: its commit hash gets automatically stored into a file - named <code>flake.lock</code> - making it easy to, say, upgrade it:
+
====Enable flakes permanently in NixOS====
  
<syntaxHighlight lang=console>
+
Add the following to the [https://nixos.wiki/wiki/Overview_of_the_NixOS_Linux_distribution#Declarative_Configuration system configuration] ([https://nixos.wiki/wiki/Flakes#Using_nix_flakes_with_NixOS flakes]):
$ nix flake lock --update-input home-manager
+
 
 +
<syntaxHighlight lang=nix>
 +
  nix.settings.experimental-features = [ "nix-command" "flakes" ];
 
</syntaxHighlight>
 
</syntaxHighlight>
  
''(if you're familiar with modern packages managers like <code>cargo</code> or <code>npm</code>, then the overall mechanism shouldn't surprise you - Nix works in a similar way, although without a centralized repository.)''
+
=====Other Distros, with Home-Manager=====
  
Flakes replace the nix-channels command and things like ad-hoc invocations of <code>builtins.fetchgit</code> - no more worrying about keeping your channels in sync, no more worrying about forgetting about a dependency deep down in your tree: everything's at hand right inside <code>flake.lock</code>.
+
Add the following to your home-manager config:
  
== Installing flakes ==
 
 
=== NixOS ===
 
In NixOS this can be achieved with the following options in <code>configuration.nix</code>.
 
 
==== System-wide installation ====
 
 
<syntaxHighlight lang=nix>
 
<syntaxHighlight lang=nix>
{ pkgs, ... }: {
 
 
   nix = {
 
   nix = {
     package = pkgs.nixFlakes; # or versioned attributes like nixVersions.nix_2_8
+
     package = pkgs.nix;
     extraOptions = ''
+
     settings.experimental-features = [ "nix-command" "flakes" ];
      experimental-features = nix-command flakes
+
  };
    '';
 
  };
 
}
 
 
</syntaxHighlight>
 
</syntaxHighlight>
  
==== Installation as an extra command ====
+
=====Other Distros, without Home-Manager=====
Add command <code>nixFlakes</code> that serves as a flakes-enabled alias to the <code>nix</code> command.
 
  
<syntaxHighlight lang=nix>
+
{{Note | The  [https://github.com/DeterminateSystems/nix-installer Nix Determinate Installer] enables flakes by default.}}
{ pkgs, ... }: {
+
 
  environment.systemPackages = [
+
Add the following to <code>~/.config/nix/nix.conf</code> or <code>/etc/nix/nix.conf</code>:
    (pkgs.writeShellScriptBin "nixFlakes" ''
 
      exec ${pkgs.nixFlakes}/bin/nix --experimental-features "nix-command flakes" "$@"
 
    '')
 
  ];
 
}
 
  
 +
<syntaxHighlight lang=text>
 +
experimental-features = nix-command flakes
 
</syntaxHighlight>
 
</syntaxHighlight>
  
=== Non-NixOS ===
+
===Basic Usage of Flake===
On non-nixos systems, install <code>nixFlakes</code> in your environment:
 
  
<syntaxHighlight lang=console>
+
Before running any nix commands at this point, please note the two warnings below: one for encryption and the other for git.
$ nix-env -iA nixpkgs.nixFlakes
 
</syntaxHighlight>
 
  
Edit either <code>~/.config/nix/nix.conf</code> or <code>/etc/nix/nix.conf</code> and add:
+
====Encryption WARNING====
  
<syntaxHighlight lang=text>
+
{{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]].}}
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.
+
====Git WARNING====
 +
For flakes in git repos, only files in the working tree will be copied to the store.
  
Finally, if the Nix installation is in multi-user mode, don’t forget to restart the nix-daemon.
+
Therefore, if you use <code>git</code> for your flake, ensure to <code>git add</code> any project files after you first create them.
  
== Basic project usage ==
+
See also https://www.tweag.io/blog/2020-05-25-flakes/
  
{{warning | All files tracked by the version control system (e.g. git or mercurial) will be copied to the nix store when the flake is evaluated. So be careful when putting secrets in version control (which is not optimal by itself) around a flake.}}
+
====Generate flake.nix file====
  
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.
+
To start the basic usage of flake, run the flake command in the project directory:
  
See also https://www.tweag.io/blog/2020-05-25-flakes/
+
<syntaxHighlight lang=text>
 
+
nix flake init
To install a flake when using nix outside of nixOS, use <code>nix profile install /path/to/flake</code>. The path may also be an URL (e.g.: <code>nix profile install git+https://example.com/my-repo?dir=subdirectory</code>).
+
</syntaxHighlight>
  
 
== Flake schema ==
 
== Flake schema ==
Line 97: Line 76:
 
The flake.nix file is a Nix file but that has special restrictions (more on that later).
 
The flake.nix file is a Nix file but that has special restrictions (more on that later).
  
It has 3 top-level attributes:
+
It has 4 top-level attributes:
  
 
* <code>description</code> is a string describing the flake.
 
* <code>description</code> is a string describing the flake.
 
* <code>inputs</code> is an attribute set of all the dependencies of the flake. The schema is described below.
 
* <code>inputs</code> is an attribute set of all the dependencies of the flake. The schema is described below.
* <code>outputs</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.
+
* <code>outputs</code> is a function of one argument that takes an attribute set of all the realized inputs, and outputs another attribute set whose schema is described below.
 +
* <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.
  
 
=== Input schema ===
 
=== Input schema ===
  
This is not a complete schema but should be enough to get you started:
+
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-inputs The nix flake inputs manual].
 +
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references The nix flake references manual].
  
<syntaxHighlight lang=nix>
+
=== Output schema ===
{
 
  inputs = {
 
    # github example, also supported gitlab:
 
    nixpkgs.url = "github:Mic92/nixpkgs/master";
 
    # git urls
 
    git-example.url = "git+https://git.somehost.tld/user/path";
 
    # local directories (for absolute paths you can omit 'path:')
 
    directory-example.url = "path:/path/to/repo";
 
    # Use this for non-flakes
 
    bar.url = "github:foo/bar/branch";
 
    bar.flake = false;
 
    # Overwrite inputs in a flake
 
    # This is useful to use the same nixpkgs version in both flakes
 
    sops-nix.url = "github:Mic92/sops-nix";
 
    sops-nix.inputs.nixpkgs.follows = "nixpkgs";
 
    # Pin flakes to a specific revision
 
    nix-doom-emacs.url = "github:vlaci/nix-doom-emacs?rev=238b18d7b2c8239f676358634bfb32693d3706f3";
 
    nix-doom-emacs.flake = false;
 
    # To use a subdirectory of a repo, pass dir=
 
    nixpkgs.url = "github:foo/bar?dir=shu";
 
  }
 
}
 
</syntaxHighlight>
 
Also see [https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references the nix flake manual].
 
 
 
The bar input is then passed to the output schema
 
  
=== Output schema ===
+
Once the inputs are resolved, they're passed to the function `outputs` along with with `self`, which is the directory of this flake in the store. `outputs` returns the outputs of the flake, according to the following 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.
 
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:
 
Where:
+
 
 
* <code><system></code> is something like "x86_64-linux", "aarch64-linux", "i686-linux", "x86_64-darwin"
 
* <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><name></code> is an attribute name like "hello".
 
* <code><flake></code> is a flake name like "nixpkgs".
 
* <code><flake></code> is a flake name like "nixpkgs".
 
* <code><store-path></code> is a <code>/nix/store..</code> path
 
* <code><store-path></code> is a <code>/nix/store..</code> path
Line 163: Line 118:
 
   apps."<system>".default = { type = "app"; program = "..."; };
 
   apps."<system>".default = { type = "app"; program = "..."; };
  
 +
  # Formatter (alejandra, nixfmt or nixpkgs-fmt)
 +
  formatter."<system>" = derivation;
 
   # Used for nixpkgs packages, also accessible via `nix build .#<name>`
 
   # Used for nixpkgs packages, also accessible via `nix build .#<name>`
 
   legacyPackages."<system>"."<name>" = derivation;
 
   legacyPackages."<system>"."<name>" = derivation;
Line 168: Line 125:
 
   overlays."<name>" = final: prev: { };
 
   overlays."<name>" = final: prev: { };
 
   # Default overlay
 
   # Default overlay
   overlays.default = {};
+
   overlays.default = final: prev: { };
 
   # Nixos module, consumed by other flakes
 
   # Nixos module, consumed by other flakes
   nixosModules."<name>" = { config }: { options = {}; config = {}; };
+
   nixosModules."<name>" = { config, ... }: { options = {}; config = {}; };
 
   # Default module
 
   # Default module
   nixosModules.default = {};
+
   nixosModules.default = { config, ... }: { options = {}; config = {}; };
   # Used with `nixos-rebuild --flake .#<hostname>`
+
   # Used with `nixos-rebuild switch --flake .#<hostname>`
 
   # nixosConfigurations."<hostname>".config.system.build.toplevel must be a derivation
 
   # nixosConfigurations."<hostname>".config.system.build.toplevel must be a derivation
 
   nixosConfigurations."<hostname>" = {};
 
   nixosConfigurations."<hostname>" = {};
Line 194: Line 151:
 
You can also define additional arbitrary attributes, but these are the outputs that Nix knows about.
 
You can also define additional arbitrary attributes, but these are the outputs that Nix knows about.
  
== Using flakes project from a legacy Nix ==
+
==== nix run ====
There is a [https://github.com/edolstra/flake-compat flake-compat] library you can use to shim legacy <code>default.nix</code> and <code>shell.nix</code> files. It will download the inputs of the flake, pass them to the flake’s <code>outputs</code> function and return an attribute set containing <code>defaultNix</code> and <code>shellNix</code> attributes. The attributes will contain the output attribute set with an extra <code>default</code> attribute pointing to current platform’s <code>defaultPackage</code> (resp. <code>devShell</code> for <code>shellNix</code>).
+
When output <code>apps.<system>.myapp</code> is not defined, <code>nix run myapp</code> runs <code><packages or legacyPackages.<system>.myapp>/bin/<myapp.meta.mainProgram or myapp.pname or myapp.name (the non-version part)></code>
 +
 
 +
== Using flakes with stable Nix ==
 +
 
 +
There exists the [https://github.com/edolstra/flake-compat flake-compat] library that you can use to shim <code>default.nix</code> and <code>shell.nix</code> files. It will download the inputs of the flake, pass them to the flake’s <code>outputs</code> function and return an attribute set containing <code>defaultNix</code> and <code>shellNix</code> attributes. The attributes will contain the output attribute set with an extra <code>default</code> attribute pointing to current platform’s <code>defaultPackage</code> (resp. <code>devShell</code> for <code>shellNix</code>).
  
 
Place the following into <code>default.nix</code> (for <code>shell.nix</code>, replace <code>defaultNix</code> with <code>shellNix</code>) to use the shim:
 
Place the following into <code>default.nix</code> (for <code>shell.nix</code>, replace <code>defaultNix</code> with <code>shellNix</code>) to use the shim:
Line 231: Line 192:
 
}).defaultNix
 
}).defaultNix
 
</syntaxHighlight>
 
</syntaxHighlight>
 +
 +
== Accessing flakes from Nix expressions ==
 +
 +
If you want to access a flake from within a regular Nix expression on a system that has flakes enabled, you can use something like <code>(builtins.getFlake "path:/path/to/directory").packages.x86_64-linux.default</code>, where 'directory' is the directory that contains your <code>flake.nix</code>.
  
 
== Making your evaluations pure ==
 
== Making your evaluations pure ==
Line 244: Line 209:
 
   {
 
   {
 
     nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
 
     nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
 +
      # Note that you cannot put arbitrary configuration here: the configuration must be placed in the files loaded via modules
 
       system = "x86_64-linux";
 
       system = "x86_64-linux";
 
       modules = [
 
       modules = [
Line 255: Line 221:
 
== The nix flakes command ==
 
== The nix flakes command ==
  
The {{ic|nix flake}} subcommand is described in [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html command reference page of the unstable manual] and here in the [[Nix command/flake]] article.
+
The {{ic|nix flake}} subcommand is described in [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html command reference page of the unstable manual].
 +
 
 +
== Install packages with `nix profile` ==
 +
 
 +
[https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-profile-install.html <code>nix profile install</code> in the manual]
  
 
== Using nix flakes with NixOS ==
 
== Using nix flakes with NixOS ==
Line 277: Line 247:
 
<syntaxHighlight lang=nix>
 
<syntaxHighlight lang=nix>
 
{
 
{
   inputs.nixpkgs.url = github:NixOS/nixpkgs;
+
   inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;
 
   inputs.home-manager.url = github:nix-community/home-manager;
 
   inputs.home-manager.url = github:nix-community/home-manager;
 
+
 
 
   outputs = { self, nixpkgs, ... }@attrs: {
 
   outputs = { self, nixpkgs, ... }@attrs: {
 
     nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
 
     nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
Line 293: Line 263:
 
{ config, lib, nixpkgs, home-manager, ... }: {
 
{ config, lib, nixpkgs, home-manager, ... }: {
 
   # do something with home-manager here, for instance:
 
   # do something with home-manager here, for instance:
   imports = [ home-manager.nixosModule ];
+
   imports = [ home-manager.nixosModules.default ];
 
   ...
 
   ...
 
}
 
}
Line 311: Line 281:
  
 
To switch a remote configuration, use:
 
To switch a remote configuration, use:
<syntaxHighlight lang=console>
+
<syntaxHighlight lang=bash>
 
$ nixos-rebuild --flake .#mymachine \
 
$ nixos-rebuild --flake .#mymachine \
   --target-host mymachine-hostname --build-host localhost \
+
   --target-host mymachine-hostname --build-host mymachine-hostname --fast \
 
   switch
 
   switch
 
</syntaxHighlight>
 
</syntaxHighlight>
+
 
{{warning|Remote building seems to be broken at the moment, which is why the build host is set to “localhost”.}}
+
{{warning|Remote building seems to have an issue that's [https://github.com/NixOS/nixpkgs/issues/134952#issuecomment-1367056358 resolved by setting the <code>--fast</code> flag].}}
 +
 
 +
== Pinning the registry to the system pkgs on NixOS ==
 +
 
 +
<syntaxHighlight lang=nix>
 +
  nix.registry = {
 +
    nixpkgs.to = {
 +
      type = "path";
 +
      path = pkgs.path;
 +
    };
 +
  };
 +
</syntaxHighlight>
  
 
== Super fast nix-shell ==
 
== Super fast nix-shell ==
  
One of the nix feature of the Flake edition is that Nix evaluations are cached.
+
A feature of the nix 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:
 
Let’s say that your project has a <code>shell.nix</code> file that looks like this:
Line 354: Line 335:
 
         let pkgs = nixpkgs.legacyPackages.${system}; in
 
         let pkgs = nixpkgs.legacyPackages.${system}; in
 
         {
 
         {
           devShell = import ./shell.nix { inherit pkgs; };
+
           devShells.default = import ./shell.nix { inherit pkgs; };
 
         }
 
         }
 
       );
 
       );
Line 368: Line 349:
 
{{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.}}
 
{{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 ===
+
=== Automatically switch nix shells with nix-direnv ===
 
 
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>.
 
 
 
Note: You may not need to create <code>use_flake()</code> yourself; as of [https://github.com/direnv/direnv/releases/tag/v2.29.0#:~:text=add%20use_flake%20function direnv 2.29,] <code>use flake</code> is part of direnv's standard library.
 
 
 
With this in place, you can now replace the use nix invocation in the <code>.envrc</code> file with <code>use flake</code>:
 
 
 
<syntaxHighlight lang=text>
 
# .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 if 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.
+
You can easily switch nix shells when you cd into different projects with nix-direnv. [https://github.com/nix-community/nix-direnv View their guide here]
 
 
==== Setting the bash prompt like nix-shell ====
 
 
 
A [https://github.com/NixOS/nix/pull/4189 new experimental feature of flakes] allow to setup a bash-prompt per flake:
 
<syntaxHighlight lang=nix>
 
{
 
  description = "...";
 
  nixConfig.bash-prompt = "\[nix-develop\]$ ";
 
  ...
 
}
 
</syntaxHighlight>
 
 
 
Otherwise it's also possible to set the <code>nix develop</code> bash prompt system wide using the [https://nixos.org/manual/nix/unstable/command-ref/conf-file.html nix.conf option bash-prompt]. (On nixos I think it is set in <code>nix.extraOptions</code>)
 
  
 
== Pushing Flakes to Cachix ==
 
== Pushing Flakes to Cachix ==
  
 
https://docs.cachix.org/pushing#flakes
 
https://docs.cachix.org/pushing#flakes
 +
 +
To push ''all'' flake outputs automatically, use [https://github.com/srid/devour-flake#usage devour-flake].
  
 
== Build specific attributes in a flake repository ==
 
== Build specific attributes in a flake repository ==
Line 439: Line 381:
 
== Importing packages from multiple channels ==
 
== Importing packages from multiple channels ==
  
You can import packages from different channels by creating an overlay on the ''pkgs'' attribute :
+
A NixOS config flake skeleton could be as follows:
<syntaxHighlight lang=nix>
 
let
 
  overlay-unstable = final: prev: {
 
    unstable = nixpkgs-unstable.legacyPackages.${prev.system}; # considering nixpkgs-unstable is an input registered before.
 
  };
 
in nixpkgs.overlays = [ overlay-unstable ]; # we assign the overlay created before to the overlays of nixpkgs.
 
</syntaxHighlight>
 
should make a package accessible through <code>pkgs.unstable.package</code>
 
For example, a NixOS config flake skeleton could be as follows:
 
 
<syntaxHighlight lang=nix>
 
<syntaxHighlight lang=nix>
 
{
 
{
Line 454: Line 387:
  
 
   inputs = {
 
   inputs = {
     nixpkgs.url = "nixpkgs/nixos-21.11";  
+
     nixpkgs.url = "nixpkgs/nixos-21.11";
     nixpkgs-unstable.url = "nixpkgs/nixos-unstable";  
+
     nixpkgs-unstable.url = "nixpkgs/nixos-unstable";
 
   };
 
   };
  
Line 481: Line 414:
 
     };
 
     };
 
}
 
}
 +
</syntaxHighlight>
  
 +
<syntaxHighlight lang=nix>
 
# NixOS configuration.nix, can now use "pkgs.package" or "pkgs.unstable.package"
 
# NixOS configuration.nix, can now use "pkgs.package" or "pkgs.unstable.package"
 
{ config, pkgs, ... }: {
 
{ config, pkgs, ... }: {
 
   environment.systemPackages = [pkgs.firefox pkgs.unstable.chromium];
 
   environment.systemPackages = [pkgs.firefox pkgs.unstable.chromium];
 
   # ...
 
   # ...
}  
+
}
 
</syntaxHighlight>
 
</syntaxHighlight>
 
Same can be done with the NURs, as it already has an ''overlay'' attribute in the flake.nix of the project, you can just add <syntaxHighlight lang=nix>nixpkgs.overlays = [ nur.overlay ];</syntaxHighlight>
 
Same can be done with the NURs, as it already has an ''overlay'' attribute in the flake.nix of the project, you can just add <syntaxHighlight lang=nix>nixpkgs.overlays = [ nur.overlay ];</syntaxHighlight>
Line 501: Line 436:
  
 
<syntaxHighlight lang=text>
 
<syntaxHighlight lang=text>
# nix repl  
+
# nix repl
 
>> :lf /etc/nixos
 
>> :lf /etc/nixos
 
>> nixosConfigurations.myhost.config
 
>> nixosConfigurations.myhost.config
Line 509: Line 444:
 
Or out of your current flake:
 
Or out of your current flake:
 
<syntaxHighlight lang=text>
 
<syntaxHighlight lang=text>
# nix repl  
+
# nix repl
 
>> :lf .#
 
>> :lf .#
 
</syntaxHighlight>
 
</syntaxHighlight>
  
 +
You can then access to the inputs, outputs… For instance if you would like to check the default version of the kernel present in nixpgs:
 +
<syntaxHighlight lang=text>
 +
nix-repl> inputs.nixpkgs.legacyPackages.x86_64-linux.linuxPackages.kernel.version
 +
"5.15.74"
 +
</syntaxHighlight>
  
 
However, this won't be instant upon evaluation if any file changes have been done since your last configuration rebuild. Instead, if one puts:
 
However, this won't be instant upon evaluation if any file changes have been done since your last configuration rebuild. Instead, if one puts:
Line 542: Line 482:
  
 
This will launch a repl with access to <code>nixpkgs</code>, <code>lib</code>, and the <code>flake</code> options in a split of a second.
 
This will launch a repl with access to <code>nixpkgs</code>, <code>lib</code>, and the <code>flake</code> options in a split of a second.
 +
 +
An alternative approach to the above shell alias is omitting <code>repl</code> from <code>nix.nixPath</code> and creating a shell script:
 +
<syntaxHighlight lang=nix>
 +
nix.nixPath = [ "nixpkgs=${inputs.nixpkgs}" ];
 +
environment.systemPackages = let
 +
  repl_path = toString ./.;
 +
  my-nix-fast-repl = pkgs.writeShellScriptBin "my-nix-fast-repl" ''
 +
    source /etc/set-environment
 +
    nix repl "${repl_path}/repl.nix" "$@"
 +
  '';
 +
in [
 +
  my-nix-fast-repl
 +
];
 +
</syntaxHighlight>
  
 
== Enable unfree software ==
 
== Enable unfree software ==
  
Because flake evalutations are hermetic, they will ignore the system configuration on nonfree software and the <code>NIXPKGS_ALLOW_UNFREE</code> environment variable by default.
+
Refer to [[Unfree Software]].
 +
 
 +
== Development tricks ==
 +
=== How to add a file locally in git but not include it in commits ===
  
To use nonfree software with CLI tools like <code>nix shell</code> or <code>nix run</code>, the <code>--impure</code> flag must be used for Nixpkgs to access the current environment 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>):
<syntaxHighlight lang=console>
 
$ NIXPKGS_ALLOW_UNFREE=1 nix run --impure nixpkgs#discord
 
</syntaxHighlight>
 
  
To use nonfree software in a flake, add <code>nixpkgs</code> as an input in your flake and import it with the <code>allowUnfree</code> option:
+
<syntaxHighlight>
<syntaxHighlight lang=nix>
+
git add --intent-to-add extra/flake.nix
pkgs = import nixpkgs { config = { allowUnfree = true; }; };
+
git update-index --skip-worktree --assume-unchanged extra/flake.nix
 
</syntaxHighlight>
 
</syntaxHighlight>
  
=== Enable unfree software in home-manager ===
+
=== Rapid iteration of a direct dependency ===
 +
One common pain point with using Nix as a development environment is the need to completely rebuild dependencies and re-enter the dev shell every time they are updated. The <code>nix develop --redirect <flake> <directory></code> command allows you to provide a mutable dependency to your shell as if it were built by Nix.
  
If you want to install software using home-manager via nix flakes in non NixOS systems (like darwin) you can use the home-manager <code>nixpkgs.config</code> option for example
+
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=nix>
+
<syntaxHighlight lang=bash>
nixpkgs.config.allowUnfree = true;
+
cd ~/libdep-src-checkout/
 +
nix develop # Or `nix-shell` if applicable.
 +
export prefix="./install" # configure nix to install it here
 +
buildPhase  # build it like nix does
 +
installPhase # install it like nix does
 +
</syntaxHighlight>
 +
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/
 +
nix develop --redirect libdep ~/libdep-src-checkout/install
 +
echo $buildInputs | tr " " "\n" | grep libdep
 +
# Output should show ~/libdep-src-checkout/ so you know it worked
 
</syntaxHighlight>
 
</syntaxHighlight>
 +
If Nix warns you that your redirected flake isn't actually used as an input to the evaluated flake, try using the <code>--inputs-from .</code> flag. If all worked well you should be able to <code>buildPhase && installPhase</code> when the dependency changes and rebuild your consumer with the new version ''without'' exiting the development shell.
  
== Official Nix links ==
+
== See also ==
  
These are links out to information from official Nix sources on Flakes.
+
* [https://www.tweag.io/blog/2020-05-25-flakes/ Nix Flakes, Part 1: An introduction and tutorial] (Eelco Dolstra, 2020)
 +
* [https://www.tweag.io/blog/2020-06-25-eval-cache/ Nix Flakes, Part 2: Evaluation caching] (Eelco Dolstra, 2020)
 +
* [https://www.tweag.io/blog/2020-07-31-nixos-flakes/ Nix Flakes, Part 3: Managing NixOS systems] (Eelco Dolstra, 2020)
 +
* [https://github.com/ryan4yin/nixos-and-flakes-book NixOS & Flakes Book](Ryan4yin, 2023) - 🛠️ ❤️ An unofficial NixOS & Flakes book for beginners.
 +
* [https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html Nix flake command reference manual] - Many additional details about flakes, and their parts.
 +
* [https://xeiaso.net/blog/nix-flakes-1-2022-02-21 Nix Flakes: an Introduction] (Xe Iaso, 2022)
 +
* [https://serokell.io/blog/practical-nix-flakes Practical Nix Flakes] (Alexander Bantyev, 2021) - Intro article on working with Nix and Flakes
 +
* [https://www.youtube.com/watch?v=QXUlhnhuRX4&list=PLgknCdxP89RcGPTjngfNR9WmBgvD_xW0l Nix flakes 101: Introduction to nix flakes] (Jörg Thalheim, 2020)
 +
* [https://github.com/NixOS/rfcs/pull/49 RFC 49] (2019) - Original flakes specification
 +
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]
 +
* [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://github.com/nix-community/todomvc-nix building Rust and Haskell flakes]
  
* [https://github.com/NixOS/rfcs/pull/49 Eelco Dolstra's RFC #49] - This is the initial RFC for Flakes to be included in NixOS, from July 2019
 
* [https://github.com/NixOS/nix/blob/master/src/nix/flake.md spec describing flake inputs in more detail]
 
  
 
[[Category:Software]]
 
[[Category:Software]]
 
[[Category:Nix]]
 
[[Category:Nix]]
 
[[Category:Flakes]]
 
[[Category:Flakes]]

Latest revision as of 16:39, 17 March 2024

Nix flakes is an experimental feature of the Nix package manager. Flakes was introduced with Nix 2.4 (see release notes).

Introduction

Nix flakes provide a standard way to write Nix expressions (and therefore packages) whose dependencies are version-pinned in a lock file, improving reproducibility of Nix installations. The experimental nix CLI lets you evaluate or build an expression contained within a flake, install a derivation from a flake into an User Environment, and operate on flake outputs much like the original nix-{build,eval,...} commands would.

  • A flake refers to a file-system tree whose root directory contains the Nix file specification called flake.nix.
  • An installation may contain any number of flakes, independent of each other or even call each other.
  • The contents of flake.nix file follow the uniform naming schema for expressing packages and dependencies on Nix.
  • Flakes use the standard Nix protocols, including the URL-like syntax for specifying repositories and package names.
  • To simplify the long URL syntax with shorter names, flakes uses a registry of symbolic identifiers.
  • Flakes also allow for locking references and versions that can then be easily queried and updated programmatically.
  • Nix command-line interface accepts flake references for expressions that build, run, and deploy packages.

Enable flakes temporarily

When using any nix command, add the following command-line options:

 --experimental-features 'nix-command flakes'

Enable flakes permanently in NixOS

Add the following to the system configuration (flakes):

  nix.settings.experimental-features = [ "nix-command" "flakes" ];
Other Distros, with Home-Manager

Add the following to your home-manager config:

  nix = {
    package = pkgs.nix;
    settings.experimental-features = [ "nix-command" "flakes" ];
  };
Other Distros, without Home-Manager
Note: The Nix Determinate Installer enables flakes by default.

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

experimental-features = nix-command flakes

Basic Usage of Flake

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

Encryption WARNING

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 secret managing scheme.

Git WARNING

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

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

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

Generate flake.nix file

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

nix flake init

Flake schema

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

It has 4 top-level attributes:

  • description is a string describing the flake.
  • inputs is an attribute set of all the dependencies of the flake. The schema is described below.
  • outputs is a function of one argument that takes an attribute set of all the realized inputs, and outputs another attribute set whose schema is described below.
  • nixConfig is an attribute set of values which reflect the 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.

Input schema

The nix flake inputs manual. The nix flake references manual.

Output schema

Once the inputs are resolved, they're passed to the function `outputs` along with with `self`, which is the directory of this flake in the store. `outputs` returns the outputs of the flake, according to the following schema.

This is described in the nix package manager src/nix/flake.cc in CmdFlakeCheck.

Where:

  • <system> is something like "x86_64-linux", "aarch64-linux", "i686-linux", "x86_64-darwin"
  • <name> is an attribute name like "hello".
  • <flake> is a flake name like "nixpkgs".
  • <store-path> is a /nix/store.. path
{ self, ... }@inputs:
{
  # Executed by `nix flake check`
  checks."<system>"."<name>" = derivation;
  # Executed by `nix build .#<name>`
  packages."<system>"."<name>" = derivation;
  # Executed by `nix build .`
  packages."<system>".default = derivation;
  # Executed by `nix run .#<name>`
  apps."<system>"."<name>" = {
    type = "app";
    program = "<store-path>";
  };
  # Executed by `nix run . -- <args?>`
  apps."<system>".default = { type = "app"; program = "..."; };

  # Formatter (alejandra, nixfmt or nixpkgs-fmt)
  formatter."<system>" = derivation;
  # Used for nixpkgs packages, also accessible via `nix build .#<name>`
  legacyPackages."<system>"."<name>" = derivation;
  # Overlay, consumed by other flakes
  overlays."<name>" = final: prev: { };
  # Default overlay
  overlays.default = final: prev: { };
  # Nixos module, consumed by other flakes
  nixosModules."<name>" = { config, ... }: { options = {}; config = {}; };
  # Default module
  nixosModules.default = { config, ... }: { options = {}; config = {}; };
  # Used with `nixos-rebuild switch --flake .#<hostname>`
  # nixosConfigurations."<hostname>".config.system.build.toplevel must be a derivation
  nixosConfigurations."<hostname>" = {};
  # Used by `nix develop .#<name>`
  devShells."<system>"."<name>" = derivation;
  # Used by `nix develop`
  devShells."<system>".default = derivation;
  # Hydra build jobs
  hydraJobs."<attr>"."<system>" = derivation;
  # Used by `nix flake init -t <flake>#<name>`
  templates."<name>" = {
    path = "<store-path>";
    description = "template description goes here?";
  };
  # Used by `nix flake init -t <flake>`
  templates.default = { path = "<store-path>"; description = ""; };
}

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

nix run

When output apps.<system>.myapp is not defined, nix run myapp runs <packages or legacyPackages.<system>.myapp>/bin/<myapp.meta.mainProgram or myapp.pname or myapp.name (the non-version part)>

Using flakes with stable Nix

There exists the flake-compat library that you can use to shim default.nix and shell.nix files. It will download the inputs of the flake, pass them to the flake’s outputs function and return an attribute set containing defaultNix and shellNix attributes. The attributes will contain the output attribute set with an extra default attribute pointing to current platform’s defaultPackage (resp. devShell for shellNix).

Place the following into default.nix (for shell.nix, replace defaultNix with shellNix) to use the shim:

(import (
  fetchTarball {
    url = "https://github.com/edolstra/flake-compat/archive/12c64ca55c1014cdc1b16ed5a804aa8576601ff2.tar.gz";
    sha256 = "0jm6nzb83wa6ai17ly9fzpqc40wg1viib8klq8lby54agpl213w5"; }
) {
  src =  ./.;
}).defaultNix

You can also use the lockfile to make updating the hashes easier using nix flake lock --update-input flake-compat. Add the following to your flake.nix:

  inputs.flake-compat = {
    url = "github:edolstra/flake-compat";
    flake = false;
  };

and add flake-compat to the arguments of outputs attribute. Then you will be able to use default.nix like the following:

(import (
  let
    lock = builtins.fromJSON (builtins.readFile ./flake.lock);
  in fetchTarball {
    url = "https://github.com/edolstra/flake-compat/archive/${lock.nodes.flake-compat.locked.rev}.tar.gz";
    sha256 = lock.nodes.flake-compat.locked.narHash; }
) {
  src =  ./.;
}).defaultNix

Accessing flakes from Nix expressions

If you want to access a flake from within a regular Nix expression on a system that has flakes enabled, you can use something like (builtins.getFlake "path:/path/to/directory").packages.x86_64-linux.default, where 'directory' is the directory that contains your flake.nix.

Making your evaluations pure

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

  • fetchurl and fetchtar 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.
  • Imports from channels like <nixpkgs> can be made pure by instead importing from the output function in flake.nix, where the arguments provide the store path to the flake's inputs:
 outputs = { self, nixpkgs, ... }:
  {
    nixosConfigurations.machine = nixpkgs.lib.nixosSystem {
      # Note that you cannot put arbitrary configuration here: the configuration must be placed in the files loaded via modules
      system = "x86_64-linux";
      modules = [
        (nixpkgs + "/nixos/modules/<some-module>.nix")
        ./machine.nix
      ];
    };
  };

The nix flakes command

The nix flake subcommand is described in command reference page of the unstable manual.

Install packages with `nix profile`

nix profile install in the manual

Using nix flakes with NixOS

nixos-rebuild switch will read its configuration from /etc/nixos/flake.nix if it is present.

A basic nixos flake.nix could look like this:

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

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

{
  inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-unstable;
  inputs.home-manager.url = github:nix-community/home-manager;

  outputs = { self, nixpkgs, ... }@attrs: {
    nixosConfigurations.fnord = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      specialArgs = attrs;
      modules = [ ./configuration.nix ];
    };
  };
}

Then, you can access the flake inputs from the file configuration.nix like this:

{ config, lib, nixpkgs, home-manager, ... }: {
  # do something with home-manager here, for instance:
  imports = [ home-manager.nixosModules.default ];
  ...
}

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

$ sudo nixos-rebuild switch --flake '.#'

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

$ sudo nixos-rebuild switch --flake '/etc/nixos#joes-desktop'

To switch a remote configuration, use:

$ nixos-rebuild --flake .#mymachine \
  --target-host mymachine-hostname --build-host mymachine-hostname --fast \
  switch
Warning: Remote building seems to have an issue that's resolved by setting the --fast flag.

Pinning the registry to the system pkgs on NixOS

  nix.registry = {
    nixpkgs.to = {
      type = "path";
      path = pkgs.path;
    };
  };

Super fast nix-shell

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

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

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

  shellHook = ''
    # ...
  '';
}

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

Now create a flake.nix file in the same repository:

{
  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
        {
          devShells.default = import ./shell.nix { inherit pkgs; };
        }
      );
}

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

And finally, run nix develop. 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.

Automatically switch nix shells with nix-direnv

You can easily switch nix shells when you cd into different projects with nix-direnv. View their guide here

Pushing Flakes to Cachix

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

To push all flake outputs automatically, use devour-flake.

Build specific attributes in a flake repository

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

Eg, in nixpkgs:

$ nix build .#hello

Building flakes from a Git repo url with submodules

As per nix 2.9.1, git submodules in package srcs 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

Importing packages from multiple channels

A NixOS config flake skeleton could be as follows:

{
  description = "NixOS configuration with two or more channels";

  inputs = {
    nixpkgs.url = "nixpkgs/nixos-21.11";
    nixpkgs-unstable.url = "nixpkgs/nixos-unstable";
  };

  outputs = { self, nixpkgs, nixpkgs-unstable }:
    let
      system = "x86_64-linux";
      overlay-unstable = final: prev: {
        unstable = nixpkgs-unstable.legacyPackages.${prev.system};
        # use this variant if unfree packages are needed:
        # unstable = import nixpkgs-unstable {
        #   inherit system;
        #   config.allowUnfree = true;
        # };

      };
    in {
      nixosConfigurations."<hostname>" = nixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          # Overlays-module makes "pkgs.unstable" available in configuration.nix
          ({ config, pkgs, ... }: { nixpkgs.overlays = [ overlay-unstable ]; })
          ./configuration.nix
        ];
      };
    };
}
# NixOS configuration.nix, can now use "pkgs.package" or "pkgs.unstable.package"
{ config, pkgs, ... }: {
  environment.systemPackages = [pkgs.firefox pkgs.unstable.chromium];
  # ...
}

Same can be done with the NURs, as it already has an overlay attribute in the flake.nix of the project, you can just add

nixpkgs.overlays = [ nur.overlay ];

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

pkgs = import nixpkgs { overlays = [ /*the overlay in question*/ ]; };

Getting Instant System Flakes Repl

How to get a nix repl out of your system flake:

# nix repl
>> :lf /etc/nixos
>> nixosConfigurations.myhost.config
{ ... }

Or out of your current flake:

# nix repl
>> :lf .#

You can then access to the inputs, outputs… For instance if you would like to check the default version of the kernel present in nixpgs:

nix-repl> inputs.nixpkgs.legacyPackages.x86_64-linux.linuxPackages.kernel.version
"5.15.74"

However, this won't be instant upon evaluation if any file changes have been done since your last configuration rebuild. Instead, if one puts:

nix.nixPath = let path = toString ./.; in [ "repl=${path}/repl.nix" "nixpkgs=${inputs.nixpkgs}" ];

In their system flake.nix configuration file, and includes the following file in their root directory flake as repl.nix:

let
  flake = builtins.getFlake (toString ./.);
  nixpkgs = import <nixpkgs> { };
in
{ inherit flake; }
// flake
// builtins
// nixpkgs
// nixpkgs.lib
// flake.nixosConfigurations

(Don't forget to git add repl.nix && nixos-rebuild switch --flake "/etc/nixos") Then one can run (or bind a shell alias):

source /etc/set-environment && nix repl $(echo $NIX_PATH | perl -pe 's|.*(/nix/store/.*-source/repl.nix).*|\1|')

This will launch a repl with access to nixpkgs, lib, and the flake options in a split of a second.

An alternative approach to the above shell alias is omitting repl from nix.nixPath and creating a shell script:

nix.nixPath = [ "nixpkgs=${inputs.nixpkgs}" ];
environment.systemPackages = let
  repl_path = toString ./.;
  my-nix-fast-repl = pkgs.writeShellScriptBin "my-nix-fast-repl" ''
    source /etc/set-environment
    nix repl "${repl_path}/repl.nix" "$@"
  '';
in [
  my-nix-fast-repl
];

Enable unfree software

Refer to Unfree Software.

Development tricks

How to add a file locally in git but not include it in commits

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 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 extra/flake.nix):

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

Rapid iteration of a direct dependency

One common pain point with using Nix as a development environment is the need to completely rebuild dependencies and re-enter the dev shell every time they are updated. The nix develop --redirect <flake> <directory> command allows you to provide a mutable dependency to your shell as if it were built by Nix.

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

cd ~/libdep-src-checkout/
nix develop # Or `nix-shell` if applicable.
export prefix="./install" # configure nix to install it here
buildPhase   # build it like nix does
installPhase # install it like nix does

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

cd ~/consumexe-src-checkout/
nix develop --redirect libdep ~/libdep-src-checkout/install
echo $buildInputs | tr " " "\n" | grep libdep
# Output should show ~/libdep-src-checkout/ so you know it worked

If Nix warns you that your redirected flake isn't actually used as an input to the evaluated flake, try using the --inputs-from . flag. If all worked well you should be able to buildPhase && installPhase when the dependency changes and rebuild your consumer with the new version without exiting the development shell.

See also