Nix Language: Tips & Tricks

Finding the definition of a function or package

Nix is often criticized that it has no working “jump to definition”. The good news is that you can have something very similar by using a regular expression:

If your package is named hello, searching for the regular expression hello\ = lists all nix symbol definitions that are named this way. In many cases there’s only two or three results. You should find what you are searching for easily.

This trick even works for functions, because their arguments come *after* the equals sign. If you search for mkDerivation\ = for example, you will see that there is more than one definition of that symbol in nixpkgs, but at least all definitions are shown.

You will also notice that searching with grep takes quite a while on a large repository like nixpkgs. Tools like ag (The Silver Searcher) and rg (ripgrep) are orders of magnitudes faster (especially on modern SSDs).

If you don’t have a nixpkgs checkout at hand, you can use the repo search at search.nix.gsc.io. This even searches in all repositories of the NixOS Github organization.

Another trick that only works for functions, is evaluating the function on the nix repl:

nix-repl> pkgs.lib.strings.makeBinPath
«lambda @ /home/user/nixpkgs/lib/strings.nix:94:42»

This doesn't work for non-functions or builtin functions, which show «primop». It will always find the actual lambda, not an attribute that reexports a partial application, for example.

Convert a string to an (import-able) path

nix-repl> "/home/bernd/folder"
"/home/bernd/folder"

nix-repl> :t "/home/bernd/folder"
a string

nix-repl> builtins.toPath "/home/bernd/folder"
"/home/bernd/folder"

nix-repl> :t builtins.toPath "/home/bernd/folder"
a string

nix-repl> /. + builtins.toPath "/home/bernd/folder"
/home/bernd/folder

nix-repl> :t /. + builtins.toPath "/home/bernd/folder"
a path

In contrast to what builtins.toPath suggests, it does not result in a path, but only checks whether the string is an absolute path, and normalizes it. The trick is to prepend the /. (“root”) path literal, which converts the result to a nix path (that will be copied to the store when used in a derivation).

Be careful not to confuse it with ./., which is the “directory of the current nix file” path literal, and will result in something like /my/scripts/folder/home/bernd/folder (provided you are in /my/scripts/folder).

This trick might be helpful in combination with builtins.getEnv, which returns a string (which might be a path). Be careful, depending on environment variables introduces heavy non-determinism and might lead to rebuilds!

If you need to build a path from a mix of paths and strings variables, you can concatenate strings and paths, but you need to be careful of the evaluation order because Nix removes trailing /.

For example if you need to concatenate /data with a variable call my_var you need to add parenthesis:

nix-repl> let my_var = "tmp"; in /data + "/" + my_var  # WRONG
/datatmp

nix-repl> let my_var = "tmp"; in /data + ("/" + my_var) # Better :)
/data/tmp

Coercing a relative path with interpolated variables to an absolute path (for imports)

Sometimes you need to interpolate the value of a Nix variable into the path for an import, however these will not work:

• ./desktop-${desktop}.nix (invalid curly, can't interpolate outside of a string in this location)
• "./desktop-${desktop}.nix" (nix paths must be absolute)
• ./. + "desktop-${desktop}.nix" (missing slash at the start of the string part)
• ./. + "./desktop-${desktop}.nix" (can't have the dot in front of that same slash)

Instead, use this construction:

• ./. + "/desktop-${desktop}.nix"

As a fuller example:

let
  desktops = [ "elementary" "gnome" "plasma" "sway" ];
in
{
  config.specialisation = 
    pkgs.lib.genAttrs desktops (desktop: {
      configuration = {
        boot.loader.grub.configurationName = "${desktop}";
        imports = [
          (./. + "/desktop-${desktop}.nix")
        ];
      };
    });
}

Note that this requires ./. to refer to the current directory, but also importantly requires the leading slash on the quoted-string-path part.

Writing update scripts / Referencing a relative path as string

Nix has relative path syntax that describes files relative to the current nix file, for example

with import <nixpkgs> {};
let textdata = ../foo.txt;
in runCommand "alldata" {} ''
  echo "=this is a header=" >> $out
  cat ${textdata} >> $out
''

If the file ../foo.txt are needed by evaluation, it is copied to the nix store first, so the script in the resulting drv file looks like this:

"echo \"=this is a header=\" >> $out\ncat /nix/store/dcaph3ib0vq0c27bqzw2vhrakk272mga-foo.txt >> $out\n"

Notice the /nix/store path of foo.txt. When we build the file:

$ nix-build code.nix
these derivations will be built:
  /nix/store/bfv13hxqlwll398y5vi3wn44raw48yva-alldata.drv
building '/nix/store/bfv13hxqlwll398y5vi3wn44raw48yva-alldata.drv'...
/nix/store/9fav4aw2fs8ybaj06gg6cjzz7bkqf461-alldata

$ cat /nix/store/9fav4aw2fs8ybaj06gg6cjzz7bkqf461-alldata
=this is a header=
this
is
some
data

Now, what if we don’t want to import the data file into the store, but still reference the absolute path of that file? We use toString:

with import <nixpkgs> {};
let textdata = toString ../foo.txt;
in writeScript "update-foo.sh" ''
  echo "updating foo.txt!"
  cat "additional new data" >> ${lib.escapeShellArg textdata}
''

In this example we use the actual absolute path of the file to write a script (notice the change from runCommand to writeScript, which are both helper functions from nixpkgs). This script can update the foo.txt file when it is run by bash:

$ cat $(nix-build code.nix)
echo "updating foo.txt!"
echo "additional new data" >> '/home/philip/tmp/foo.txt'

$ bash $(nix-build code.nix)
updating foo.txt!

$ cat foo.txt
this
is
some
data
additional new data

Bear in mind that this makes the absolute path vary between different systems. The users Bob and Alice are going to get different scripts, because the paths of their home folders differ: /home/bob/foo.txt and /home/alice/foo.txt; so it’s not reproducible.

We can use this trick to update the sources of nix expressions (for example by generating a script which updates a json file with the software’s hashes).

Relevant pages

• Overview of the Nix Expression Language
• Editor Modes for Nix Files
• Learning resources