What is the purpose of nix-instantiate? What is a store-derivation?

Question

In the manual it is written :

The command nix-instantiate generates store derivations from (high-level) Nix expressions.

But what are store derivations ?

The manual says the following about store derivations :

A description of a build action. The result of a derivation is a store object. Derivations are typically specified in Nix expressions using the derivation primitive. These are translated into low-level store derivations (implicitly by nix-env and nix-build, or explicitly by nix-instantiate)

This is a little bit difficult to understand for a nix-newbee and I found nothing more enlightening about nix-instantiate and store derivations by googling. I also asked on #nixos, I got no answer, yet.

Could someone please explain on a simple example what a store derivation is, what is it used for ?

Why one would generate store derivations using nix-instantiate ? Could you give a super simple, easy to understand example ?

Answer 1

What is nix-instantiate good for ?

The command nix-instantiate sole purpose is to evaluate Nix expressions. The primary purpose of the Nix languages is to generate derivations.

What is a store-derivation?

A derivation (see example) is a computer-friendly representation of the build recipes used for building (realize) packages. They are files with the extension .drv which are listed in the store directory, usually /nix/store.

These build recipes are understood by the Nix daemon, and are used to ensure that all the dependencies are built before, and stored in the pre-computed paths. Once all dependencies are successfully compiled, then the Nix daemon can look for substitute, or realize the derivation locally. All the detailed explanation is available in Eelco Dolstra PhD Thesis.

These files are created each time the nix-instantiate command evaluates the derivation function of the Nix language, unless the --eval command line option is provided.

Why one would generate store derivations using nix-instantiate ?

If you are interested in the build output, you should prefer nix-build, which is equivalent to:

$ nix-store -r $(nix-instantiate '<nixpkgs>' -A hello)

In some cases you are not interested in the build results, but in looking at the compilation time dependencies. For example, if you want you to investigate the build time dependencies of hello. Then using the nix-store command as follow, you can request all the dependencies of the build recipe:

$ nix-store --tree -q $(nix-instantiate '<nixpkgs>' -A hello)