Wombat’s Book of Nix

Strings are enclosed by double quotes ("), or two single quotes (').

They can span multiple lines.

The Boolean values in Nix are true and false.

File paths are play an important role in building software, so Nix has a special data type for them. Paths may be absolute (e.g. /bin/sh) or relative (e.g. ./data/file1.csv). Note that paths are not enclosed in quotation marks; they are not strings!

Enclosing a path in angle brackets, e.g. <nixpkgs> causes the directories listed in the environment variable NIX_PATH to be searched for the given file or directory name. These are called lookup paths.

List elements are enclosed in square brackets and separated by spaces (not commas). The elements need not be of the same type.

Lists can be empty.

List elements can be of any type, and can even be lists themselves.

Attribute sets associate keys with values. They are enclosed in curly brackets, and the associations are terminated by semi-colons. Note that the final semi-colon before the closing bracket is required.

The keys of an attribute set must be strings. When the key is not a valid identifier, it must be enclosed in quotation marks.

Attribute sets can be empty.

Values of attribute sets can be of any type, and can even be attribute sets themselves.

In Section 2.11.4, “Recursive attribute sets” you will be introduced to a special type of attribute set.

We’ll learn how to write functions later in this chapter. For now, note that functions are "first-class values", meaning that they can be treated like any other data type. For example, a function can be assigned to a variable, appear as an element in a list, or be associated with a key in an attribute set.

You can declare variables in Nix and assign values to them.

In Nix, values are immutable; once you assign a value to a variable, you cannot change it. You can, however, create a new variable with the same name, but in a different scope. Don’t worry if you don’t completely understand the previous sentence; we will see some examples in [_functions], Section 2.15, “Let expressions”, and Section 2.16, “With expressions”.

The usual arithmetic operators are provided.

Numbers without a decimal point are assumed to be integers. To ensure that a number is interpreted as a floating-point value, add a decimal point.

In the example below, the first expression results in integer division (rounding down), while the second produces a floating-point result.

String concatenation uses the + operator.

You can use the ${variable} syntax to insert the value of a variable within a string.

Nix provides some built-in functions for working with strings; a few examples are shown below. For more information on these and other built-in functions, see the Nix Manual (https://nixos.org/manual/nix/stable/language/builtins).

How long is this string?

Given a starting position and a length, extract a substring. The first character of a string has index 0.

Convert an expression to a string.

Paths can be concatenated to produce a new path.

A path can be concatenated with a string to produce a new path.

Strings can be concatenated with paths, but with a side-effect that may surprise you: if the path exists, the file is copied to the Nix store! The result is a string, not a path.

In the example below, the file file.txt is copied to /nix/store/gp8ba25gpwvbqizqfr58jr014gmv1hd8-file.txt (not, as you might expect, to /home/wombat/nix/store/gp8ba25gpwvbqizqfr58jr014gmv1hd8-file.txt).

The path must exist.

Nix provides some built-in functions for working with paths; a few examples are shown below. For more information on these and other built-in functions, see the Nix Manual (https://nixos.org/manual/nix/stable/language/builtins).

Does the path exist?

Get a list of the files in a directory, along with the type of each file.

Read the contents of a file into a string.

Lists can be concatenated using the ++ operator.

Nix provides some built-in functions for working with lists; a few examples are shown below. For more information on these and other built-in functions, see the Nix Manual (https://nixos.org/manual/nix/stable/language/builtins).

Testing if an element appears in a list.

Selecting an item from a list by index. The first element in a list has index 0.

Determining the number of elements in a list.

Accessing the first element of a list.

Dropping the first element of a list.

Functions are useful for working with lists. Functions will be introduced in Section 2.12, “Functions”, but the following examples should be somewhat self-explanatory.

Using a function to filter (select elements from) a list.

Applying a function to all the elements in a list.

The . operator selects an attribute from a set.

We can use the ? operator to find out if a set has a particular attribute.

We can use the // operator to modify an attribute set. Recall that Nix values are immutable, so the result is a new value (the original is not modified). Attributes in the right-hand set take preference.

An ordinary attribute set cannot refer to its own elements. To do this, you need a recursive attribute set.

Nix provides some built-in functions for working with attribute sets; a few examples are shown below. For more information on these and other built-in functions, see the Nix Manual (https://nixos.org/manual/nix/stable/language/builtins).

Get an alphabetical list of the keys.

Get the values associated with each key, in alphabetical order by the key names.

What value is associated with a key?

Does the set have a value for a key?

Remove one or more keys and associated values from a set.

Functions are defined using the syntax parameter: expression, where the expression typically involves the parameter. Consider the following example.

We created a function that adds 1 to its input. However, it doesn’t have a name, so we can’t use it directly. Anonymous functions do have their uses, as we shall see shortly.

Note that the message printed by the Nix REPL when we created the function uses the term lambda. This derives from a branch of mathematics called lambda calculus. Lambda calculus was the inspiration for most functional languages such as Nix. Functional programmers often call anonymous functions "lambdas".

The Nix REPL confirms that the expression x: x + 1 defines a function.

How can we use a function? Recall from Section 2.2.8, “Functions” that functions can be treated like any other data type. In particular, we can assign it to a variable.

Procedural languages such as C or Java often use parenthesis to apply a function to a value, e.g. f(5). Nix, like lambda calculus and most functional languages, does not require parenthesis for function application. This reduces visual clutter when chaining a series of functions.

Now that our function has a name, we can use it.

Functions in Nix always have a single parameter. To define a calculation that requires more than one parameter, we create functions that return functions!

We have created a function called add. When applied to a parameter a, it returns a new function that adds a to its input. Note that the expression (b: a+b) is an anonymous function. We never call it directly, so it doesn’t need a name. Anonymous functions are useful after all!

I used parentheses to emphasise the inner function, but they aren’t necessary. More commonly we would write the following.

If we only supply one parameter to add, the result is a new function rather than a simple value. Invoking a function without supplying all of the expected parameters is called partial application.

Now let’s apply add 3 to the value 5.

In fact, the parentheses aren’t needed.

If you’ve never used a functional programming language, this all probably seems very strange. Imagine that you want to add two numbers, but you have a very unusual calculator labeled "add". This calculator never displays a result, it only produces more calculators! If you enter the value 3 into the "add" calculator, it gives you a second calculator labeled "add 3". You then enter 5 into the "add 3" calculator, which displays the result of the addition, 8.

With that image in mind, let’s walk through the steps again in the REPL, but this time in more detail. The function add takes a single parameter a, and returns a new function that takes a single parameter b, and returns the value a + b. Let’s apply add to the value 3, and give the resulting new function a name, g.

The function g takes a single parameter and adds 3 to it. The Nix REPL confirms that g is indeed a function.

Now we can apply g to a number to get a new number.

I said earlier that a function in Nix always has a single parameter. However, that parameter need not be a simple value; it could be a list or an attribute set. This approach is widely used in Nix, and the language has some special features to support it. This is an important topic, so we will cover it separately in Section 2.13, “Argument sets”.

To specify an attribute set as a function parameter, we use a set pattern, which has the form

Note that while the key-value associations in attribute sets are separated by semi-colons, the key names in the attribute set _pattern are separated by commas. Here’s an example of a function that has an attribute set as an input parameter.

We can make some values in an argument set optional by providing default values, using the syntax name ? value. This is illustrated below.

A function can allow the caller to supply argument sets that contain "extra" values. This is done with the special parameter …​.

One reason for doing this is to allow the caller to pass the same argument set to multiple functions, even though each function may not need all of the values.

Another reason for allowing variadic arguments is when a function calls another function, supplying the same argument set. An example is shown in Section 2.13.4, “@-patterns”.

It can be convenient for a function to be able to reference the argument set as a whole. This is done using an @-pattern.

Alternatively, the @-pattern can appear after the argument set, as in the example below.

An @-pattern is the only way a function can access variadic attributes, so they are often used together. In the example below, the function greet passes its argument set, including the variadic arguments, to the function confirmAddress.

Next, we’ll create a simple Haskell program.

Before we package the program, let’s verify that it runs. We’re going to need a Haskell compiler. By now you’ve probably figured out that we can write a flake.nix and define a development shell that includes Haskell. We’ll do that shortly, but first I want to show you a handy shortcut. We can launch a temporary shell with any Nix packages we want. This is convenient when you just want to try out some new software and you’re not sure if you’ll use it again. It’s also convenient when you’re not ready to write flake.nix (perhaps you’re not sure what tools and packages you need), and you want to experiment a bit first.

The command to enter a temporary shell is

nix-shell -p packages

If there are multiple packages, they should be separated by spaces.

It’s time to write a Cabal file for this program. This is just an ordinary Cabal file; we don’t need to do anything special for Nix.

At this point, I would normally write flake.nix and use Nix to build the program. I’ll cover that in the next section. However, it’s useful to know how to build the package manually in a Nix environment, without using a Nix flake. When you’re new to Nix, this can help you differentiate between problems in your flake definition and problems in your Cabal file.

Aha! We need cabal-install in our shell. Rather than launch another shell-within-a-shell, let’s exit create a new one.

After a lot of output messages, the build succeeds and the program runs.

Now we should write flake.nix. We already know how to write most of the flake from the examples we did earlier. The two parts that would be different are the development shell and the package builder.

However, there’s a simpler way, using haskell-flake.

The above definition will work for most of your haskell projects; simply change the description and the package name in packages.default. Let’s try out the new flake.

Why can’t it find flake.nix? Nix flakes only “see” files that are part of the repository. We need to add all of the important files to the repo before building or running the flake.

We’d like to share this package with others, but first we should do some cleanup. When the package was built (automatically by the nix run command), it created a flake.lock file. We need to add this to the repo, and commit all important files.

You can test that your package is properly configured by going to another directory and running it from there.

If you move the project to a public repo, anyone can run it. Recall from the beginning of the tutorial that you were able to run hello-flake directly from my repo with the following command.

Modify the URL accordingly and invite someone else to run your new Haskell flake.

Next, we’ll create a simple Python program.

Before we package the program, let’s verify that it runs. We’re going to need Python. By now you’ve probably figured out that we can write a flake.nix and define a development shell that includes Python. We’ll do that shortly, but first I want to show you a handy shortcut. We can launch a temporary shell with any Nix packages we want. This is convenient when you just want to try out some new software and you’re not sure if you’ll use it again. It’s also convenient when you’re not ready to write flake.nix (perhaps you’re not sure what tools and packages you need), and you want to experiment a bit first.

The command to enter a temporary shell is

nix-shell -p packages

If there are multiple packages, they should be separated by spaces.

Let’s enter a shell with Python so we can test the program.

Next, create a Python script to build the package. We’ll use Python’s setuptools, but you can use other build tools. For more information on setuptools, see the Python Packaging User Guide, especially the section on setup args.

We won’t write flake.nix just yet. First we’ll try building the package manually.

The missing module error happens because we don’t have build available in the temporary shell. We can fix that by adding “build” to the temporary shell. When you need support for both a language and some of its packages, it’s best to use one of the Nix functions that are specific to the programming language and build system. For Python, we can use the withPackages function.

Note that we’re now inside a temporary shell inside the previous temporary shell! To get back to the original shell, we have to exit twice. Alternatively, we could have done exit followed by the nix-shell command.

After a lot of output messages, the build succeeds.

Now we should write flake.nix. We already know how to write most of the flake from the examples we did earlier. The two parts that will be different are the development shell and the package builder.

Let’s start with the development shell. It seems logical to write something like the following.

Note that we need the parentheses to prevent python.withPackages and the argument from being processed as two separate tokens. Suppose we wanted to work with virtualenv and pip instead of build. We could write something like the following.

For the package builder, we can use the buildPythonApplication function.

If you put all the pieces together, your flake.nix should look something like this.

Let’s try out the new flake.

Why can’t it find flake.nix? Nix flakes only “see” files that are part of the repository. We need to add all of the important files to the repo before building or running the flake.

We’d like to share this package with others, but first we should do some cleanup. When the package was built (automatically by the nix run command), it created a flake.lock file. We need to add this to the repo, and commit all important files.

You can test that your package is properly configured by going to another directory and running it from there.

If you move the project to a public repo, anyone can run it. Recall from the beginning of the tutorial that you were able to run hello-flake directly from my repo with the following command.

Modify the URL accordingly and invite someone else to run your new Python flake.

Here’s a demonstration using the shell.

Here’s a demonstration using the shell.

Here’s a demonstration using the shell.

Here’s a short Haskell program that uses it.

Here’s a demonstration using the program.